3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be included
12 .\" in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
24 .\" ES - Example Start - indents and turns off line fill
29 .\" EE - Example End - ends indent and turns line fill back on
34 .TH SCONS 1 "__MONTH_YEAR__"
36 scons \- a software construction tool
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found.
65 An alternate file name may be
72 file can specify subsidiary
73 configuration files using the
77 these subsidiary files are named
79 although any name may be used.
80 (Because of this naming convention,
81 the term "SConscript files"
82 is sometimes used to refer
86 regardless of actual file name.)
88 The configuration files
89 specify the target files to be built, and
90 (optionally) the rules to build those targets. Reasonable default
91 rules exist for building common software components (executable
92 programs, object files, libraries), so that for most software
93 projects, only the target and input files need be specified.
96 reads and executes the SConscript files as Python scripts,
97 so you may use normal Python scripting capabilities
98 (such as flow control, data manipulation, and imported Python libraries)
99 to handle complicated build situations.
101 however, reads and executes all of the SConscript files
103 it begins building any targets.
104 To make this obvious,
106 prints the following messages about what it is doing:
110 scons: Reading SConscript files ...
111 scons: done reading SConscript files.
112 scons: Building targets ...
114 scons: done building targets.
119 (everything except the line that reads "cp foo.in foo.out")
120 may be suppressed using the
125 does not automatically propagate
126 the external environment used to execute
128 to the commands used to build target files.
129 This is so that builds will be guaranteed
130 repeatable regardless of the environment
131 variables set at the time
134 This also means that if the compiler or other commands
135 that you want to use to build your target files
136 are not in standard system locations,
138 will not find them unless
139 you explicitly set the PATH
140 to include those locations.
141 Whenever you create an
143 construction environment,
144 you can propagate the value of PATH
145 from your external environment as follows:
149 env = Environment(ENV = {'PATH' : os.environ['PATH']})
152 Similarly, if the commands use external environment variables
153 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
154 these variables can also be explicitly propagated:
158 env = Environment(ENV = {'PATH' : os.environ['PATH'],
159 'HOME' : os.environ['HOME']})
162 Or you may explicitly propagate the invoking user's
163 complete external environment:
167 env = Environment(ENV = os.environ['PATH'])
170 This comes at the expense of making your build
171 dependent on the user's environment being set correctly,
172 but it may be more convenient for many configurations.
175 can scan known input files automatically for dependency
176 information (for example, #include statements
177 in C or C++ files) and will rebuild dependent files appropriately
178 whenever any "included" input file changes.
181 ability to define new scanners for unknown input file types.
184 knows how to fetch files automatically from
185 SCCS or RCS subdirectories
186 using SCCS, RCS or BitKeeper.
189 is normally executed in a top-level directory containing a
191 file, optionally specifying
192 as command-line arguments
193 the target file or files to be built.
195 By default, the command
201 will build all target files in or below the current directory.
202 Explicit default targets
203 (to be built when no targets are specified on the command line)
204 may be defined the SConscript file(s)
207 function, described below.
211 targets are specified in the SConscript file(s),
212 all target files in or below the current directory
213 may be built by explicitly specifying
214 the current directory (.)
215 as a command-line target:
221 Building all target files,
222 including any files outside of the current directory,
223 may be specified by supplying a command-line target
224 of the root directory (on POSIX systems):
230 or the path name(s) of the volume(s) in which all the targets
231 should be built (on Windows systems):
237 To build only specific targets,
238 supply them as command-line arguments:
244 in which case only the specified targets will be built
245 (along with any derived files on which they depend).
247 Specifying "cleanup" targets in SConscript files is not
250 flag removes all files
251 necessary to build the specified target:
257 to remove all target files, or:
260 scons -c build export
263 to remove target files under build and export.
264 Additional files or directories to remove can be specified using the
267 Conversely, targets that would normally be removed by the
270 can be prevented from being removed by using the
274 A subset of a hierarchical tree may be built by
275 remaining at the top-level directory (where the
277 file lives) and specifying the subdirectory as the target to be
284 or by changing directory and invoking scons with the
286 option, which traverses up the directory
287 hierarchy until it finds the
289 file, and then builds
290 targets relatively to the current subdirectory:
298 supports building multiple targets in parallel via a
300 option that takes, as its argument, the number
301 of simultaneous tasks that may be spawned:
307 builds four targets in parallel, for example.
310 can maintain a cache of target (derived) files that can
311 be shared between multiple builds. When caching is enabled in a
312 SConscript file, any target files built by
315 to the cache. If an up-to-date target file is found in the cache, it
316 will be retrieved from the cache instead of being rebuilt locally.
317 Caching behavior may be disabled and controlled in other ways by the
319 .BR --cache-disable ,
322 command-line options. The
324 option is useful to prevent multiple builds
325 from trying to update the cache simultaneously.
327 Values of variables to be passed to the SConscript file(s)
328 may be specified on the command line:
334 These variables are available in SConscript files
335 through the ARGUMENTS dictionary,
336 and can be used in the SConscript file(s) to modify
337 the build in any way:
340 if ARGUMENTS.get('debug', 0):
341 env = Environment(CCFLAGS = '-g')
346 The command-line variable arguments are also available
348 indexed by their order on the command line.
349 This allows you to process them in order rather than by name,
351 ARGLIST[0] returns a tuple
352 containing (argname, argvalue).
353 A Python exception is thrown if you
354 try to access a list member that
358 requires Python version 1.5.2 or later.
359 There should be no other dependencies or requirements to run
362 .\" The following paragraph reflects the default tool search orders
363 .\" currently in SCons/Tool/__init__.py. If any of those search orders
364 .\" change, this documentation should change, too.
367 knows how to search for available programming tools
371 searches in order for the
372 Microsoft Visual C++ tools,
373 the MinGW tool chain,
374 the Intel compiler tools,
375 and the PharLap ETS compiler.
378 searches in order for the
381 and the Microsoft Visual C++ tools,
382 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
384 searches for the native compiler tools
385 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
386 and the GCC tool chain.
387 On all other platforms,
388 including POSIX (Linux and UNIX) platforms,
391 for the GCC tool chain,
392 the Microsoft Visual C++ tools,
393 and the Intel compiler tools.
394 You may, of course, override these default values
395 by appropriate configuration of
396 Environment construction variables.
401 supports the same command-line options as GNU
403 and many of those supported by
408 Ignored for compatibility with non-GNU versions of
412 -c, --clean, --remove
413 Clean up by removing all target files for which a construction
414 command is specified.
415 Also remove any files or directories associated to the construction command
419 Will not remove any targets specified by the
424 .RI --cache-debug= file
425 Print debug information about the
435 the debug information are printed to the standard output.
436 The printed messages describe what signature file names are
437 being looked for in, retrieved from, or written to the
442 --cache-disable, --no-cache
443 Disable the derived-file caching specified by
446 will neither retrieve files from the cache
447 nor copy files to the cache.
450 --cache-force, --cache-populate
453 populate a cache by copying any already-existing, up-to-date
454 derived files to the cache,
455 in addition to files built by this invocation.
456 This is useful to populate a new cache with
457 all the current derived files,
458 or to add to the cache any derived files
459 recently built with caching disabled via the
467 and retrieving a derived file from the cache,
469 that would have been executed to build the file,
470 instead of the usual report,
471 "Retrieved `file' from cache."
472 This will produce consistent output for build logs,
473 regardless of whether a target
474 file was rebuilt or retrieved from the cache.
478 This specifies how the
480 call should use or generate the
481 results of configuration tests.
482 The option should be specified from
483 among the following choices:
487 scons will use its normal dependency mechanisms
488 to decide if a test must be rebuilt or not.
489 This saves time by not running the same configuration tests
490 every time you invoke scons,
491 but will overlook changes in system header files
492 or external commands (such as compilers)
493 if you don't specify those dependecies explicitly.
494 This is the default behavior.
498 If this option is specified,
499 all configuration tests will be re-run
500 regardless of whether the
501 cached results are out of date.
502 This can be used to explicitly
503 force the configuration tests to be updated
504 in response to an otherwise unconfigured change
505 in a system header file or compiler.
509 If this option is specified,
510 no configuration tests will be rerun
511 and all results will be taken from cache.
512 Note that scons will still consider it an error
513 if --config=cache is specified
514 and a necessary test does not
515 yet have any results in the cache.
518 .RI "-C" " directory" ", --directory=" directory
519 Change to the specified
521 before searching for the
526 file, or doing anything
529 options are interpreted
530 relative to the previous one, and the right-most
532 option wins. (This option is nearly
534 .BR "-f directory/SConstruct" ,
535 except that it will search for
540 in the specified directory.)
544 .\" Display dependencies while building target files. Useful for
545 .\" figuring out why a specific file is being rebuilt, as well as
546 .\" general debugging of the build process.
550 Works exactly the same way as the
552 option except for the way default targets are handled.
553 When this option is used and no targets are specified on the command line,
554 all default targets are built, whether or not they are below the current
559 Debug the build process.
561 specifies what type of debugging:
565 Print how many objects are created
566 of the various classes used internally by SCons
567 before and after reading the SConscript files
568 and before and after building targets.
569 This only works when run under Python 2.1 or later.
573 Print the dependency tree
574 after each top-level target is built. This prints out only derived files.
578 Print an explanation of precisely why
580 is deciding to (re-)build any targets.
581 (Note: this does not print anything
588 Instruct the scanner that searches for libraries
589 to print a message about each potential library
590 name it is searching for,
591 and about the actual libraries it finds.
595 Print the include tree after each top-level target is built.
596 This is generally used to find out what files are included by the sources
597 of a given derived file:
600 $ scons --debug=includes foo.o
605 Prints a summary of hits and misses using the Memoizer,
606 an internal subsystem that counts
607 how often SCons uses cached values in memory
608 instead of recomputing them each time they're needed.
609 Only available when using Python 2.2 or later.
613 Prints how much memory SCons uses
614 before and after reading the SConscript files
615 and before and after building targets.
619 A deprecated option preserved for backwards compatibility.
623 Prints a list of the various objects
624 of the various classes used internally by SCons.
625 This only works when run under Python 2.1 or later.
629 Re-run SCons under the control of the
635 Print the raw command line used to build each target
636 before the construction environment variables are substituted.
637 Also shows which targets are being built by this command.
638 Output looks something like this:
640 $ scons --debug=presub
641 Building myprog.o with action(s):
642 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
648 Prints an internal Python stack trace
649 when encountering an otherwise unexplained error.
653 Print the dependency tree along with status information. This is the
654 same as the debug=tree option, but additional status information is
655 provided for each node in the tree.
659 Prints various time profiling information: the time spent
660 executing each build command, the total build time, the total time spent
661 executing build commands, the total time spent executing SConstruct and
662 SConscript files, and the total time spent executing SCons itself.
666 Print the dependency tree
667 after each top-level target is built. This prints out the complete
668 dependency tree including implicit dependencies and ignored
672 .RI --diskcheck= types
673 Enable specific checks for
674 whether or not there is a file on disk
675 where the SCons configuration expects a directory
677 and whether or not RCS or SCCS sources exist
678 when searching for source and include files.
681 argument can be set to:
683 to enable all checks explicitly
684 (the default behavior);
686 to disable all such checks;
688 to check that files and directories on disk
689 match SCons' expected configuration;
691 to check for the existence of an RCS source
692 for any missing source or include files;
694 to check for the existence of an SCCS source
695 for any missing source or include files.
696 Multiple checks can be specified separated by commas;
698 .B --diskcheck=sccs,rcs
699 would still check for SCCS and RCS sources,
700 but disable the check for on-disk matches of files and directories.
701 Disabling some or all of these checks
702 can provide a performance boost for large configurations,
703 or when the configuration will check for files and/or directories
704 across networked or shared file systems,
705 at the slight increased risk of an incorrect build
706 or of not handling errors gracefully
707 (if include files really should be
708 found in SCCS or RCS, for example,
709 or if a file really does exist
710 where the SCons configuration expects a directory).
713 .\" -e, --environment-overrides
714 .\" Variables from the execution environment override construction
715 .\" variables from the SConscript files.
718 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
721 as the initial SConscript file.
725 Print a local help message for this build, if one is defined in
726 the SConscript file(s), plus a line that describes the
728 option for command-line option help. If no local help message
729 is defined, prints the standard help message about command-line
730 options. Exits after displaying the appropriate message.
734 Print the standard help message about command-line options and
739 Ignore all errors from commands executed to rebuild files.
742 .RI -I " directory" ", --include-dir=" directory
746 imported Python modules. If several
749 are used, the directories are searched in the order specified.
753 Cache implicit dependencies. This can cause
755 to miss changes in the implicit dependencies in cases where a new implicit
756 dependency is added earlier in the implicit dependency search path
757 (e.g. CPPPATH) than a current implicit dependency with the same name.
760 --implicit-deps-changed
761 Force SCons to ignore the cached implicit dependencies. This causes the
762 implicit dependencies to be rescanned and recached. This implies
763 .BR --implicit-cache .
766 --implicit-deps-unchanged
767 Force SCons to ignore changes in the implicit dependencies.
768 This causes cached implicit dependencies to always be used.
770 .BR --implicit-cache .
773 .RI -j " N" ", --jobs=" N
774 Specifies the number of jobs (commands) to run simultaneously.
775 If there is more than one
777 option, the last one is effective.
781 .\" is specified without an argument,
783 .\" will not limit the number of
784 .\" simultaneous jobs.
788 Continue as much as possible after an error. The target that
789 failed and those that depend on it will not be remade, but other
790 targets specified on the command line will still be processed.
793 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
794 .\" No new jobs (commands) will be started if
795 .\" there are other jobs running and the system load
796 .\" average is at least
798 .\" (a floating-point number).
801 .RI --duplicate= ORDER
802 There are three ways to duplicate files in a build tree: hard links,
803 soft (symbolic) links and copies. The default behaviour of SCons is to
804 prefer hard links to soft links to copies. You can specify different
805 behaviours with this option.
815 SCons will attempt to duplicate files using
816 the mechanisms in the specified order.
821 .\" List derived files (targets, dependencies) that would be built,
822 .\" but do not build them.
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, with the actions
829 .\" (commands) that build them. Does not build the files.
830 .\" [XXX This can probably go away with the right
831 .\" combination of other options. Revisit this issue.]
835 .\" List derived files that would be built, plus where the file is
836 .\" defined (file name and line number). Does not build the files.
837 .\" [XXX This can probably go away with the right
838 .\" combination of other options. Revisit this issue.]
842 Ignored for compatibility with non-GNU versions of
846 .RI --max-drift= SECONDS
847 Set the maximum expected drift in the modification time of files to
849 This value determines how long a file must be unmodified
850 before its cached content signature
851 will be used instead of
852 calculating a new content signature (MD5 checksum)
853 of the file's contents.
854 The default value is 2 days, which means a file must have a
855 modification time of at least two days ago in order to have its
856 cached content signature used.
857 A negative value means to never cache the content
858 signature and to ignore the cached value if there already is one. A value
859 of 0 means to always use the cached signature,
860 no matter how old the file is.
863 -n, --just-print, --dry-run, --recon
864 No execute. Print the commands that would be executed to build
865 any out-of-date target files, but do not execute the commands.
868 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
872 .\" not rebuild anything due to changes in the contents of
875 .\" .RI --override " file"
876 .\" Read values to override specific build environment variables
877 .\" from the specified
881 .\" Print the data base (construction environments,
882 .\" Builder and Scanner objects) that are defined
883 .\" after reading the SConscript files.
884 .\" After printing, a normal build is performed
885 .\" as usual, as specified by other command-line options.
886 .\" This also prints version information
891 .\" To print the database without performing a build do:
899 Run SCons under the Python profiler
900 and save the results in the specified
902 The results may be analyzed using the Python
907 Do not run any commands, or print anything. Just return an exit
908 status that is zero if the specified targets are already up to
909 date, non-zero otherwise.
912 Quiets SCons status messages about
913 reading SConscript files,
915 and entering directories.
916 Commands that are executed
917 to rebuild target files are still printed.
920 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
921 .\" Clear the default construction variables. Construction
922 .\" environments that are created will be completely empty.
926 Build dependencies in a random order. This is useful when
927 building multiple trees simultaneously with caching enabled,
928 to prevent multiple builds from simultaneously trying to build
929 or retrieve the same target files.
932 -s, --silent, --quiet
933 Silent. Do not print commands that are executed to rebuild
935 Also suppresses SCons status messages.
938 -S, --no-keep-going, --stop
939 Ignored for compatibility with GNU
944 Ignored for compatibility with GNU
946 (Touching a file to make it
947 appear up-to-date is unnecessary when using
951 .RI --taskmastertrace= file
952 Prints trace information to the specified
954 about how the internal Taskmaster object
955 evaluates and controls the order in which Nodes are built.
958 may be used to specify the standard output.
961 -u, --up, --search-up
962 Walks up the directory structure until an
967 file is found, and uses that
968 as the top of the directory tree.
969 If no targets are specified on the command line,
970 only targets at or below the
971 current directory will be built.
975 Works exactly the same way as the
977 option except for the way default targets are handled.
978 When this option is used and no targets are specified on the command line,
979 all default targets that are defined in the SConscript(s) in the current
980 directory are built, regardless of what directory the resultant targets end
987 version, copyright information,
988 list of authors, and any other relevant information.
992 -w, --print-directory
993 Print a message containing the working directory before and
994 after other processing.
997 .RI --warn= type ", --warn=no-" type
998 Enable or disable warnings.
1000 specifies the type of warnings to be enabled or disabled:
1003 --warn=all, --warn=no-all
1004 Enables or disables all warnings.
1007 --warn=dependency, --warn=no-dependency
1008 Enables or disables warnings about dependencies.
1009 These warnings are disabled by default.
1012 --warn=deprecated, --warn=no-deprecated
1013 Enables or disables warnings about use of deprecated features.
1014 These warnings are enabled by default.
1017 --warn=missing-sconscript, --warn=no-missing-sconscript
1018 Enables or disables warnings about missing SConscript files.
1019 These warnings are enabled by default.
1022 --no-print-directory
1023 Turn off -w, even if it was turned on implicitly.
1026 .\" .RI --write-filenames= file
1027 .\" Write all filenames considered into
1031 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1032 .\" Pretend that the target
1035 .\" modified. When used with the
1038 .\" show you what would be rebuilt if you were to modify that file.
1044 .\" --warn-undefined-variables
1045 .\" Warn when an undefined variable is referenced.
1048 .RI -Y " repository" ", --repository=" repository
1049 Search the specified repository for any input and target
1050 files not found in the local directory hierarchy. Multiple
1052 options may specified, in which case the
1053 repositories are searched in the order specified.
1055 .SH CONFIGURATION FILE REFERENCE
1056 .\" .SS Python Basics
1057 .\" XXX Adding this in the future would be a help.
1058 .SS Construction Environments
1059 A construction environment is the basic means by which the SConscript
1060 files communicate build information to
1062 A new construction environment is created using the
1070 By default, a new construction environment is
1071 initialized with a set of builder methods
1072 and construction variables that are appropriate
1073 for the current platform.
1074 An optional platform keyword argument may be
1075 used to specify that an environment should
1076 be initialized for a different platform:
1079 env = Environment(platform = 'cygwin')
1080 env = Environment(platform = 'os2')
1081 env = Environment(platform = 'posix')
1082 env = Environment(platform = 'win32')
1085 Specifying a platform initializes the appropriate
1086 construction variables in the environment
1087 to use and generate file names with prefixes
1088 and suffixes appropriate for the platform.
1096 variables from the user's external environment
1097 to the construction environment's
1100 This is so that any executed commands
1101 that use sockets to connect with other systems
1102 (such as fetching source files from
1103 external CVS repository specifications like
1104 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1105 will work on Windows systems.
1107 The platform argument may be function or callable object,
1108 in which case the Environment() method
1109 will call the specified argument to update
1110 the new construction environment:
1113 def my_platform(env):
1114 env['VAR'] = 'xyzzy'
1116 env = Environment(platform = my_platform)
1119 Additionally, a specific set of tools
1120 with which to initialize the environment
1121 may specified as an optional keyword argument:
1124 env = Environment(tools = ['msvc', 'lex'])
1127 Non-built-in tools may be specified using the toolpath argument:
1130 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1133 This looks for a tool specification in tools/foo.py (as well as
1134 using the ordinary default tools for the platform). foo.py should
1135 have two functions: generate(env, **kw) and exists(env).
1139 modifies the passed-in environment
1140 to set up variables so that the tool
1142 it may use any keyword arguments
1143 that the user supplies (see below)
1144 to vary its initialization.
1147 function should return a true
1148 value if the tool is available.
1149 Tools in the toolpath are used before
1150 any of the built-in ones. For example, adding gcc.py to the toolpath
1151 would override the built-in gcc tool.
1152 Also note that the toolpath is
1153 stored in the environment for use
1161 base = Environment(toolpath=['custom_path'])
1162 derived = base.Clone(tools=['custom_tool'])
1163 derived.CustomBuilder()
1166 The elements of the tools list may also
1167 be functions or callable objects,
1168 in which case the Environment() method
1169 will call the specified elements
1170 to update the new construction environment:
1174 env['XYZZY'] = 'xyzzy'
1176 env = Environment(tools = [my_tool])
1179 The individual elements of the tools list
1180 may also themselves be two-element lists of the form
1181 .RI ( toolname ", " kw_dict ).
1182 SCons searches for the
1184 specification file as described above, and
1187 which must be a dictionary, as keyword arguments to the tool's
1192 function can use the arguments to modify the tool's behavior
1193 by setting up the environment in different ways
1194 or otherwise changing its initialization.
1197 # in tools/my_tool.py:
1198 def generate(env, **kw):
1199 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1200 env['MY_TOOL'] = kw.get('arg1', '1')
1205 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1209 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1210 the environment it receives to customize the tool for different platforms.
1212 If no tool list is specified, then SCons will auto-detect the installed
1213 tools using the PATH variable in the ENV construction variable and the
1214 platform name when the Environment is constructed. Changing the PATH
1215 variable after the Environment is constructed will not cause the tools to
1218 SCons supports the following tool specifications out of the box:
1294 Additionally, there is a "tool" named
1296 which configures the
1297 environment with a default set of tools for the current platform.
1299 On posix and cygwin platforms
1300 the GNU tools (e.g. gcc) are preferred by SCons,
1301 on Windows the Microsoft tools (e.g. msvc)
1302 followed by MinGW are preferred by SCons,
1303 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1307 Build rules are specified by calling a construction
1308 environment's builder methods.
1309 The arguments to the builder methods are
1311 (a list of target files)
1314 (a list of source files).
1316 Because long lists of file names
1317 can lead to a lot of quoting,
1322 and a same-named environment method
1323 that split a single string
1324 into a list, separated on
1325 strings of white-space characters.
1326 (These are similar to the
1327 string.split() method
1328 from the standard Python library,
1329 but work even if the input isn't a string.)
1331 Like all Python arguments,
1332 the target and source arguments to a builder method
1333 can be specified either with or without
1334 the "target" and "source" keywords.
1335 When the keywords are omitted,
1336 the target is first,
1337 followed by the source.
1338 The following are equivalent examples of calling the Program builder method:
1341 env.Program('bar', ['bar.c', 'foo.c'])
1342 env.Program('bar', Split('bar.c foo.c'))
1343 env.Program('bar', env.Split('bar.c foo.c'))
1344 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1345 env.Program(target = 'bar', Split('bar.c foo.c'))
1346 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1347 env.Program('bar', source = string.split('bar.c foo.c'))
1350 When the target shares the same base name
1351 as the source and only the suffix varies,
1352 and if the builder method has a suffix defined for the target file type,
1353 then the target argument may be omitted completely,
1356 will deduce the target file name from
1357 the source file name.
1358 The following examples all build the
1364 (on Windows systems)
1365 from the bar.c source file:
1368 env.Program(target = 'bar', source = 'bar.c')
1369 env.Program('bar', source = 'bar.c')
1370 env.Program(source = 'bar.c')
1371 env.Program('bar.c')
1376 keyword argument may be specified
1377 when calling a Builder.
1379 all source file strings that are not absolute paths
1380 will be interpreted relative to the specified
1382 The following example will build the
1387 program from the files
1393 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1396 It is possible to override or add construction variables when calling a
1397 builder method by passing additional keyword arguments.
1398 These overridden or added
1399 variables will only be in effect when building the target, so they will not
1400 affect other parts of the build. For example, if you want to add additional
1401 libraries for just one program:
1404 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1407 or generate a shared library with a non-standard suffix:
1410 env.SharedLibrary('word', 'word.cpp',
1412 LIBSUFFIXES=['.ocx'])
1415 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1416 if you want SCons to search automatically
1417 for dependencies on the non-standard library names;
1418 see the descriptions of these variables, below, for more information.)
1420 Although the builder methods defined by
1423 methods of a construction environment object,
1424 they may also be called without an explicit environment:
1427 Program('hello', 'hello.c')
1428 SharedLibrary('word', 'word.cpp')
1432 the methods are called internally using a default construction
1433 environment that consists of the tools and values that
1435 has determined are appropriate for the local system.
1437 Builder methods that can be called without an explicit
1438 environment may be called from custom Python modules that you
1439 import into an SConscript file by adding the following
1440 to the Python module:
1443 from SCons.Script import *
1446 All builder methods return a list of Nodes
1447 that represent the target or targets that will be built.
1450 is an internal SCons object
1452 build targets or sources.
1454 The returned Node(s)
1455 can be passed to other builder methods as source(s)
1456 or passed to any SCons function or method
1457 where a filename would normally be accepted.
1458 For example, if it were necessary
1461 flag when compiling one specific object file:
1464 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1465 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1468 Using a Node in this way
1469 makes for a more portable build
1470 by avoiding having to specify
1471 a platform-specific object suffix
1472 when calling the Program() builder method.
1474 Note that Builder calls will automatically "flatten"
1475 the source and target file lists,
1476 so it's all right to have the bar_obj list
1477 return by the StaticObject() call
1478 in the middle of the source file list.
1479 If you need to manipulate a list of lists returned by Builders
1480 directly using Python,
1481 you can either build the list by hand:
1484 foo = Object('foo.c')
1485 bar = Object('bar.c')
1486 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1487 for object in objects:
1494 to create a list containing just the Nodes,
1495 which may be more convenient:
1498 foo = Object('foo.c')
1499 bar = Object('bar.c')
1500 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1501 for object in objects:
1505 The path name for a Node's file may be used
1506 by passing the Node to the Python-builtin
1511 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1512 print "The path to bar_obj is:", str(bar_obj_list[0])
1515 Note again that because the Builder call returns a list,
1516 we have to access the first element in the list
1517 .B (bar_obj_list[0])
1518 to get at the Node that actually represents
1521 Builder calls support a
1523 keyword argument that
1524 specifies that the Builder's action(s)
1526 after changing directory.
1530 a string or a directory Node,
1531 scons will change to the specified directory.
1534 is not a string or Node
1536 then scons will change to the
1537 target file's directory.
1540 # scons will change to the "sub" subdirectory
1541 # before executing the "cp" command.
1542 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1543 "cp dir/foo.in dir/foo.out",
1546 # Because chdir is not a string, scons will change to the
1547 # target's directory ("sub/dir") before executing the
1549 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1550 "cp foo.in foo.out",
1554 Note that scons will
1556 automatically modify
1558 construction variables like
1562 when using the chdir
1563 keyword argument--that is,
1564 the expanded file names
1565 will still be relative to
1566 the top-level SConstruct directory,
1567 and consequently incorrect
1568 relative to the chdir directory.
1569 If you use the chdir keyword argument,
1570 you will typically need to supply a different
1576 to use just the filename portion of the
1580 provides the following builder methods:
1582 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1583 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1585 '\" The descriptions below of the various SCons Builders are generated
1586 '\" from the .xml files that live next to the various Python modules in
1587 '\" the build enginer library. If you're reading this [gnt]roff file
1588 '\" with an eye towards patching this man page, you can still submit
1589 '\" a diff against this text, but it will have to be translated to a
1590 '\" diff against the underlying .xml file before the patch is actually
1591 '\" accepted. If you do that yourself, it will make it easier to
1592 '\" integrate the patch.
1594 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
1595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1597 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1598 '\" END GENERATED BUILDER DESCRIPTIONS
1600 '\" The descriptions above of the various SCons Builders are generated
1601 '\" from the .xml files that live next to the various Python modules in
1602 '\" the build enginer library. If you're reading this [gnt]roff file
1603 '\" with an eye towards patching this man page, you can still submit
1604 '\" a diff against this text, but it will have to be translated to a
1605 '\" diff against the underlying .xml file before the patch is actually
1606 '\" accepted. If you do that yourself, it will make it easier to
1607 '\" integrate the patch.
1609 '\" END GENERATED BUILDER DESCRIPTIONS
1610 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1613 targets of builder methods automatically depend on their sources.
1614 An explicit dependency can
1615 be specified using the
1617 method of a construction environment (see below).
1622 source files for various programming languages,
1623 so the dependencies do not need to be specified explicitly.
1624 By default, SCons can
1627 Fortran source files with
1629 (POSIX systems only),
1634 and assembly language files with
1636 (POSIX systems only),
1641 for C preprocessor dependencies.
1642 SCons also has default support
1643 for scanning D source files,
1644 You can also write your own Scanners
1645 to add support for additional source file types.
1646 These can be added to the default
1647 Scanner object used by
1653 Builders by adding them
1655 .B SourceFileScanner
1658 See the section "Scanner Objects,"
1659 below, for a more information about
1660 defining your own Scanner objects.
1662 .SS Methods and Functions to Do Things
1663 In addition to Builder methods,
1665 provides a number of other construction environment methods
1666 and global functions to
1667 manipulate the build configuration.
1669 Usually, a construction environment method
1670 and global function with the same name both exist
1671 so that you don't have to remember whether
1672 to a specific bit of functionality
1673 must be called with or without a construction environment.
1674 In the following list,
1675 if you call something as a global function
1678 .RI Function( arguments )
1680 and if you call something through a construction
1681 environment it looks like:
1683 .RI env.Function( arguments )
1685 If you can call the functionality in both ways,
1686 then both forms are listed.
1688 Global functions may be called from custom Python modules that you
1689 import into an SConscript file by adding the following
1690 to the Python module:
1693 from SCons.Script import *
1696 Except where otherwise noted,
1698 construction environment method
1700 provide the exact same functionality.
1701 The only difference is that,
1703 calling the functionality through a construction environment will
1704 substitute construction variables into
1705 any supplied strings.
1708 env = Environment(FOO = 'foo')
1712 the first call to the global
1714 function will actually add a target named
1716 to the list of default targets,
1717 while the second call to the
1719 construction environment method
1720 will expand the value
1721 and add a target named
1723 to the list of default targets.
1724 For more on construction variable expansion,
1725 see the next section on
1726 construction variables.
1728 Construction environment methods
1729 and global functions supported by
1733 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1735 .RI Action( action ", [" strfunction ", " varlist ])
1737 .RI env.Action( action ", [" strfunction ", " varlist ])
1738 Creates an Action object for
1741 See the section "Action Objects,"
1742 below, for a complete explanation of the arguments and behavior.
1746 form of the invocation will expand
1747 construction variables in any arguments strings,
1751 at the time it is called
1752 using the construction variables in the
1754 construction environment through which
1759 form delays all variable expansion
1760 until the Action object is actually used.
1762 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1764 .RI AddPostAction( target ", " action )
1766 .RI env.AddPostAction( target ", " action )
1767 Arranges for the specified
1773 The specified action(s) may be
1774 an Action object, or anything that
1775 can be converted into an Action object
1778 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1780 .RI AddPreAction( target ", " action )
1782 .RI env.AddPreAction( target ", " action )
1783 Arranges for the specified
1786 before the specified
1789 The specified action(s) may be
1790 an Action object, or anything that
1791 can be converted into an Action object
1794 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1796 .RI Alias( alias ", [" targets ", [" action ]])
1798 .RI env.Alias( alias ", [" targets ", [" action ]])
1799 Creates one or more phony targets that
1800 expand to one or more other targets.
1805 can be specified that will be executed
1806 whenever the any of the alias targets are out-of-date.
1807 Returns the Node object representing the alias,
1808 which exists outside of any file system.
1809 This Node object, or the alias name,
1810 may be used as a dependency of any other target,
1811 including another alias.
1813 can be called multiple times for the same
1814 alias to add additional targets to the alias,
1815 or additional actions to the list for this alias.
1819 Alias('install', '/usr/bin')
1820 Alias(['install', 'install-lib'], '/usr/local/lib')
1822 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
1823 env.Alias('install', ['/usr/local/man'])
1825 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
1828 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1830 .RI AllowSubstExceptions([ exception ", ...])"
1831 Specifies the exceptions that will be allowed
1832 when expanding construction variables.
1834 any construction variable expansions that generate a
1838 exception will expand to a
1840 (a null string) and not cause scons to fail.
1841 All exceptions not in the specified list
1842 will generate an error message
1843 and terminate processing.
1846 .B AllowSubstExceptions
1847 is called multiple times,
1848 each call completely overwrites the previous list
1849 of allowed exceptions.
1853 # Requires that all construction variable names exist.
1854 # (You may wish to do this if you want to enforce strictly
1855 # that all construction variables must be defined before use.)
1856 AllowSubstExceptions()
1858 # Also allow a string containing a zero-division expansion
1859 # like '${1 / 0}' to evalute to ''.
1860 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
1863 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1865 .RI AlwaysBuild( target ", ...)"
1867 .RI env.AlwaysBuild( target ", ...)"
1870 so that it is always assumed to be out of date,
1871 and will always be rebuilt if needed.
1874 does not add its target(s) to the default target list,
1875 so the targets will only be built
1876 if they are specified on the command line,
1877 or are a dependent of a target specified on the command line--but
1880 be built if so specified.
1881 Multiple targets can be passed in to a single call to
1884 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1886 .RI env.Append( key = val ", [...])"
1887 Appends the specified keyword arguments
1888 to the end of construction variables in the environment.
1889 If the Environment does not have
1890 the specified construction variable,
1891 it is simply added to the environment.
1892 If the values of the construction variable
1893 and the keyword argument are the same type,
1894 then the two values will be simply added together.
1895 Otherwise, the construction variable
1896 and the value of the keyword argument
1897 are both coerced to lists,
1898 and the lists are added together.
1899 (See also the Prepend method, below.)
1902 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
1905 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1907 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
1908 This appends new path elements to the given path in the
1909 specified external environment
1913 any particular path once (leaving the last one it encounters and
1914 ignoring the rest, to preserve path order),
1915 and to help assure this,
1916 will normalize all paths (using
1919 .BR os.path.normcase ).
1920 This can also handle the
1921 case where the given old path variable is a list instead of a
1922 string, in which case a list will be returned instead of a string.
1926 print 'before:',env['ENV']['INCLUDE']
1927 include_path = '/foo/bar:/foo'
1928 env.AppendENVPath('INCLUDE', include_path)
1929 print 'after:',env['ENV']['INCLUDE']
1933 after: /biz:/foo/bar:/foo
1936 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1938 .RI env.AppendUnique( key = val ", [...])"
1939 Appends the specified keyword arguments
1940 to the end of construction variables in the environment.
1941 If the Environment does not have
1942 the specified construction variable,
1943 it is simply added to the environment.
1944 If the construction variable being appended to is a list,
1945 then any value(s) that already exist in the
1946 construction variable will
1948 be added again to the list.
1951 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
1954 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1957 A factory function that
1958 returns a Builder object
1959 to be used to fetch source files
1961 The returned Builder
1962 is intended to be passed to the
1967 env.SourceCode('.', env.BitKeeper())
1970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1972 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
1974 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
1975 This specifies a build directory
1977 in which to build all derived files
1978 that would normally be built under
1980 Multiple build directories can be set up for multiple build variants, for
1983 must be underneath the SConstruct file's directory,
1986 may not be underneath the
1989 The default behavior is for
1991 to duplicate all of the files in the tree underneath
1995 and then build the derived files within the copied tree.
1996 (The duplication is performed by
1998 depending on the platform; see also the
2001 This guarantees correct builds
2002 regardless of whether intermediate source files
2003 are generated during the build,
2004 where preprocessors or other scanners search
2006 or whether individual compilers or other invoked tools
2007 are hard-coded to put derived files in the same directory as source files.
2009 This behavior of making a complete copy of the source tree
2010 may be disabled by setting
2015 to invoke Builders using the
2016 path names of source files in
2018 and the path names of derived files within
2020 This is always more efficient than
2022 and is usually safe for most builds.
2026 may cause build problems
2027 if source files are generated during the build,
2028 if any invoked tools are hard-coded to
2029 put derived files in the same directory as the source files.
2031 Note that specifying a
2033 works most naturally
2034 with a subsidiary SConscript file
2035 in the source directory.
2037 you would then call the subsidiary SConscript file
2038 not in the source directory,
2043 had made a virtual copy of the source tree
2044 regardless of the value of
2046 This is how you tell
2048 which variant of a source tree to build.
2052 BuildDir('build-variant1', 'src')
2053 SConscript('build-variant1/SConscript')
2054 BuildDir('build-variant2', 'src')
2055 SConscript('build-variant2/SConscript')
2061 function, described below,
2063 specify a build directory
2064 in conjunction with calling a subsidiary
2067 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2069 .RI Builder( action ", [" arguments ])
2071 .RI env.Builder( action ", [" arguments ])
2072 Creates a Builder object for
2075 See the section "Builder Objects,"
2076 below, for a complete explanation of the arguments and behavior.
2080 form of the invocation will expand
2081 construction variables in any arguments strings,
2085 at the time it is called
2086 using the construction variables in the
2088 construction environment through which
2093 form delays all variable expansion
2094 until after the Builder object is actually called.
2096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2098 .RI CacheDir( cache_dir )
2100 .RI env.CacheDir( cache_dir )
2103 will maintain a cache of derived files in
2105 The derived files in the cache will be shared
2106 among all the builds using the same
2114 finds a derived file that needs to be rebuilt,
2115 it will first look in the cache to see if a
2116 derived file has already been built
2117 from identical input files and an identical build action
2118 (as incorporated into the MD5 build signature).
2121 will retrieve the file from the cache.
2122 If the derived file is not present in the cache,
2125 then place a copy of the built file in the cache
2126 (identified by its MD5 build signature),
2127 so that it may be retrieved by other
2128 builds that need to build the same derived file
2129 from identical inputs.
2133 may be disabled for any invocation
2142 will place a copy of
2144 derived files in the cache,
2145 even if they already existed
2146 and were not built by this invocation.
2147 This is useful to populate a cache
2150 is added to a build,
2159 "Retrieved `file' from cache,"
2162 option is being used.
2167 will print the action that
2169 have been used to build the file,
2170 without any indication that
2171 the file was actually retrieved from the cache.
2172 This is useful to generate build logs
2173 that are equivalent regardless of whether
2174 a given derived file has been built in-place
2175 or retrieved from the cache.
2177 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2179 .RI Clean( targets ", " files_or_dirs )
2181 .RI env.Clean( targets ", " files_or_dirs )
2182 This specifies a list of files or directories which should be removed
2183 whenever the targets are specified with the
2185 command line option.
2186 The specified targets may be a list
2187 or an individual target.
2191 and create new targets or add files and directories to the
2192 clean list for the specified targets.
2194 Multiple files or directories should be specified
2195 either as separate arguments to the
2197 method, or as a list.
2199 will also accept the return value of any of the construction environment
2205 function overrides calling
2207 for the same target,
2208 and any targets passed to both functions will
2217 Clean('foo', ['bar', 'baz'])
2218 Clean('dist', env.Program('hello', 'hello.c'))
2219 Clean(['foo', 'bar'], 'something_else_to_clean')
2222 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2224 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2226 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2227 Executes a specific action
2228 (or list of actions)
2229 to build a target file or files.
2230 This is more convenient
2231 than defining a separate Builder object
2232 for a single special-case build.
2234 As a special case, the
2236 keyword argument can
2239 that will be used to scan the sources.
2243 if any of the sources will be directories
2244 that must be scanned on-disk for
2245 changes to files that aren't
2246 already specified in other Builder of function calls.)
2248 Any other keyword arguments specified override any
2249 same-named existing construction variables.
2251 An action can be an external command,
2252 specified as a string,
2253 or a callable Python object;
2254 see "Action Objects," below,
2255 for more complete information.
2256 Also note that a string specifying an external command
2257 may be preceded by an
2260 to suppress printing the command in question,
2264 to ignore the exit status of the external command.
2268 env.Command('foo.out', 'foo.in',
2269 "$FOO_BUILD < $SOURCES > $TARGET")
2271 env.Command('bar.out', 'bar.in',
2273 "$BAR_BUILD < $SOURCES > $TARGET"],
2274 ENV = {'PATH' : '/usr/local/bin/'})
2276 def rename(env, target, source):
2278 os.rename('.tmp', str(target[0]))
2280 env.Command('baz.out', 'baz.in',
2281 ["$BAZ_BUILD < $SOURCES > .tmp",
2287 function will usually assume, by default,
2288 that the specified targets and/or sources are Files,
2289 if no other part of the configuration
2290 identifies what type of entry it is.
2291 If necessary, you can explicitly specify
2292 that targets or source nodes should
2293 be treated as directoriese
2301 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2303 env['DISTDIR'] = 'destination/directory'
2304 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2307 (Also note that SCons will usually
2308 automatically create any directory necessary to hold a target file,
2309 so you normally don't need to create directories by hand.)
2311 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2313 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2315 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2316 Creates a Configure object for integrated
2317 functionality similar to GNU autoconf.
2318 See the section "Configure Contexts,"
2319 below, for a complete explanation of the arguments and behavior.
2321 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2323 .RI env.Clone([ key = val ", ...])"
2324 Return a separate copy of a construction environment.
2325 If there are any keyword arguments specified,
2326 they are added to the returned copy,
2327 overwriting any existing values
2332 env3 = env.Clone(CCFLAGS = '-g')
2335 Additionally, a list of tools and a toolpath may be specified, as in
2336 the Environment constructor:
2339 def MyTool(env): env['FOO'] = 'bar'
2340 env4 = env.Clone(tools = ['msvc', MyTool])
2343 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2345 .RI env.Copy([ key = val ", ...])"
2348 (This will probably be officially deprecated some day.)
2350 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2352 .RI env.CVS( repository ", " module )
2353 A factory function that
2354 returns a Builder object
2355 to be used to fetch source files
2359 The returned Builder
2360 is intended to be passed to the
2364 The optional specified
2366 will be added to the beginning
2367 of all repository path names;
2368 this can be used, in essence,
2369 to strip initial directory names
2370 from the repository path names,
2371 so that you only have to
2372 replicate part of the repository
2373 directory hierarchy in your
2374 local build directory:
2377 # Will fetch foo/bar/src.c
2378 # from /usr/local/CVSROOT/foo/bar/src.c.
2379 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2381 # Will fetch bar/src.c
2382 # from /usr/local/CVSROOT/foo/bar/src.c.
2383 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2386 # from /usr/local/CVSROOT/foo/bar/src.c.
2387 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2390 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2392 .RI Default( targets )
2394 .RI env.Default( targets )
2395 This specifies a list of default targets,
2396 which will be built by
2398 if no explicit targets are given on the command line.
2402 and add to the list of default targets.
2404 Multiple targets should be specified as
2405 separate arguments to the
2407 method, or as a list.
2409 will also accept the Node returned by any
2410 of a construction environment's
2415 Default('foo', 'bar', 'baz')
2416 env.Default(['a', 'b', 'c'])
2417 hello = env.Program('hello', 'hello.c')
2425 will clear all default targets.
2428 will add to the (now empty) default-target list
2431 The current list of targets added using the
2433 function or method is available in the
2438 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2440 .RI DefaultEnvironment([ args ])
2441 Creates and returns a default construction environment object.
2442 This construction environment is used internally by SCons
2443 in order to execute many of the global functions in this list,
2444 and to fetch source files transparently
2445 from source code management systems.
2447 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2449 .RI Depends( target ", " dependency )
2451 .RI env.Depends( target ", " dependency )
2452 Specifies an explicit dependency;
2453 the target file(s) will be rebuilt
2454 whenever the dependency file(s) has changed.
2455 This should only be necessary
2456 for cases where the dependency
2457 is not caught by a Scanner
2461 env.Depends('foo', 'other-input-file-for-foo')
2464 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2466 .RI env.Dictionary([ vars ])
2467 Returns a dictionary object
2468 containing copies of all of the
2469 construction variables in the environment.
2470 If there are any variable names specified,
2471 only the specified construction
2472 variables are returned in the dictionary.
2475 dict = env.Dictionary()
2476 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2479 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2481 .RI Dir( name ", [" directory ])
2483 .RI env.Dir( name ", [" directory ])
2484 This returns a Directory Node,
2485 an object that represents the specified directory
2488 can be a relative or absolute path.
2490 is an optional directory that will be used as the parent directory.
2493 is specified, the current script's directory is used as the parent.
2495 Directory Nodes can be used anywhere you
2496 would supply a string as a directory name
2497 to a Builder method or function.
2498 Directory Nodes have attributes and methods
2499 that are useful in many situations;
2500 see "File and Directory Nodes," below.
2502 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2504 .RI env.Dump([ key ])
2505 Returns a pretty printable representation of the environment.
2509 should be a string containing the name of the variable of interest.
2514 print env.Dump('CCCOM')
2518 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2528 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2531 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2538 .RI EnsurePythonVersion( major ", " minor )
2540 .RI env.EnsurePythonVersion( major ", " minor )
2541 Ensure that the Python version is at least
2544 print out an error message and exit SCons with a non-zero exit code if the
2545 actual Python version is not late enough.
2548 EnsurePythonVersion(2,2)
2551 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2553 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
2555 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
2556 Ensure that the SCons version is at least
2559 .IR major.minor.revision .
2564 print out an error message and exit SCons with a non-zero exit code if the
2565 actual SCons version is not late enough.
2568 EnsureSConsVersion(0,14)
2570 EnsureSConsVersion(0,96,90)
2573 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2575 .RI Environment([ key = value ", ...])"
2577 .RI env.Environment([ key = value ", ...])"
2578 Return a new construction environment
2579 initialized with the specified
2583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2585 .RI Execute( action ", [" strfunction ", " varlist ])
2587 .RI env.Execute( action ", [" strfunction ", " varlist ])
2588 Executes an Action object.
2591 may be an Action object
2592 (see the section "Action Objects,"
2593 below, for a complete explanation of the arguments and behavior),
2594 or it may be a command-line string,
2596 or executable Python function,
2597 each of which will be converted
2598 into an Action object
2600 The exit value of the command
2601 or return value of the Python function
2604 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2608 .RI env.Exit([ value ])
2614 A default exit value of
2617 is used if no value is specified.
2619 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2623 .RI env.Export( vars )
2626 to export a list of variables from the current
2627 SConscript file to all other SConscript files.
2628 The exported variables are kept in a global collection,
2629 so subsequent calls to
2631 will over-write previous exports that have the same name.
2632 Multiple variable names can be passed to
2634 as separate arguments or as a list. A dictionary can be used to map
2635 variables to a different name when exported. Both local variables and
2636 global variables can be exported.
2641 # Make env available for all SConscript files to Import().
2645 # Make env and package available for all SConscript files:.
2646 Export("env", "package")
2648 # Make env and package available for all SConscript files:
2649 Export(["env", "package"])
2651 # Make env available using the name debug:.
2652 Export({"debug":env})
2658 function supports an
2660 argument that makes it easier to to export a variable or
2661 set of variables to a single SConscript file.
2662 See the description of the
2666 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2668 .RI File( name ", [" directory ])
2670 .RI env.File( name ", [" directory ])
2673 an object that represents the specified file
2676 can be a relative or absolute path.
2678 is an optional directory that will be used as the parent directory.
2680 File Nodes can be used anywhere you
2681 would supply a string as a file name
2682 to a Builder method or function.
2683 File Nodes have attributes and methods
2684 that are useful in many situations;
2685 see "File and Directory Nodes," below.
2687 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2689 .RI FindFile( file ", " dirs )
2691 .RI env.FindFile( file ", " dirs )
2694 in the path specified by
2697 may be a list of file names or a single file name. In addition to searching
2698 for files that exist in the filesytem, this function also searches for
2699 derived files that have not yet been built.
2702 foo = env.FindFile('foo', ['dir1', 'dir2'])
2705 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2707 .RI Flatten( sequence )
2709 .RI env.Flatten( sequence )
2710 Takes a sequence (that is, a Python list or tuple)
2711 that may contain nested sequences
2712 and returns a flattened list containing
2713 all of the individual elements in any sequence.
2714 This can be helpful for collecting
2715 the lists returned by calls to Builders;
2716 other Builders will automatically
2717 flatten lists specified as input,
2718 but direct Python manipulation of
2719 these lists does not:
2722 foo = Object('foo.c')
2723 bar = Object('bar.c')
2725 # Because `foo' and `bar' are lists returned by the Object() Builder,
2726 # `objects' will be a list containing nested lists:
2727 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2729 # Passing such a list to another Builder is all right because
2730 # the Builder will flatten the list automatically:
2731 Program(source = objects)
2733 # If you need to manipulate the list directly using Python, you need to
2734 # call Flatten() yourself, or otherwise handle nested lists:
2735 for object in Flatten(objects):
2739 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2741 .RI GetBuildPath( file ", [" ... ])
2743 .RI env.GetBuildPath( file ", [" ... ])
2746 path name (or names) for the specified
2754 Nodes or strings representing path names.
2756 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2760 .RI env.GetLaunchDir()
2761 Returns the absolute path name of the directory from which
2764 was initially invoked.
2765 This can be useful when using the
2770 options, which internally
2771 change to the directory in which the
2775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2777 .RI GetOption( name )
2779 .RI env.GetOption( name )
2780 This function provides a way to query a select subset of the scons command line
2781 options from a SConscript file. See
2783 for a description of the options available.
2785 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2787 '\".RI GlobalBuilders( flag )
2791 '\"adds the names of the default builders
2792 '\"(Program, Library, etc.)
2793 '\"to the global name space
2794 '\"so they can be called without an explicit construction environment.
2795 '\"(This is the default.)
2799 '\"the names of the default builders are removed
2800 '\"from the global name space
2801 '\"so that an explicit construction environment is required
2802 '\"to call all builders.
2804 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2808 .RI env.Help( text )
2809 This specifies help text to be printed if the
2811 argument is given to
2815 is called multiple times, the text is appended together in the order
2820 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2822 .RI Ignore( target ", " dependency )
2824 .RI env.Ignore( target ", " dependency )
2825 The specified dependency file(s)
2826 will be ignored when deciding if
2827 the target file(s) need to be rebuilt.
2830 env.Ignore('foo', 'foo.c')
2831 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2834 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2838 .RI env.Import( vars )
2841 to import a list of variables into the current SConscript file. This
2842 will import variables that were exported with
2848 Variables exported by
2851 Multiple variable names can be passed to
2853 as separate arguments or as a list. The variable "*" can be used
2854 to import all variables.
2859 Import("env", "variable")
2860 Import(["env", "variable"])
2864 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2866 .RI Install( dir ", " source )
2868 .RI env.Install( dir ", " source )
2869 Installs one or more source files or directories
2870 in a destination directory
2872 The names of the specified source files or directories
2873 remain the same within the destination directory.
2876 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2879 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2881 .RI InstallAs( target ", " source )
2883 .RI env.InstallAs( target ", " source )
2884 Installs one or more source files or directories
2886 allowing changing a file or directory name
2887 as part of the installation.
2888 It is an error if the
2892 arguments list different numbers of files or directories.
2895 env.InstallAs(target = '/usr/local/bin/foo',
2896 source = 'foo_debug')
2897 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2898 source = ['libFOO.a', 'libBAR.a'])
2901 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2903 .RI Literal( string )
2905 .RI env.Literal( string )
2908 will be preserved as-is
2909 and not have construction variables expanded.
2911 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2913 .RI Local( targets )
2915 .RI env.Local( targets )
2918 will have copies made in the local tree,
2919 even if an already up-to-date copy
2920 exists in a repository.
2921 Returns a list of the target Node or Nodes.
2923 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2925 .RI env.MergeFlags( arg ", [" unique ])
2926 Merges the specified
2928 values to the construction envrionment's construction variables.
2931 argument is not a dictionary,
2932 it is converted to one by calling
2935 before the values are merged.
2938 must be a single value,
2939 so multiple strings must
2940 be passed in as a list,
2941 not as separate arguments to
2942 .BR env.MergeFlags ().
2945 duplicate values are eliminated;
2946 you can, however, specify
2950 When eliminating duplicate values,
2951 any construction variables that end with
2954 keep the left-most unique value.
2955 All other construction variables keep
2956 the right-most unique value.
2961 # Add an optimization flag to $CCFLAGS.
2962 env.MergeFlags('-O3')
2964 # Combine the flags returned from running pkg-config with an optimization
2965 # flag and merge the result into the construction variables.
2966 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
2968 env.MergeFlags(['-O3',
2969 '!pkg-config gtk+-2.0 --cflags --libs',
2970 '!pkg-config libpng12 --cflags --libs'])
2973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2975 .RI NoClean( target ", ...)"
2977 .RI env.NoClean( target ", ...)"
2978 Specifies a list of files or directories which should
2980 be removed whenever the targets (or their dependencies)
2981 are specified with the
2983 command line option.
2984 The specified targets may be a list
2985 or an individual target.
2989 and prevent each specified target
2990 from being removed by calls to the
2994 Multiple files or directories should be specified
2995 either as separate arguments to the
2997 method, or as a list.
2999 will also accept the return value of any of the construction environment
3004 for a target overrides calling
3006 for the same target,
3007 and any targets passed to both functions will
3017 NoClean(env.Program('hello', 'hello.c'))
3020 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3022 .RI env.ParseConfig( command ", [" function ", " unique ])
3025 to modify the environment as specified by the output of
3030 .BR env.MergeFlags (),
3031 which expects the output of a typical
3035 and adds the options
3036 to the appropriate construction variables.
3038 duplicate values are not
3039 added to any construction variables;
3046 and the construction variables they affect
3047 are as specified for the
3048 .BR env.ParseFlags ()
3049 method (which thie method calls).
3050 See that method's description, below,
3051 for a table of options and construction variables.
3053 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3055 .RI ParseDepends( filename ", [" must_exist ])
3057 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3058 Parses the contents of the specified
3060 as a list of dependencies in the style of
3064 and explicitly establishes all of the listed dependencies.
3073 argument may be set to a non-zero
3076 throw an exception and
3077 generate an error if the file does not exist,
3078 or is otherwise inaccessible.
3082 argument may be set to a non-zero
3085 thrown an exception and
3087 if the file contains dependency
3088 information for more than one target.
3089 This can provide a small sanity check
3090 for files intended to be generated
3091 by, for example, the
3094 which should typically only
3095 write dependency information for
3096 one output file into a corresponding
3102 and all of the files listed therein
3103 will be interpreted relative to
3104 the directory of the
3106 file which calls the
3110 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3112 .RI env.ParseFlags( flags ", ...)"
3113 Parses one or more strings containing
3114 typical command-line flags for GCC tool chains
3115 and returns a dictionary with the flag values
3116 separated into the appropriate SCons construction variables.
3117 This is intended as a companion to the
3118 .BR env.MergeFlags ()
3119 method, but allows for the values in the returned dictionary
3120 to be modified, if necessary,
3121 before merging them into the construction environment.
3123 .BR env.MergeFlags ()
3124 will call this method if its argument is not a dictionary,
3125 so it is usually not necessary to call
3126 .BR env.ParseFlags ()
3127 directly unless you want to manipulate the values.)
3129 If the first character in any string is
3130 an exclamation mark (!),
3131 the rest of the string is executed as a command,
3132 and the output from the command is
3133 parsed as GCC tool chain command-line flags
3134 and added to the resulting dictionary.
3136 Flag values are translated accordig to the prefix found,
3137 and added to the following construction variables:
3140 -arch CCFLAGS, LINKFLAGS
3142 -framework FRAMEWORKS
3143 -frameworkdir= FRAMEWORKPATH
3145 -isysroot CCFLAGS, LINKFLAGS
3149 -mno-cygwin CCFLAGS, LINKFLAGS
3151 -pthread CCFLAGS, LINKFLAGS
3153 -Wa, ASFLAGS, CCFLAGS
3160 + CCFLAGS, LINKFLAGS
3163 Any other strings not associated with options
3164 are assumed to be the names of libraries
3167 construction variable.
3169 Examples (all of which produce the same result):
3172 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3173 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3174 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3175 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3178 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3181 A factory function that
3182 returns a Builder object
3183 to be used to fetch source files
3184 from the Perforce source code management system.
3185 The returned Builder
3186 is intended to be passed to the
3191 env.SourceCode('.', env.Perforce())
3194 Perforce uses a number of external
3195 environment variables for its operation.
3196 Consequently, this function adds the
3197 following variables from the user's external environment
3198 to the construction environment's
3211 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3213 .RI Platform( string )
3214 Returns a callable object
3215 that can be used to initialize
3216 a construction environment using the
3217 platform keyword of the Environment() method:
3220 env = Environment(platform = Platform('win32'))
3223 .RI env.Platform( string )
3224 Applies the callable object for the specified platform
3226 to the environment through which the method was called.
3229 env.Platform('posix')
3238 variables from the user's external environment
3239 to the construction environment's
3242 This is so that any executed commands
3243 that use sockets to connect with other systems
3244 (such as fetching source files from
3245 external CVS repository specifications like
3246 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3247 will work on Windows systems.
3249 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3251 .RI Precious( target ", ...)"
3253 .RI env.Precious( target ", ...)"
3256 as precious so it is not deleted before it is rebuilt. Normally
3258 deletes a target before building it.
3259 Multiple targets can be passed in to a single call to
3262 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3264 .RI env.Prepend( key = val ", [...])"
3265 Appends the specified keyword arguments
3266 to the beginning of construction variables in the environment.
3267 If the Environment does not have
3268 the specified construction variable,
3269 it is simply added to the environment.
3270 If the values of the construction variable
3271 and the keyword argument are the same type,
3272 then the two values will be simply added together.
3273 Otherwise, the construction variable
3274 and the value of the keyword argument
3275 are both coerced to lists,
3276 and the lists are added together.
3277 (See also the Append method, above.)
3280 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3283 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3285 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3286 This appends new path elements to the given path in the
3287 specified external environment
3291 any particular path once (leaving the first one it encounters and
3292 ignoring the rest, to preserve path order),
3293 and to help assure this,
3294 will normalize all paths (using
3297 .BR os.path.normcase ).
3298 This can also handle the
3299 case where the given old path variable is a list instead of a
3300 string, in which case a list will be returned instead of a string.
3304 print 'before:',env['ENV']['INCLUDE']
3305 include_path = '/foo/bar:/foo'
3306 env.PrependENVPath('INCLUDE', include_path)
3307 print 'after:',env['ENV']['INCLUDE']
3311 after: /foo/bar:/foo:/biz
3314 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3316 .RI env.PrependUnique( key = val ", [...])"
3317 Appends the specified keyword arguments
3318 to the beginning of construction variables in the environment.
3319 If the Environment does not have
3320 the specified construction variable,
3321 it is simply added to the environment.
3322 If the construction variable being appended to is a list,
3323 then any value(s) that already exist in the
3324 construction variable will
3326 be added again to the list.
3329 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
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.RCS())
3350 will fetch source files
3351 from RCS 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 RCS
3360 for a specific subdirectory.
3362 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3364 .RI env.Replace( key = val ", [...])"
3365 Replaces construction variables in the Environment
3366 with the specified keyword arguments.
3369 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3372 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3374 .RI Repository( directory )
3376 .RI env.Repository( directory )
3379 is a repository to be searched for files.
3383 and each one adds to the list of
3384 repositories that will be searched.
3388 a repository is a copy of the source tree,
3389 from the top-level directory on down,
3391 both source files and derived files
3392 that can be used to build targets in
3393 the local source tree.
3394 The canonical example would be an
3395 official source tree maintained by an integrator.
3396 If the repository contains derived files,
3397 then the derived files should have been built using
3399 so that the repository contains the necessary
3400 signature information to allow
3402 to figure out when it is appropriate to
3403 use the repository copy of a derived file,
3404 instead of building one locally.
3406 Note that if an up-to-date derived file
3407 already exists in a repository,
3411 make a copy in the local directory tree.
3412 In order to guarantee that a local copy
3418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3423 what variable(s) to use as the return value(s) of the current SConscript
3424 file. These variables will be returned to the "calling" SConscript file
3425 as the return value(s) of
3427 Multiple variable names should be passed to
3433 Return(["foo", "bar"])
3436 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3438 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3440 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3441 Creates a Scanner object for
3444 See the section "Scanner Objects,"
3445 below, for a complete explanation of the arguments and behavior.
3447 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3450 A factory function that
3451 returns a Builder object
3452 to be used to fetch source files
3454 The returned Builder
3455 is intended to be passed to the
3460 env.SourceCode('.', env.SCCS())
3465 will fetch source files
3466 from SCCS subdirectories automatically,
3468 as demonstrated in the above example
3469 should only be necessary if
3470 you are fetching from
3473 directory as the source files,
3474 or if you need to explicitly specify SCCS
3475 for a specific subdirectory.
3477 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3479 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3481 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3483 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3485 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3489 one or more subsidiary SConscript (configuration) files.
3490 There are two ways to call the
3494 The first way you can call
3496 is to explicitly specify one or more
3498 as the first argument.
3499 A single script may be specified as a string;
3500 multiple scripts must be specified as a list
3501 (either explicitly or as created by
3505 The second way you can call
3507 is to specify a list of (sub)directory names
3514 execute a subsidiary configuration file named
3516 in each of the specified directories.
3517 You may specify a name other than
3519 by supplying an optional
3525 argument provides a list of variable names or a dictionary of
3526 named values to export to the
3528 These variables are locally exported only to the specified
3530 and do not affect the
3531 global pool of variables used by
3535 '\"If multiple dirs are provided,
3536 '\"each script gets a fresh export.
3541 function to import the variables.
3545 argument specifies that all of the target files
3546 (for example, object files and executables)
3547 that would normally be built in the subdirectory in which
3549 resides should actually
3553 is interpreted relative to the directory
3554 of the calling SConscript file.
3558 argument specifies that the
3559 source files from which
3560 the target files should be built
3564 is interpreted relative to the directory
3565 of the calling SConscript file.
3569 will link or copy (depending on the platform)
3570 all the source files into the build directory.
3571 This behavior may be disabled by
3572 setting the optional
3575 (it is set to 1 by default),
3578 will refer directly to
3579 the source files in their source directory
3580 when building target files.
3583 is usually safe, and always more efficient
3586 but it may cause build problems in certain end-cases,
3587 such as compiling from source files that
3588 are generated by the build.)
3590 Any variables returned by
3594 will be returned by the call to
3600 SConscript('subdir/SConscript')
3601 foo = SConscript('sub/SConscript', exports='env')
3602 SConscript('dir/SConscript', exports=['env', 'variable'])
3603 SConscript('src/SConscript', build_dir='build', duplicate=0)
3604 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3605 SConscript(dirs=['sub1', 'sub2'])
3606 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3609 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3611 .RI SConscriptChdir( value )
3613 .RI env.SConscriptChdir( value )
3616 changes its working directory
3617 to the directory in which each
3618 subsidiary SConscript file lives.
3619 This behavior may be disabled
3620 by specifying either:
3624 env.SConscriptChdir(0)
3629 will stay in the top-level directory
3630 while reading all SConscript files.
3631 (This may be necessary when building from repositories,
3632 when all the directories in which SConscript files may be found
3633 don't necessarily exist locally.)
3635 You may enable and disable
3636 this ability by calling
3643 SConscript('foo/SConscript') # will not chdir to foo
3644 env.SConscriptChdir(1)
3645 SConscript('bar/SConscript') # will chdir to bar
3648 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3650 .RI SConsignFile([ file , dbm_module ])
3652 .RI env.SConsignFile([ file , dbm_module ])
3655 to store all file signatures
3656 in the specified database
3663 (The actual file name(s) stored on disk
3664 may have an appropriated suffix appended
3669 is not an absolute path name,
3670 the file is placed in the same directory as the top-level
3680 will store file signatures
3683 file in each directory,
3684 not in one global database file.
3685 (This was the default behavior
3686 prior to SCons 0.96.91 and 0.97.)
3690 argument can be used to specify
3691 which Python database module
3692 The default is to use a custom
3694 module that uses pickled
3695 Python data structures,
3696 and which works on all Python versions from 1.5.2 on.
3701 # Explicitly stores signatures in ".sconsign.dblite"
3702 # in the top-level SConstruct directory (the
3703 # default behavior).
3706 # Stores signatures in the file "etc/scons-signatures"
3707 # relative to the top-level SConstruct directory.
3708 SConsignFile("etc/scons-signatures")
3710 # Stores signatures in the specified absolute file name.
3711 SConsignFile("/home/me/SCons/signatures")
3713 # Stores signatures in a separate .sconsign file
3714 # in each directory.
3718 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3720 .RI env.SetDefault(key = val ", [...])"
3721 Sets construction variables to default values specified with the keyword
3722 arguments if (and only if) the variables are not already set.
3723 The following statements are equivalent:
3726 env.SetDefault(FOO = 'foo')
3728 if not env.has_key('FOO'): env['FOO'] = 'foo'
3731 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3733 .RI SetOption( name ", " value )
3735 .RI env.SetOption( name ", " value )
3736 This function provides a way to set a select subset of the scons command
3737 line options from a SConscript file. The options supported are:
3739 which corresponds to -c, --clean, and --remove;
3742 corresponds to --duplicate;
3744 which corresponds to --implicit-cache;
3746 which corresponds to --max-drift;
3748 which corresponds to -j and --jobs.
3749 See the documentation for the
3750 corresponding command line object for information about each specific
3754 SetOption('max_drift', 1)
3757 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3759 .RI SideEffect( side_effect ", " target )
3761 .RI env.SideEffect( side_effect ", " target )
3764 as a side effect of building
3770 can be a list, a file name, or a node.
3771 A side effect is a target that is created
3772 as a side effect of building other targets.
3773 For example, a Windows PDB
3774 file is created as a side effect of building the .obj
3775 files for a static library.
3776 If a target is a side effect of multiple build commands,
3778 will ensure that only one set of commands
3779 is executed at a time.
3780 Consequently, you only need to use this method
3781 for side-effect targets that are built as a result of
3782 multiple build commands.
3784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3786 .RI SourceCode( entries ", " builder )
3788 .RI env.SourceCode( entries ", " builder )
3789 Arrange for non-existent source files to
3790 be fetched from a source code management system
3795 may be a Node, string or list of both,
3796 and may represent either individual
3797 source files or directories in which
3798 source files can be found.
3800 For any non-existent source files,
3802 will search up the directory tree
3812 will not use a builder to fetch
3813 source files for the specified
3817 builder has been specified
3818 for a directory higher up the tree.
3822 fetch files from SCCS or RCS subdirectories
3823 without explicit configuration.
3824 This takes some extra processing time
3825 to search for the necessary
3826 source code management files on disk.
3827 You can avoid these extra searches
3828 and speed up your build a little
3829 by disabling these searches as follows:
3832 env.SourceCode('.', None)
3836 Note that if the specified
3838 is one you create by hand,
3839 it must have an associated
3840 construction environment to use
3841 when fetching a source file.
3844 provides a set of canned factory
3845 functions that return appropriate
3846 Builders for various popular
3847 source code management systems.
3848 Canonical examples of invocation include:
3851 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3852 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3853 env.SourceCode('/', env.RCS())
3854 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3855 env.SourceCode('no_source.c', None)
3857 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3859 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3861 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
3862 Performs construction variable interpolation
3863 on the specified string argument.
3866 leading or trailing white space will
3867 be removed from the result.
3868 and all sequences of white space
3869 will be compressed to a single space character.
3874 character sequences will be stripped from the returned string,
3877 argument may be set to
3879 if you want to preserve white space and
3884 argument may be set to
3886 if you want to strip
3887 all characters between
3893 (as is done for signature calculation).
3900 must be set to lists of
3901 target and source nodes, respectively,
3908 to be available for expansion.
3909 This is usually necessary if you are
3912 from within a Python function used
3916 all returned values are converted
3917 to their string representation.
3921 may specify a conversion function
3922 that will be used in place of
3924 For example, if you want Python objects
3925 (including SCons Nodes)
3926 to be returned as Python objects,
3927 you can use the Python
3929 idiom to pass in an unnamed function
3930 that simply returns its unconverted argument.
3933 print env.subst("The C compiler is: $CC")
3935 def compile(target, source, env):
3936 sourceDir = env.subst("${SOURCE.srcdir}",
3940 source_nodes = env.subst('$EXPAND_TO_NODELIST',
3944 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3946 '\".RI Subversion( repository ", " module )
3947 '\"A factory function that
3948 '\"returns a Builder object
3949 '\"to be used to fetch source files
3950 '\"from the specified Subversion
3952 '\"The returned Builder
3953 '\"is intended to be passed to the
3957 '\"The optional specified
3959 '\"will be added to the beginning
3960 '\"of all repository path names;
3961 '\"this can be used, in essence,
3962 '\"to strip initial directory names
3963 '\"from the repository path names,
3964 '\"so that you only have to
3965 '\"replicate part of the repository
3966 '\"directory hierarchy in your
3967 '\"local build directory:
3970 '\"# Will fetch foo/bar/src.c
3971 '\"# from /usr/local/Subversion/foo/bar/src.c.
3972 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3974 '\"# Will fetch bar/src.c
3975 '\"# from /usr/local/Subversion/foo/bar/src.c.
3976 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3978 '\"# Will fetch src.c
3979 '\"# from /usr/local/Subversion/foo/bar/src.c.
3980 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3983 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3985 .RI SourceSignatures( type )
3987 .RI env.SourceSignatures( type )
3988 This function tells SCons what type of signature to use for source files:
3992 If the environment method is used,
3993 the specified type of source signature
3994 is only used when deciding whether targets
3995 built with that environment are up-to-date or must be rebuilt.
3996 If the global function is used,
3997 the specified type of source signature becomes the default
3998 used for all decisions
3999 about whether targets are up-to-date.
4001 "MD5" means the signature of a source file
4002 is the MD5 checksum of its contents.
4003 "timestamp" means the signature of a source file
4004 is its timestamp (modification time).
4005 There is no different between the two behaviors
4009 "MD5" signatures take longer to compute,
4010 but are more accurate than "timestamp" signatures.
4011 The default is "MD5".
4013 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4017 .RI env.Split( arg )
4018 Returns a list of file names or other objects.
4020 it will be split on strings of white-space characters
4022 making it easier to write long lists of file names.
4023 If arg is already a list,
4024 the list will be returned untouched.
4025 If arg is any other type of object,
4026 it will be returned as a list
4027 containing just the object.
4030 files = Split("f1.c f2.c f3.c")
4031 files = env.Split("f4.c f5.c f6.c")
4039 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4041 .RI TargetSignatures( type )
4043 .RI env.TargetSignatures( type )
4044 This function tells SCons what type of signatures to use
4049 If the environment method is used,
4050 the specified type of signature is only used
4051 for targets built with that environment.
4052 If the global function is used,
4053 the specified type of signature becomes the default
4054 used for all target files that
4055 don't have an explicit target signature type
4056 specified for their environments.
4058 "build" means the signature of a target file
4059 is made by concatenating all of the
4060 signatures of all its source files.
4061 "content" means the signature of a target
4062 file is an MD5 checksum of its contents.
4063 "build" signatures are usually faster to compute,
4064 but "content" signatures can prevent unnecessary rebuilds
4065 when a target file is rebuilt to the exact same contents
4066 as the previous build.
4067 The default is "build".
4069 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4071 .RI Tool( string [, toolpath ", " **kw ])
4072 Returns a callable object
4073 that can be used to initialize
4074 a construction environment using the
4075 tools keyword of the Environment() method.
4076 The object may be called with a construction
4077 environment as an argument,
4078 in which case the object will
4079 add the necessary variables
4080 to the construction environment
4081 and the name of the tool will be added to the
4083 construction variable.
4085 Additional keyword arguments are passed to the tool's
4090 env = Environment(tools = [ Tool('msvc') ])
4094 t(env) # adds 'msvc' to the TOOLS variable
4095 u = Tool('opengl', toolpath = ['tools'])
4096 u(env) # adds 'opengl' to the TOOLS variable
4099 .RI env.Tool( string [, toolpath ", " **kw ])
4100 Applies the callable object for the specified tool
4102 to the environment through which the method was called.
4104 Additional keyword arguments are passed to the tool's
4110 env.Tool('opengl', toolpath = ['build/tools'])
4113 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4115 .RI Value( value ", [" built_value ])
4117 .RI env.Value( value ", [" built_value ])
4118 Returns a Node object representing the specified Python value. Value
4119 Nodes can be used as dependencies of targets. If the result of
4122 changes between SCons runs, any targets depending on
4124 will be rebuilt. When using timestamp source signatures, Value Nodes'
4125 timestamps are equal to the system time when the Node is created.
4127 The returned Value Node object has a
4129 method that can be used to "build" a Value Node
4130 by setting a new value.
4133 argument can be specified
4134 when the Value Node is created
4135 to indicate the Node should already be considered
4137 There is a corresponding
4139 method that will return the built value of the Node.
4142 def create(target, source, env):
4143 f = open(str(target[0]), 'wb')
4144 f.write('prefix=' + source[0].get_contents())
4146 prefix = ARGUMENTS.get('prefix', '/usr/local')
4148 env['BUILDERS']['Config'] = Builder(action = create)
4149 env.Config(target = 'package-config', source = Value(prefix))
4151 def build_value(target, source, env):
4152 target[0].write(source[0].get_contents())
4154 output = env.Value('before')
4155 input = env.Value('after')
4157 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
4158 env.UpdateValue(target = Value(output), source = Value(input))
4161 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4163 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4165 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4167 Searches for the specified executable
4169 returning the full path name to the program
4171 and returning None if not.
4172 Searches the specified
4174 the value of the calling environment's PATH
4175 (env['ENV']['PATH']),
4176 or the user's current external PATH
4177 (os.environ['PATH'])
4179 On Windows systems, searches for executable
4180 programs with any of the file extensions
4181 listed in the specified
4183 the calling environment's PATHEXT
4184 (env['ENV']['PATHEXT'])
4185 or the user's current PATHEXT
4186 (os.environ['PATHEXT'])
4194 .SS SConscript Variables
4195 In addition to the global functions and methods,
4197 supports a number of Python variables
4198 that can be used in SConscript files
4199 to affect how you want the build to be performed.
4200 These variables may be accessed from custom Python modules that you
4201 import into an SConscript file by adding the following
4202 to the Python module:
4205 from SCons.Script import *
4208 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4213 arguments specified on the command line.
4214 Each element in the list is a tuple
4216 .RI ( keyword , value )
4222 elements of the tuple
4224 subscripting for element
4228 of the tuple, respectively.
4231 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4232 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4233 third_tuple = ARGLIST[2]
4234 print "third keyword, value =", third_tuple[0], third_tuple[1]
4235 for key, value in ARGLIST:
4236 # process key and value
4239 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4242 A dictionary of all the
4244 arguments specified on the command line.
4245 The dictionary is not in order,
4246 and if a given keyword has
4247 more than one value assigned to it
4248 on the command line,
4249 the last (right-most) value is
4255 if ARGUMENTS.get('debug', 0):
4256 env = Environment(CCFLAGS = '-g')
4261 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4264 A list of the targets which
4266 will actually try to build,
4267 regardless of whether they were specified on
4268 the command line or via the
4271 The elements of this list may be strings
4273 nodes, so you should run the list through the Python
4275 function to make sure any Node path names
4276 are converted to strings.
4278 Because this list may be taken from the
4279 list of targets specified using the
4282 the contents of the list may change
4283 on each successive call to
4288 for additional information.
4291 if 'foo' in BUILD_TARGETS:
4292 print "Don't forget to test the `foo' program!"
4293 if 'special/program' in BUILD_TARGETS:
4294 SConscript('special')
4299 list only contains targets expected listed
4300 on the command line or via calls to the
4305 contain all dependent targets that will be built as
4306 a result of making the sure the explicitly-specified
4307 targets are up to date.
4309 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4311 COMMAND_LINE_TARGETS
4312 A list of the targets explicitly specified on
4314 If there are no targets specified on the command line,
4316 This can be used, for example,
4317 to take specific actions only
4318 when a certain target or targets
4319 is explicitly being built:
4322 if 'foo' in COMMAND_LINE_TARGETS:
4323 print "Don't forget to test the `foo' program!"
4324 if 'special/program' in COMMAND_LINE_TARGETS:
4325 SConscript('special')
4328 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4331 A list of the target
4333 that have been specified using the
4336 The elements of the list are nodes,
4337 so you need to run them through the Python
4339 function to get at the path name for each Node.
4342 print str(DEFAULT_TARGETS[0])
4343 if 'foo' in map(str, DEFAULT_TARGETS):
4344 print "Don't forget to test the `foo' program!"
4349 list change on on each successive call to the
4354 print map(str, DEFAULT_TARGETS) # originally []
4356 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4358 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4360 print map(str, DEFAULT_TARGETS) # back to []
4363 Consequently, be sure to use
4365 only after you've made all of your
4368 or else simply be careful of the order
4369 of these statements in your SConscript files
4370 so that you don't look for a specific
4371 default target before it's actually been added to the list.
4373 .SS Construction Variables
4374 .\" XXX From Gary Ruben, 23 April 2002:
4375 .\" I think it would be good to have an example with each construction
4376 .\" variable description in the documentation.
4378 .\" CC The C compiler
4379 .\" Example: env["CC"] = "c68x"
4380 .\" Default: env["CC"] = "cc"
4382 .\" CCCOM The command line ...
4384 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4385 .\" env["CC"] = "c68x"
4386 .\" env["CFLAGS"] = "-ps -qq -mr"
4387 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4389 .\" (I dunno what this is ;-)
4390 A construction environment has an associated dictionary of
4391 .I construction variables
4392 that are used by built-in or user-supplied build rules.
4393 Construction variables must follow the same rules for
4395 the initial character must be an underscore or letter,
4396 followed by any number of underscores, letters, or digits.
4398 A number of useful construction variables are automatically defined by
4399 scons for each supported platform, and additional construction variables
4400 can be defined by the user. The following is a list of the automatically
4401 defined construction variables:
4403 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4404 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4406 '\" The descriptions below of the various SCons contruction variables
4407 '\" are generated from the .xml files that live next to the various
4408 '\" Python modules in the build enginer library. If you're reading
4409 '\" this [gnt]roff file with an eye towards patching this man page,
4410 '\" you can still submit a diff against this text, but it will have to
4411 '\" be translated to a diff against the underlying .xml file before the
4412 '\" patch is actually accepted. If you do that yourself, it will make
4413 '\" it easier to integrate the patch.
4415 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4416 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4419 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4421 '\" The descriptions above of the various SCons contruction variables
4422 '\" are generated from the .xml files that live next to the various
4423 '\" Python modules in the build enginer library. If you're reading
4424 '\" this [gnt]roff file with an eye towards patching this man page,
4425 '\" you can still submit a diff against this text, but it will have to
4426 '\" be translated to a diff against the underlying .xml file before the
4427 '\" patch is actually accepted. If you do that yourself, it will make
4428 '\" it easier to integrate the patch.
4430 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
4431 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4434 Construction variables can be retrieved and set using the
4436 method of the construction environment:
4439 dict = env.Dictionary()
4443 or using the [] operator:
4449 Construction variables can also be passed to the construction environment
4453 env = Environment(CC="cc")
4456 or when copying a construction environment using the
4461 env2 = env.Clone(CC="cl.exe")
4464 .SS Configure Contexts
4468 .I configure contexts,
4469 an integrated mechanism similar to the
4470 various AC_CHECK macros in GNU autoconf
4471 for testing for the existence of C header
4472 files, libraries, etc.
4473 In contrast to autoconf,
4475 does not maintain an explicit cache of the tested values,
4476 but uses its normal dependency tracking to keep the checked values
4477 up to date. However, users may override this behaviour with the
4479 command line option.
4481 The following methods can be used to perform checks:
4484 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
4486 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
4487 This creates a configure context, which can be used to perform checks.
4489 specifies the environment for building the tests.
4490 This environment may be modified when performing checks.
4492 is a dictionary containing custom tests.
4493 See also the section about custom tests below.
4494 By default, no custom tests are added to the configure context.
4496 specifies a directory where the test cases are built.
4497 Note that this directory is not used for building
4499 The default value is the directory
4502 specifies a file which collects the output from commands
4503 that are executed to check for the existence of header files, libraries, etc.
4504 The default is the file #/config.log.
4505 If you are using the
4508 you may want to specify a subdirectory under your build directory.
4510 specifies a C header file where the results of tests
4511 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
4512 The default is to not write a
4515 You can specify the same
4517 file in multiple calls to Configure,
4520 will concatenate all results in the specified file.
4522 uses its normal dependency checking
4523 to decide if it's necessary to rebuild
4527 This means that the file is not necessarily re-built each
4529 but is only rebuilt if its contents will have changed
4530 and some target that depends on the
4532 file is being built.
4537 instance has the following associated methods:
4540 .RI Configure.Finish( self )
4541 This method should be called after configuration is done.
4542 It returns the environment as modified
4543 by the configuration checks performed.
4544 After this method is called, no further checks can be performed
4545 with this configuration context.
4546 However, you can create a new
4548 context to perform additional checks.
4549 Only one context should be active at a time.
4551 The following Checks are predefined.
4552 (This list will likely grow larger as time
4553 goes by and developers contribute new useful tests.)
4556 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
4559 is usable in the specified language.
4562 in which case the last item in the list
4563 is the header file to be checked,
4564 and the previous list items are
4567 lines should precede the
4568 header line being checked for.
4569 The optional argument
4572 a two character string, where the first character denotes the opening
4573 quote and the second character denotes the closing quote.
4574 By default, both characters are " (double quote).
4575 The optional argument
4581 and selects the compiler to be used for the check.
4582 Returns 1 on success and 0 on failure.
4585 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
4586 This is a wrapper around
4587 .B Configure.CheckHeader
4590 is usable in the C language.
4593 in which case the last item in the list
4594 is the header file to be checked,
4595 and the previous list items are
4598 lines should precede the
4599 header line being checked for.
4600 The optional argument
4603 a two character string, where the first character denotes the opening
4604 quote and the second character denotes the closing quote (both default
4606 Returns 1 on success and 0 on failure.
4609 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
4610 This is a wrapper around
4611 .B Configure.CheckHeader
4614 is usable in the C++ language.
4617 in which case the last item in the list
4618 is the header file to be checked,
4619 and the previous list items are
4622 lines should precede the
4623 header line being checked for.
4624 The optional argument
4627 a two character string, where the first character denotes the opening
4628 quote and the second character denotes the closing quote (both default
4630 Returns 1 on success and 0 on failure.
4633 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
4634 Checks if the specified
4635 C or C++ function is available.
4637 is the name of the function to check for.
4640 argument is a string
4644 that will be compiled
4645 to check if the function exists;
4651 char function_name();
4659 and selects the compiler to be used for the check;
4663 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
4670 is 1 and the library provides the specified
4672 appends the library to the LIBS construction environment variable.
4674 may also be None (the default),
4677 is checked with the current LIBS variable,
4678 or a list of library names,
4679 in which case each library in the list
4687 .BR Configure.CheckLib ()
4689 you can link against the specified
4697 and selects the compiler to be used for the check;
4699 The default value for
4702 This method returns 1 on success and 0 on error.
4705 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
4708 .RI Configure.CheckLib
4709 call, this call provides a more sophisticated way to check against libraries.
4712 specifies the library or a list of libraries to check.
4714 specifies a header to check for.
4717 in which case the last item in the list
4718 is the header file to be checked,
4719 and the previous list items are
4722 lines should precede the
4723 header line being checked for.
4725 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
4727 can be any valid expression (with a trailing ';').
4731 the default simply checks that you
4732 can link against the specified
4735 specifies whether to add the library to the environment (only if the check
4736 succeeds). This method returns 1 on success and 0 on error.
4739 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
4740 Checks for the existence of a type defined by
4743 specifies the typedef name to check for.
4745 is a string containing one or more
4747 lines that will be inserted into the program
4748 that will be run to test for the existence of the type.
4755 and selects the compiler to be used for the check;
4759 Example of a typical Configure usage:
4763 conf = Configure( env )
4764 if not conf.CheckCHeader( 'math.h' ):
4765 print 'We really need math.h!'
4767 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
4768 # do stuff for qt - usage, e.g.
4769 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
4774 You can define your own custom checks.
4775 in addition to the predefined checks.
4776 These are passed in a dictionary to the Configure function.
4777 This dictionary maps the names of the checks
4778 to user defined Python callables
4779 (either Python functions or class instances implementing the
4782 The first argument of the call is always a
4784 instance followed by the arguments,
4785 which must be supplied by the user of the check.
4786 These CheckContext instances define the following methods:
4789 .RI CheckContext.Message( self ", " text )
4791 Usually called before the check is started.
4793 will be displayed to the user, e.g. 'Checking for library X...'
4796 .RI CheckContext.Result( self, ", " res )
4798 Usually called after the check is done.
4800 can be either an integer or a string. In the former case, 'ok' (res != 0)
4801 or 'failed' (res == 0) is displayed to the user, in the latter case the
4802 given string is displayed.
4805 .RI CheckContext.TryCompile( self ", " text ", " extension )
4806 Checks if a file with the specified
4808 (e.g. '.c') containing
4810 can be compiled using the environment's
4812 builder. Returns 1 on success and 0 on failure.
4815 .RI CheckContext.TryLink( self ", " text ", " extension )
4816 Checks, if a file with the specified
4818 (e.g. '.c') containing
4820 can be compiled using the environment's
4822 builder. Returns 1 on success and 0 on failure.
4825 .RI CheckContext.TryRun( self ", " text ", " extension )
4826 Checks, if a file with the specified
4828 (e.g. '.c') containing
4830 can be compiled using the environment's
4832 builder. On success, the program is run. If the program
4833 executes successfully
4834 (that is, its return status is 0),
4839 is the standard output of the
4841 If the program fails execution
4842 (its return status is non-zero),
4843 then (0, '') is returned.
4846 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
4847 Checks if the specified
4849 with an optional source file (contents
4856 may be anything which can be converted to a
4863 is the content of the target file.
4869 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
4870 Low level implementation for testing specific builds;
4871 the methods above are based on this method.
4872 Given the Builder instance
4876 of a source file with optional
4878 this method returns 1 on success and 0 on failure. In addition,
4880 is set to the build target node, if the build was successful.
4883 Example for implementing and using custom tests:
4886 def CheckQt(context, qtdir):
4887 context.Message( 'Checking for qt ...' )
4888 lastLIBS = context.env['LIBS']
4889 lastLIBPATH = context.env['LIBPATH']
4890 lastCPPPATH= context.env['CPPPATH']
4891 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
4892 ret = context.TryLink("""
4894 int main(int argc, char **argv) {
4895 QApplication qapp(argc, argv);
4900 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
4901 context.Result( ret )
4905 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
4906 if not conf.CheckQt('/usr/lib/qt'):
4907 print 'We really need qt!'
4912 .SS Construction Variable Options
4914 Often when building software, various options need to be specified at build
4915 time that are not known when the SConstruct/SConscript files are
4916 written. For example, libraries needed for the build may be in non-standard
4917 locations, or site-specific compiler options may need to be passed to the
4920 provides a mechanism for overridding construction variables from the
4921 command line or a text-based SConscript file through an Options
4922 object. To create an Options object, call the Options() function:
4925 .RI Options([ files "], [" args ])
4926 This creates an Options object that will read construction variables from
4927 the file or list of filenames specified in
4929 If no files are specified,
4934 then no files will be read.
4935 The optional argument
4938 values that will override anything read from the specified files;
4939 it is primarily intended to be passed the
4941 dictionary that holds variables
4942 specified on the command line.
4946 opts = Options('custom.py')
4947 opts = Options('overrides.py', ARGUMENTS)
4948 opts = Options(None, {FOO:'expansion', BAR:7})
4951 Options objects have the following methods:
4954 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
4955 This adds a customizable construction variable to the Options object.
4957 is the name of the variable.
4959 is the help text for the variable.
4961 is the default value of the variable;
4962 if the default value is
4964 and there is no explicit value specified,
4965 the construction variable will
4967 be added to the construction environment.
4969 is called to validate the value of the variable, and should take three
4970 arguments: key, value, and environment.
4971 The recommended way to handle an invalid value is
4972 to raise an exception (see example below).
4974 is called to convert the value before putting it in the environment, and
4975 should take either a value, or the value and environment, as parameters.
4978 must return a value,
4979 which will be converted into a string
4980 before being validated by the
4983 and then added to the environment.
4988 opts.Add('CC', 'The C compiler')
4990 def validate_color(key, val, env):
4991 if not val in ['red', 'blue', 'yellow']:
4992 raise "Invalid color value '%s'" % val
4993 opts.Add('COLOR', validator=valid_color)
4997 .RI AddOptions( list )
4998 A wrapper script that adds
4999 multiple customizable construction variables
5000 to an Options object.
5002 is a list of tuple or list objects
5003 that contain the arguments
5004 for an individual call to the
5011 ('CC', 'The C compiler'),
5012 ('VALIDATE', 'An option for testing validation',
5013 'notset', validator, None),
5018 .RI Update( env ", [" args ])
5019 This updates a construction environment
5021 with the customized construction variables. Normally this method is not
5022 called directly, but is called indirectly by passing the Options object to
5023 the Environment() function:
5026 env = Environment(options=opts)
5030 The text file(s) that were specified
5031 when the Options object was created
5032 are executed as Python scripts,
5033 and the values of (global) Python variables set in the file
5034 are added to the construction environment.
5042 .RI Save( filename ", " env )
5043 This saves the currently set options into a script file named
5045 that can be used on the next invocation to automatically load the current
5046 settings. This method combined with the Options method can be used to
5047 support caching of options between runs.
5051 opts = Options(['options.cache', 'custom.py'])
5054 opts.Save('options.cache', env)
5058 .RI GenerateHelpText( env ", [" sort ])
5059 This generates help text documenting the customizable construction
5060 variables suitable to passing in to the Help() function.
5062 is the construction environment that will be used to get the actual values
5063 of customizable variables. Calling with
5067 will cause the output to be sorted
5068 by the specified argument.
5072 should take two arguments
5075 (like the standard Python
5080 Help(opts.GenerateHelpText(env))
5081 Help(opts.GenerateHelpText(env, sort=cmp))
5085 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
5086 This method returns a formatted string
5087 containing the printable help text
5089 It is normally not called directly,
5090 but is called by the
5091 .IR GenerateHelpText ()
5092 method to create the returned help text.
5093 It may be overridden with your own
5094 function that takes the arguments specified above
5095 and returns a string of help text formatted to your liking.
5097 .IR GenerateHelpText ()
5098 will not put any blank lines or extra
5099 characters in between the entries,
5100 so you must add those characters to the returned
5101 string if you want the entries separated.
5104 def my_format(env, opt, help, default, actual):
5105 fmt = "\n%s: default=%s actual=%s (%s)\n"
5106 return fmt % (opt, default. actual, help)
5107 opts.FormatOptionHelpText = my_format
5110 To make it more convenient to work with customizable Options,
5112 provides a number of functions
5113 that make it easy to set up
5114 various types of Options:
5117 .RI BoolOption( key ", " help ", " default )
5118 Return a tuple of arguments
5119 to set up a Boolean option.
5123 have a default value of
5125 and display the specified
5128 The option will interpret the values
5150 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
5151 Return a tuple of arguments
5153 whose value may be one
5154 of a specified list of legal enumerated values.
5158 have a default value of
5160 and display the specified
5163 The option will only support those
5169 argument is a dictionary
5170 that can be used to convert
5171 input values into specific legal values
5180 then the values are case-sensitive.
5185 then values will be matched
5191 then values will be matched
5193 and all input values will be
5194 converted to lower case.
5197 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
5198 Return a tuple of arguments
5200 whose value may be one or more
5201 of a specified list of legal enumerated values.
5205 have a default value of
5207 and display the specified
5210 The option will only support the values
5213 or the values in the
5216 More than one value may be specified,
5217 with all values separated by commas.
5218 The default may be a string of
5219 comma-separated default values,
5220 or a list of the default values.
5223 argument is a dictionary
5224 that can be used to convert
5225 input values into specific legal values
5231 .RI PackageOption( key ", " help ", " default )
5232 Return a tuple of arguments
5234 whose value is a path name
5235 of a package that may be
5236 enabled, disabled or
5237 given an explicit path name.
5241 have a default value of
5243 and display the specified
5246 The option will support the values
5253 in which case the specified
5256 or the option may be set to an
5258 (typically the path name to a package
5259 that is being enabled).
5260 The option will also support the values
5266 to disable use of the specified option.
5269 .RI PathOption( key ", " help ", " default ", [" validator ])
5270 Return a tuple of arguments
5272 whose value is expected to be a path name.
5276 have a default value of
5278 and display the specified
5284 that will be called to
5285 verify that the specified path
5288 following ready-made validators:
5289 .BR PathOption.PathExists
5291 which verifies that the specified path exists;
5292 .BR PathOption.PathIsFile ,
5293 which verifies that the specified path is an existing file;
5294 .BR PathOption.PathIsDir ,
5295 which verifies that the specified path is an existing directory;
5297 .BR PathOption.PathIsDirCreate ,
5298 which verifies that the specified path is a directory,
5299 and will create the specified directory if the path does not exist.
5300 You may supply your own
5303 which must take three arguments
5305 the name of the options variable to be set;
5307 the specified value being checked;
5310 the construction environment)
5311 and should raise an exception
5312 if the specified value is not acceptable.
5315 These functions make it
5316 convenient to create a number
5317 of options with consistent behavior
5318 in a single call to the
5324 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
5325 EnumOption('debug', 'debug output and symbols', 'no'
5326 allowed_values=('yes', 'no', 'full'),
5327 map={}, ignorecase=0), # case sensitive
5328 ListOption('shared',
5329 'libraries to build as shared libraries',
5331 names = list_of_libs),
5332 PackageOption('x11',
5333 'use X11 installed here (yes = search some places)',
5335 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
5336 PathOption('foopath', 'where the foo library is installed', foopath,
5337 PathOption.PathIsDir),
5342 .SS File and Directory Nodes
5352 Nodes, respectively.
5353 python objects, respectively.
5354 Those objects have several user-visible attributes
5355 and methods that are often useful:
5361 This path is relative to the top-level directory
5365 The build path is the same as the source path if
5370 The absolute build path of the given file or directory.
5380 object representing the
5389 # Get the current build dir's path, relative to top.
5391 # Current dir's absolute path
5393 # Next line is always '.', because it is the top dir's path relative to itself.
5395 File('foo.c').srcnode().path # source path of the given source file.
5397 # Builders also return File objects:
5398 foo = env.Program('foo.c')
5399 print "foo will be built in %s"%foo.path
5405 can be extended to build different types of targets
5406 by adding new Builder objects
5407 to a construction environment.
5409 you should only need to add a new Builder object
5410 when you want to build a new type of file or other external target.
5411 If you just want to invoke a different compiler or other tool
5412 to build a Program, Object, Library, or any other
5413 type of output file for which
5415 already has an existing Builder,
5416 it is generally much easier to
5417 use those existing Builders
5418 in a construction environment
5419 that sets the appropriate construction variables
5422 Builder objects are created
5428 function accepts the following arguments:
5431 The command line string used to build the target from the source.
5434 a list of strings representing the command
5435 to be executed and its arguments
5436 (suitable for enclosing white space in an argument),
5438 mapping source file name suffixes to
5439 any combination of command line strings
5440 (if the builder should accept multiple source file extensions),
5443 (see the next section);
5444 or a list of any of the above.
5447 takes three arguments:
5449 - a list of source nodes,
5451 - a list of target nodes,
5453 - the construction environment.
5456 The prefix that will be prepended to the target file name.
5457 This may be specified as a:
5467 - a function or other callable that takes
5468 two arguments (a construction environment and a list of sources)
5469 and returns a prefix,
5474 - specifies a mapping from a specific source suffix (of the first
5475 source specified) to a corresponding target prefix. Both the source
5476 suffix and target prefix specifications may use environment variable
5477 substitution, and the target prefix (the 'value' entries in the
5478 dictionary) may also be a callable object. The default target prefix
5479 may be indicated by a dictionary entry with a key value of None.
5484 b = Builder("build_it < $SOURCE > $TARGET"
5487 def gen_prefix(env, sources):
5488 return "file-" + env['PLATFORM'] + '-'
5489 b = Builder("build_it < $SOURCE > $TARGET",
5490 prefix = gen_prefix)
5492 b = Builder("build_it < $SOURCE > $TARGET",
5493 suffix = { None: "file-",
5494 "$SRC_SFX_A": gen_prefix })
5498 The suffix that will be appended to the target file name.
5499 This may be specified in the same manner as the prefix above.
5500 If the suffix is a string, then
5502 will append a '.' to the beginning of the suffix if it's not already
5503 there. The string returned by callable object (or obtained from the
5504 dictionary) is untouched and must append its own '.' to the beginning
5508 b = Builder("build_it < $SOURCE > $TARGET"
5511 def gen_suffix(env, sources):
5512 return "." + env['PLATFORM'] + "-file"
5513 b = Builder("build_it < $SOURCE > $TARGET",
5514 suffix = gen_suffix)
5516 b = Builder("build_it < $SOURCE > $TARGET",
5517 suffix = { None: ".sfx1",
5518 "$SRC_SFX_A": gen_suffix })
5522 The expected source file name suffix. This may be a string or a list
5526 A Scanner object that
5527 will be invoked to find
5528 implicit dependencies for this target file.
5529 This keyword argument should be used
5530 for Scanner objects that find
5531 implicit dependencies
5532 based only on the target file
5533 and the construction environment,
5536 (See the section "Scanner Objects," below,
5537 for information about creating Scanner objects.)
5540 A Scanner object that
5542 find implicit dependences in
5544 used to build this target file.
5545 This is where you would
5546 specify a scanner to
5549 lines in source files.
5552 Scanner object may be used to
5553 indicate that this Builder
5554 should scan directory trees
5555 for on-disk changes to files
5558 does not know about from other Builder or function calls.
5559 (See the section "Scanner Objects," below,
5560 for information about creating your own Scanner objects.)
5563 A factory function that the Builder will use
5564 to turn any targets specified as strings into SCons Nodes.
5566 SCons assumes that all targets are files.
5567 Other useful target_factory
5570 for when a Builder creates a directory target,
5573 for when a Builder can create either a file
5574 or directory target.
5579 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
5581 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
5582 env.MakeDirectory('new_directory', [])
5585 Note that the call to the MakeDirectory Builder
5586 needs to specify an empty source list
5587 to make the string represent the builder's target;
5588 without that, it would assume the argument is the source,
5589 and would try to deduce the target name from it,
5590 which in the absence of an automatically-added prefix or suffix
5591 would lead to a matching target and source name
5592 and a circular dependency.
5595 A factory function that the Builder will use
5596 to turn any sources specified as strings into SCons Nodes.
5598 SCons assumes that all source are files.
5599 Other useful source_factory
5602 for when a Builder uses a directory as a source,
5605 for when a Builder can use files
5606 or directories (or both) as sources.
5611 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
5613 env.Append(BUILDERS = {'Collect':CollectBuilder})
5614 env.Collect('archive', ['directory_name', 'file_name'])
5618 A function or list of functions to manipulate the target and source
5619 lists before dependencies are established
5620 and the target(s) are actually built.
5622 can also be a string containing a construction variable to expand
5623 to an emitter function or list of functions,
5624 or a dictionary mapping source file suffixes
5625 to emitter functions.
5626 (Only the suffix of the first source file
5627 is used to select the actual emitter function
5628 from an emitter dictionary.)
5631 takes three arguments:
5633 - a list of source nodes,
5635 - a list of target nodes,
5637 - the construction environment.
5638 An emitter must return a tuple containing two lists,
5639 the list of targets to be built by this builder,
5640 and the list of sources for this builder.
5645 def e(target, source, env):
5646 return (target + ['foo.foo'], source + ['foo.src'])
5648 # Simple association of an emitter function with a Builder.
5649 b = Builder("my_build < $TARGET > $SOURCE",
5652 def e2(target, source, env):
5653 return (target + ['bar.foo'], source + ['bar.src'])
5655 # Simple association of a list of emitter functions with a Builder.
5656 b = Builder("my_build < $TARGET > $SOURCE",
5659 # Calling an emitter function through a construction variable.
5660 env = Environment(MY_EMITTER = e)
5661 b = Builder("my_build < $TARGET > $SOURCE",
5662 emitter = '$MY_EMITTER')
5664 # Calling a list of emitter functions through a construction variable.
5665 env = Environment(EMITTER_LIST = [e, e2])
5666 b = Builder("my_build < $TARGET > $SOURCE",
5667 emitter = '$EMITTER_LIST')
5669 # Associating multiple emitters with different file
5670 # suffixes using a dictionary.
5671 def e_suf1(target, source, env):
5672 return (target + ['another_target_file'], source)
5673 def e_suf2(target, source, env):
5674 return (target, source + ['another_source_file'])
5675 b = Builder("my_build < $TARGET > $SOURCE",
5676 emitter = {'.suf1' : e_suf1,
5681 Specifies whether this builder is allowed to be called multiple times for
5682 the same target file(s). The default is 0, which means the builder
5683 can not be called multiple times for the same target file(s). Calling a
5684 builder multiple times for the same target simply adds additional source
5685 files to the target; it is not allowed to change the environment associated
5686 with the target, specify addition environment overrides, or associate a different
5687 builder with the target.
5690 A construction environment that can be used
5691 to fetch source code using this Builder.
5692 (Note that this environment is
5694 used for normal builds of normal target files,
5695 which use the environment that was
5696 used to call the Builder for the target file.)
5699 A function that returns a list of actions that will be executed to build
5700 the target(s) from the source(s).
5701 The returned action(s) may be
5702 an Action object, or anything that
5703 can be converted into an Action object
5704 (see the next section).
5706 The generator function
5707 takes four arguments:
5709 - a list of source nodes,
5711 - a list of target nodes,
5713 - the construction environment,
5715 - a Boolean value that specifies
5716 whether the generator is being called
5717 for generating a build signature
5718 (as opposed to actually executing the command).
5722 def g(source, target, env, for_signature):
5723 return [["gcc", "-c", "-o"] + target + source]
5725 b = Builder(generator=g)
5733 arguments must not both be used for the same Builder.
5736 Specifies a builder to use when a source file name suffix does not match
5737 any of the suffixes of the builder. Using this argument produces a
5738 multi-stage builder.
5741 Specifies that this builder expects exactly one source file per call. Giving
5742 more than one source files without target files results in implicitely calling
5743 the builder multiple times (once for each source given). Giving multiple
5744 source files together with target files results in a UserError exception.
5752 arguments must not both be used for the same Builder.
5754 .IP source_ext_match
5757 argument is a dictionary,
5758 the default behavior when a builder is passed
5759 multiple source files is to make sure that the
5760 extensions of all the source files match.
5761 If it is legal for this builder to be
5762 called with a list of source files with different extensions,
5763 this check can be suppressed by setting
5767 or some other non-true value.
5772 will use the suffix of the first specified
5773 source file to select the appropriate action from the
5777 In the following example,
5782 from exiting with an error
5783 due to the mismatched suffixes of
5789 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
5790 source_ext_match = None)
5792 env = Environment(BUILDERS = {'MyBuild':b})
5793 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
5797 A construction environment that can be used
5798 to fetch source code using this Builder.
5799 (Note that this environment is
5801 used for normal builds of normal target files,
5802 which use the environment that was
5803 used to call the Builder for the target file.)
5806 b = Builder(action="build < $SOURCE > $TARGET")
5807 env = Environment(BUILDERS = {'MyBuild' : b})
5808 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
5812 A directory from which scons
5819 a string or a directory Node,
5820 scons will change to the specified directory.
5823 is not a string or Node
5825 then scons will change to the
5826 target file's directory.
5828 Note that scons will
5830 automatically modify
5832 construction variables like
5836 when using the chdir
5837 keyword argument--that is,
5838 the expanded file names
5839 will still be relative to
5840 the top-level SConstruct directory,
5841 and consequently incorrect
5842 relative to the chdir directory.
5843 Builders created using chdir keyword argument,
5844 will need to use construction variable
5849 to use just the filename portion of the
5853 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
5855 env = Environment(BUILDERS = {'MyBuild' : b})
5856 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
5860 Python only keeps one current directory
5861 location for all of the threads.
5862 This means that use of the
5870 because individual worker threads spawned
5871 by SCons interfere with each other
5872 when they start changing directory.
5875 Any additional keyword arguments supplied
5876 when a Builder object is created
5877 (that is, when the Builder() function is called)
5878 will be set in the executing construction
5879 environment when the Builder object is called.
5880 The canonical example here would be
5881 to set a construction variable to
5882 the repository of a source code system.
5884 Any additional keyword arguments supplied
5888 will only be associated with the target
5889 created by that particular Builder call
5890 (and any other files built as a
5891 result of the call).
5893 These extra keyword arguments are passed to the
5894 following functions:
5895 command generator functions,
5897 and emitter functions.
5903 function will turn its
5905 keyword argument into an appropriate
5906 internal Action object.
5907 You can also explicity create Action objects
5911 which can then be passed to the
5914 This can be used to configure
5915 an Action object more flexibly,
5916 or it may simply be more efficient
5917 than letting each separate Builder object
5918 create a separate Action
5920 Builder objects need to do the same thing.
5925 returns an appropriate object for the action
5926 represented by the type of the first argument:
5929 If the first argument is already an Action object,
5930 the object is simply returned.
5933 If the first argument is a string,
5934 a command-line Action is returned.
5935 Note that the command line string
5936 may be preceded by an
5939 to suppress printing of the
5940 specified command line,
5944 to ignore the exit status from
5945 the specified command.
5949 Action('$CC -c -o $TARGET $SOURCES')
5951 # Doesn't print the line being executed.
5952 Action('@build $TARGET $SOURCES')
5955 Action('-build $TARGET $SOURCES')
5958 .\" XXX From Gary Ruben, 23 April 2002:
5959 .\" What would be useful is a discussion of how you execute command
5960 .\" shell commands ie. what is the process used to spawn the shell, pass
5961 .\" environment variables to it etc., whether there is one shell per
5962 .\" environment or one per command etc. It might help to look at the Gnu
5963 .\" make documentation to see what they think is important to discuss about
5964 .\" a build system. I'm sure you can do a better job of organising the
5965 .\" documentation than they have :-)
5969 If the first argument is a list,
5970 then a list of Action objects is returned.
5971 An Action object is created as necessary
5972 for each element in the list.
5975 the list is itself a list,
5976 the internal list is the
5977 command and arguments to be executed via
5979 This allows white space to be enclosed
5980 in an argument by defining
5981 a command in a list within a list:
5984 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
5988 If the first argument is a Python function,
5989 a function Action is returned.
5990 The Python function takes three keyword arguments,
5992 (a Node object representing the target file),
5994 (a Node object representing the source file)
5997 (the construction environment
5998 used for building the target file).
6003 arguments may be lists of Node objects if there is
6004 more than one target file or source file.
6005 The actual target and source file name(s) may
6006 be retrieved from their Node objects
6007 via the built-in Python str() function:
6010 target_file_name = str(target)
6011 source_file_names = map(lambda x: str(x), source)
6014 The function should return
6018 to indicate a successful build of the target file(s).
6019 The function may raise an exception
6020 or return a non-zero exit status
6021 to indicate an unsuccessful build.
6024 def build_it(target = None, source = None, env = None):
6025 # build the target from the source
6028 a = Action(build_it)
6031 If the action argument is not one of the above,
6035 The second, optional argument
6036 is used to define the output which is printed
6037 when the Action is actually performed.
6038 In the absence of this parameter, or if it's an
6039 empty string, a default output depending on the type of the action
6040 is used. For example, a command-line action will print
6041 the executed command. The argument is either a python function
6044 In the first case, it's a function that returns
6045 a string to be printed to describe the action being executed.
6046 Like a function to build a file,
6047 this function takes three arguments:
6049 (a Node object representing the target file),
6051 (a Node object representing the source file)
6054 (a construction environment).
6059 arguments may be lists of Node objects if there is
6060 more than one target file or source file.
6062 In the second case, you provide the string itself.
6063 The string typically contains variables, notably
6064 $TARGET(S) and $SOURCE(S), or consists of just a single
6065 variable, which is optionally defined somewhere else.
6066 SCons itself heavily uses the latter variant.
6071 def build_it(target, source, env):
6072 # build the target from the source
6075 def string_it(target, source, env):
6076 return "building '%s' from '%s'" % (target[0], source[0])
6078 # Use a positional argument.
6079 f = Action(build_it, string_it)
6080 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
6082 # Alternatively, use a keyword argument.
6083 f = Action(build_it, strfunction=string_it)
6084 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
6086 # You can provide a configurable variable.
6087 l = Action(build_it, '$STRINGIT')
6090 The third, also optional argument
6091 is a list of construction variables
6092 whose values will be included
6093 in the signature of the Action
6094 when deciding whether a target should
6095 be rebuilt because the action changed.
6096 This is necessary whenever you want a target to
6097 be rebuilt when a specific
6098 construction variable changes,
6099 because the underlying Python code for a function
6100 will not change when the value of the construction variable does.
6103 def build_it(target, source, env):
6104 # build the target from the 'XXX' construction variable
6105 open(target[0], 'w').write(env['XXX'])
6108 # Use positional arguments.
6109 a = Action(build_it, '$STRINGIT', ['XXX'])
6111 # Alternatively, use a keyword argument.
6112 a = Action(build_it, varlist=['XXX'])
6121 which specifies that
6122 scons will execute the action
6123 after changing to the specified directory.
6124 If the chdir argument is
6125 a string or a directory Node,
6126 scons will change to the specified directory.
6127 If the chdir argument
6128 is not a string or Node
6130 then scons will change to the
6131 target file's directory.
6133 Note that scons will
6135 automatically modify
6137 construction variables like
6141 when using the chdir
6142 keyword argument--that is,
6143 the expanded file names
6144 will still be relative to
6145 the top-level SConstruct directory,
6146 and consequently incorrect
6147 relative to the chdir directory.
6148 Builders created using chdir keyword argument,
6149 will need to use construction variable
6154 to use just the filename portion of the
6158 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6168 which specifies a function
6169 that is passed the exit status
6171 from the specified action
6172 and can return an arbitrary
6174 This can be used, for example,
6175 to specify that an Action object's
6176 return value should be ignored
6177 and SCons should, therefore,
6178 consider that the action always suceeds:
6181 def always_succeed(s):
6182 # Always return 0, which indicates success.
6184 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
6185 exitstatfunc=always_succeed)
6188 .SS Miscellaneous Action Functions
6191 supplies a number of functions
6192 that arrange for various common
6193 file and directory manipulations
6195 These are similar in concept to "tasks" in the
6197 although the implementation is slightly different.
6198 These functions do not actually
6199 perform the specified action
6200 at the time the function is called,
6201 but instead return an Action object
6202 that can be executed at the
6204 (In Object-Oriented terminology,
6209 that return Action objects.)
6212 there are two natural ways
6215 are intended to be used.
6219 to perform the action
6220 at the time the SConscript
6224 global function to do so:
6226 Execute(Touch('file'))
6230 you can use these functions
6231 to supply Actions in a list
6235 This can allow you to
6236 perform more complicated
6237 sequences of file manipulation
6239 on platform-specific
6243 env = Environment(TMPBUILD = '/tmp/builddir')
6244 env.Command('foo.out', 'foo.in',
6245 [Mkdir('$TMPBUILD'),
6246 Copy('$TMPBUILD', '${SOURCE.dir}'),
6247 "cd $TMPBUILD && make",
6248 Delete('$TMPBUILD')])
6252 .RI Chmod( dest ", " mode )
6253 Returns an Action object that
6254 changes the permissions on the specified
6256 file or directory to the specified
6261 Execute(Chmod('file', 0755))
6263 env.Command('foo.out', 'foo.in',
6264 [Copy('$TARGET', '$SOURCE'),
6265 Chmod('$TARGET', 0755)])
6269 .RI Copy( dest ", " src )
6270 Returns an Action object
6273 source file or directory to the
6275 destination file or directory.
6279 Execute(Copy('foo.output', 'foo.input'))
6281 env.Command('bar.out', 'bar.in',
6282 Copy('$TARGET', '$SOURCE'))
6286 .RI Delete( entry ", [" must_exist ])
6287 Returns an Action that
6288 deletes the specified
6290 which may be a file or a directory tree.
6291 If a directory is specified,
6292 the entire directory tree
6297 then a Python error will be thrown
6298 if the specified entry does not exist;
6301 that is, the Action will silently do nothing
6302 if the entry does not exist.
6306 Execute(Delete('/tmp/buildroot'))
6308 env.Command('foo.out', 'foo.in',
6309 [Delete('${TARGET.dir}'),
6312 Execute(Delete('file_that_must_exist', must_exist=1))
6318 that creates the specified
6324 Execute(Mkdir('/tmp/outputdir'))
6326 env.Command('foo.out', 'foo.in',
6327 [Mkdir('/tmp/builddir',
6328 Copy('$SOURCE', '/tmp/builddir')
6329 "cd /tmp/builddir && ])
6334 .RI Move( dest ", " src )
6336 that moves the specified
6338 file or directory to
6345 Execute(Move('file.destination', 'file.source'))
6347 env.Command('output_file', 'input_file',
6349 Move('$TARGET', 'file_created_by_MyBuildAction')])
6355 that updates the modification time
6361 Execute(Touch('file_to_be_touched'))
6363 env.Command('marker', 'input_file',
6368 .SS Variable Substitution
6370 Before executing a command,
6372 performs construction variable interpolation on the strings that make up
6373 the command line of builders.
6374 Variables are introduced by a
6377 Besides construction variables, scons provides the following
6378 variables for each command execution:
6381 The file name of the target being built, or the file name of the first
6382 target if multiple targets are being built.
6385 The file names of all targets being built.
6388 The file name of the source of the build command, or the file name of the
6389 first source if multiple sources are being built.
6392 The file names of the sources of the build command.
6394 (Note that the above variables are reserved
6395 and may not be set in a construction environment.)
6398 For example, given the construction variable CC='cc', targets=['foo'], and
6399 sources=['foo.c', 'bar.c']:
6402 action='$CC -c -o $TARGET $SOURCES'
6405 would produce the command line:
6408 cc -c -o foo foo.c bar.c
6411 Variable names may be surrounded by curly braces ({})
6412 to separate the name from the trailing characters.
6413 Within the curly braces, a variable name may have
6414 a Python slice subscript appended to select one
6415 or more items from a list.
6416 In the previous example, the string:
6428 Additionally, a variable name may
6429 have the following special
6430 modifiers appended within the enclosing curly braces
6431 to modify the interpolated string:
6434 The base path of the file name,
6435 including the directory path
6436 but excluding any suffix.
6439 The name of the directory in which the file exists.
6443 minus any directory portion.
6446 Just the basename of the file,
6448 and minus the directory.
6451 Just the file suffix.
6454 The absolute path name of the file.
6457 The POSIX form of the path,
6458 with directories separated by
6462 This is sometimes necessary on Windows systems
6463 when a path references a file on other (POSIX) systems.
6466 The directory and file name to the source file linked to this file
6467 through BuildDir. If this file isn't linked, it just returns the
6468 directory and filename unchanged.
6471 The directory containing the source file linked to this file
6472 through BuildDir. If this file isn't linked, it just returns the
6473 directory part of the filename.
6476 The directory and file name to the source file linked to this file
6477 through BuildDir. If the file does not exist locally but exists in
6478 a Repository, the path in the Repository is returned.
6479 If this file isn't linked, it just returns the
6480 directory and filename unchanged.
6483 The Repository directory containing the source file linked to this file
6484 through BuildDir. If this file isn't linked, it just returns the
6485 directory part of the filename.
6488 For example, the specified target will
6489 expand as follows for the corresponding modifiers:
6492 $TARGET => sub/dir/file.x
6493 ${TARGET.base} => sub/dir/file
6494 ${TARGET.dir} => sub/dir
6495 ${TARGET.file} => file.x
6496 ${TARGET.filebase} => file
6497 ${TARGET.suffix} => .x
6498 ${TARGET.abspath} => /top/dir/sub/dir/file.x
6500 SConscript('src/SConscript', build_dir='sub/dir')
6501 $SOURCE => sub/dir/file.x
6502 ${SOURCE.srcpath} => src/file.x
6503 ${SOURCE.srcdir} => src
6505 Repository('/usr/repository')
6506 $SOURCE => sub/dir/file.x
6507 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
6508 ${SOURCE.rsrcdir} => /usr/repository/src
6511 Lastly, a variable name
6512 may be a callable Python function
6514 construction variable in the environment.
6516 take four arguments:
6518 - a list of target nodes,
6520 - a list of source nodes,
6522 - the construction environment,
6524 - a Boolean value that specifies
6525 whether the function is being called
6526 for generating a build signature.
6527 SCons will insert whatever
6528 the called function returns
6529 into the expanded string:
6532 def foo(target, source, env, for_signature):
6535 # Will expand $BAR to "bar baz"
6536 env=Environment(FOO=foo, BAR="$FOO baz")
6539 You can use this feature to pass arguments to a
6540 Python function by creating a callable class
6541 that stores one or more arguments in an object,
6542 and then uses them when the
6545 Note that in this case,
6546 the entire variable expansion must
6547 be enclosed by curly braces
6548 so that the arguments will
6549 be associated with the
6550 instantiation of the class:
6554 def __init__(self, arg):
6557 def __call__(self, target, source, env, for_signature):
6560 # Will expand $BAR to "my argument bar baz"
6561 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
6565 The special pseudo-variables
6569 may be used to surround parts of a command line
6572 causing a rebuild--that is,
6573 which are not included in the signature
6574 of target files built with this command.
6579 will be removed from the command line
6580 before it is added to file signatures,
6585 will be removed before the command is executed.
6586 For example, the command line:
6589 echo Last build occurred $( $TODAY $). > $TARGET
6593 would execute the command:
6596 echo Last build occurred $TODAY. > $TARGET
6600 but the command signature added to any target files would be:
6603 echo Last build occurred . > $TARGET
6606 SCons uses the following rules when converting construction variables into
6610 When the value is a string it is interpreted as a space delimited list of
6611 command line arguments.
6614 When the value is a list it is interpreted as a list of command line
6615 arguments. Each element of the list is converted to a string.
6618 Anything that is not a list or string is converted to a string and
6619 interpreted as a single command line argument.
6622 Newline characters (\\n) delimit lines. The newline parsing is done after
6623 all other parsing, so it is not possible for arguments (e.g. file names) to
6624 contain embedded newline characters. This limitation will likely go away in
6625 a future version of SCons.
6633 new file types for implicit dependencies.
6634 Scanner accepts the following arguments:
6637 A Python function that will process
6639 and return a list of strings (file names)
6640 representing the implicit
6641 dependencies found in the contents.
6642 The function takes three or four arguments:
6644 def scanner_function(node, env, path):
6646 def scanner_function(node, env, path, arg):
6650 argument is the internal
6651 SCons node representing the file.
6654 to fetch the name of the file, and
6655 .B node.get_contents()
6656 to fetch contents of the file.
6657 Note that the file is
6659 guaranteed to exist before the scanner is called,
6660 so the scanner function should check that
6661 if there's any chance that the scanned file
6663 (for example, if it's built from other files).
6667 argument is the construction environment for the scan.
6668 Fetch values from it using the
6674 argument is a tuple (or list)
6675 of directories that can be searched
6677 This will usually be the tuple returned by the
6679 argument (see below).
6683 argument is the argument supplied
6684 when the scanner was created, if any.
6687 The name of the Scanner.
6689 to identify the Scanner internally.
6692 An optional argument that, if specified,
6693 will be passed to the scanner function
6695 and the path function
6699 An optional list that can be used to
6700 determine which scanner should be used for
6702 In the usual case of scanning for file names,
6703 this argument will be a list of suffixes
6704 for the different file types that this
6705 Scanner knows how to scan.
6706 If the argument is a string,
6707 then it will be expanded
6708 into a list by the current environment.
6711 A Python function that takes four or five arguments:
6712 a construction environment,
6713 a Node for the directory containing
6714 the SConscript file in which
6715 the first target was defined,
6716 a list of target nodes,
6717 a list of source nodes,
6718 and an optional argument supplied
6719 when the scanner was created.
6722 returns a tuple of directories
6723 that can be searched for files to be returned
6724 by this Scanner object.
6727 The class of Node that should be returned
6728 by this Scanner object.
6729 Any strings or other objects returned
6730 by the scanner function
6731 that are not of this class
6732 will be run through the
6737 A Python function that will take a string
6739 and turn it into the appropriate class of Node
6740 to be returned by this Scanner object.
6743 An optional Python function that takes two arguments,
6744 a Node (file) and a construction environment,
6745 and returns whether the
6746 Node should, in fact,
6747 be scanned for dependencies.
6748 This check can be used to eliminate unnecessary
6749 calls to the scanner function when,
6750 for example, the underlying file
6751 represented by a Node does not yet exist.
6754 An optional flag that
6755 specifies whether this scanner should be re-invoked
6756 on the dependency files returned by the scanner.
6757 When this flag is not set,
6758 the Node subsystem will
6759 only invoke the scanner on the file being scanned,
6760 and not (for example) also on the files
6761 specified by the #include lines
6762 in the file being scanned.
6764 may be a callable function,
6765 in which case it will be called with a list of
6767 should return a list of Nodes
6768 that should be scanned recursively;
6769 this can be used to select a specific subset of
6770 Nodes for additional scanning.
6775 .B SourceFileScanner
6776 object that is used by
6779 .BR SharedObject (),
6783 which scanner should be used
6784 for different file extensions.
6786 .BR SourceFileScanner.add_scanner ()
6787 method to add your own Scanner object
6791 that builds target programs or
6792 libraries from a list of
6793 source files of different types:
6796 def xyz_scan(node, env, path):
6797 contents = node.get_contents()
6798 # Scan the contents and return the included files.
6800 XYZScanner = Scanner(xyz_scan)
6802 SourceFileScanner.add_scanner('.xyx', XYZScanner)
6804 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
6807 .SH SYSTEM-SPECIFIC BEHAVIOR
6808 SCons and its configuration files are very portable,
6809 due largely to its implementation in Python.
6810 There are, however, a few portability
6811 issues waiting to trap the unwary.
6813 SCons handles the upper-case
6815 file suffix differently,
6816 depending on the capabilities of
6817 the underlying system.
6818 On a case-sensitive system
6819 such as Linux or UNIX,
6820 SCons treats a file with a
6822 suffix as a C++ source file.
6823 On a case-insensitive system
6825 SCons treats a file with a
6827 suffix as a C source file.
6829 SCons handles the upper-case
6831 file suffix differently,
6832 depending on the capabilities of
6833 the underlying system.
6834 On a case-sensitive system
6835 such as Linux or UNIX,
6836 SCons treats a file with a
6838 suffix as a Fortran source file
6839 that is to be first run through
6840 the standard C preprocessor.
6841 On a case-insensitive system
6843 SCons treats a file with a
6845 suffix as a Fortran source file that should
6847 be run through the C preprocessor.
6848 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
6849 Cygwin supplies a set of tools and utilities
6850 that let users work on a
6851 Windows system using a more POSIX-like environment.
6852 The Cygwin tools, including Cygwin Python,
6854 by sharing an ability to interpret UNIX-like path names.
6855 For example, the Cygwin tools
6856 will internally translate a Cygwin path name
6857 like /cygdrive/c/mydir
6858 to an equivalent Windows pathname
6859 of C:/mydir (equivalent to C:\\mydir).
6862 that are built for native Windows execution,
6863 such as the python.org and ActiveState versions,
6864 do not have the Cygwin path name semantics.
6865 This means that using a native Windows version of Python
6866 to build compiled programs using Cygwin tools
6867 (such as gcc, bison, and flex)
6868 may yield unpredictable results.
6869 "Mixing and matching" in this way
6870 can be made to work,
6871 but it requires careful attention to the use of path names
6872 in your SConscript files.
6874 In practice, users can sidestep
6875 the issue by adopting the following rules:
6877 use the Cygwin-supplied Python interpreter
6879 when using Microsoft Visual C/C++
6880 (or some other Windows compiler)
6881 use the python.org or ActiveState version of Python
6883 .SS Windows: scons.bat file
6885 SCons is executed via a wrapper
6888 This has (at least) two ramifications:
6890 First, Windows command-line users
6891 that want to use variable assignment
6893 may have to put double quotes
6894 around the assignments:
6897 scons "FOO=BAR" "BAZ=BLEH"
6900 Second, the Cygwin shell does not
6901 recognize this file as being the same
6904 command issued at the command-line prompt.
6905 You can work around this either by
6908 from the Cygwin command line,
6909 or by creating a wrapper shell
6915 The MinGW bin directory must be in your PATH environment variable or the
6916 PATH variable under the ENV construction variable for SCons
6917 to detect and use the MinGW tools. When running under the native Windows
6918 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
6919 tools, if they are both installed, regardless of the order of the bin
6920 directories in the PATH variable. If you have both MSVC and MinGW
6921 installed and you want to use MinGW instead of MSVC,
6922 then you must explictly tell SCons to use MinGW by passing
6928 to the Environment() function, because SCons will prefer the MSVC tools
6929 over the MinGW tools.
6933 To help you get started using SCons,
6934 this section contains a brief overview of some common tasks.
6936 .SS Basic Compilation From a Single Source File
6940 env.Program(target = 'foo', source = 'foo.c')
6943 Note: Build the file by specifying
6944 the target as an argument
6945 ("scons foo" or "scons foo.exe").
6946 or by specifying a dot ("scons .").
6948 .SS Basic Compilation From Multiple Source Files
6952 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
6955 .SS Setting a Compilation Flag
6958 env = Environment(CCFLAGS = '-g')
6959 env.Program(target = 'foo', source = 'foo.c')
6962 .SS Search The Local Directory For .h Files
6966 need to set CCFLAGS to specify -I options by hand.
6967 SCons will construct the right -I options from CPPPATH.
6970 env = Environment(CPPPATH = ['.'])
6971 env.Program(target = 'foo', source = 'foo.c')
6974 .SS Search Multiple Directories For .h Files
6977 env = Environment(CPPPATH = ['include1', 'include2'])
6978 env.Program(target = 'foo', source = 'foo.c')
6981 .SS Building a Static Library
6985 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
6986 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
6989 .SS Building a Shared Library
6993 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
6994 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
6997 .SS Linking a Local Library Into a Program
7000 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
7001 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
7002 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
7005 .SS Defining Your Own Builder Object
7007 Notice that when you invoke the Builder,
7008 you can leave off the target file suffix,
7009 and SCons will add it automatically.
7012 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
7014 src_suffix = '.tex')
7015 env = Environment(BUILDERS = {'PDFBuilder' : bld})
7016 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
7018 # The following creates "bar.pdf" from "bar.tex"
7019 env.PDFBuilder(target = 'bar', source = 'bar')
7022 Note also that the above initialization
7023 overwrites the default Builder objects,
7024 so the Environment created above
7025 can not be used call Builders like env.Program(),
7026 env.Object(), env.StaticLibrary(), etc.
7028 .SS Adding Your Own Builder Object to an Environment
7031 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
7033 src_suffix = '.tex')
7035 env.Append(BUILDERS = {'PDFBuilder' : bld})
7036 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
7037 env.Program(target = 'bar', source = 'bar.c')
7040 You also can use other Pythonic techniques to add
7041 to the BUILDERS construction variable, such as:
7045 env['BUILDERS]['PDFBuilder'] = bld
7048 .SS Defining Your Own Scanner Object
7053 '\" Note: the \\ in the following are for the benefit of nroff/troff,
7054 '\" not inappropriate doubled escape characters within the r'' raw string.
7055 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
7057 def kfile_scan(node, env, path, arg):
7058 contents = node.get_contents()
7059 includes = include_re.findall(contents)
7062 kscan = Scanner(name = 'kfile',
7063 function = kfile_scan,
7066 scanners = Environment().Dictionary('SCANNERS')
7067 env = Environment(SCANNERS = scanners + [kscan])
7069 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
7071 bar_in = File('bar.in')
7072 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
7073 bar_in.target_scanner = kscan
7076 .SS Creating a Hierarchical Build
7078 Notice that the file names specified in a subdirectory's
7080 file are relative to that subdirectory.
7086 env.Program(target = 'foo', source = 'foo.c')
7088 SConscript('sub/SConscript')
7093 # Builds sub/foo from sub/foo.c
7094 env.Program(target = 'foo', source = 'foo.c')
7096 SConscript('dir/SConscript')
7101 # Builds sub/dir/foo from sub/dir/foo.c
7102 env.Program(target = 'foo', source = 'foo.c')
7105 .SS Sharing Variables Between SConscript Files
7107 You must explicitly Export() and Import() variables that
7108 you want to share between SConscript files.
7114 env.Program(target = 'foo', source = 'foo.c')
7117 SConscript('subdirectory/SConscript')
7119 subdirectory/SConscript:
7122 env.Program(target = 'foo', source = 'foo.c')
7125 .SS Building Multiple Variants From the Same Source
7127 Use the build_dir keyword argument to
7128 the SConscript function to establish
7129 one or more separate build directories for
7130 a given source directory:
7135 cppdefines = ['FOO']
7136 Export("cppdefines")
7137 SConscript('src/SConscript', build_dir='foo')
7139 cppdefines = ['BAR']
7140 Export("cppdefines")
7141 SConscript('src/SConscript', build_dir='bar')
7145 Import("cppdefines")
7146 env = Environment(CPPDEFINES = cppdefines)
7147 env.Program(target = 'src', source = 'src.c')
7150 Note the use of the Export() method
7151 to set the "cppdefines" variable to a different
7152 value each time we call the SConscript function.
7154 .SS Hierarchical Build of Two Libraries Linked With a Program
7159 env = Environment(LIBPATH = ['#libA', '#libB'])
7161 SConscript('libA/SConscript')
7162 SConscript('libB/SConscript')
7163 SConscript('Main/SConscript')
7168 env.Library('a', Split('a1.c a2.c a3.c'))
7173 env.Library('b', Split('b1.c b2.c b3.c'))
7178 e = env.Copy(LIBS = ['a', 'b'])
7179 e.Program('foo', Split('m1.c m2.c m3.c'))
7182 The '#' in the LIBPATH directories specify that they're relative to the
7183 top-level directory, so they don't turn into "Main/libA" when they're
7184 used in Main/SConscript.
7186 Specifying only 'a' and 'b' for the library names
7187 allows SCons to append the appropriate library
7188 prefix and suffix for the current platform
7189 (for example, 'liba.a' on POSIX systems,
7190 'a.lib' on Windows).
7192 .SS Customizing contruction variables from the command line.
7194 The following would allow the C compiler to be specified on the command
7195 line or in the file custom.py.
7198 opts = Options('custom.py')
7199 opts.Add('CC', 'The C compiler.')
7200 env = Environment(options=opts)
7201 Help(opts.GenerateHelpText(env))
7204 The user could specify the C compiler on the command line:
7210 or in the custom.py file:
7216 or get documentation on the options:
7227 .SS Using Microsoft Visual C++ precompiled headers
7229 Since windows.h includes everything and the kitchen sink, it can take quite
7230 some time to compile it over and over again for a bunch of object files, so
7231 Microsoft provides a mechanism to compile a set of headers once and then
7232 include the previously compiled headers in any object file. This
7233 technology is called precompiled headers. The general recipe is to create a
7234 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
7235 then include every header you want to precompile in "StdAfx.h", and finally
7236 include "StdAfx.h" as the first header in all the source files you are
7237 compiling to object files. For example:
7241 #include <windows.h>
7242 #include <my_big_header.h>
7261 /* do some other stuff */
7267 env['PCHSTOP'] = 'StdAfx.h'
7268 env['PCH'] = env.PCH('StdAfx.cpp')[0]
7269 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7272 For more information see the document for the PCH builder, and the PCH and
7273 PCHSTOP construction variables. To learn about the details of precompiled
7274 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
7276 .SS Using Microsoft Visual C++ external debugging information
7278 Since including debugging information in programs and shared libraries can
7279 cause their size to increase significantly, Microsoft provides a mechanism
7280 for including the debugging information in an external file called a PDB
7281 file. SCons supports PDB files through the PDB construction
7287 env['PDB'] = 'MyApp.pdb'
7288 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7291 For more information see the document for the PDB construction variable.
7296 Specifies the directory that contains the SCons Python module directory
7297 (e.g. /home/aroach/scons-src-0.01/src/engine).
7300 A string of options that will be used by scons in addition to those passed
7301 on the command line.
7312 Steven Knight <knight@baldmt.com>
7314 Anthony Roach <aroach@electriceyeball.com>