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 "January 2005"
36 scons \- a software construction tool
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found.
65 An alternate file name may be
72 file can specify subsidiary
73 configuration files using the
77 these subsidiary files are named
79 although any name may be used.
80 (Because of this naming convention,
81 the term "SConscript files"
82 is sometimes used to refer
86 regardless of actual file name.)
88 The configuration files
89 specify the target files to be built, and
90 (optionally) the rules to build those targets. Reasonable default
91 rules exist for building common software components (executable
92 programs, object files, libraries), so that for most software
93 projects, only the target and input files need be specified.
96 reads and executes the SConscript files as Python scripts,
97 so you may use normal Python scripting capabilities
98 (such as flow control, data manipulation, and imported Python libraries)
99 to handle complicated build situations.
101 however, reads and executes all of the SConscript files
103 it begins building any targets.
104 To make this obvious,
106 prints the following messages about what it is doing:
110 scons: Reading SConscript files ...
111 scons: done reading SConscript files.
112 scons: Building targets ...
114 scons: done building targets.
119 (everything except the line that reads "cp foo.in foo.out")
120 may be suppressed using the
125 does not automatically propagate
126 the external environment used to execute
128 to the commands used to build target files.
129 This is so that builds will be guaranteed
130 repeatable regardless of the environment
131 variables set at the time
134 This also means that if the compiler or other commands
135 that you want to use to build your target files
136 are not in standard system locations,
138 will not find them unless
139 you explicitly set the PATH
140 to include those locations.
141 Whenever you create an
143 construction environment,
144 you can propagate the value of PATH
145 from your external environment as follows:
149 env = Environment(ENV = {'PATH' : os.environ['PATH']})
153 can scan known input files automatically for dependency
154 information (for example, #include statements
155 in C or C++ files) and will rebuild dependent files appropriately
156 whenever any "included" input file changes.
159 ability to define new scanners for unknown input file types.
162 knows how to fetch files automatically from
163 SCCS or RCS subdirectories
164 using SCCS, RCS or BitKeeper.
167 is normally executed in a top-level directory containing a
169 file, optionally specifying
170 as command-line arguments
171 the target file or files to be built.
173 By default, the command
179 will build all target files in or below the current directory.
180 Explicit default targets
181 (to be built when no targets are specified on the command line)
182 may be defined the SConscript file(s)
185 function, described below.
189 targets are specified in the SConscript file(s),
190 all target files in or below the current directory
191 may be built by explicitly specifying
192 the current directory (.)
193 as a command-line target:
199 Building all target files,
200 including any files outside of the current directory,
201 may be specified by supplying a command-line target
202 of the root directory (on POSIX systems):
208 or the path name(s) of the volume(s) in which all the targets
209 should be built (on Windows systems):
215 To build only specific targets,
216 supply them as command-line arguments:
222 in which case only the specified targets will be built
223 (along with any derived files on which they depend).
225 Specifying "cleanup" targets in SConscript files is not
228 flag removes all files
229 necessary to build the specified target:
235 to remove all target files, or:
238 scons -c build export
241 to remove target files under build and export.
242 Additional files or directories to remove can be specified using the
245 A subset of a hierarchical tree may be built by
246 remaining at the top-level directory (where the
248 file lives) and specifying the subdirectory as the target to be
255 or by changing directory and invoking scons with the
257 option, which traverses up the directory
258 hierarchy until it finds the
260 file, and then builds
261 targets relatively to the current subdirectory:
269 supports building multiple targets in parallel via a
271 option that takes, as its argument, the number
272 of simultaneous tasks that may be spawned:
278 builds four targets in parallel, for example.
281 can maintain a cache of target (derived) files that can
282 be shared between multiple builds. When caching is enabled in a
283 SConscript file, any target files built by
286 to the cache. If an up-to-date target file is found in the cache, it
287 will be retrieved from the cache instead of being rebuilt locally.
288 Caching behavior may be disabled and controlled in other ways by the
290 .BR --cache-disable ,
293 command-line options. The
295 option is useful to prevent multiple builds
296 from trying to update the cache simultaneously.
298 Values of variables to be passed to the SConscript file(s)
299 may be specified on the command line:
305 These variables are available in SConscript files
306 through the ARGUMENTS dictionary,
307 and can be used in the SConscript file(s) to modify
308 the build in any way:
311 if ARGUMENTS.get('debug', 0):
312 env = Environment(CCFLAGS = '-g')
317 The command-line variable arguments are also available
319 indexed by their order on the command line.
320 This allows you to process them in order rather than by name,
322 ARGLIST[0] returns a tuple
323 containing (argname, argvalue).
324 A Python exception is thrown if you
325 try to access a list member that
329 requires Python version 1.5.2 or later.
330 There should be no other dependencies or requirements to run
333 .\" The following paragraph reflects the default tool search orders
334 .\" currently in SCons/Tool/__init__.py. If any of those search orders
335 .\" change, this documentation should change, too.
338 knows how to search for available programming tools
342 searches in order for the
343 Microsoft Visual C++ tools,
344 the MinGW tool chain,
345 the Intel compiler tools,
346 and the PharLap ETS compiler.
349 searches in order for the
352 and the Microsoft Visual C++ tools,
353 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
355 searches for the native compiler tools
356 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
357 and the GCC tool chain.
358 On all other platforms,
359 including POSIX (Linux and UNIX) platforms,
362 for the GCC tool chain,
363 the Microsoft Visual C++ tools,
364 and the Intel compiler tools.
365 You may, of course, override these default values
366 by appropriate configuration of
367 Environment construction variables.
372 supports the same command-line options as GNU
374 and many of those supported by
379 Ignored for compatibility with non-GNU versions of
383 -c, --clean, --remove
384 Clean up by removing all target files for which a construction
385 command is specified.
386 Also remove any files or directories associated to the construction command
387 using the Clean() function.
390 --cache-disable, --no-cache
391 Disable the derived-file caching specified by
394 will neither retrieve files from the cache
395 nor copy files to the cache.
398 --cache-force, --cache-populate
401 populate a cache by copying any already-existing, up-to-date
402 derived files to the cache,
403 in addition to files built by this invocation.
404 This is useful to populate a new cache with
405 all the current derived files,
406 or to add to the cache any derived files
407 recently built with caching disabled via the
415 and retrieving a derived file from the cache,
417 that would have been executed to build the file,
418 instead of the usual report,
419 "Retrieved `file' from cache."
420 This will produce consistent output for build logs,
421 regardless of whether a target
422 file was rebuilt or retrieved from the cache.
426 This specifies how the
428 call should use or generate the
429 results of configuration tests.
430 The option should be specified from
431 among the following choices:
435 scons will use its normal dependency mechanisms
436 to decide if a test must be rebuilt or not.
437 This saves time by not running the same configuration tests
438 every time you invoke scons,
439 but will overlook changes in system header files
440 or external commands (such as compilers)
441 if you don't specify those dependecies explicitly.
442 This is the default behavior.
446 If this option is specified,
447 all configuration tests will be re-run
448 regardless of whether the
449 cached results are out of date.
450 This can be used to explicitly
451 force the configuration tests to be updated
452 in response to an otherwise unconfigured change
453 in a system header file or compiler.
457 If this option is specified,
458 no configuration tests will be rerun
459 and all results will be taken from cache.
460 Note that scons will still consider it an error
461 if --config=cache is specified
462 and a necessary test does not
463 yet have any results in the cache.
466 .RI "-C" " directory" ", --directory=" directory
467 Change to the specified
469 before searching for the
474 file, or doing anything
477 options are interpreted
478 relative to the previous one, and the right-most
480 option wins. (This option is nearly
482 .BR "-f directory/SConstruct" ,
483 except that it will search for
488 in the specified directory.)
492 .\" Display dependencies while building target files. Useful for
493 .\" figuring out why a specific file is being rebuilt, as well as
494 .\" general debugging of the build process.
498 Works exactly the same way as the
500 option except for the way default targets are handled.
501 When this option is used and no targets are specified on the command line,
502 all default targets are built, whether or not they are below the current
507 Debug the build process.
509 specifies what type of debugging:
513 Print how many objects are created
514 of the various classes used internally by SCons
515 before and after reading the SConscript files
516 and before and after building targets.
517 This only works when run under Python 2.1 or later.
521 Print the dependency tree
522 after each top-level target is built. This prints out only derived files.
526 Instruct the scanner that searches for libraries
527 to print a message about each potential library
528 name it is searching for,
529 and about the actual libraries it finds.
533 Print the include tree after each top-level target is built.
534 This is generally used to find out what files are included by the sources
535 of a given derived file:
538 $ scons --debug=includes foo.o
543 Prints a summary of hits and misses in the Memoizer,
544 the internal SCons subsystem for caching
545 various values in memory instead of
546 recomputing them each time they're needed.
550 Prints how much memory SCons uses
551 before and after reading the SConscript files
552 and before and after building targets.
556 Disables use of the Memoizer,
557 the internal SCons subsystem for caching
558 various values in memory instead of
559 recomputing them each time they're needed.
560 This provides more accurate counts of the
561 underlying function calls in the
562 Python profiler output when using the
565 (When the Memoizer is used,
566 the profiler counts all
567 memoized functions as being executed
568 by the Memoizer's wrapper calls.)
572 Prints a list of the various objects
573 of the various classes used internally by SCons.
574 This only works when run under Python 2.1 or later.
578 Re-run SCons under the control of the
584 Print the raw command line used to build each target
585 before the construction environment variables are substituted.
586 Also shows which targets are being built by this command.
587 Output looks something like this:
589 $ scons --debug=presub
590 Building myprog.o with action(s):
591 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
597 Prints an internal Python stack trace
598 when encountering an otherwise unexplained error.
602 Print the dependency tree along with status information. This is the
603 same as the debug=tree option, but additional status information is
604 provided for each node in the tree.
608 Prints various time profiling information: the time spent
609 executing each build command, the total build time, the total time spent
610 executing build commands, the total time spent executing SConstruct and
611 SConscript files, and the total time spent executing SCons itself.
615 Print the dependency tree
616 after each top-level target is built. This prints out the complete
617 dependency tree including implicit dependencies and ignored
621 .RI --diskcheck= types
622 Enable specific checks for
623 whether or not there is a file on disk
624 where the SCons configuration expects a directory
626 and whether or not RCS or SCCS sources exist
627 when searching for source and include files.
630 argument can be set to:
632 to enable all checks explicitly
633 (the default behavior);
635 to disable all such checks;
637 to check that files and directories on disk
638 match SCons' expected configuration;
640 to check for the existence of an RCS source
641 for any missing source or include files;
643 to check for the existence of an SCCS source
644 for any missing source or include files.
645 Multiple checks can be specified separated by commas;
647 .B --diskcheck=sccs,rcs
648 would still check for SCCS and RCS sources,
649 but disable the check for on-disk matches of files and directories.
650 Disabling some or all of these checks
651 can provide a performance boost for large configurations,
652 or when the configuration will check for files and/or directories
653 across networked or shared file systems,
654 at the slight increased risk of an incorrect build
655 or of not handling errors gracefully
656 (if include files really should be
657 found in SCCS or RCS, for example,
658 or if a file really does exist
659 where the SCons configuration expects a directory).
662 .\" -e, --environment-overrides
663 .\" Variables from the execution environment override construction
664 .\" variables from the SConscript files.
667 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
670 as the initial SConscript file.
674 Print a local help message for this build, if one is defined in
675 the SConscript file(s), plus a line that describes the
677 option for command-line option help. If no local help message
678 is defined, prints the standard help message about command-line
679 options. Exits after displaying the appropriate message.
683 Print the standard help message about command-line options and
688 Ignore all errors from commands executed to rebuild files.
691 .RI -I " directory" ", --include-dir=" directory
695 imported Python modules. If several
698 are used, the directories are searched in the order specified.
702 Cache implicit dependencies. This can cause
704 to miss changes in the implicit dependencies in cases where a new implicit
705 dependency is added earlier in the implicit dependency search path
706 (e.g. CPPPATH) than a current implicit dependency with the same name.
709 --implicit-deps-changed
710 Force SCons to ignore the cached implicit dependencies. This causes the
711 implicit dependencies to be rescanned and recached. This implies
712 .BR --implicit-cache .
715 --implicit-deps-unchanged
716 Force SCons to ignore changes in the implicit dependencies.
717 This causes cached implicit dependencies to always be used.
719 .BR --implicit-cache .
722 .RI -j " N" ", --jobs=" N
723 Specifies the number of jobs (commands) to run simultaneously.
724 If there is more than one
726 option, the last one is effective.
730 .\" is specified without an argument,
732 .\" will not limit the number of
733 .\" simultaneous jobs.
737 Continue as much as possible after an error. The target that
738 failed and those that depend on it will not be remade, but other
739 targets specified on the command line will still be processed.
742 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
743 .\" No new jobs (commands) will be started if
744 .\" there are other jobs running and the system load
745 .\" average is at least
747 .\" (a floating-point number).
750 .RI --duplicate= ORDER
751 There are three ways to duplicate files in a build tree: hard links,
752 soft (symbolic) links and copies. The default behaviour of SCons is to
753 prefer hard links to soft links to copies. You can specify different
754 behaviours with this option.
764 SCons will attempt to duplicate files using
765 the mechanisms in the specified order.
770 .\" List derived files (targets, dependencies) that would be built,
771 .\" but do not build them.
772 .\" [XXX This can probably go away with the right
773 .\" combination of other options. Revisit this issue.]
777 .\" List derived files that would be built, with the actions
778 .\" (commands) that build them. Does not build the files.
779 .\" [XXX This can probably go away with the right
780 .\" combination of other options. Revisit this issue.]
784 .\" List derived files that would be built, plus where the file is
785 .\" defined (file name and line number). Does not build the files.
786 .\" [XXX This can probably go away with the right
787 .\" combination of other options. Revisit this issue.]
791 Ignored for compatibility with non-GNU versions of
795 .RI --max-drift= SECONDS
796 Set the maximum expected drift in the modification time of files to
798 This value determines how long a file must be unmodified
799 before its cached content signature
800 will be used instead of
801 calculating a new content signature (MD5 checksum)
802 of the file's contents.
803 The default value is 2 days, which means a file must have a
804 modification time of at least two days ago in order to have its
805 cached content signature used.
806 A negative value means to never cache the content
807 signature and to ignore the cached value if there already is one. A value
808 of 0 means to always use the cached signature,
809 no matter how old the file is.
812 -n, --just-print, --dry-run, --recon
813 No execute. Print the commands that would be executed to build
814 any out-of-date target files, but do not execute the commands.
817 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
821 .\" not rebuild anything due to changes in the contents of
824 .\" .RI --override " file"
825 .\" Read values to override specific build environment variables
826 .\" from the specified
830 .\" Print the data base (construction environments,
831 .\" Builder and Scanner objects) that are defined
832 .\" after reading the SConscript files.
833 .\" After printing, a normal build is performed
834 .\" as usual, as specified by other command-line options.
835 .\" This also prints version information
840 .\" To print the database without performing a build do:
848 Run SCons under the Python profiler
849 and save the results in the specified
851 The results may be analyzed using the Python
855 Do not run any commands, or print anything. Just return an exit
856 status that is zero if the specified targets are already up to
857 date, non-zero otherwise.
860 Quiets SCons status messages about
861 reading SConscript files,
863 and entering directories.
864 Commands that are executed
865 to rebuild target files are still printed.
868 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
869 .\" Clear the default construction variables. Construction
870 .\" environments that are created will be completely empty.
874 Build dependencies in a random order. This is useful when
875 building multiple trees simultaneously with caching enabled,
876 to prevent multiple builds from simultaneously trying to build
877 or retrieve the same target files.
880 -s, --silent, --quiet
881 Silent. Do not print commands that are executed to rebuild
883 Also suppresses SCons status messages.
886 -S, --no-keep-going, --stop
887 Ignored for compatibility with GNU
892 Ignored for compatibility with GNU
894 (Touching a file to make it
895 appear up-to-date is unnecessary when using
899 -u, --up, --search-up
900 Walks up the directory structure until an
905 file is found, and uses that
906 as the top of the directory tree.
907 If no targets are specified on the command line,
908 only targets at or below the
909 current directory will be built.
913 Works exactly the same way as the
915 option except for the way default targets are handled.
916 When this option is used and no targets are specified on the command line,
917 all default targets that are defined in the SConscript(s) in the current
918 directory are built, regardless of what directory the resultant targets end
925 version, copyright information,
926 list of authors, and any other relevant information.
930 -w, --print-directory
931 Print a message containing the working directory before and
932 after other processing.
935 .RI --warn= type ", --warn=no-" type
936 Enable or disable warnings.
938 specifies the type of warnings to be enabled or disabled:
941 --warn=all, --warn=no-all
942 Enables or disables all warnings.
945 --warn=dependency, --warn=no-dependency
946 Enables or disables warnings about dependencies.
947 These warnings are disabled by default.
950 --warn=deprecated, --warn=no-deprecated
951 Enables or disables warnings about use of deprecated features.
952 These warnings are enabled by default.
955 --warn=missing-sconscript, --warn=no-missing-sconscript
956 Enables or disables warnings about missing SConscript files.
957 These warnings are enabled by default.
961 Turn off -w, even if it was turned on implicitly.
964 .\" .RI --write-filenames= file
965 .\" Write all filenames considered into
969 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
970 .\" Pretend that the target
973 .\" modified. When used with the
976 .\" show you what would be rebuilt if you were to modify that file.
982 .\" --warn-undefined-variables
983 .\" Warn when an undefined variable is referenced.
986 .RI -Y " repository" ", --repository=" repository
987 Search the specified repository for any input and target
988 files not found in the local directory hierarchy. Multiple
990 options may specified, in which case the
991 repositories are searched in the order specified.
993 .SH CONFIGURATION FILE REFERENCE
994 .\" .SS Python Basics
995 .\" XXX Adding this in the future would be a help.
996 .SS Construction Environments
997 A construction environment is the basic means by which the SConscript
998 files communicate build information to
1000 A new construction environment is created using the
1008 By default, a new construction environment is
1009 initialized with a set of builder methods
1010 and construction variables that are appropriate
1011 for the current platform.
1012 An optional platform keyword argument may be
1013 used to specify that an environment should
1014 be initialized for a different platform:
1017 env = Environment(platform = 'cygwin')
1018 env = Environment(platform = 'os2')
1019 env = Environment(platform = 'posix')
1020 env = Environment(platform = 'win32')
1023 Specifying a platform initializes the appropriate
1024 construction variables in the environment
1025 to use and generate file names with prefixes
1026 and suffixes appropriate for the platform.
1034 variables from the user's external environment
1035 to the construction environment's
1038 This is so that any executed commands
1039 that use sockets to connect with other systems
1040 (such as fetching source files from
1041 external CVS repository specifications like
1042 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1043 will work on Win32 systems.
1045 The platform argument may be function or callable object,
1046 in which case the Environment() method
1047 will call the specified argument to update
1048 the new construction environment:
1051 def my_platform(env):
1052 env['VAR'] = 'xyzzy'
1054 env = Environment(platform = my_platform)
1057 Additionally, a specific set of tools
1058 with which to initialize the environment
1059 may specified as an optional keyword argument:
1062 env = Environment(tools = ['msvc', 'lex'])
1065 Non-built-in tools may be specified using the toolpath argument:
1068 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1071 This looks for a tool specification in tools/foo.py (as well as
1072 using the ordinary default tools for the platform). foo.py should
1073 have two functions: generate(env, **kw) and exists(env).
1077 modifies the passed-in environment
1078 to set up variables so that the tool
1080 it may use any keyword arguments
1081 that the user supplies (see below)
1082 to vary its initialization.
1085 function should return a true
1086 value if the tool is available.
1087 Tools in the toolpath are used before
1088 any of the built-in ones. For example, adding gcc.py to the toolpath
1089 would override the built-in gcc tool.
1090 Also note that the toolpath is
1091 stored in the environment for use
1099 base = Environment(toolpath=['custom_path'])
1100 derived = base.Copy(tools=['custom_tool'])
1101 derived.CustomBuilder()
1104 The elements of the tools list may also
1105 be functions or callable objects,
1106 in which case the Environment() method
1107 will call the specified elements
1108 to update the new construction environment:
1112 env['XYZZY'] = 'xyzzy'
1114 env = Environment(tools = [my_tool])
1117 The individual elements of the tools list
1118 may also themselves be two-element lists of the form
1119 .RI ( toolname ", " kw_dict ).
1120 SCons searches for the
1122 specification file as described above, and
1125 which must be a dictionary, as keyword arguments to the tool's
1130 function can use the arguments to modify the tool's behavior
1131 by setting up the environment in different ways
1132 or otherwise changing its initialization.
1135 # in tools/my_tool.py:
1136 def generate(env, **kw):
1137 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1138 env['MY_TOOL'] = kw.get('arg1', '1')
1143 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1147 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1148 the environment it receives to customize the tool for different platforms.
1150 If no tool list is specified, then SCons will auto-detect the installed
1151 tools using the PATH variable in the ENV construction variable and the
1152 platform name when the Environment is constructed. Changing the PATH
1153 variable after the Environment is constructed will not cause the tools to
1156 SCons supports the following tool specifications out of the box:
1232 Additionally, there is a "tool" named
1234 which configures the
1235 environment with a default set of tools for the current platform.
1237 On posix and cygwin platforms
1238 the GNU tools (e.g. gcc) are preferred by SCons,
1239 on win32 the Microsoft tools (e.g. msvc)
1240 followed by MinGW are preferred by SCons,
1241 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1245 Build rules are specified by calling a construction
1246 environment's builder methods.
1247 The arguments to the builder methods are
1249 (a list of target files)
1252 (a list of source files).
1254 Because long lists of file names
1255 can lead to a lot of quoting,
1260 and a same-named environment method
1261 that split a single string
1262 into a list, separated on
1263 strings of white-space characters.
1264 (These are similar to the
1265 string.split() method
1266 from the standard Python library,
1267 but work even if the input isn't a string.)
1269 Like all Python arguments,
1270 the target and source arguments to a builder method
1271 can be specified either with or without
1272 the "target" and "source" keywords.
1273 When the keywords are omitted,
1274 the target is first,
1275 followed by the source.
1276 The following are equivalent examples of calling the Program builder method:
1279 env.Program('bar', ['bar.c', 'foo.c'])
1280 env.Program('bar', Split('bar.c foo.c'))
1281 env.Program('bar', env.Split('bar.c foo.c'))
1282 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1283 env.Program(target = 'bar', Split('bar.c foo.c'))
1284 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1285 env.Program('bar', source = string.split('bar.c foo.c'))
1288 When the target shares the same base name
1289 as the source and only the suffix varies,
1290 and if the builder method has a suffix defined for the target file type,
1291 then the target argument may be omitted completely,
1294 will deduce the target file name from
1295 the source file name.
1296 The following examples all build the
1302 (on Windows systems)
1303 from the bar.c source file:
1306 env.Program(target = 'bar', source = 'bar.c')
1307 env.Program('bar', source = 'bar.c')
1308 env.Program(source = 'bar.c')
1309 env.Program('bar.c')
1312 It is possible to override or add construction variables when calling a
1313 builder method by passing additional keyword arguments.
1314 These overridden or added
1315 variables will only be in effect when building the target, so they will not
1316 affect other parts of the build. For example, if you want to add additional
1317 libraries for just one program:
1320 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1323 or generate a shared library with a nonstandard suffix:
1326 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1329 Although the builder methods defined by
1332 methods of a construction environment object,
1333 they may also be called without an explicit environment:
1336 Program('hello', 'hello.c')
1337 SharedLibrary('word', 'word.cpp')
1341 the methods are called internally using a default construction
1342 environment that consists of the tools and values that
1344 has determined are appropriate for the local system.
1346 Builder methods that can be called without an explicit
1347 environment may be called from custom Python modules that you
1348 import into an SConscript file by adding the following
1349 to the Python module:
1352 from SCons.Script import *
1355 All builder methods return a list of Nodes
1356 that represent the target or targets that will be built.
1359 is an internal SCons object
1361 build targets or sources.
1363 The returned Node(s)
1364 can be passed to other builder methods as source(s)
1365 or passed to any SCons function or method
1366 where a filename would normally be accepted.
1367 For example, if it were necessary
1370 flag when compiling one specific object file:
1373 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1374 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1377 Using a Node in this way
1378 makes for a more portable build
1379 by avoiding having to specify
1380 a platform-specific object suffix
1381 when calling the Program() builder method.
1383 Note that Builder calls will automatically "flatten"
1384 the source and target file lists,
1385 so it's all right to have the bar_obj list
1386 return by the StaticObject() call
1387 in the middle of the source file list.
1388 If you need to manipulate a list of lists returned by Builders
1389 directly using Python,
1390 you can either build the list by hand:
1393 foo = Object('foo.c')
1394 bar = Object('bar.c')
1395 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1396 for object in objects:
1403 to create a list containing just the Nodes,
1404 which may be more convenient:
1407 foo = Object('foo.c')
1408 bar = Object('bar.c')
1409 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1410 for object in objects:
1414 The path name for a Node's file may be used
1415 by passing the Node to the Python-builtin
1420 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1421 print "The path to bar_obj is:", str(bar_obj_list[0])
1424 Note again that because the Builder call returns a list,
1425 we have to access the first element in the list
1426 .B (bar_obj_list[0])
1427 to get at the Node that actually represents
1430 Builder calls support a
1432 keyword argument that
1433 specifies that the Builder's action(s)
1435 after changing directory.
1439 a string or a directory Node,
1440 scons will change to the specified directory.
1443 is not a string or Node
1445 then scons will change to the
1446 target file's directory.
1449 # scons will change to the "sub" subdirectory
1450 # before executing the "cp" command.
1451 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1452 "cp dir/foo.in dir/foo.out",
1455 # Because chdir is not a string, scons will change to the
1456 # target's directory ("sub/dir") before executing the
1458 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1459 "cp foo.in foo.out",
1463 Note that scons will
1465 automatically modify
1467 construction variables like
1471 when using the chdir
1472 keyword argument--that is,
1473 the expanded file names
1474 will still be relative to
1475 the top-level SConstruct directory,
1476 and consequently incorrect
1477 relative to the chdir directory.
1478 If you use the chdir keyword argument,
1479 you will typically need to supply a different
1485 to use just the filename portion of the
1489 provides the following builder methods:
1491 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1494 Builds a C source file given a lex (.l) or yacc (.y) input file.
1495 The suffix specified by the $CFILESUFFIX construction variable
1497 is automatically added to the target
1498 if it is not already present. Example:
1502 env.CFile(target = 'foo.c', source = 'foo.l')
1504 env.CFile(target = 'bar', source = 'bar.y')
1507 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1510 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1512 The suffix specified by the $CXXFILESUFFIX construction variable
1514 is automatically added to the target
1515 if it is not already present. Example:
1519 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1521 env.CXXFile(target = 'bar', source = 'bar.yy')
1524 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1527 Builds a .dvi file from a .tex, .ltx or .latex input file.
1528 If the source file suffix is .tex,
1530 will examine the contents of the file;
1535 is found, the file is assumed to be a LaTeX file and
1536 the target is built by invoking the $LATEXCOM command line;
1537 otherwise, the $TEXCOM command line is used.
1538 If the file is a LaTeX file,
1541 builder method will also examine the contents
1544 and invoke the $BIBTEX command line
1548 and will examine the contents
1550 file and re-run the $LATEXCOM command
1551 if the log file says it is necessary.
1554 (hard-coded within TeX itself)
1555 is automatically added to the target
1556 if it is not already present. Examples:
1559 # builds from aaa.tex
1560 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1562 env.DVI(target = 'bbb', source = 'bbb.ltx')
1563 # builds from ccc.latex
1564 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1567 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1570 Builds a Java archive (.jar) file
1571 from a source tree of .class files.
1572 If the $JARCHDIR value is set, the
1574 command will change to the specified directory using the
1577 If the contents any of the source files begin with the string
1578 .BR Manifest-Version ,
1579 the file is assumed to be a manifest
1580 and is passed to the
1587 env.Jar(target = 'foo.jar', source = 'classes')
1590 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1593 Builds one or more Java class files
1594 from one or more source trees of .java files.
1595 The class files will be placed underneath
1596 the specified target directory.
1597 SCons will parse each source .java file
1599 (including inner classes)
1600 defined within that file,
1601 and from that figure out the
1602 target .class files that will be created.
1603 SCons will also search each Java file
1604 for the Java package name,
1605 which it assumes can be found on a line
1606 beginning with the string
1608 in the first column;
1609 the resulting .class files
1610 will be placed in a directory reflecting
1611 the specified package name.
1615 defining a single public
1618 containing a package name of
1620 will generate a corresponding
1621 .IR sub/dir/Foo.class
1627 env.Java(target = 'classes', source = 'src')
1628 env.Java(target = 'classes', source = ['src1', 'src2'])
1631 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1634 Builds C header and source files for
1635 implementing Java native methods.
1636 The target can be either a directory
1637 in which the header files will be written,
1638 or a header file name which
1639 will contain all of the definitions.
1640 The source can be either the names of .class files,
1641 or the objects returned from the
1645 If the construction variable
1647 is set, either in the environment
1648 or in the call to the
1650 builder method itself,
1651 then the value of the variable
1652 will be stripped from the
1653 beginning of any .class file names.
1658 # builds java_native.h
1659 classes = env.Java(target = 'classdir', source = 'src')
1660 env.JavaH(target = 'java_native.h', source = classes)
1662 # builds include/package_foo.h and include/package_bar.h
1663 env.JavaH(target = 'include',
1664 source = ['package/foo.class', 'package/bar.class'])
1666 # builds export/foo.h and export/bar.h
1667 env.JavaH(target = 'export',
1668 source = ['classes/foo.class', 'classes/bar.class'],
1669 JAVACLASSDIR = 'classes')
1672 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1679 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1680 .IP LoadableModule()
1681 .IP env.LoadableModule()
1684 .BR SharedLibrary ().
1685 On Mac OS X (Darwin) platforms,
1686 this creates a loadable module bundle.
1689 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1692 Builds an output file from an M4 input file.
1693 This uses a default $M4FLAGS value of
1695 which considers all warnings to be fatal
1696 and stops on the first warning
1697 when using the GNU version of m4.
1701 env.M4(target = 'foo.c', source = 'foo.c.m4')
1704 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1707 Builds an output file from a moc input file. Moc input files are either
1708 header files or cxx files. This builder is only available after using the
1709 tool 'qt'. See the QTDIR variable for more information.
1713 env.Moc('foo.h') # generates moc_foo.cc
1714 env.Moc('foo.cpp') # generates foo.moc
1717 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1719 .IP env.MSVSProject()
1720 Builds Microsoft Visual Studio project files.
1721 This builds a Visual Studio project file, based on the version of
1722 Visual Studio that is configured (either the latest installed version,
1723 or the version set by
1725 in the Environment constructor).
1726 For VS 6, it will generate
1730 files, for VS 7, it will
1737 It takes several lists of filenames to be placed into the project
1738 file, currently these are limited to
1739 .B srcs, incs, localincs, resources,
1742 These are pretty self explanatory, but it
1743 should be noted that the 'srcs' list is NOT added to the $SOURCES
1744 environment variable. This is because it represents a list of files
1745 to be added to the project file, not the source used to build the
1746 project file (in this case, the 'source' is the SConscript file used
1747 to call MSVSProject).
1749 In addition to these values (which are all optional, although not
1750 specifying any of them results in an empty project file), the
1751 following values must be specified:
1753 target: The name of the target .dsp or .vcproj file. The correct
1754 suffix for the version of Visual Studio must be used, but the value
1756 env['MSVSPROJECTSUFFIX']
1758 will be defined to the correct value (see example below).
1760 variant: The name of this particular variant. These are typically
1761 things like "Debug" or "Release", but really can be anything you want.
1762 Multiple calls to MSVSProject with different variants are allowed: all
1763 variants will be added to the project file with their appropriate
1764 build targets and sources.
1766 buildtarget: A list of SCons.Node.FS objects which is returned from
1767 the command which builds the target. This is used to tell SCons what
1768 to build when the 'build' button is pressed inside of the IDE.
1773 barsrcs = ['bar.cpp'],
1774 barincs = ['bar.h'],
1775 barlocalincs = ['StdAfx.h']
1776 barresources = ['bar.rc','resource.h']
1777 barmisc = ['bar_readme.txt']
1779 dll = local.SharedLibrary(target = 'bar.dll',
1782 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1785 localincs = barlocalincs,
1786 resources = barresources,
1789 variant = 'Release')
1792 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1802 Builds a Microsoft Visual C++ precompiled header.
1803 Calling this builder method
1804 returns a list of two targets: the PCH as the first element, and the object
1805 file as the second element. Normally the object file is ignored.
1806 This builder method is only
1807 provided when Microsoft Visual C++ is being used as the compiler.
1808 The PCH builder method is generally used in
1809 conjuction with the PCH construction variable to force object files to use
1810 the precompiled header:
1813 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1816 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1819 Builds a .pdf file from a .dvi input file
1820 (or, by extension, a .tex, .ltx, or .latex input file).
1821 The suffix specified by the $PDFSUFFIX construction variable
1823 is added automatically to the target
1824 if it is not already present. Example:
1827 # builds from aaa.tex
1828 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1829 # builds bbb.pdf from bbb.dvi
1830 env.PDF(target = 'bbb', source = 'bbb.dvi')
1833 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1835 .IP env.PostScript()
1836 Builds a .ps file from a .dvi input file
1837 (or, by extension, a .tex, .ltx, or .latex input file).
1838 The suffix specified by the $PSSUFFIX construction variable
1840 is added automatically to the target
1841 if it is not already present. Example:
1844 # builds from aaa.tex
1845 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1846 # builds bbb.ps from bbb.dvi
1847 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1850 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1853 Builds an executable given one or more object files
1854 or C, C++, D, or Fortran source files.
1855 If any C, C++, D or Fortran source files are specified,
1856 then they will be automatically
1857 compiled to object files using the
1860 see that builder method's description for
1861 a list of legal source file suffixes
1862 and how they are interpreted.
1863 The target executable file prefix
1864 (specified by the $PROGPREFIX construction variable; nothing by default)
1866 (specified by the $PROGSUFFIX construction variable;
1867 by default, .exe on Windows systems, nothing on POSIX systems)
1868 are automatically added to the target if not already present.
1872 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1875 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1878 Builds a Microsoft Visual C++ resource file.
1879 This builder method is only provided
1880 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1884 for MinGW) suffix is added to the target name if no other suffix is given. The source
1885 file is scanned for implicit dependencies as though it were a C file. Example:
1888 env.RES('resource.rc')
1891 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1894 Builds stub and skeleton class files
1896 from Java .class files.
1897 The target is a directory
1898 relative to which the stub
1899 and skeleton class files will be written.
1900 The source can be the names of .class files,
1901 or the objects return from the
1905 If the construction variable
1907 is set, either in the environment
1908 or in the call to the
1910 builder method itself,
1911 then the value of the variable
1912 will be stripped from the
1913 beginning of any .class file names.
1916 classes = env.Java(target = 'classdir', source = 'src')
1917 env.RMIC(target = 'outdir1', source = classes)
1919 env.RMIC(target = 'outdir2',
1920 source = ['package/foo.class', 'package/bar.class'])
1922 env.RMIC(target = 'outdir3',
1923 source = ['classes/foo.class', 'classes/bar.class'],
1924 JAVACLASSDIR = 'classes')
1927 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1929 .IP env.RPCGenClient()
1930 Generates an RPC client stub (_clnt.c) file
1931 from a specified RPC (.x) source file.
1932 Because rpcgen only builds output files
1933 in the local directory,
1934 the command will be executed
1935 in the source file's directory by default.
1938 # Builds src/rpcif_clnt.c
1939 env.RPCGenClient('src/rpcif.x')
1942 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1944 .IP env.RPCGenHeader()
1945 Generates an RPC header (.h) file
1946 from a specified RPC (.x) source file.
1947 Because rpcgen only builds output files
1948 in the local directory,
1949 the command will be executed
1950 in the source file's directory by default.
1953 # Builds src/rpcif.h
1954 env.RPCGenHeader('src/rpcif.x')
1957 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1959 .IP env.RPCGenService()
1960 Generates an RPC server-skeleton (_svc.c) file
1961 from a specified RPC (.x) source file.
1962 Because rpcgen only builds output files
1963 in the local directory,
1964 the command will be executed
1965 in the source file's directory by default.
1968 # Builds src/rpcif_svc.c
1969 env.RPCGenClient('src/rpcif.x')
1972 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1975 Generates an RPC XDR routine (_xdr.c) file
1976 from a specified RPC (.x) source file.
1977 Because rpcgen only builds output files
1978 in the local directory,
1979 the command will be executed
1980 in the source file's directory by default.
1983 # Builds src/rpcif_xdr.c
1984 env.RPCGenClient('src/rpcif.x')
1987 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1989 .IP env.SharedLibrary()
1990 Builds a shared library
1991 (.so on a POSIX system, .dll on WIN32)
1992 given one or more object files
1993 or C, C++, D or Fortran source files.
1994 If any source files are given,
1995 then they will be automatically
1996 compiled to object files.
1997 The static library prefix and suffix (if any)
1998 are automatically added to the target.
1999 The target library file prefix
2000 (specified by the $SHLIBPREFIX construction variable;
2001 by default, lib on POSIX systems, nothing on Windows systems)
2003 (specified by the $SHLIBSUFFIX construction variable;
2004 by default, .dll on Windows systems, .so on POSIX systems)
2005 are automatically added to the target if not already present.
2009 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2012 On WIN32 systems, the
2014 builder method will always build an import (.lib) library
2015 in addition to the shared (.dll) library,
2016 adding a .lib library with the same basename
2017 if there is not already a .lib file explicitly
2018 listed in the targets.
2020 Any object files listed in the
2022 must have been built for a shared library
2027 will raise an error if there is any mismatch.
2029 On WIN32 systems, specifying "register=1" will cause the dll to be
2030 registered after it is built using REGSVR32. The command that is run
2031 ("regsvr32" by default) is determined by $REGSVR construction
2032 variable, and the flags passed are determined by $REGSVRFLAGS. By
2033 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
2034 up and requiring user attention when it is run. If you change
2035 $REGSVRFLAGS, be sure to include "/s". For example,
2038 env.SharedLibrary(target = 'bar',
2039 source = ['bar.cxx', 'foo.obj'],
2044 will register "bar.dll" as a COM object when it is done linking it.
2046 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2048 .IP env.SharedObject()
2049 Builds an object file for
2050 inclusion in a shared library.
2051 Source files must have one of the same set of extensions
2052 specified above for the
2055 On some platforms building a shared object requires additional
2056 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
2057 normal (static) object, but on some platforms there is no difference between a
2058 shared object and a normal (static) one. When there is a difference, SCons
2059 will only allow shared objects to be linked into a shared library, and will
2060 use a different suffix for shared objects. On platforms where there is no
2061 difference, SCons will allow both normal (static)
2062 and shared objects to be linked into a
2063 shared library, and will use the same suffix for shared and normal
2065 The target object file prefix
2066 (specified by the $SHOBJPREFIX construction variable;
2067 by default, the same as $OBJPREFIX)
2069 (specified by the $SHOBJSUFFIX construction variable)
2070 are automatically added to the target if not already present.
2074 env.SharedObject(target = 'ddd', source = 'ddd.c')
2075 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2076 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2079 Note that the source files will be scanned
2080 according to the suffix mappings in
2081 .B SourceFileScanner
2083 See the section "Scanner Objects,"
2084 below, for a more information.
2086 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2088 .IP env.StaticLibrary()
2089 Builds a static library given one or more object files
2090 or C, C++, D or Fortran source files.
2091 If any source files are given,
2092 then they will be automatically
2093 compiled to object files.
2094 The static library prefix and suffix (if any)
2095 are automatically added to the target.
2096 The target library file prefix
2097 (specified by the $LIBPREFIX construction variable;
2098 by default, lib on POSIX systems, nothing on Windows systems)
2100 (specified by the $LIBSUFFIX construction variable;
2101 by default, .lib on Windows systems, .a on POSIX systems)
2102 are automatically added to the target if not already present.
2106 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2110 Any object files listed in the
2112 must have been built for a static library
2117 will raise an error if there is any mismatch.
2119 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2121 .IP env.StaticObject()
2122 Builds a static object file
2123 from one or more C, C++, D, or Fortran source files.
2124 Source files must have one of the following extensions:
2127 .asm assembly language file
2128 .ASM assembly language file
2140 .F WIN32: Fortran file
2141 POSIX: Fortran file + C pre-processor
2144 .fpp Fortran file + C pre-processor
2145 .FPP Fortran file + C pre-processor
2147 .mm Objective C++ file
2148 .s assembly language file
2149 .S WIN32: assembly language file
2150 POSIX: assembly language file + C pre-processor
2151 .spp assembly language file + C pre-processor
2152 .SPP assembly language file + C pre-processor
2155 The target object file prefix
2156 (specified by the $OBJPREFIX construction variable; nothing by default)
2158 (specified by the $OBJSUFFIX construction variable;
2159 \.obj on Windows systems, .o on POSIX systems)
2160 are automatically added to the target if not already present.
2164 env.StaticObject(target = 'aaa', source = 'aaa.c')
2165 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2166 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2169 Note that the source files will be scanned
2170 according to the suffix mappings in
2171 .B SourceFileScanner
2173 See the section "Scanner Objects,"
2174 below, for a more information.
2176 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2179 Builds a tar archive of the specified files
2181 Unlike most builder methods,
2184 builder method may be called multiple times
2186 each additional call
2187 adds to the list of entries
2188 that will be built into the archive.
2189 Any source directories will
2190 be scanned for changes to
2192 regardless of whether or not
2194 knows about them from other Builder or function calls.
2197 env.Tar('src.tar', 'src')
2199 # Create the stuff.tar file.
2200 env.Tar('stuff', ['subdir1', 'subdir2'])
2201 # Also add "another" to the stuff.tar file.
2202 env.Tar('stuff', 'another')
2204 # Set TARFLAGS to create a gzip-filtered archive.
2205 env = Environment(TARFLAGS = '-c -z')
2206 env.Tar('foo.tar.gz', 'foo')
2208 # Also set the suffix to .tgz.
2209 env = Environment(TARFLAGS = '-c -z',
2214 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2216 .IP env.TypeLibrary()
2217 Builds a Windows type library (.tlb) file from and input IDL file
2218 (.idl). In addition, it will build the associated inteface stub and
2219 proxy source files. It names them according to the base name of the .idl file.
2224 env.TypeLibrary(source="foo.idl")
2227 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2229 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2232 Builds a header file, an implementation file and a moc file from an ui file.
2233 and returns the corresponding nodes in the above order.
2234 This builder is only available after using the tool 'qt'. Note: you can
2235 specify .ui files directly as inputs for Program, Library and SharedLibrary
2236 without using this builder. Using the builder lets you override the standard
2237 naming conventions (be careful: prefixes are always prepended to names of
2238 built files; if you don't want prefixes, you may set them to ``).
2239 See the QTDIR variable for more information.
2243 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2244 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2245 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2248 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2251 Builds a zip archive of the specified files
2253 Unlike most builder methods,
2256 builder method may be called multiple times
2258 each additional call
2259 adds to the list of entries
2260 that will be built into the archive.
2261 Any source directories will
2262 be scanned for changes to
2264 regardless of whether or not
2266 knows about them from other Builder or function calls.
2269 env.Zip('src.zip', 'src')
2271 # Create the stuff.zip file.
2272 env.Zip('stuff', ['subdir1', 'subdir2'])
2273 # Also add "another" to the stuff.tar file.
2274 env.Zip('stuff', 'another')
2278 targets of builder methods automatically depend on their sources.
2279 An explicit dependency can
2280 be specified using the
2282 method of a construction environment (see below).
2287 source files for various programming languages,
2288 so the dependencies do not need to be specified explicitly.
2289 By default, SCons can
2292 Fortran source files with
2294 (POSIX systems only),
2299 and assembly language files with
2301 (POSIX systems only),
2306 for C preprocessor dependencies.
2307 SCons also has default support
2308 for scanning D source files,
2309 You can also write your own Scanners
2310 to add support for additional source file types.
2311 These can be added to the default
2312 Scanner object used by
2318 Builders by adding them
2320 .B SourceFileScanner
2323 See the section "Scanner Objects,"
2324 below, for a more information about
2325 defining your own Scanner objects.
2327 .SS Methods and Functions to Do Things
2328 In addition to Builder methods,
2330 provides a number of other construction environment methods
2331 and global functions to
2332 manipulate the build configuration.
2334 Usually, a construction environment method
2335 and global function with the same name both exist
2336 so that you don't have to remember whether
2337 to a specific bit of functionality
2338 must be called with or without a construction environment.
2339 In the following list,
2340 if you call something as a global function
2343 .RI Function( arguments )
2345 and if you call something through a construction
2346 environment it looks like:
2348 .RI env.Function( arguments )
2350 If you can call the functionality in both ways,
2351 then both forms are listed.
2353 Global functions may be called from custom Python modules that you
2354 import into an SConscript file by adding the following
2355 to the Python module:
2358 from SCons.Script import *
2361 Except where otherwise noted,
2363 construction environment method
2365 provide the exact same functionality.
2366 The only difference is that,
2368 calling the functionality through a construction environment will
2369 substitute construction variables into
2370 any supplied strings.
2373 env = Environment(FOO = 'foo')
2377 the first call to the global
2379 function will actually add a target named
2381 to the list of default targets,
2382 while the second call to the
2384 construction environment method
2385 will expand the value
2386 and add a target named
2388 to the list of default targets.
2389 For more on construction variable expansion,
2390 see the next section on
2391 construction variables.
2393 Construction environment methods
2394 and global functions supported by
2398 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2400 .RI Action( action ", [" strfunction ", " varlist ])
2402 .RI env.Action( action ", [" strfunction ", " varlist ])
2403 Creates an Action object for
2406 See the section "Action Objects,"
2407 below, for a complete explanation of the arguments and behavior.
2409 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2411 .RI AddPostAction( target ", " action )
2413 .RI env.AddPostAction( target ", " action )
2414 Arranges for the specified
2420 The specified action(s) may be
2421 an Action object, or anything that
2422 can be converted into an Action object
2425 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2427 .RI AddPreAction( target ", " action )
2429 .RI env.AddPreAction( target ", " action )
2430 Arranges for the specified
2433 before the specified
2436 The specified action(s) may be
2437 an Action object, or anything that
2438 can be converted into an Action object
2441 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2443 .RI Alias( alias ", [" targets ", [" action ]])
2445 .RI env.Alias( alias ", [" targets ", [" action ]])
2446 Creates one or more phony targets that
2447 expand to one or more other targets.
2452 can be specified that will be executed
2453 whenever the any of the alias targets are out-of-date.
2454 Returns the Node object representing the alias,
2455 which exists outside of any file system.
2456 This Node object, or the alias name,
2457 may be used as a dependency of any other target,
2458 including another alias.
2460 can be called multiple times for the same
2461 alias to add additional targets to the alias,
2462 or additional actions to the list for this alias.
2466 Alias('install', '/usr/bin')
2467 Alias(['install', 'install-lib'], '/usr/local/lib')
2469 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2470 env.Alias('install', ['/usr/local/man'])
2472 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2475 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2477 .RI AlwaysBuild( target ", ...)"
2479 .RI env.AlwaysBuild( target ", ...)"
2482 so that it is always assumed to be out of date,
2483 and will always be rebuilt if needed.
2486 does not add its target(s) to the default target list,
2487 so the targets will only be built
2488 if they are specified on the command line,
2489 or are a dependent of a target specified on the command line--but
2492 be built if so specified.
2493 Multiple targets can be passed in to a single call to
2496 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2498 .RI env.Append( key = val ", [...])"
2499 Appends the specified keyword arguments
2500 to the end of construction variables in the environment.
2501 If the Environment does not have
2502 the specified construction variable,
2503 it is simply added to the environment.
2504 If the values of the construction variable
2505 and the keyword argument are the same type,
2506 then the two values will be simply added together.
2507 Otherwise, the construction variable
2508 and the value of the keyword argument
2509 are both coerced to lists,
2510 and the lists are added together.
2511 (See also the Prepend method, below.)
2514 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2517 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2519 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2520 This appends new path elements to the given path in the
2521 specified external environment
2525 any particular path once (leaving the last one it encounters and
2526 ignoring the rest, to preserve path order),
2527 and to help assure this,
2528 will normalize all paths (using
2531 .BR os.path.normcase ).
2532 This can also handle the
2533 case where the given old path variable is a list instead of a
2534 string, in which case a list will be returned instead of a string.
2538 print 'before:',env['ENV']['INCLUDE']
2539 include_path = '/foo/bar:/foo'
2540 env.PrependENVPath('INCLUDE', include_path)
2541 print 'after:',env['ENV']['INCLUDE']
2545 after: /biz:/foo/bar:/foo
2548 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2550 .RI env.AppendUnique( key = val ", [...])"
2551 Appends the specified keyword arguments
2552 to the end of construction variables in the environment.
2553 If the Environment does not have
2554 the specified construction variable,
2555 it is simply added to the environment.
2556 If the construction variable being appended to is a list,
2557 then any value(s) that already exist in the
2558 construction variable will
2560 be added again to the list.
2563 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2569 A factory function that
2570 returns a Builder object
2571 to be used to fetch source files
2573 The returned Builder
2574 is intended to be passed to the
2579 env.SourceCode('.', env.BitKeeper())
2582 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2584 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2586 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2587 This specifies a build directory
2589 in which to build all derived files
2590 that would normally be built under
2592 Multiple build directories can be set up for multiple build variants, for
2595 must be underneath the SConstruct file's directory,
2598 may not be underneath the
2601 The default behavior is for
2603 to duplicate all of the files in the tree underneath
2607 and then build the derived files within the copied tree.
2608 (The duplication is performed by
2610 depending on the platform; see also the
2613 This guarantees correct builds
2614 regardless of whether intermediate source files
2615 are generated during the build,
2616 where preprocessors or other scanners search
2618 or whether individual compilers or other invoked tools
2619 are hard-coded to put derived files in the same directory as source files.
2621 This behavior of making a complete copy of the source tree
2622 may be disabled by setting
2627 to invoke Builders using the
2628 path names of source files in
2630 and the path names of derived files within
2632 This is always more efficient than
2634 and is usually safe for most builds.
2638 may cause build problems
2639 if source files are generated during the build,
2640 if any invoked tools are hard-coded to
2641 put derived files in the same directory as the source files.
2643 Note that specifying a
2645 works most naturally
2646 with a subsidiary SConscript file
2647 in the source directory.
2649 you would then call the subsidiary SConscript file
2650 not in the source directory,
2655 had made a virtual copy of the source tree
2656 regardless of the value of
2658 This is how you tell
2660 which variant of a source tree to build.
2664 BuildDir('build-variant1', 'src')
2665 SConscript('build-variant1/SConscript')
2666 BuildDir('build-variant2', 'src')
2667 SConscript('build-variant2/SConscript')
2673 function, described below,
2675 specify a build directory
2676 in conjunction with calling a subsidiary
2679 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2681 .RI Builder( action ", [" arguments ])
2683 .RI env.Builder( action ", [" arguments ])
2684 Creates a Builder object for
2687 See the section "Builder Objects,"
2688 below, for a complete explanation of the arguments and behavior.
2690 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2692 .RI CacheDir( cache_dir )
2694 .RI env.CacheDir( cache_dir )
2697 will maintain a cache of derived files in
2699 The derived files in the cache will be shared
2700 among all the builds using the same
2708 finds a derived file that needs to be rebuilt,
2709 it will first look in the cache to see if a
2710 derived file has already been built
2711 from identical input files and an identical build action
2712 (as incorporated into the MD5 build signature).
2715 will retrieve the file from the cache.
2716 If the derived file is not present in the cache,
2719 then place a copy of the built file in the cache
2720 (identified by its MD5 build signature),
2721 so that it may be retrieved by other
2722 builds that need to build the same derived file
2723 from identical inputs.
2727 may be disabled for any invocation
2736 will place a copy of
2738 derived files in the cache,
2739 even if they already existed
2740 and were not built by this invocation.
2741 This is useful to populate a cache
2744 is added to a build,
2753 "Retrieved `file' from cache,"
2756 option is being used.
2761 will print the action that
2763 have been used to build the file,
2764 without any indication that
2765 the file was actually retrieved from the cache.
2766 This is useful to generate build logs
2767 that are equivalent regardless of whether
2768 a given derived file has been built in-place
2769 or retrieved from the cache.
2771 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2773 .RI Clean( targets ", " files_or_dirs )
2775 .RI env.Clean( targets ", " files_or_dirs )
2776 This specifies a list of files or directories which should be removed
2777 whenever the targets are specified with the
2779 command line option.
2780 The specified targets may be a list
2781 or an individual target.
2785 and create new targets or add files and directories to the
2786 clean list for the specified targets.
2788 Multiple files or directories should be specified
2789 either as separate arguments to the
2791 method, or as a list.
2793 will also accept the return value of any of the construction environment
2798 Clean('foo', ['bar', 'baz'])
2799 Clean('dist', env.Program('hello', 'hello.c'))
2800 Clean(['foo', 'bar'], 'something_else_to_clean')
2803 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2805 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2807 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2808 Executes a specific action
2809 (or list of actions)
2810 to build a target file or files.
2811 This is more convenient
2812 than defining a separate Builder object
2813 for a single special-case build.
2815 As a special case, the
2817 keyword argument can
2820 that will be used to scan the sources.
2824 if any of the sources will be directories
2825 that must be scanned on-disk for
2826 changes to files that aren't
2827 already specified in other Builder of function calls.)
2829 Any other keyword arguments specified override any
2830 same-named existing construction variables.
2832 An action can be an external command,
2833 specified as a string,
2834 or a callable Python object;
2835 see "Action Objects," below,
2836 for more complete information.
2837 Also note that a string specifying an external command
2838 may be preceded by an
2841 to suppress printing the command in question,
2845 to ignore the exit status of the external command.
2849 env.Command('foo.out', 'foo.in',
2850 "$FOO_BUILD < $SOURCES > $TARGET")
2852 env.Command('bar.out', 'bar.in',
2854 "$BAR_BUILD < $SOURCES > $TARGET"],
2855 ENV = {'PATH' : '/usr/local/bin/'})
2857 def rename(env, target, source):
2859 os.rename('.tmp', str(target[0]))
2861 env.Command('baz.out', 'baz.in',
2862 ["$BAZ_BUILD < $SOURCES > .tmp",
2866 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2868 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2870 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2871 Creates a Configure object for integrated
2872 functionality similar to GNU autoconf.
2873 See the section "Configure Contexts,"
2874 below, for a complete explanation of the arguments and behavior.
2876 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2878 .RI env.Copy([ key = val ", ...])"
2879 Return a separate copy of a construction environment.
2880 If there are any keyword arguments specified,
2881 they are added to the returned copy,
2882 overwriting any existing values
2887 env3 = env.Copy(CCFLAGS = '-g')
2890 Additionally, a list of tools and a toolpath may be specified, as in
2891 the Environment constructor:
2894 def MyTool(env): env['FOO'] = 'bar'
2895 env4 = env.Copy(tools = ['msvc', MyTool])
2898 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2900 .RI env.CVS( repository ", " module )
2901 A factory function that
2902 returns a Builder object
2903 to be used to fetch source files
2907 The returned Builder
2908 is intended to be passed to the
2912 The optional specified
2914 will be added to the beginning
2915 of all repository path names;
2916 this can be used, in essence,
2917 to strip initial directory names
2918 from the repository path names,
2919 so that you only have to
2920 replicate part of the repository
2921 directory hierarchy in your
2922 local build directory:
2925 # Will fetch foo/bar/src.c
2926 # from /usr/local/CVSROOT/foo/bar/src.c.
2927 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2929 # Will fetch bar/src.c
2930 # from /usr/local/CVSROOT/foo/bar/src.c.
2931 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2934 # from /usr/local/CVSROOT/foo/bar/src.c.
2935 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2938 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2940 .RI Default( targets )
2942 .RI env.Default( targets )
2943 This specifies a list of default targets,
2944 which will be built by
2946 if no explicit targets are given on the command line.
2950 and add to the list of default targets.
2952 Multiple targets should be specified as
2953 separate arguments to the
2955 method, or as a list.
2957 will also accept the Node returned by any
2958 of a construction environment's
2963 Default('foo', 'bar', 'baz')
2964 env.Default(['a', 'b', 'c'])
2965 hello = env.Program('hello', 'hello.c')
2973 will clear all default targets.
2976 will add to the (now empty) default-target list
2979 The current list of targets added using the
2981 function or method is available in the
2986 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2988 .RI DefaultEnvironment([ args ])
2989 Creates and returns a default construction environment object.
2990 This construction environment is used internally by SCons
2991 in order to execute many of the global functions in this list,
2992 and to fetch source files transparently
2993 from source code management systems.
2995 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2997 .RI Depends( target ", " dependency )
2999 .RI env.Depends( target ", " dependency )
3000 Specifies an explicit dependency;
3001 the target file(s) will be rebuilt
3002 whenever the dependency file(s) has changed.
3003 This should only be necessary
3004 for cases where the dependency
3005 is not caught by a Scanner
3009 env.Depends('foo', 'other-input-file-for-foo')
3012 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3014 .RI env.Dictionary([ vars ])
3015 Returns a dictionary object
3016 containing copies of all of the
3017 construction variables in the environment.
3018 If there are any variable names specified,
3019 only the specified construction
3020 variables are returned in the dictionary.
3023 dict = env.Dictionary()
3024 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3027 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3029 .RI Dir( name ", [" directory ])
3031 .RI env.Dir( name ", [" directory ])
3032 This returns a Directory Node,
3033 an object that represents the specified directory
3036 can be a relative or absolute path.
3038 is an optional directory that will be used as the parent directory.
3041 is specified, the current script's directory is used as the parent.
3043 Directory Nodes can be used anywhere you
3044 would supply a string as a directory name
3045 to a Builder method or function.
3046 Directory Nodes have attributes and methods
3047 that are useful in many situations;
3048 see "File and Directory Nodes," below.
3050 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3052 .RI env.Dump([ key ])
3053 Returns a pretty printable representation of the environment.
3057 should be a string containing the name of the variable of interest.
3062 print env.Dump('CCCOM')
3066 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3076 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3079 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3084 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3086 .RI EnsurePythonVersion( major ", " minor )
3088 .RI env.EnsurePythonVersion( major ", " minor )
3089 Ensure that the Python version is at least
3092 print out an error message and exit SCons with a non-zero exit code if the
3093 actual Python version is not late enough.
3096 EnsurePythonVersion(2,2)
3099 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3101 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3103 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3104 Ensure that the SCons version is at least
3107 .IR major.minor.revision .
3112 print out an error message and exit SCons with a non-zero exit code if the
3113 actual SCons version is not late enough.
3116 EnsureSConsVersion(0,14)
3118 EnsureSConsVersion(0,96,90)
3121 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3123 .RI Environment([ key = value ", ...])"
3125 .RI env.Environment([ key = value ", ...])"
3126 Return a new construction environment
3127 initialized with the specified
3131 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3133 .RI Execute( action ", [" strfunction ", " varlist ])
3135 .RI env.Execute( action ", [" strfunction ", " varlist ])
3136 Executes an Action object.
3139 may be an Action object
3140 (see the section "Action Objects,"
3141 below, for a complete explanation of the arguments and behavior),
3142 or it may be a command-line string,
3144 or executable Python function,
3145 each of which will be converted
3146 into an Action object
3148 The exit value of the command
3149 or return value of the Python function
3152 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3156 .RI env.Exit([ value ])
3162 A default exit value of
3165 is used if no value is specified.
3167 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3171 .RI env.Export( vars )
3174 to export a list of variables from the current
3175 SConscript file to all other SConscript files.
3176 The exported variables are kept in a global collection,
3177 so subsequent calls to
3179 will over-write previous exports that have the same name.
3180 Multiple variable names can be passed to
3182 as separate arguments or as a list. A dictionary can be used to map
3183 variables to a different name when exported. Both local variables and
3184 global variables can be exported.
3189 # Make env available for all SConscript files to Import().
3193 # Make env and package available for all SConscript files:.
3194 Export("env", "package")
3196 # Make env and package available for all SConscript files:
3197 Export(["env", "package"])
3199 # Make env available using the name debug:.
3200 Export({"debug":env})
3206 function supports an
3208 argument that makes it easier to to export a variable or
3209 set of variables to a single SConscript file.
3210 See the description of the
3214 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3216 .RI File( name ", [" directory ])
3218 .RI env.File( name ", [" directory ])
3221 an object that represents the specified file
3224 can be a relative or absolute path.
3226 is an optional directory that will be used as the parent directory.
3228 File Nodes can be used anywhere you
3229 would supply a string as a file name
3230 to a Builder method or function.
3231 File Nodes have attributes and methods
3232 that are useful in many situations;
3233 see "File and Directory Nodes," below.
3235 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3237 .RI FindFile( file ", " dirs )
3239 .RI env.FindFile( file ", " dirs )
3242 in the path specified by
3245 may be a list of file names or a single file name. In addition to searching
3246 for files that exist in the filesytem, this function also searches for
3247 derived files that have not yet been built.
3250 foo = env.FindFile('foo', ['dir1', 'dir2'])
3253 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3255 .RI Flatten( sequence )
3257 .RI env.Flatten( sequence )
3258 Takes a sequence (that is, a Python list or tuple)
3259 that may contain nested sequences
3260 and returns a flattened list containing
3261 all of the individual elements in any sequence.
3262 This can be helpful for collecting
3263 the lists returned by calls to Builders;
3264 other Builders will automatically
3265 flatten lists specified as input,
3266 but direct Python manipulation of
3267 these lists does not:
3270 foo = Object('foo.c')
3271 bar = Object('bar.c')
3273 # Because `foo' and `bar' are lists returned by the Object() Builder,
3274 # `objects' will be a list containing nested lists:
3275 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3277 # Passing such a list to another Builder is all right because
3278 # the Builder will flatten the list automatically:
3279 Program(source = objects)
3281 # If you need to manipulate the list directly using Python, you need to
3282 # call Flatten() yourself, or otherwise handle nested lists:
3283 for object in Flatten(objects):
3287 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3289 .RI GetBuildPath( file ", [" ... ])
3291 .RI env.GetBuildPath( file ", [" ... ])
3294 path name (or names) for the specified
3302 Nodes or strings representing path names.
3304 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3308 .RI env.GetLaunchDir()
3309 Returns the absolute path name of the directory from which
3312 was initially invoked.
3313 This can be useful when using the
3318 options, which internally
3319 change to the directory in which the
3323 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3325 .RI GetOption( name )
3327 .RI env.GetOption( name )
3328 This function provides a way to query a select subset of the scons command line
3329 options from a SConscript file. See
3331 for a description of the options available.
3333 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3335 '\".RI GlobalBuilders( flag )
3339 '\"adds the names of the default builders
3340 '\"(Program, Library, etc.)
3341 '\"to the global name space
3342 '\"so they can be called without an explicit construction environment.
3343 '\"(This is the default.)
3347 '\"the names of the default builders are removed
3348 '\"from the global name space
3349 '\"so that an explicit construction environment is required
3350 '\"to call all builders.
3352 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3356 .RI env.Help( text )
3357 This specifies help text to be printed if the
3359 argument is given to
3363 is called multiple times, the text is appended together in the order
3368 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3370 .RI Ignore( target ", " dependency )
3372 .RI env.Ignore( target ", " dependency )
3373 The specified dependency file(s)
3374 will be ignored when deciding if
3375 the target file(s) need to be rebuilt.
3378 env.Ignore('foo', 'foo.c')
3379 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3382 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3386 .RI env.Import( vars )
3389 to import a list of variables into the current SConscript file. This
3390 will import variables that were exported with
3396 Variables exported by
3399 Multiple variable names can be passed to
3401 as separate arguments or as a list. The variable "*" can be used
3402 to import all variables.
3407 Import("env", "variable")
3408 Import(["env", "variable"])
3412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3414 .RI Install( dir ", " source )
3416 .RI env.Install( dir ", " source )
3417 Installs one or more files in a destination directory.
3418 The file names remain the same.
3421 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3424 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3426 .RI InstallAs( target ", " source )
3428 .RI env.InstallAs( target ", " source )
3429 Installs one or more files as specific file names,
3430 allowing changing a file name as part of the
3432 It is an error if the target and source
3433 list different numbers of files.
3436 env.InstallAs(target = '/usr/local/bin/foo',
3437 source = 'foo_debug')
3438 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3439 source = ['libFOO.a', 'libBAR.a'])
3442 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3444 .RI Literal( string )
3446 .RI env.Literal( string )
3449 will be preserved as-is
3450 and not have construction variables expanded.
3452 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3454 .RI Local( targets )
3456 .RI env.Local( targets )
3459 will have copies made in the local tree,
3460 even if an already up-to-date copy
3461 exists in a repository.
3462 Returns a list of the target Node or Nodes.
3464 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3466 .RI env.ParseConfig( command ", [" function ", " unique ])
3469 to modify the environment as specified by the output of
3473 expects the output of a typical
3477 and adds the options
3478 to the appropriate construction variables.
3480 duplicate values are not
3481 added to any construction variables;
3504 construction variables,
3508 option gets added to both the
3515 option gets added to the
3518 Any other strings not associated with options
3519 are assumed to be the names of libraries
3522 construction variable.
3524 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3526 .RI ParseDepends( filename ", [" must_exist ])
3528 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3529 Parses the contents of the specified
3531 as a list of dependencies in the style of
3535 and explicitly establishes all of the listed dependencies.
3544 argument may be set to a non-zero
3547 throw an exception and
3548 generate an error if the file does not exist,
3549 or is otherwise inaccessible.
3553 argument may be set to a non-zero
3556 thrown an exception and
3558 if the file contains dependency
3559 information for more than one target.
3560 This can provide a small sanity check
3561 for files intended to be generated
3562 by, for example, the
3565 which should typically only
3566 write dependency information for
3567 one output file into a corresponding
3573 and all of the files listed therein
3574 will be interpreted relative to
3575 the directory of the
3577 file which calls the
3581 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3584 A factory function that
3585 returns a Builder object
3586 to be used to fetch source files
3587 from the Perforce source code management system.
3588 The returned Builder
3589 is intended to be passed to the
3594 env.SourceCode('.', env.Perforce())
3597 Perforce uses a number of external
3598 environment variables for its operation.
3599 Consequently, this function adds the
3600 following variables from the user's external environment
3601 to the construction environment's
3614 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3616 .RI Platform( string )
3617 Returns a callable object
3618 that can be used to initialize
3619 a construction environment using the
3620 platform keyword of the Environment() method:
3623 env = Environment(platform = Platform('win32'))
3626 .RI env.Platform( string )
3627 Applies the callable object for the specified platform
3629 to the environment through which the method was called.
3632 env.Platform('posix')
3641 variables from the user's external environment
3642 to the construction environment's
3645 This is so that any executed commands
3646 that use sockets to connect with other systems
3647 (such as fetching source files from
3648 external CVS repository specifications like
3649 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3650 will work on Win32 systems.
3652 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3654 .RI Precious( target ", ...)"
3656 .RI env.Precious( target ", ...)"
3659 as precious so it is not deleted before it is rebuilt. Normally
3661 deletes a target before building it.
3662 Multiple targets can be passed in to a single call to
3665 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3667 .RI env.Prepend( key = val ", [...])"
3668 Appends the specified keyword arguments
3669 to the beginning of construction variables in the environment.
3670 If the Environment does not have
3671 the specified construction variable,
3672 it is simply added to the environment.
3673 If the values of the construction variable
3674 and the keyword argument are the same type,
3675 then the two values will be simply added together.
3676 Otherwise, the construction variable
3677 and the value of the keyword argument
3678 are both coerced to lists,
3679 and the lists are added together.
3680 (See also the Append method, above.)
3683 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3686 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3688 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3689 This appends new path elements to the given path in the
3690 specified external environment
3694 any particular path once (leaving the first one it encounters and
3695 ignoring the rest, to preserve path order),
3696 and to help assure this,
3697 will normalize all paths (using
3700 .BR os.path.normcase ).
3701 This can also handle the
3702 case where the given old path variable is a list instead of a
3703 string, in which case a list will be returned instead of a string.
3707 print 'before:',env['ENV']['INCLUDE']
3708 include_path = '/foo/bar:/foo'
3709 env.PrependENVPath('INCLUDE', include_path)
3710 print 'after:',env['ENV']['INCLUDE']
3714 after: /foo/bar:/foo:/biz
3717 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3719 .RI env.AppendUnique( key = val ", [...])"
3720 Appends the specified keyword arguments
3721 to the beginning of construction variables in the environment.
3722 If the Environment does not have
3723 the specified construction variable,
3724 it is simply added to the environment.
3725 If the construction variable being appended to is a list,
3726 then any value(s) that already exist in the
3727 construction variable will
3729 be added again to the list.
3732 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3735 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3738 A factory function that
3739 returns a Builder object
3740 to be used to fetch source files
3742 The returned Builder
3743 is intended to be passed to the
3748 env.SourceCode('.', env.RCS())
3753 will fetch source files
3754 from RCS subdirectories automatically,
3756 as demonstrated in the above example
3757 should only be necessary if
3758 you are fetching from
3761 directory as the source files,
3762 or if you need to explicitly specify RCS
3763 for a specific subdirectory.
3765 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3767 .RI env.Replace( key = val ", [...])"
3768 Replaces construction variables in the Environment
3769 with the specified keyword arguments.
3772 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3777 .RI Repository( directory )
3779 .RI env.Repository( directory )
3782 is a repository to be searched for files.
3786 and each one adds to the list of
3787 repositories that will be searched.
3791 a repository is a copy of the source tree,
3792 from the top-level directory on down,
3794 both source files and derived files
3795 that can be used to build targets in
3796 the local source tree.
3797 The canonical example would be an
3798 official source tree maintained by an integrator.
3799 If the repository contains derived files,
3800 then the derived files should have been built using
3802 so that the repository contains the necessary
3803 signature information to allow
3805 to figure out when it is appropriate to
3806 use the repository copy of a derived file,
3807 instead of building one locally.
3809 Note that if an up-to-date derived file
3810 already exists in a repository,
3814 make a copy in the local directory tree.
3815 In order to guarantee that a local copy
3821 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3826 what variable(s) to use as the return value(s) of the current SConscript
3827 file. These variables will be returned to the "calling" SConscript file
3828 as the return value(s) of
3830 Multiple variable names should be passed to
3836 Return(["foo", "bar"])
3839 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3841 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3843 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3844 Creates a Scanner object for
3847 See the section "Scanner Objects,"
3848 below, for a complete explanation of the arguments and behavior.
3850 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3853 A factory function that
3854 returns a Builder object
3855 to be used to fetch source files
3857 The returned Builder
3858 is intended to be passed to the
3863 env.SourceCode('.', env.SCCS())
3868 will fetch source files
3869 from SCCS subdirectories automatically,
3871 as demonstrated in the above example
3872 should only be necessary if
3873 you are fetching from
3876 directory as the source files,
3877 or if you need to explicitly specify SCCS
3878 for a specific subdirectory.
3880 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3882 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3884 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3886 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3888 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3892 one or more subsidiary SConscript (configuration) files.
3893 There are two ways to call the
3897 The first way you can call
3899 is to explicitly specify one or more
3901 as the first argument.
3902 A single script may be specified as a string;
3903 multiple scripts must be specified as a list
3904 (either explicitly or as created by
3908 The second way you can call
3910 is to specify a list of (sub)directory names
3917 execute a subsidiary configuration file named
3919 in each of the specified directories.
3920 You may specify a name other than
3922 by supplying an optional
3928 argument provides a list of variable names or a dictionary of
3929 named values to export to the
3931 These variables are locally exported only to the specified
3933 and do not affect the
3934 global pool of variables used by
3938 '\"If multiple dirs are provided,
3939 '\"each script gets a fresh export.
3944 function to import the variables.
3948 argument specifies that all of the target files
3949 (for example, object files and executables)
3950 that would normally be built in the subdirectory in which
3952 resides should actually
3956 is interpreted relative to the directory
3957 of the calling SConscript file.
3961 argument specifies that the
3962 source files from which
3963 the target files should be built
3967 is interpreted relative to the directory
3968 of the calling SConscript file.
3972 will link or copy (depending on the platform)
3973 all the source files into the build directory.
3974 This behavior may be disabled by
3975 setting the optional
3978 (it is set to 1 by default),
3981 will refer directly to
3982 the source files in their source directory
3983 when building target files.
3986 is usually safe, and always more efficient
3989 but it may cause build problems in certain end-cases,
3990 such as compiling from source files that
3991 are generated by the build.)
3993 Any variables returned by
3997 will be returned by the call to
4003 SConscript('subdir/SConscript')
4004 foo = SConscript('sub/SConscript', exports='env')
4005 SConscript('dir/SConscript', exports=['env', 'variable'])
4006 SConscript('src/SConscript', build_dir='build', duplicate=0)
4007 SConscript('bld/SConscript', src_dir='src', exports='env variable')
4008 SConscript(dirs=['sub1', 'sub2'])
4009 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
4012 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4014 .RI SConscriptChdir( value )
4016 .RI env.SConscriptChdir( value )
4019 changes its working directory
4020 to the directory in which each
4021 subsidiary SConscript file lives.
4022 This behavior may be disabled
4023 by specifying either:
4027 env.SConscriptChdir(0)
4032 will stay in the top-level directory
4033 while reading all SConscript files.
4034 (This may be necessary when building from repositories,
4035 when all the directories in which SConscript files may be found
4036 don't necessarily exist locally.)
4038 You may enable and disable
4039 this ability by calling
4046 SConscript('foo/SConscript') # will not chdir to foo
4047 env.SConscriptChdir(1)
4048 SConscript('bar/SConscript') # will chdir to bar
4051 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4053 .RI SConsignFile([ file , dbm_module ])
4055 .RI env.SConsignFile([ file , dbm_module ])
4058 to store all file signatures
4059 in the specified database
4066 (The actual file name(s) stored on disk
4067 may have an appropriated suffix appended
4072 is not an absolute path name,
4073 the file is placed in the same directory as the top-level
4083 will store file signatures
4086 file in each directory,
4087 not in one global database file.
4088 (This was the default behavior
4089 prior to SCons 0.96.91 and 0.97.)
4093 argument can be used to specify
4094 which Python database module
4095 The default is to use a custom
4097 module that uses pickled
4098 Python data structures,
4099 and which works on all Python versions from 1.5.2 on.
4104 # Explicitly stores signatures in ".sconsign.dblite"
4105 # in the top-level SConstruct directory (the
4106 # default behavior).
4109 # Stores signatures in the file "etc/scons-signatures"
4110 # relative to the top-level SConstruct directory.
4111 SConsignFile("etc/scons-signatures")
4113 # Stores signatures in the specified absolute file name.
4114 SConsignFile("/home/me/SCons/signatures")
4116 # Stores signatures in a separate .sconsign file
4117 # in each directory.
4121 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4123 .RI env.SetDefault(key = val ", [...])"
4124 Sets construction variables to default values specified with the keyword
4125 arguments if (and only if) the variables are not already set.
4126 The following statements are equivalent:
4129 env.SetDefault(FOO = 'foo')
4131 if not env.has_key('FOO'): env['FOO'] = 'foo'
4134 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4136 .RI SetOption( name ", " value )
4138 .RI env.SetOption( name ", " value )
4139 This function provides a way to set a select subset of the scons command
4140 line options from a SConscript file. The options supported are:
4142 which corresponds to -c, --clean, and --remove;
4145 corresponds to --duplicate;
4147 which corresponds to --implicit-cache;
4149 which corresponds to --max-drift;
4151 which corresponds to -j and --jobs.
4152 See the documentation for the
4153 corresponding command line object for information about each specific
4157 SetOption('max_drift', 1)
4160 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4162 .RI SideEffect( side_effect ", " target )
4164 .RI env.SideEffect( side_effect ", " target )
4167 as a side effect of building
4173 can be a list, a file name, or a node.
4174 A side effect is a target that is created
4175 as a side effect of building other targets.
4176 For example, a Windows PDB
4177 file is created as a side effect of building the .obj
4178 files for a static library.
4179 If a target is a side effect of multiple build commands,
4181 will ensure that only one set of commands
4182 is executed at a time.
4183 Consequently, you only need to use this method
4184 for side-effect targets that are built as a result of
4185 multiple build commands.
4187 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4189 .RI SourceCode( entries ", " builder )
4191 .RI env.SourceCode( entries ", " builder )
4192 Arrange for non-existent source files to
4193 be fetched from a source code management system
4198 may be a Node, string or list of both,
4199 and may represent either individual
4200 source files or directories in which
4201 source files can be found.
4203 For any non-existent source files,
4205 will search up the directory tree
4215 will not use a builder to fetch
4216 source files for the specified
4220 builder has been specified
4221 for a directory higher up the tree.
4225 fetch files from SCCS or RCS subdirectories
4226 without explicit configuration.
4227 This takes some extra processing time
4228 to search for the necessary
4229 source code management files on disk.
4230 You can avoid these extra searches
4231 and speed up your build a little
4232 by disabling these searches as follows:
4235 env.SourceCode('.', None)
4239 Note that if the specified
4241 is one you create by hand,
4242 it must have an associated
4243 construction environment to use
4244 when fetching a source file.
4247 provides a set of canned factory
4248 functions that return appropriate
4249 Builders for various popular
4250 source code management systems.
4251 Canonical examples of invocation include:
4254 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4255 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4256 env.SourceCode('/', env.RCS())
4257 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4258 env.SourceCode('no_source.c', None)
4260 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4262 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4264 .RI env.subst( string )
4265 Performs construction variable interpolation
4266 on the specified string argument.
4269 print env.subst("The C compiler is: $CC")
4271 def compile(target, source, env):
4272 sourceDir = env.subst("${SOURCE.srcdir}")
4275 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4277 '\".RI Subversion( repository ", " module )
4278 '\"A factory function that
4279 '\"returns a Builder object
4280 '\"to be used to fetch source files
4281 '\"from the specified Subversion
4283 '\"The returned Builder
4284 '\"is intended to be passed to the
4288 '\"The optional specified
4290 '\"will be added to the beginning
4291 '\"of all repository path names;
4292 '\"this can be used, in essence,
4293 '\"to strip initial directory names
4294 '\"from the repository path names,
4295 '\"so that you only have to
4296 '\"replicate part of the repository
4297 '\"directory hierarchy in your
4298 '\"local build directory:
4301 '\"# Will fetch foo/bar/src.c
4302 '\"# from /usr/local/Subversion/foo/bar/src.c.
4303 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4305 '\"# Will fetch bar/src.c
4306 '\"# from /usr/local/Subversion/foo/bar/src.c.
4307 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4309 '\"# Will fetch src.c
4310 '\"# from /usr/local/Subversion/foo/bar/src.c.
4311 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4314 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4316 .RI SourceSignatures( type )
4318 .RI env.SourceSignatures( type )
4319 This function tells SCons what type of signature to use for source files:
4323 If the environment method is used,
4324 the specified type of source signature
4325 is only used when deciding whether targets
4326 built with that environment are up-to-date or must be rebuilt.
4327 If the global function is used,
4328 the specified type of source signature becomes the default
4329 used for all decisions
4330 about whether targets are up-to-date.
4332 "MD5" means the signature of a source file
4333 is the MD5 checksum of its contents.
4334 "timestamp" means the signature of a source file
4335 is its timestamp (modification time).
4336 There is no different between the two behaviors
4340 "MD5" signatures take longer to compute,
4341 but are more accurate than "timestamp" signatures.
4342 The default is "MD5".
4344 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4348 .RI env.Split( arg )
4349 Returns a list of file names or other objects.
4351 it will be split on strings of white-space characters
4353 making it easier to write long lists of file names.
4354 If arg is already a list,
4355 the list will be returned untouched.
4356 If arg is any other type of object,
4357 it will be returned as a list
4358 containing just the object.
4361 files = Split("f1.c f2.c f3.c")
4362 files = env.Split("f4.c f5.c f6.c")
4370 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4372 .RI TargetSignatures( type )
4374 .RI env.TargetSignatures( type )
4375 This function tells SCons what type of signatures to use
4380 If the environment method is used,
4381 the specified type of signature is only used
4382 for targets built with that environment.
4383 If the global function is used,
4384 the specified type of signature becomes the default
4385 used for all target files that
4386 don't have an explicit target signature type
4387 specified for their environments.
4389 "build" means the signature of a target file
4390 is made by concatenating all of the
4391 signatures of all its source files.
4392 "content" means the signature of a target
4393 file is an MD5 checksum of its contents.
4394 "build" signatures are usually faster to compute,
4395 but "content" signatures can prevent unnecessary rebuilds
4396 when a target file is rebuilt to the exact same contents
4397 as the previous build.
4398 The default is "build".
4400 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4402 .RI Tool( string [, toolpath ", " **kw ])
4403 Returns a callable object
4404 that can be used to initialize
4405 a construction environment using the
4406 tools keyword of the Environment() method.
4407 The object may be called with a construction
4408 environment as an argument,
4409 in which case the object will
4410 add the necessary variables
4411 to the construction environment
4412 and the name of the tool will be added to the
4414 construction variable.
4416 Additional keyword arguments are passed to the tool's
4421 env = Environment(tools = [ Tool('msvc') ])
4425 t(env) # adds 'msvc' to the TOOLS variable
4426 u = Tool('opengl', toolpath = ['tools'])
4427 u(env) # adds 'opengl' to the TOOLS variable
4430 .RI env.Tool( string [, toolpath ", " **kw ])
4431 Applies the callable object for the specified tool
4433 to the environment through which the method was called.
4435 Additional keyword arguments are passed to the tool's
4441 env.Tool('opengl', toolpath = ['build/tools'])
4444 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4448 .RI env.Value( value )
4449 Returns a Node object representing the specified Python value. Value
4450 nodes can be used as dependencies of targets. If the result of
4453 changes between SCons runs, any targets depending on
4455 will be rebuilt. When using timestamp source signatures, Value nodes'
4456 timestamps are equal to the system time when the node is created.
4459 def create(target, source, env):
4460 f = open(str(target[0]), 'wb')
4461 f.write('prefix=' + source[0].get_contents())
4463 prefix = ARGUMENTS.get('prefix', '/usr/local')
4465 env['BUILDERS']['Config'] = Builder(action = create)
4466 env.Config(target = 'package-config', source = Value(prefix))
4469 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4471 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4473 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4475 Searches for the specified executable
4477 returning the full path name to the program
4479 and returning None if not.
4480 Searches the specified
4482 the value of the calling environment's PATH
4483 (env['ENV']['PATH']),
4484 or the user's current external PATH
4485 (os.environ['PATH'])
4487 On Win32 systems, searches for executable
4488 programs with any of the file extensions
4489 listed in the specified
4491 the calling environment's PATHEXT
4492 (env['ENV']['PATHEXT'])
4493 or the user's current PATHEXT
4494 (os.environ['PATHEXT'])
4502 .SS SConscript Variables
4503 In addition to the global functions and methods,
4505 supports a number of Python variables
4506 that can be used in SConscript files
4507 to affect how you want the build to be performed.
4508 These variables may be accessed from custom Python modules that you
4509 import into an SConscript file by adding the following
4510 to the Python module:
4513 from SCons.Script import *
4516 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4521 arguments specified on the command line.
4522 Each element in the list is a tuple
4524 .RI ( keyword , value )
4530 elements of the tuple
4532 subscripting for element
4536 of the tuple, respectively.
4539 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4540 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4541 third_tuple = ARGLIST[2]
4542 print "third keyword, value =", third_tuple[0], third_tuple[1]
4543 for key, value in ARGLIST:
4544 # process key and value
4547 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4550 A dictionary of all the
4552 arguments specified on the command line.
4553 The dictionary is not in order,
4554 and if a given keyword has
4555 more than one value assigned to it
4556 on the command line,
4557 the last (right-most) value is
4563 if ARGUMENTS.get('debug', 0):
4564 env = Environment(CCFLAGS = '-g')
4569 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4572 A list of the targets which
4574 will actually try to build,
4575 regardless of whether they were specified on
4576 the command line or via the
4579 The elements of this list may be strings
4581 nodes, so you should run the list through the Python
4583 function to make sure any Node path names
4584 are converted to strings.
4586 Because this list may be taken from the
4587 list of targets specified using the
4590 the contents of the list may change
4591 on each successive call to
4596 for additional information.
4599 if 'foo' in BUILD_TARGETS:
4600 print "Don't forget to test the `foo' program!"
4601 if 'special/program' in BUILD_TARGETS:
4602 SConscript('special')
4607 list only contains targets expected listed
4608 on the command line or via calls to the
4613 contain all dependent targets that will be built as
4614 a result of making the sure the explicitly-specified
4615 targets are up to date.
4617 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4619 COMMAND_LINE_TARGETS
4620 A list of the targets explicitly specified on
4622 If there are no targets specified on the command line,
4624 This can be used, for example,
4625 to take specific actions only
4626 when a certain target or targets
4627 is explicitly being built:
4630 if 'foo' in COMMAND_LINE_TARGETS:
4631 print "Don't forget to test the `foo' program!"
4632 if 'special/program' in COMMAND_LINE_TARGETS:
4633 SConscript('special')
4636 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4639 A list of the target
4641 that have been specified using the
4644 The elements of the list are nodes,
4645 so you need to run them through the Python
4647 function to get at the path name for each Node.
4650 print str(DEFAULT_TARGETS[0])
4651 if 'foo' in map(str, DEFAULT_TARGETS):
4652 print "Don't forget to test the `foo' program!"
4657 list change on on each successive call to the
4662 print map(str, DEFAULT_TARGETS) # originally []
4664 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4666 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4668 print map(str, DEFAULT_TARGETS) # back to []
4671 Consequently, be sure to use
4673 only after you've made all of your
4676 or else simply be careful of the order
4677 of these statements in your SConscript files
4678 so that you don't look for a specific
4679 default target before it's actually been added to the list.
4681 .SS Construction Variables
4682 .\" XXX From Gary Ruben, 23 April 2002:
4683 .\" I think it would be good to have an example with each construction
4684 .\" variable description in the documentation.
4686 .\" CC The C compiler
4687 .\" Example: env["CC"] = "c68x"
4688 .\" Default: env["CC"] = "cc"
4690 .\" CCCOM The command line ...
4692 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4693 .\" env["CC"] = "c68x"
4694 .\" env["CFLAGS"] = "-ps -qq -mr"
4695 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4697 .\" (I dunno what this is ;-)
4698 A construction environment has an associated dictionary of
4699 .I construction variables
4700 that are used by built-in or user-supplied build rules.
4701 Construction variables must follow the same rules for
4703 the initial character must be an underscore or letter,
4704 followed by any number of underscores, letters, or digits.
4706 A number of useful construction variables are automatically defined by
4707 scons for each supported platform, and additional construction variables
4708 can be defined by the user. The following is a list of the automatically
4709 defined construction variables:
4712 The static library archiver.
4715 The command line used to generate a static library from object files.
4718 The string displayed when an object file
4719 is generated from an assembly-language source file.
4720 If this is not set, then $ARCOM (the command line) is displayed.
4723 env = Environment(ARCOMSTR = "Archiving $TARGET")
4727 General options passed to the static library archiver.
4733 The command line used to generate an object file
4734 from an assembly-language source file.
4737 The string displayed when an object file
4738 is generated from an assembly-language source file.
4739 If this is not set, then $ASCOM (the command line) is displayed.
4742 env = Environment(ASCOMSTR = "Assembling $TARGET")
4746 General options passed to the assembler.
4749 The command line used to assemble an assembly-language
4750 source file into an object file
4751 after first running the file through the C preprocessor.
4752 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4753 are included on this command line.
4756 The string displayed when an object file
4757 is generated from an assembly-language source file
4758 after first running the file through the C preprocessor.
4759 If this is not set, then $ASPPCOM (the command line) is displayed.
4762 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4766 General options when an assembling an assembly-language
4767 source file into an object file
4768 after first running the file through the C preprocessor.
4769 The default is to use the value of $ASFLAGS.
4772 The bibliography generator for the TeX formatter and typesetter and the
4773 LaTeX structured formatter and typesetter.
4776 The command line used to call the bibliography generator for the
4777 TeX formatter and typesetter and the LaTeX structured formatter and
4781 The string displayed when generating a bibliography
4783 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4786 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4791 General options passed to the bibliography generator for the TeX formatter
4792 and typesetter and the LaTeX structured formatter and typesetter.
4795 The BitKeeper executable.
4798 The command line for
4799 fetching source files using BitKeeper.
4802 The string displayed when fetching
4803 a source file using BitKeeper.
4804 If this is not set, then $BITKEEPERCOM
4805 (the command line) is displayed.
4808 The command ($BITKEEPER) and subcommand
4809 for fetching source files using BitKeeper.
4811 .IP BITKEEPERGETFLAGS
4812 Options that are passed to the BitKeeper
4817 A dictionary mapping the names of the builders
4818 available through this environment
4819 to underlying Builder objects.
4821 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4822 are available by default.
4823 If you initialize this variable when an
4824 Environment is created:
4827 env = Environment(BUILDERS = {'NewBuilder' : foo})
4830 the default Builders will no longer be available.
4831 To use a new Builder object in addition to the default Builders,
4832 add your new Builder object like this:
4836 env.Append(BUILDERS = {'NewBuilder' : foo})
4843 env['BUILDERS]['NewBuilder'] = foo
4850 The command line used to compile a C source file to a (static) object file.
4851 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4852 are included on this command line.
4855 The string displayed when a C source file
4856 is compiled to a (static) object file.
4857 If this is not set, then $CCCOM (the command line) is displayed.
4860 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4864 General options that are passed to the C compiler.
4867 The suffix for C source files.
4868 This is used by the internal CFile builder
4869 when generating C files from Lex (.l) or YACC (.y) input files.
4870 The default suffix, of course, is
4873 On case-insensitive systems (like Win32),
4880 The version number of the C compiler.
4881 This may or may not be set,
4882 depending on the specific C compiler being used.
4885 A function used to produce variables like $_CPPINCFLAGS. It takes
4887 arguments: a prefix to concatenate onto each element, a list of
4888 elements, a suffix to concatenate onto each element, an environment
4889 for variable interpolation, and an optional function that will be
4890 called to transform the list before concatenation.
4893 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4897 A platform independent specification of C preprocessor definitions.
4898 The definitions will be added to command lines
4899 through the automatically-generated
4900 $_CPPDEFFLAGS construction variable (see below),
4901 which is constructed according to
4902 the type of value of $CPPDEFINES:
4905 If $CPPDEFINES is a string,
4907 $CPPDEFPREFIX and $CPPDEFSUFFIX
4908 construction variables
4909 will be added to the beginning and end.
4912 # Will add -Dxyz to POSIX compiler command lines,
4913 # and /Dxyz to Microsoft Visual C++ command lines.
4914 env = Environment(CPPDEFINES='xyz')
4918 If $CPPDEFINES is a list,
4920 $CPPDEFPREFIX and $CPPDEFSUFFIX
4921 construction variables
4922 will be appended to the beginning and end
4923 of each element in the list.
4924 If any element is a list or tuple,
4925 then the first item is the name being
4926 defined and the second item is its value:
4929 # Will add -DB=2 -DA to POSIX compiler command lines,
4930 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4931 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4935 If $CPPDEFINES is a dictionary,
4937 $CPPDEFPREFIX and $CPPDEFSUFFIX
4938 construction variables
4939 will be appended to the beginning and end
4940 of each item from the dictionary.
4941 The key of each dictionary item
4942 is a name being defined
4943 to the dictionary item's corresponding value;
4946 then the name is defined without an explicit value.
4947 Note that the resulting flags are sorted by keyword
4948 to ensure that the order of the options on the
4949 command line is consistent each time
4954 # Will add -DA -DB=2 to POSIX compiler command lines,
4955 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4956 env = Environment(CPPDEFINES={'B':2, 'A':None})
4960 An automatically-generated construction variable
4961 containing the C preprocessor command-line options
4963 The value of $_CPPDEFFLAGS is created
4964 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4965 to the beginning and end
4966 of each directory in $CPPDEFINES.
4969 The prefix used to specify preprocessor definitions
4970 on the C compiler command line.
4971 This will be appended to the beginning of each definition
4972 in the $CPPDEFINES construction variable
4973 when the $_CPPDEFFLAGS variable is automatically generated.
4976 The suffix used to specify preprocessor definitions
4977 on the C compiler command line.
4978 This will be appended to the end of each definition
4979 in the $CPPDEFINES construction variable
4980 when the $_CPPDEFFLAGS variable is automatically generated.
4983 User-specified C preprocessor options.
4984 These will be included in any command that uses the C preprocessor,
4985 including not just compilation of C and C++ source files
4986 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4987 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4988 $F77PPCOM and $SHF77PPCOM command lines
4989 used to compile a Fortran source file,
4990 and the $ASPPCOM command line
4991 used to assemble an assembly language source file,
4992 after first running each file through the C preprocessor.
4993 Note that this variable does
4997 (or similar) include search path options
4998 that scons generates automatically from $CPPPATH.
5002 for the variable that expands to those options.
5005 An automatically-generated construction variable
5006 containing the C preprocessor command-line options
5007 for specifying directories to be searched for include files.
5008 The value of $_CPPINCFLAGS is created
5009 by appending $INCPREFIX and $INCSUFFIX
5010 to the beginning and end
5011 of each directory in $CPPPATH.
5014 The list of directories that the C preprocessor will search for include
5015 directories. The C/C++ implicit dependency scanner will search these
5016 directories for include files. Don't explicitly put include directory
5017 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
5018 and the directories will not be searched by the dependency scanner. Note:
5019 directory names in CPPPATH will be looked-up relative to the SConscript
5020 directory when they are used in a command. To force
5022 to look-up a directory relative to the root of the source tree use #:
5025 env = Environment(CPPPATH='#/include')
5029 The directory look-up can also be forced using the
5034 include = Dir('include')
5035 env = Environment(CPPPATH=include)
5039 The directory list will be added to command lines
5040 through the automatically-generated
5042 construction variable,
5043 which is constructed by
5044 appending the values of the
5045 $INCPREFIX and $INCSUFFIX
5046 construction variables
5047 to the beginning and end
5048 of each directory in $CPPPATH.
5049 Any command lines you define that need
5050 the CPPPATH directory list should
5051 include $_CPPINCFLAGS:
5054 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5058 The list of suffixes of files that will be scanned
5059 for C preprocessor implicit dependencies
5061 The default list is:
5064 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5065 ".h", ".H", ".hxx", ".hpp", ".hh",
5066 ".F", ".fpp", ".FPP",
5068 ".S", ".spp", ".SPP"]
5075 Options that are passed to the CVS checkout subcommand.
5078 The command line used to
5079 fetch source files from a CVS repository.
5082 The string displayed when fetching
5083 a source file from a CVS repository.
5084 If this is not set, then $CVSCOM
5085 (the command line) is displayed.
5088 General options that are passed to CVS.
5089 By default, this is set to
5091 to specify from where the files must be fetched.
5094 The path to the CVS repository.
5095 This is referenced in the default
5102 The suffix for C++ source files.
5103 This is used by the internal CXXFile builder
5104 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
5105 The default suffix is
5107 SCons also treats files with the suffixes
5116 suffixes as Objective C++ files.
5117 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5124 The command line used to compile a C++ source file to an object file.
5125 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
5126 are included on this command line.
5129 The string displayed when a C++ source file
5130 is compiled to a (static) object file.
5131 If this is not set, then $CXXCOM (the command line) is displayed.
5134 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5138 General options that are passed to the C++ compiler.
5139 By default, this includes the value of $CCFLAGS,
5140 so that setting $CCFLAGS affects both C and C++ compilation.
5141 If you want to add C++-specific flags,
5142 you must set or override the value of $CXXFLAGS.
5145 The version number of the C++ compiler.
5146 This may or may not be set,
5147 depending on the specific C++ compiler being used.
5150 A function that converts a file name into a Dir instance relative to the
5154 The list of suffixes of files that will be scanned
5155 for imported D package files.
5156 The default list is:
5163 The TeX DVI file to PDF file converter.
5166 General options passed to the TeX DVI file to PDF file converter.
5169 The command line used to convert TeX DVI files into a PDF file.
5172 The string displayed when a TeX DVI file
5173 is converted into a PDF file.
5174 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5177 The TeX DVI file to PostScript converter.
5180 General options passed to the TeX DVI file to PostScript converter.
5183 A dictionary of environment variables
5184 to use when invoking commands. When ENV is used in a command all list
5185 values will be joined using the path separator and any other non-string
5186 values will simply be coerced to a string.
5187 Note that, by default,
5191 propagate the environment in force when you
5194 to the commands used to build target files.
5195 This is so that builds will be guaranteed
5196 repeatable regardless of the environment
5197 variables set at the time
5201 If you want to propagate your
5202 environment variables
5203 to the commands executed
5204 to build target files,
5205 you must do so explicitly:
5209 env = Environment(ENV = os.environ)
5213 Note that you can choose only to propagate
5214 certain environment variables.
5218 environment variable,
5221 uses the same utilities
5222 as the invoking shell (or other process):
5227 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5231 A function that will be called to escape shell special characters in
5232 command lines. The function should take one argument: the command line
5233 string to escape; and should return the escaped command line.
5236 The Fortran 77 compiler.
5237 You should normally set the $FORTRAN variable,
5238 which specifies the default Fortran compiler
5239 for all Fortran versions.
5240 You only need to set $F77 if you need to use a specific compiler
5241 or compiler version for Fortran 77 files.
5244 The command line used to compile a Fortran 77 source file to an object file.
5245 You only need to set $F77COM if you need to use a specific
5246 command line for Fortran 77 files.
5247 You should normally set the $FORTRANCOM variable,
5248 which specifies the default command line
5249 for all Fortran versions.
5252 The string displayed when a Fortran 77 source file
5253 is compiled to an object file.
5254 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5257 General user-specified options that are passed to the Fortran 77 compiler.
5258 Note that this variable does
5262 (or similar) include search path options
5263 that scons generates automatically from $F77PATH.
5267 for the variable that expands to those options.
5268 You only need to set $F77FLAGS if you need to define specific
5269 user options for Fortran 77 files.
5270 You should normally set the $FORTRANFLAGS variable,
5271 which specifies the user-specified options
5272 passed to the default Fortran compiler
5273 for all Fortran versions.
5276 An automatically-generated construction variable
5277 containing the Fortran 77 compiler command-line options
5278 for specifying directories to be searched for include files.
5279 The value of $_F77INCFLAGS is created
5280 by appending $INCPREFIX and $INCSUFFIX
5281 to the beginning and end
5282 of each directory in $F77PATH.
5285 The list of directories that the Fortran 77 compiler will search for include
5286 directories. The implicit dependency scanner will search these
5287 directories for include files. Don't explicitly put include directory
5288 arguments in $F77FLAGS because the result will be non-portable
5289 and the directories will not be searched by the dependency scanner. Note:
5290 directory names in $F77PATH will be looked-up relative to the SConscript
5291 directory when they are used in a command. To force
5293 to look-up a directory relative to the root of the source tree use #:
5294 You only need to set $F77PATH if you need to define a specific
5295 include path for Fortran 77 files.
5296 You should normally set the $FORTRANPATH variable,
5297 which specifies the include path
5298 for the default Fortran compiler
5299 for all Fortran versions.
5302 env = Environment(F77PATH='#/include')
5306 The directory look-up can also be forced using the
5311 include = Dir('include')
5312 env = Environment(F77PATH=include)
5316 The directory list will be added to command lines
5317 through the automatically-generated
5319 construction variable,
5320 which is constructed by
5321 appending the values of the
5322 $INCPREFIX and $INCSUFFIX
5323 construction variables
5324 to the beginning and end
5325 of each directory in $F77PATH.
5326 Any command lines you define that need
5327 the F77PATH directory list should
5328 include $_F77INCFLAGS:
5331 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5335 The command line used to compile a Fortran 77 source file to an object file
5336 after first running the file through the C preprocessor.
5337 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5338 are included on this command line.
5339 You only need to set $F77PPCOM if you need to use a specific
5340 C-preprocessor command line for Fortran 77 files.
5341 You should normally set the $FORTRANPPCOM variable,
5342 which specifies the default C-preprocessor command line
5343 for all Fortran versions.
5346 The Fortran 90 compiler.
5347 You should normally set the $FORTRAN variable,
5348 which specifies the default Fortran compiler
5349 for all Fortran versions.
5350 You only need to set $F90 if you need to use a specific compiler
5351 or compiler version for Fortran 90 files.
5354 The command line used to compile a Fortran 90 source file to an object file.
5355 You only need to set $F90COM if you need to use a specific
5356 command line for Fortran 90 files.
5357 You should normally set the $FORTRANCOM variable,
5358 which specifies the default command line
5359 for all Fortran versions.
5362 The string displayed when a Fortran 90 source file
5363 is compiled to an object file.
5364 If this is not set, then $F90COM or $FORTRANCOM
5365 (the command line) is displayed.
5368 General user-specified options that are passed to the Fortran 90 compiler.
5369 Note that this variable does
5373 (or similar) include search path options
5374 that scons generates automatically from $F90PATH.
5378 for the variable that expands to those options.
5379 You only need to set $F90FLAGS if you need to define specific
5380 user options for Fortran 90 files.
5381 You should normally set the $FORTRANFLAGS variable,
5382 which specifies the user-specified options
5383 passed to the default Fortran compiler
5384 for all Fortran versions.
5387 An automatically-generated construction variable
5388 containing the Fortran 90 compiler command-line options
5389 for specifying directories to be searched for include files.
5390 The value of $_F90INCFLAGS is created
5391 by appending $INCPREFIX and $INCSUFFIX
5392 to the beginning and end
5393 of each directory in $F90PATH.
5396 The list of directories that the Fortran 90 compiler will search for include
5397 directories. The implicit dependency scanner will search these
5398 directories for include files. Don't explicitly put include directory
5399 arguments in $F90FLAGS because the result will be non-portable
5400 and the directories will not be searched by the dependency scanner. Note:
5401 directory names in $F90PATH will be looked-up relative to the SConscript
5402 directory when they are used in a command. To force
5404 to look-up a directory relative to the root of the source tree use #:
5405 You only need to set $F90PATH if you need to define a specific
5406 include path for Fortran 90 files.
5407 You should normally set the $FORTRANPATH variable,
5408 which specifies the include path
5409 for the default Fortran compiler
5410 for all Fortran versions.
5413 env = Environment(F90PATH='#/include')
5417 The directory look-up can also be forced using the
5422 include = Dir('include')
5423 env = Environment(F90PATH=include)
5427 The directory list will be added to command lines
5428 through the automatically-generated
5430 construction variable,
5431 which is constructed by
5432 appending the values of the
5433 $INCPREFIX and $INCSUFFIX
5434 construction variables
5435 to the beginning and end
5436 of each directory in $F90PATH.
5437 Any command lines you define that need
5438 the F90PATH directory list should
5439 include $_F90INCFLAGS:
5442 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5446 The command line used to compile a Fortran 90 source file to an object file
5447 after first running the file through the C preprocessor.
5448 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5449 are included on this command line.
5450 You only need to set $F90PPCOM if you need to use a specific
5451 C-preprocessor command line for Fortran 90 files.
5452 You should normally set the $FORTRANPPCOM variable,
5453 which specifies the default C-preprocessor command line
5454 for all Fortran versions.
5457 The Fortran 95 compiler.
5458 You should normally set the $FORTRAN variable,
5459 which specifies the default Fortran compiler
5460 for all Fortran versions.
5461 You only need to set $F95 if you need to use a specific compiler
5462 or compiler version for Fortran 95 files.
5465 The command line used to compile a Fortran 95 source file to an object file.
5466 You only need to set $F95COM if you need to use a specific
5467 command line for Fortran 95 files.
5468 You should normally set the $FORTRANCOM variable,
5469 which specifies the default command line
5470 for all Fortran versions.
5473 The string displayed when a Fortran 95 source file
5474 is compiled to an object file.
5475 If this is not set, then $F95COM or $FORTRANCOM
5476 (the command line) is displayed.
5479 General user-specified options that are passed to the Fortran 95 compiler.
5480 Note that this variable does
5484 (or similar) include search path options
5485 that scons generates automatically from $F95PATH.
5489 for the variable that expands to those options.
5490 You only need to set $F95FLAGS if you need to define specific
5491 user options for Fortran 95 files.
5492 You should normally set the $FORTRANFLAGS variable,
5493 which specifies the user-specified options
5494 passed to the default Fortran compiler
5495 for all Fortran versions.
5498 An automatically-generated construction variable
5499 containing the Fortran 95 compiler command-line options
5500 for specifying directories to be searched for include files.
5501 The value of $_F95INCFLAGS is created
5502 by appending $INCPREFIX and $INCSUFFIX
5503 to the beginning and end
5504 of each directory in $F95PATH.
5507 The list of directories that the Fortran 95 compiler will search for include
5508 directories. The implicit dependency scanner will search these
5509 directories for include files. Don't explicitly put include directory
5510 arguments in $F95FLAGS because the result will be non-portable
5511 and the directories will not be searched by the dependency scanner. Note:
5512 directory names in $F95PATH will be looked-up relative to the SConscript
5513 directory when they are used in a command. To force
5515 to look-up a directory relative to the root of the source tree use #:
5516 You only need to set $F95PATH if you need to define a specific
5517 include path for Fortran 95 files.
5518 You should normally set the $FORTRANPATH variable,
5519 which specifies the include path
5520 for the default Fortran compiler
5521 for all Fortran versions.
5524 env = Environment(F95PATH='#/include')
5528 The directory look-up can also be forced using the
5533 include = Dir('include')
5534 env = Environment(F95PATH=include)
5538 The directory list will be added to command lines
5539 through the automatically-generated
5541 construction variable,
5542 which is constructed by
5543 appending the values of the
5544 $INCPREFIX and $INCSUFFIX
5545 construction variables
5546 to the beginning and end
5547 of each directory in $F95PATH.
5548 Any command lines you define that need
5549 the F95PATH directory list should
5550 include $_F95INCFLAGS:
5553 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5557 The command line used to compile a Fortran 95 source file to an object file
5558 after first running the file through the C preprocessor.
5559 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5560 are included on this command line.
5561 You only need to set $F95PPCOM if you need to use a specific
5562 C-preprocessor command line for Fortran 95 files.
5563 You should normally set the $FORTRANPPCOM variable,
5564 which specifies the default C-preprocessor command line
5565 for all Fortran versions.
5568 The default Fortran compiler
5569 for all versions of Fortran.
5572 The command line used to compile a Fortran source file to an object file.
5573 By default, any options specified
5574 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5575 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5576 are included on this command line.
5579 The string displayed when a Fortran source file
5580 is compiled to an object file.
5581 If this is not set, then $FORTRANCOM
5582 (the command line) is displayed.
5585 General user-specified options that are passed to the Fortran compiler.
5586 Note that this variable does
5590 (or similar) include or module search path options
5591 that scons generates automatically from $FORTRANPATH.
5593 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5595 for the variables that expand those options.
5597 .IP _FORTRANINCFLAGS
5598 An automatically-generated construction variable
5599 containing the Fortran compiler command-line options
5600 for specifying directories to be searched for include
5601 files and module files.
5602 The value of $_FORTRANINCFLAGS is created
5603 by prepending/appending $INCPREFIX and $INCSUFFIX
5604 to the beginning and end
5605 of each directory in $FORTRANPATH.
5608 Directory location where the Fortran compiler should place
5609 any module files it generates. This variable is empty, by default. Some
5610 Fortran compilers will internally append this directory in the search path
5611 for module files, as well.
5613 .IP FORTRANMODDIRPREFIX
5614 The prefix used to specify a module directory on the Fortran compiler command
5616 This will be appended to the beginning of the directory
5617 in the $FORTRANMODDIR construction variables
5618 when the $_FORTRANMODFLAG variables is automatically generated.
5620 .IP FORTRANMODDIRSUFFIX
5621 The suffix used to specify a module directory on the Fortran compiler command
5623 This will be appended to the beginning of the directory
5624 in the $FORTRANMODDIR construction variables
5625 when the $_FORTRANMODFLAG variables is automatically generated.
5628 An automatically-generated construction variable
5629 containing the Fortran compiler command-line option
5630 for specifying the directory location where the Fortran
5631 compiler should place any module files that happen to get
5632 generated during compilation.
5633 The value of $_FORTRANMODFLAG is created
5634 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5635 to the beginning and end of the directory in $FORTRANMODDIR.
5637 .IP FORTRANMODPREFIX
5638 The module file prefix used by the Fortran compiler. SCons assumes that
5639 the Fortran compiler follows the quasi-standard naming convention for
5641 .I <module_name>.mod.
5642 As a result, this variable is left empty, by default. For situations in
5643 which the compiler does not necessarily follow the normal convention,
5644 the user may use this variable. Its value will be appended to every
5645 module file name as scons attempts to resolve dependencies.
5647 .IP FORTRANMODSUFFIX
5648 The module file suffix used by the Fortran compiler. SCons assumes that
5649 the Fortran compiler follows the quasi-standard naming convention for
5651 .I <module_name>.mod.
5652 As a result, this variable is set to ".mod", by default. For situations
5653 in which the compiler does not necessarily follow the normal convention,
5654 the user may use this variable. Its value will be appended to every
5655 module file name as scons attempts to resolve dependencies.
5658 The list of directories that the Fortran compiler will search for
5659 include files and (for some compilers) module files. The Fortran implicit
5660 dependency scanner will search these directories for include files (but
5661 not module files since they are autogenerated and, as such, may not
5662 actually exist at the time the scan takes place). Don't explicitly put
5663 include directory arguments in FORTRANFLAGS because the result will be
5664 non-portable and the directories will not be searched by the dependency
5665 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5666 to the SConscript directory when they are used in a command. To force
5668 to look-up a directory relative to the root of the source tree use #:
5671 env = Environment(FORTRANPATH='#/include')
5675 The directory look-up can also be forced using the
5680 include = Dir('include')
5681 env = Environment(FORTRANPATH=include)
5685 The directory list will be added to command lines
5686 through the automatically-generated
5688 construction variable,
5689 which is constructed by
5690 appending the values of the
5691 $INCPREFIX and $INCSUFFIX
5692 construction variables
5693 to the beginning and end
5694 of each directory in $FORTRANPATH.
5695 Any command lines you define that need
5696 the FORTRANPATH directory list should
5697 include $_FORTRANINCFLAGS:
5700 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5704 The command line used to compile a Fortran source file to an object file
5705 after first running the file through the C preprocessor.
5706 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5707 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5708 construction variables are included on this command line.
5711 The list of suffixes of files that will be scanned
5712 for Fortran implicit dependencies
5713 (INCLUDE lines & USE statements).
5714 The default list is:
5717 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5718 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5722 A function that converts a file name into a File instance relative to the
5726 On Mac OS X with gcc,
5727 a list containing the paths to search for frameworks.
5728 Used by the compiler to find framework-style includes like
5729 #include <Fmwk/Header.h>.
5730 Used by the linker to find user-specified frameworks when linking (see
5734 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
5739 ... -Fmyframeworkdir
5742 to the compiler and linker command lines.
5745 On Mac OS X with gcc, an automatically-generated construction variable
5746 containing the linker command-line options corresponding to FRAMEWORKPATH.
5748 .IP FRAMEWORKPATHPREFIX
5749 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
5750 (see $FRAMEWORKPATH).
5751 The default value is
5755 On Mac OS X with gcc,
5756 the prefix to be used for linking in frameworks
5758 The default value is
5762 On Mac OS X with gcc, a list of the framework names to be linked into a
5763 program or shared library or bundle.
5764 The default value is the empty list.
5767 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
5771 On Mac OS X with gcc,
5772 an automatically-generated construction variable
5773 containing the linker command-line options
5774 for linking with FRAMEWORKS.
5777 On Mac OS X with gcc,
5778 general user-supplied frameworks options to be added at
5779 the end of a command
5780 line building a loadable module.
5781 (This has been largely superceded by
5782 the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX,
5783 $FRAMWORKPREFIX and $FRAMEWORKS variables
5787 The Ghostscript program used to convert PostScript to PDF files.
5790 General options passed to the Ghostscript program
5791 when converting PostScript to PDF files.
5794 The Ghostscript command line used to convert PostScript to PDF files.
5797 The string displayed when
5798 Ghostscript is used to convert
5799 a PostScript file to a PDF file.
5800 If this is not set, then $GSCOM (the command line) is displayed.
5803 The list of suffixes of files that will be scanned
5804 for IDL implicit dependencies
5805 (#include or import lines).
5806 The default list is:
5813 The prefix used to specify an include directory on the C compiler command
5815 This will be appended to the beginning of each directory
5816 in the $CPPPATH and $FORTRANPATH construction variables
5817 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5818 variables are automatically generated.
5821 The suffix used to specify an include directory on the C compiler command
5823 This will be appended to the end of each directory
5824 in the $CPPPATH and $FORTRANPATH construction variables
5825 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5826 variables are automatically generated.
5829 A function to be called to install a file into a
5830 destination file name.
5831 The default function copies the file into the destination
5832 (and sets the destination file's mode and permission bits
5833 to match the source file's).
5834 The function takes the following arguments:
5837 def install(dest, source, env):
5841 is the path name of the destination file.
5843 is the path name of the source file.
5845 is the construction environment
5846 (a dictionary of construction values)
5847 in force for this file installation.
5849 .IP INTEL_C_COMPILER_VERSION
5850 Set by the "intelc" Tool
5851 to the major version number of the Intel C compiler
5855 The Java archive tool.
5858 The directory to which the Java archive tool should change
5864 The command line used to call the Java archive tool.
5867 The string displayed when the Java archive tool
5869 If this is not set, then $JARCOM (the command line) is displayed.
5872 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5876 General options passed to the Java archive tool.
5877 By default this is set to
5879 to create the necessary
5884 The suffix for Java archives:
5892 The command line used to compile a directory tree containing
5893 Java source files to
5894 corresponding Java class files.
5895 Any options specified in the $JAVACFLAGS construction variable
5896 are included on this command line.
5899 The string displayed when compiling
5900 a directory tree of Java source files to
5901 corresponding Java class files.
5902 If this is not set, then $JAVACCOM (the command line) is displayed.
5905 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5909 General options that are passed to the Java compiler.
5912 The directory in which Java class files may be found.
5913 This is stripped from the beginning of any Java .class
5914 file names supplied to the
5919 The suffix for Java class files;
5924 The Java generator for C header and stub files.
5927 The command line used to generate C header and stub files
5929 Any options specified in the $JAVAHFLAGS construction variable
5930 are included on this command line.
5933 The string displayed when C header and stub files
5934 are generated from Java classes.
5935 If this is not set, then $JAVAHCOM (the command line) is displayed.
5938 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5942 General options passed to the C header and stub file generator
5946 The suffix for Java files;
5951 The LaTeX structured formatter and typesetter.
5954 The command line used to call the LaTeX structured formatter and typesetter.
5957 The string displayed when calling
5958 the LaTeX structured formatter and typesetter.
5959 If this is not set, then $LATEXCOM (the command line) is displayed.
5962 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5966 General options passed to the LaTeX structured formatter and typesetter.
5969 The linker for building loadable modules.
5970 By default, this is the same as $SHLINK.
5973 The command line for building loadable modules.
5974 On Mac OS X, this uses the $LDMODULE,
5975 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
5976 On other systems, this is the same as $SHLINK.
5979 The string displayed when building loadable modules.
5980 If this is not set, then $LDMODULECOM (the command line) is displayed.
5983 General user options passed to the linker for building loadable modules.
5986 The prefix used for loadable module file names.
5987 On Mac OS X, this is null;
5988 on other systems, this is
5989 the same as $SHLIBPREFIX.
5992 The suffix used for loadable module file names.
5993 On Mac OS X, this is null;
5994 on other systems, this is
5995 the same as $SHLIBSUFFIX.
5998 The lexical analyzer generator.
6001 General options passed to the lexical analyzer generator.
6004 The command line used to call the lexical analyzer generator
6005 to generate a source file.
6008 The string displayed when generating a source file
6009 using the lexical analyzer generator.
6010 If this is not set, then $LEXCOM (the command line) is displayed.
6013 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
6017 An automatically-generated construction variable
6018 containing the linker command-line options
6019 for specifying directories to be searched for library.
6020 The value of $_LIBDIRFLAGS is created
6021 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
6022 to the beginning and end
6023 of each directory in $LIBPATH.
6026 The prefix used to specify a library directory on the linker command line.
6027 This will be appended to the beginning of each directory
6028 in the $LIBPATH construction variable
6029 when the $_LIBDIRFLAGS variable is automatically generated.
6032 The suffix used to specify a library directory on the linker command line.
6033 This will be appended to the end of each directory
6034 in the $LIBPATH construction variable
6035 when the $_LIBDIRFLAGS variable is automatically generated.
6038 An automatically-generated construction variable
6039 containing the linker command-line options
6040 for specifying libraries to be linked with the resulting target.
6041 The value of $_LIBFLAGS is created
6042 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
6043 to the beginning and end
6044 of each filename in $LIBS.
6047 The prefix used to specify a library to link on the linker command line.
6048 This will be appended to the beginning of each library
6049 in the $LIBS construction variable
6050 when the $_LIBFLAGS variable is automatically generated.
6053 The suffix used to specify a library to link on the linker command line.
6054 This will be appended to the end of each library
6055 in the $LIBS construction variable
6056 when the $_LIBFLAGS variable is automatically generated.
6059 The list of directories that will be searched for libraries.
6060 The implicit dependency scanner will search these
6061 directories for include files. Don't explicitly put include directory
6062 arguments in $LINKFLAGS or $SHLINKFLAGS
6063 because the result will be non-portable
6064 and the directories will not be searched by the dependency scanner. Note:
6065 directory names in LIBPATH will be looked-up relative to the SConscript
6066 directory when they are used in a command. To force
6068 to look-up a directory relative to the root of the source tree use #:
6071 env = Environment(LIBPATH='#/libs')
6075 The directory look-up can also be forced using the
6081 env = Environment(LIBPATH=libs)
6085 The directory list will be added to command lines
6086 through the automatically-generated
6088 construction variable,
6089 which is constructed by
6090 appending the values of the
6091 $LIBDIRPREFIX and $LIBDIRSUFFIX
6092 construction variables
6093 to the beginning and end
6094 of each directory in $LIBPATH.
6095 Any command lines you define that need
6096 the LIBPATH directory list should
6097 include $_LIBDIRFLAGS:
6100 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6104 The prefix used for (static) library file names.
6105 A default value is set for each platform
6106 (posix, win32, os2, etc.),
6107 but the value is overridden by individual tools
6108 (ar, mslib, sgiar, sunar, tlib, etc.)
6109 to reflect the names of the libraries they create.
6112 An array of legal prefixes for library file names.
6115 A list of one or more libraries
6116 that will be linked with
6117 any executable programs
6118 created by this environment.
6121 The library list will be added to command lines
6122 through the automatically-generated
6124 construction variable,
6125 which is constructed by
6126 appending the values of the
6127 $LIBLINKPREFIX and $LIBLINKSUFFIX
6128 construction variables
6129 to the beginning and end
6130 of each filename in $LIBS.
6131 Any command lines you define that need
6132 the LIBS library list should
6136 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6144 list, the name of that file will be added to
6146 and thus the link line, as is, without
6152 env.Append(LIBS=File('/tmp/mylib.so'))
6156 In all cases, scons will add dependencies from the executable program to
6157 all the libraries in this list.
6160 The suffix used for (static) library file names.
6161 A default value is set for each platform
6162 (posix, win32, os2, etc.),
6163 but the value is overridden by individual tools
6164 (ar, mslib, sgiar, sunar, tlib, etc.)
6165 to reflect the names of the libraries they create.
6168 An array of legal suffixes for library file names.
6174 General user options passed to the linker.
6175 Note that this variable should
6179 (or similar) options for linking with the libraries listed in $LIBS,
6182 (or similar) library search path options
6183 that scons generates automatically from $LIBPATH.
6187 for the variable that expands to library-link options,
6191 for the variable that expands to library search path options.
6194 The command line used to link object files into an executable.
6197 The string displayed when object files
6198 are linked into an executable.
6199 If this is not set, then $LINKCOM (the command line) is displayed.
6202 env = Environment(LINKCOMSTR = "Linking $TARGET")
6206 The M4 macro preprocessor.
6209 General options passed to the M4 macro preprocessor.
6212 The command line used to pass files through the M4 macro preprocessor.
6215 The string displayed when
6216 a file is passed through the M4 macro preprocessor.
6217 If this is not set, then $M4COM (the command line) is displayed.
6220 The maximum number of characters allowed on an external command line.
6222 link lines longer than this many characters
6223 are linke via a temporary file name.
6226 When the Microsoft Visual Studio tools are initialized, they set up
6227 this dictionary with the following keys:
6230 the version of MSVS being used (can be set via
6234 the available versions of MSVS installed
6237 installed directory of Visual C++
6240 installed directory of Visual Studio
6243 installed directory of the .NET framework
6245 .B FRAMEWORKVERSIONS:
6246 list of installed versions of the .NET framework, sorted latest to oldest.
6248 .B FRAMEWORKVERSION:
6249 latest installed version of the .NET framework
6252 installed location of the .NET SDK.
6255 installed location of the Platform SDK.
6257 .B PLATFORMSDK_MODULES:
6258 dictionary of installed Platform SDK modules,
6259 where the dictionary keys are keywords for the various modules, and
6260 the values are 2-tuples where the first is the release date, and the
6261 second is the version number.
6263 If a value isn't set, it wasn't available in the registry.
6265 .IP MSVS_IGNORE_IDE_PATHS
6266 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6267 instead of the settings from the IDE.
6269 For Visual Studio, SCons will (by default) automatically determine
6270 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6271 set by the IDE. You can override this behavior by setting these
6272 variables after Environment initialization, or by setting
6273 .B MSVS_IGNORE_IDE_PATHS = 1
6274 in the Environment initialization.
6275 Specifying this will not leave these unset, but will set them to a
6276 minimal set of paths needed to run the tools successfully.
6279 For VS6, the mininimal set is:
6280 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6281 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6282 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6284 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6285 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6286 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6290 Where '<VSDir>' is the installed location of Visual Studio.
6292 .IP MSVS_USE_MFC_DIRS
6293 Tells the MS Visual Studio tool(s) to use
6294 the MFC directories in its default paths
6295 for compiling and linking.
6296 Under MSVS version 6,
6298 .B MSVS_USE_MFC_DIRS
6307 external environment variable,
6313 external environment variable.
6314 Under MSVS version 7,
6316 .B MSVS_USE_MFC_DIRS
6319 .B "atlmfc\\\\include"
6320 directory to the default
6322 external environment variable,
6325 directory to the default
6327 external environment variable.
6328 The current default value is
6330 which means these directories
6331 are added to the paths by default.
6332 This default value is likely to change
6333 in a future release,
6334 so users who want the ATL and MFC
6335 values included in their paths
6336 are encouraged to enable the
6337 .B MSVS_USE_MFC_DIRS
6339 to avoid future incompatibility.
6340 This variable has no effect if the
6344 environment variables are set explictly.
6347 Sets the preferred version of MSVS to use.
6349 SCons will (by default) select the latest version of MSVS
6350 installed on your machine. So, if you have version 6 and version 7
6351 (MSVS .NET) installed, it will prefer version 7. You can override this by
6354 variable in the Environment initialization, setting it to the
6355 appropriate version ('6.0' or '7.0', for example).
6356 If the given version isn't installed, tool initialization will fail.
6359 The action used to generate Microsoft Visual Studio
6360 project and solution files.
6362 .IP MSVSPROJECTSUFFIX
6363 The suffix used for Microsoft Visual Studio project (DSP) files.
6364 The default value is
6366 when using Visual Studio version 7.x (.NET),
6369 when using earlier versions of Visual Studio.
6371 .IP MSVSSOLUTIONSUFFIX
6372 The suffix used for Microsoft Visual Studio solution (DSW) files.
6373 The default value is
6375 when using Visual Studio version 7.x (.NET),
6378 when using earlier versions of Visual Studio.
6381 The version number of the MetroWerks CodeWarrior C compiler
6385 A list of installed versions of the MetroWerks CodeWarrior C compiler
6389 When set to non-zero,
6390 suppresses creation of a corresponding Win32 static import lib by the
6392 builder when used with
6393 MinGW or Microsoft Visual Studio.
6394 This also suppresses creation
6395 of an export (.exp) file
6396 when using Microsoft Visual Studio.
6399 The prefix used for (static) object file names.
6402 The suffix used for (static) object file names.
6405 The Perforce executable.
6408 The command line used to
6409 fetch source files from Perforce.
6412 The string displayed when
6413 fetching a source file from Perforce.
6414 If this is not set, then $P4COM (the command line) is displayed.
6417 General options that are passed to Perforce.
6420 The Microsoft Visual C++ precompiled header that will be used when compiling
6421 object files. This variable is ignored by tools other than Microsoft Visual C++.
6422 When this variable is
6423 defined SCons will add options to the compiler command line to
6424 cause it to use the precompiled header, and will also set up the
6425 dependencies for the PCH file. Example:
6428 env['PCH'] = 'StdAfx.pch'
6432 The command line used by the
6434 builder to generated a precompiled header.
6437 The string displayed when generating a precompiled header.
6438 If this is not set, then $PCHCOM (the command line) is displayed.
6441 This variable specifies how much of a source file is precompiled. This
6442 variable is ignored by tools other than Microsoft Visual C++, or when
6443 the PCH variable is not being used. When this variable is define it
6444 must be a string that is the name of the header that
6445 is included at the end of the precompiled portion of the source files, or
6446 the empty string if the "#pragma hrdstop" construct is being used:
6449 env['PCHSTOP'] = 'StdAfx.h'
6453 The Microsoft Visual C++ PDB file that will store debugging information for
6454 object files, shared libraries, and programs. This variable is ignored by
6455 tools other than Microsoft Visual C++.
6456 When this variable is
6457 defined SCons will add options to the compiler and linker command line to
6458 cause them to generate external debugging information, and will also set up the
6459 dependencies for the PDB file. Example:
6462 env['PDB'] = 'hello.pdb'
6466 A deprecated synonym for $DVIPDFCOM.
6469 The prefix used for PDF file names.
6472 The suffix used for PDF file names.
6475 The name of the platform used to create the Environment. If no platform is
6476 specified when the Environment is created,
6478 autodetects the platform.
6481 env = Environment(tools = [])
6482 if env['PLATFORM'] == 'cygwin':
6488 .IP PRINT_CMD_LINE_FUNC
6489 A Python function used to print the command lines as they are executed
6490 (assuming command printing is not disabled by the
6494 options or their equivalents).
6495 The function should take four arguments:
6497 the command being executed (a string),
6499 the target being built (file node, list, or string name(s)),
6501 the source(s) used (file node, list, or string name(s)), and
6503 the environment being used.
6505 The function must do the printing itself. The default implementation,
6506 used if this variable is not set or is None, is:
6508 def print_cmd_line(s, target, source, env):
6509 sys.stdout.write(s + "\n")
6512 Here's an example of a more interesting function:
6514 def print_cmd_line(s, target, source, env):
6515 sys.stdout.write("Building %s -> %s...\n" %
6516 (' and '.join([str(x) for x in source]),
6517 ' and '.join([str(x) for x in target])))
6518 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6519 env.Program('foo', 'foo.c')
6522 This just prints "Building <targetname> from <sourcename>..." instead
6523 of the actual commands.
6524 Such a function could also log the actual commands to a log file,
6528 The prefix used for executable file names.
6531 The suffix used for executable file names.
6534 The command line used to convert TeX DVI files into a PostScript file.
6537 The string displayed when a TeX DVI file
6538 is converted into a PostScript file.
6539 If this is not set, then $PSCOM (the command line) is displayed.
6542 The prefix used for PostScript file names.
6545 The prefix used for PostScript file names.
6548 The qt tool tries to take this from os.environ.
6549 It also initializes all QT_*
6550 construction variables listed below.
6551 (Note that all paths are constructed
6552 with python's os.path.join() method,
6553 but are listed here with the '/' separator
6554 for easier reading.)
6555 In addition, the construction environment
6556 variables CPPPATH, LIBPATH and LIBS may be modified
6558 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6559 are modified. Because the build-performance is affected when using this tool,
6560 you have to explicitly specify it at Environment creation:
6563 Environment(tools=['default','qt'])
6566 The qt tool supports the following operations:
6568 .B Automatic moc file generation from header files.
6569 You do not have to specify moc files explicitly, the tool does it for you.
6570 However, there are a few preconditions to do so: Your header file must have
6571 the same filebase as your implementation file and must stay in the same
6572 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6573 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6574 See also the corresponding builder method
6577 .B Automatic moc file generation from cxx files.
6578 As stated in the qt documentation, include the moc file at the end of
6579 the cxx file. Note that you have to include the file, which is generated
6580 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6581 <basename>.moc. A warning is generated after building the moc file, if you
6582 do not include the correct file. If you are using BuildDir, you may
6583 need to specify duplicate=1. You can turn off automatic moc file generation
6584 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6587 .B Automatic handling of .ui files.
6588 The implementation files generated from .ui files are handled much the same
6589 as yacc or lex files. Each .ui file given as a source of Program, Library or
6590 SharedLibrary will generate three files, the declaration file, the
6591 implementation file and a moc file. Because there are also generated headers,
6592 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6596 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6597 specify files to run moc on.
6600 The path where the qt binaries are installed.
6601 The default value is '$QTDIR/bin'.
6604 The path where the qt header files are installed.
6605 The default value is '$QTDIR/include'.
6606 Note: If you set this variable to None, the tool won't change the CPPPATH
6607 construction variable.
6610 Prints lots of debugging information while scanning for moc files.
6613 The path where the qt libraries are installed.
6614 The default value is '$QTDIR/lib'.
6615 Note: If you set this variable to None, the tool won't change the LIBPATH
6616 construction variable.
6619 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6620 this variable to None, the tool won't change the LIBS variable.
6623 Default value is '$QT_BINPATH/moc'.
6626 Default value is ''. Prefix for moc output files, when source is a cxx file.
6629 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6632 .IP QT_MOCFROMCPPFLAGS
6633 Default value is '-i'. These flags are passed to moc, when moccing a
6636 .IP QT_MOCFROMCXXCOM
6637 Command to generate a moc file from a cpp file.
6639 .IP QT_MOCFROMCXXCOMSTR
6640 The string displayed when generating a moc file from a cpp file.
6641 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6644 Command to generate a moc file from a header.
6646 .IP QT_MOCFROMHCOMSTR
6647 The string displayed when generating a moc file from a cpp file.
6648 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6650 .IP QT_MOCFROMHFLAGS
6651 Default value is ''. These flags are passed to moc, when moccing a header
6655 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6658 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6662 Default value is '$QT_BINPATH/uic'.
6665 Command to generate header files from .ui files.
6668 The string displayed when generating header files from .ui files.
6669 If this is not set, then $QT_UICCOM (the command line) is displayed.
6672 Default value is ''. These flags are passed to uic, when creating a a h
6673 file from a .ui file.
6675 .IP QT_UICDECLPREFIX
6676 Default value is ''. Prefix for uic generated header files.
6678 .IP QT_UICDECLSUFFIX
6679 Default value is '.h'. Suffix for uic generated header files.
6682 Default value is ''. These flags are passed to uic, when creating a cxx
6683 file from a .ui file.
6685 .IP QT_UICIMPLPREFIX
6686 Default value is 'uic_'. Prefix for uic generated implementation files.
6688 .IP QT_UICIMPLSUFFIX
6689 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6693 Default value is '.ui'. Suffix of designer input files.
6696 The archive indexer.
6699 General options passed to the archive indexer.
6702 The resource compiler used by the RES builder.
6705 The command line used by the RES builder.
6708 The string displayed when invoking the resource compiler.
6709 If this is not set, then $RCCOM (the command line) is displayed.
6712 The flags passed to the resource compiler by the RES builder.
6716 Note that this variable is not actually used
6717 for the command to fetch source files from RCS;
6720 construction variable, below.
6723 The RCS "checkout" executable,
6724 used to fetch source files from RCS.
6727 The command line used to
6728 fetch (checkout) source files from RCS.
6731 The string displayed when fetching
6732 a source file from RCS.
6733 If this is not set, then $RCS_COCOM
6734 (the command line) is displayed.
6737 Options that are passed to the $RCS_CO command.
6740 The program used to register DLLs on Windows systems.
6743 The command line used to register a newly-built DLL file
6745 Invoked when the "register=1"
6746 keyword argument is passed to the
6751 The string displayed when registering a newly-built DLL file.
6752 If this is not set, then $REGSVRCOM (the command line) is displayed.
6755 A function that converts a file name into a list of Dir instances by
6756 searching the repositories.
6759 The Java RMI stub compiler.
6762 The command line used to compile stub
6763 and skeleton class files
6764 from Java classes that contain RMI implementations.
6765 Any options specified in the $RMICFLAGS construction variable
6766 are included on this command line.
6769 The string displayed when compiling
6770 stub and skeleton class files
6771 from Java classes that contain RMI implementations.
6772 If this is not set, then $RMICCOM (the command line) is displayed.
6775 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6779 General options passed to the Java RMI stub compiler.
6782 The RPC protocol compiler.
6784 .IP RPCGENCLIENTFLAGS
6785 Options passed to the RPC protocol compiler
6786 when generating client side stubs.
6787 These are in addition to any flags specified in the
6789 construction variable.
6792 General options passed to the RPC protocol compiler.
6794 .IP RPCGENHEADERFLAGS
6795 Options passed to the RPC protocol compiler
6796 when generating a header file.
6797 These are in addition to any flags specified in the
6799 construction variable.
6801 .IP RPCGENSERVICEFLAGS
6802 Options passed to the RPC protocol compiler
6803 when generating server side stubs.
6804 These are in addition to any flags specified in the
6806 construction variable.
6809 Options passed to the RPC protocol compiler
6810 when generating XDR routines.
6811 These are in addition to any flags specified in the
6813 construction variable.
6816 A list of paths to search for shared libraries when running programs.
6817 Currently only used in the GNU (gnulink),
6818 IRIX (sgilink) and Sun (sunlink) linkers.
6819 Ignored on platforms and toolchains that don't support it.
6820 Note that the paths added to RPATH
6821 are not transformed by
6823 in any way: if you want an absolute
6824 path, you must make it absolute yourself.
6827 A list of the available implicit dependency scanners.
6828 New file scanners may be added by
6829 appending to this list,
6830 although the more flexible approach
6831 is to associate scanners
6832 with a specific Builder.
6833 See the sections "Builder Objects"
6834 and "Scanner Objects,"
6835 below, for more information.
6838 The SCCS executable.
6841 The command line used to
6842 fetch source files from SCCS.
6845 The string displayed when fetching
6846 a source file from a CVS repository.
6847 If this is not set, then $SCCSCOM
6848 (the command line) is displayed.
6851 General options that are passed to SCCS.
6854 Options that are passed specifically to the SCCS "get" subcommand.
6855 This can be set, for example, to
6857 to check out editable files from SCCS.
6860 The C compiler used for generating shared-library objects.
6863 The command line used to compile a C source file
6864 to a shared-library object file.
6865 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6866 are included on this command line.
6869 The string displayed when a C source file
6870 is compiled to a shared object file.
6871 If this is not set, then $SHCCCOM (the command line) is displayed.
6874 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6878 Options that are passed to the C compiler
6879 to generate shared-library objects.
6882 The C++ compiler used for generating shared-library objects.
6885 The command line used to compile a C++ source file
6886 to a shared-library object file.
6887 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6888 are included on this command line.
6891 The string displayed when a C++ source file
6892 is compiled to a shared object file.
6893 If this is not set, then $SHCXXCOM (the command line) is displayed.
6896 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6900 Options that are passed to the C++ compiler
6901 to generate shared-library objects.
6904 A string naming the shell program that will be passed to the
6909 construction variable for more information.
6912 The Fortran 77 compiler used for generating shared-library objects.
6913 You should normally set the $SHFORTRANC variable,
6914 which specifies the default Fortran compiler
6915 for all Fortran versions.
6916 You only need to set $SHF77 if you need to use a specific compiler
6917 or compiler version for Fortran 77 files.
6920 The command line used to compile a Fortran 77 source file
6921 to a shared-library object file.
6922 You only need to set $SHF77COM if you need to use a specific
6923 command line for Fortran 77 files.
6924 You should normally set the $SHFORTRANCOM variable,
6925 which specifies the default command line
6926 for all Fortran versions.
6929 The string displayed when a Fortran 77 source file
6930 is compiled to a shared-library object file.
6931 If this is not set, then $SHF77COM or $SHFORTRANCOM
6932 (the command line) is displayed.
6935 Options that are passed to the Fortran 77 compiler
6936 to generated shared-library objects.
6937 You only need to set $SHF77FLAGS if you need to define specific
6938 user options for Fortran 77 files.
6939 You should normally set the $SHFORTRANFLAGS variable,
6940 which specifies the user-specified options
6941 passed to the default Fortran compiler
6942 for all Fortran versions.
6945 The command line used to compile a Fortran 77 source file to a
6946 shared-library object file
6947 after first running the file through the C preprocessor.
6948 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6949 are included on this command line.
6950 You only need to set $SHF77PPCOM if you need to use a specific
6951 C-preprocessor command line for Fortran 77 files.
6952 You should normally set the $SHFORTRANPPCOM variable,
6953 which specifies the default C-preprocessor command line
6954 for all Fortran versions.
6957 The Fortran 90 compiler used for generating shared-library objects.
6958 You should normally set the $SHFORTRANC variable,
6959 which specifies the default Fortran compiler
6960 for all Fortran versions.
6961 You only need to set $SHF90 if you need to use a specific compiler
6962 or compiler version for Fortran 90 files.
6965 The command line used to compile a Fortran 90 source file
6966 to a shared-library object file.
6967 You only need to set $SHF90COM if you need to use a specific
6968 command line for Fortran 90 files.
6969 You should normally set the $SHFORTRANCOM variable,
6970 which specifies the default command line
6971 for all Fortran versions.
6974 The string displayed when a Fortran 90 source file
6975 is compiled to a shared-library object file.
6976 If this is not set, then $SHF90COM or $SHFORTRANCOM
6977 (the command line) is displayed.
6980 Options that are passed to the Fortran 90 compiler
6981 to generated shared-library objects.
6982 You only need to set $SHF90FLAGS if you need to define specific
6983 user options for Fortran 90 files.
6984 You should normally set the $SHFORTRANFLAGS variable,
6985 which specifies the user-specified options
6986 passed to the default Fortran compiler
6987 for all Fortran versions.
6990 The command line used to compile a Fortran 90 source file to a
6991 shared-library object file
6992 after first running the file through the C preprocessor.
6993 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6994 are included on this command line.
6995 You only need to set $SHF90PPCOM if you need to use a specific
6996 C-preprocessor command line for Fortran 90 files.
6997 You should normally set the $SHFORTRANPPCOM variable,
6998 which specifies the default C-preprocessor command line
6999 for all Fortran versions.
7002 The Fortran 95 compiler used for generating shared-library objects.
7003 You should normally set the $SHFORTRANC variable,
7004 which specifies the default Fortran compiler
7005 for all Fortran versions.
7006 You only need to set $SHF95 if you need to use a specific compiler
7007 or compiler version for Fortran 95 files.
7010 The command line used to compile a Fortran 95 source file
7011 to a shared-library object file.
7012 You only need to set $SHF95COM if you need to use a specific
7013 command line for Fortran 95 files.
7014 You should normally set the $SHFORTRANCOM variable,
7015 which specifies the default command line
7016 for all Fortran versions.
7019 The string displayed when a Fortran 95 source file
7020 is compiled to a shared-library object file.
7021 If this is not set, then $SHF95COM or $SHFORTRANCOM
7022 (the command line) is displayed.
7025 Options that are passed to the Fortran 95 compiler
7026 to generated shared-library objects.
7027 You only need to set $SHF95FLAGS if you need to define specific
7028 user options for Fortran 95 files.
7029 You should normally set the $SHFORTRANFLAGS variable,
7030 which specifies the user-specified options
7031 passed to the default Fortran compiler
7032 for all Fortran versions.
7035 The command line used to compile a Fortran 95 source file to a
7036 shared-library object file
7037 after first running the file through the C preprocessor.
7038 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
7039 are included on this command line.
7040 You only need to set $SHF95PPCOM if you need to use a specific
7041 C-preprocessor command line for Fortran 95 files.
7042 You should normally set the $SHFORTRANPPCOM variable,
7043 which specifies the default C-preprocessor command line
7044 for all Fortran versions.
7047 The default Fortran compiler used for generating shared-library objects.
7050 The command line used to compile a Fortran source file
7051 to a shared-library object file.
7054 The string displayed when a Fortran source file
7055 is compiled to a shared-library object file.
7056 If this is not set, then $SHFORTRANCOM
7057 (the command line) is displayed.
7060 Options that are passed to the Fortran compiler
7061 to generate shared-library objects.
7064 The command line used to compile a Fortran source file to a
7065 shared-library object file
7066 after first running the file through the C preprocessor.
7067 Any options specified
7068 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
7069 are included on this command line.
7072 The prefix used for shared library file names.
7075 The suffix used for shared library file names.
7078 The linker for programs that use shared libraries.
7081 The command line used to link programs using shared libaries.
7084 The string displayed when programs using shared libraries are linked.
7085 If this is not set, then $SHLINKCOM (the command line) is displayed.
7088 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
7092 General user options passed to the linker for programs using shared libraries.
7093 Note that this variable should
7097 (or similar) options for linking with the libraries listed in $LIBS,
7100 (or similar) include search path options
7101 that scons generates automatically from $LIBPATH.
7105 for the variable that expands to library-link options,
7109 for the variable that expands to library search path options.
7112 The prefix used for shared object file names.
7115 The suffix used for shared object file names.
7118 A reserved variable name
7119 that may not be set or used in a construction environment.
7120 (See "Variable Substitution," below.)
7123 A reserved variable name
7124 that may not be set or used in a construction environment.
7125 (See "Variable Substitution," below.)
7128 A command interpreter function that will be called to execute command line
7129 strings. The function must expect the following arguments:
7132 def spawn(shell, escape, cmd, args, env):
7136 is a string naming the shell program to use.
7138 is a function that can be called to escape shell special characters in
7141 is the path to the command to be executed.
7143 is the arguments to the command.
7145 is a dictionary of the environment variables
7146 in which the command should be executed.
7149 '\"The Subversion executable (usually named
7153 '\"The command line used to
7154 '\"fetch source files from a Subversion repository.
7157 '\"General options that are passed to Subversion.
7160 The scripting language wrapper and interface generator.
7163 The suffix that will be used for intermediate C
7164 source files generated by
7165 the scripting language wrapper and interface generator.
7166 The default value is
7167 .BR _wrap$CFILESUFFIX .
7168 By default, this value is used whenever the
7172 specified as part of the
7174 construction variable.
7177 The command line used to call
7178 the scripting language wrapper and interface generator.
7181 The string displayed when calling
7182 the scripting language wrapper and interface generator.
7183 If this is not set, then $SWIGCOM (the command line) is displayed.
7185 .IP SWIGCXXFILESUFFIX
7186 The suffix that will be used for intermediate C++
7187 source files generated by
7188 the scripting language wrapper and interface generator.
7189 The default value is
7190 .BR _wrap$CFILESUFFIX .
7191 By default, this value is used whenever the
7193 option is specified as part of the
7195 construction variable.
7198 General options passed to
7199 the scripting language wrapper and interface generator.
7200 This is where you should set
7204 or whatever other options you want to specify to SWIG.
7207 option in this variable,
7210 generate a C++ intermediate source file
7211 with the extension that is specified as the
7219 The command line used to call the tar archiver.
7222 The string displayed when archiving files
7223 using the tar archiver.
7224 If this is not set, then $TARCOM (the command line) is displayed.
7227 env = Environment(TARCOMSTR = "Archiving $TARGET")
7231 General options passed to the tar archiver.
7234 A reserved variable name
7235 that may not be set or used in a construction environment.
7236 (See "Variable Substitution," below.)
7239 A reserved variable name
7240 that may not be set or used in a construction environment.
7241 (See "Variable Substitution," below.)
7244 The suffix used for tar file names.
7247 The prefix for a temporary file used
7248 to execute lines longer than $MAXLINELENGTH.
7250 This may be set for toolchains that use other values,
7251 such as '-@' for the diab compiler
7252 or '-via' for ARM toolchain.
7255 The TeX formatter and typesetter.
7258 The command line used to call the TeX formatter and typesetter.
7261 The string displayed when calling
7262 the TeX formatter and typesetter.
7263 If this is not set, then $TEXCOM (the command line) is displayed.
7266 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7270 General options passed to the TeX formatter and typesetter.
7273 A list of the names of the Tool specifications
7274 that are part of this construction environment.
7276 .IP WIN32_INSERT_DEF
7277 When this is set to true,
7278 a library build of a WIN32 shared library (.dll file)
7279 will also build a corresponding .def file at the same time,
7280 if a .def file is not already listed as a build target.
7281 The default is 0 (do not build a .def file).
7284 The prefix used for WIN32 .def file names.
7287 The suffix used for WIN32 .def file names.
7290 The parser generator.
7293 The command line used to call the parser generator
7294 to generate a source file.
7297 The string displayed when generating a source file
7298 using the parser generator.
7299 If this is not set, then $YACCCOM (the command line) is displayed.
7302 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7306 General options passed to the parser generator.
7307 If $YACCFLAGS contains a \-d option,
7308 SCons assumes that the call will also create a .h file
7309 (if the yacc source file ends in a .y suffix)
7311 (if the yacc source file ends in a .yy suffix)
7315 header file generated by the parser generator
7319 Note that setting this variable does not cause
7320 the parser generator to generate a header
7321 file with the specified suffix,
7322 it exists to allow you to specify
7323 what suffix the parser generator will use of its own accord.
7324 The default value is
7327 .IP YACCHXXFILESUFFIX
7328 The suffix of the C++
7329 header file generated by the parser generator
7333 Note that setting this variable does not cause
7334 the parser generator to generate a header
7335 file with the specified suffix,
7336 it exists to allow you to specify
7337 what suffix the parser generator will use of its own accord.
7338 The default value is
7342 The zip compression and file packaging utility.
7345 The command line used to call the zip utility,
7346 or the internal Python function used to create a
7350 The string displayed when archiving files
7351 using the zip utility.
7352 If this is not set, then $ZIPCOM
7353 (the command line or internal Python function) is displayed.
7356 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7365 module used by the internal Python function
7366 to control whether the zip archive
7367 is compressed or not.
7368 The default value is
7369 .BR zipfile.ZIP_DEFLATED ,
7370 which creates a compressed zip archive.
7371 This value has no effect when using Python 1.5.2
7374 module is otherwise unavailable.
7377 General options passed to the zip utility.
7380 Construction variables can be retrieved and set using the
7382 method of the construction environment:
7385 dict = env.Dictionary()
7389 or using the [] operator:
7395 Construction variables can also be passed to the construction environment
7399 env = Environment(CC="cc")
7402 or when copying a construction environment using the
7407 env2 = env.Copy(CC="cl.exe")
7410 .SS Configure Contexts
7414 .I configure contexts,
7415 an integrated mechanism similar to the
7416 various AC_CHECK macros in GNU autoconf
7417 for testing for the existence of C header
7418 files, libraries, etc.
7419 In contrast to autoconf,
7421 does not maintain an explicit cache of the tested values,
7422 but uses its normal dependency tracking to keep the checked values
7423 up to date. However, users may override this behaviour with the
7425 command line option.
7427 The following methods can be used to perform checks:
7430 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7432 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7433 This creates a configure context, which can be used to perform checks.
7435 specifies the environment for building the tests.
7436 This environment may be modified when performing checks.
7438 is a dictionary containing custom tests.
7439 See also the section about custom tests below.
7440 By default, no custom tests are added to the configure context.
7442 specifies a directory where the test cases are built.
7443 Note that this directory is not used for building
7445 The default value is the directory
7448 specifies a file which collects the output from commands
7449 that are executed to check for the existence of header files, libraries, etc.
7450 The default is the file #/config.log.
7451 If you are using the
7454 you may want to specify a subdirectory under your build directory.
7456 specifies a C header file where the results of tests
7457 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7458 The default is to not write a
7461 You can specify the same
7463 file in multiple calls to Configure,
7466 will concatenate all results in the specified file.
7468 uses its normal dependency checking
7469 to decide if it's necessary to rebuild
7473 This means that the file is not necessarily re-built each
7475 but is only rebuilt if its contents will have changed
7476 and some target that depends on the
7478 file is being built.
7483 instance has the following associated methods:
7486 .RI Configure.Finish( self )
7487 This method should be called after configuration is done.
7488 It returns the environment as modified
7489 by the configuration checks performed.
7490 After this method is called, no further checks can be performed
7491 with this configuration context.
7492 However, you can create a new
7494 context to perform additional checks.
7495 Only one context should be active at a time.
7497 The following Checks are predefined.
7498 (This list will likely grow larger as time
7499 goes by and developers contribute new useful tests.)
7502 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7505 is usable in the specified language.
7508 in which case the last item in the list
7509 is the header file to be checked,
7510 and the previous list items are
7513 lines should precede the
7514 header line being checked for.
7515 The optional argument
7518 a two character string, where the first character denotes the opening
7519 quote and the second character denotes the closing quote.
7520 By default, both characters are " (double quote).
7521 The optional argument
7527 and selects the compiler to be used for the check.
7528 Returns 1 on success and 0 on failure.
7531 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7532 This is a wrapper around
7533 .B Configure.CheckHeader
7536 is usable in the C language.
7539 in which case the last item in the list
7540 is the header file to be checked,
7541 and the previous list items are
7544 lines should precede the
7545 header line being checked for.
7546 The optional argument
7549 a two character string, where the first character denotes the opening
7550 quote and the second character denotes the closing quote (both default
7552 Returns 1 on success and 0 on failure.
7555 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7556 This is a wrapper around
7557 .B Configure.CheckHeader
7560 is usable in the C++ language.
7563 in which case the last item in the list
7564 is the header file to be checked,
7565 and the previous list items are
7568 lines should precede the
7569 header line being checked for.
7570 The optional argument
7573 a two character string, where the first character denotes the opening
7574 quote and the second character denotes the closing quote (both default
7576 Returns 1 on success and 0 on failure.
7579 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7580 Checks if the specified
7581 C or C++ function is available.
7583 is the name of the function to check for.
7586 argument is a string
7590 that will be compiled
7591 to check if the function exists;
7597 char function_name();
7605 and selects the compiler to be used for the check;
7609 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
7616 is 1 and the library provides the specified
7618 appends the library to the LIBS construction environment variable.
7620 may also be None (the default),
7623 is checked with the current LIBS variable,
7624 or a list of library names,
7625 in which case each library in the list
7632 you can link against the specified
7640 and selects the compiler to be used for the check;
7642 The default value for
7645 It is assumed, that the C-language is used.
7646 This method returns 1 on success and 0 on error.
7649 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7652 .RI Configure.CheckLib
7653 call, this call provides a more sophisticated way to check against libraries.
7656 specifies the library or a list of libraries to check.
7658 specifies a header to check for.
7661 in which case the last item in the list
7662 is the header file to be checked,
7663 and the previous list items are
7666 lines should precede the
7667 header line being checked for.
7669 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7671 can be any valid expression (with a trailing ';'). The default is 'main();'.
7673 specifies whether to add the library to the environment (only if the check
7674 succeeds). This method returns 1 on success and 0 on error.
7677 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7678 Checks for the existence of a type defined by
7681 specifies the typedef name to check for.
7683 is a string containing one or more
7685 lines that will be inserted into the program
7686 that will be run to test for the existence of the type.
7693 and selects the compiler to be used for the check;
7697 Example of a typical Configure usage:
7701 conf = Configure( env )
7702 if not conf.CheckCHeader( 'math.h' ):
7703 print 'We really need math.h!'
7705 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7706 # do stuff for qt - usage, e.g.
7707 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7712 You can define your own custom checks.
7713 in addition to the predefined checks.
7714 These are passed in a dictionary to the Configure function.
7715 This dictionary maps the names of the checks
7716 to user defined Python callables
7717 (either Python functions or class instances implementing the
7720 The first argument of the call is always a
7722 instance followed by the arguments,
7723 which must be supplied by the user of the check.
7724 These CheckContext instances define the following methods:
7727 .RI CheckContext.Message( self ", " text )
7729 Usually called before the check is started.
7731 will be displayed to the user, e.g. 'Checking for library X...'
7734 .RI CheckContext.Result( self, ", " res )
7736 Usually called after the check is done.
7738 can be either an integer or a string. In the former case, 'ok' (res != 0)
7739 or 'failed' (res == 0) is displayed to the user, in the latter case the
7740 given string is displayed.
7743 .RI CheckContext.TryCompile( self ", " text ", " extension )
7744 Checks if a file with the specified
7746 (e.g. '.c') containing
7748 can be compiled using the environment's
7750 builder. Returns 1 on success and 0 on failure.
7753 .RI CheckContext.TryLink( self ", " text ", " extension )
7754 Checks, if a file with the specified
7756 (e.g. '.c') containing
7758 can be compiled using the environment's
7760 builder. Returns 1 on success and 0 on failure.
7763 .RI CheckContext.TryRun( self ", " text ", " extension )
7764 Checks, if a file with the specified
7766 (e.g. '.c') containing
7768 can be compiled using the environment's
7770 builder. On success, the program is run. If the program
7771 executes successfully
7772 (that is, its return status is 0),
7777 is the standard output of the
7779 If the program fails execution
7780 (its return status is non-zero),
7781 then (0, '') is returned.
7784 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7785 Checks if the specified
7787 with an optional source file (contents
7794 may be anything which can be converted to a
7801 is the content of the target file.
7807 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7808 Low level implementation for testing specific builds;
7809 the methods above are based on this method.
7810 Given the Builder instance
7814 of a source file with optional
7816 this method returns 1 on success and 0 on failure. In addition,
7818 is set to the build target node, if the build was successful.
7821 Example for implementing and using custom tests:
7824 def CheckQt(context, qtdir):
7825 context.Message( 'Checking for qt ...' )
7826 lastLIBS = context.env['LIBS']
7827 lastLIBPATH = context.env['LIBPATH']
7828 lastCPPPATH= context.env['CPPPATH']
7829 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7830 ret = context.TryLink("""
7832 int main(int argc, char **argv) {
7833 QApplication qapp(argc, argv);
7838 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7839 context.Result( ret )
7843 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7844 if not conf.CheckQt('/usr/lib/qt'):
7845 print 'We really need qt!'
7850 .SS Construction Variable Options
7852 Often when building software, various options need to be specified at build
7853 time that are not known when the SConstruct/SConscript files are
7854 written. For example, libraries needed for the build may be in non-standard
7855 locations, or site-specific compiler options may need to be passed to the
7858 provides a mechanism for overridding construction variables from the
7859 command line or a text-based SConscript file through an Options
7860 object. To create an Options object, call the Options() function:
7863 .RI Options([ files "], [" args ])
7864 This creates an Options object that will read construction variables from
7865 the file or list of filenames specified in
7867 If no files are specified,
7872 then no files will be read.
7873 The optional argument
7876 values that will override anything read from the specified files;
7877 it is primarily intended to be passed the
7879 dictionary that holds variables
7880 specified on the command line.
7884 opts = Options('custom.py')
7885 opts = Options('overrides.py', ARGUMENTS)
7886 opts = Options(None, {FOO:'expansion', BAR:7})
7889 Options objects have the following methods:
7892 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7893 This adds a customizable construction variable to the Options object.
7895 is the name of the variable.
7897 is the help text for the variable.
7899 is the default value of the variable;
7900 if the default value is
7902 and there is no explicit value specified,
7903 the construction variable will
7905 be added to the construction environment.
7907 is called to validate the value of the variable, and should take three
7908 arguments: key, value, and environment
7910 is called to convert the value before putting it in the environment, and
7911 should take a single argument: value. Example:
7914 opts.Add('CC', 'The C compiler')
7918 .RI AddOptions( list )
7919 A wrapper script that adds
7920 multiple customizable construction variables
7921 to an Options object.
7923 is a list of tuple or list objects
7924 that contain the arguments
7925 for an individual call to the
7932 ('CC', 'The C compiler'),
7933 ('VALIDATE', 'An option for testing validation',
7934 'notset', validator, None),
7939 .RI Update( env ", [" args ])
7940 This updates a construction environment
7942 with the customized construction variables. Normally this method is not
7943 called directly, but is called indirectly by passing the Options object to
7944 the Environment() function:
7947 env = Environment(options=opts)
7951 The text file(s) that were specified
7952 when the Options object was created
7953 are executed as Python scripts,
7954 and the values of (global) Python variables set in the file
7955 are added to the construction environment.
7963 .RI Save( filename ", " env )
7964 This saves the currently set options into a script file named
7966 that can be used on the next invocation to automatically load the current
7967 settings. This method combined with the Options method can be used to
7968 support caching of options between runs.
7972 opts = Options(['options.cache', 'custom.py'])
7975 opts.Save('options.cache', env)
7979 .RI GenerateHelpText( env ", [" sort ])
7980 This generates help text documenting the customizable construction
7981 variables suitable to passing in to the Help() function.
7983 is the construction environment that will be used to get the actual values
7984 of customizable variables. Calling with
7988 will cause the output to be sorted
7989 by the specified argument.
7993 should take two arguments
7996 (like the standard Python
8001 Help(opts.GenerateHelpText(env))
8002 Help(opts.GenerateHelpText(env, sort=cmp))
8006 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
8007 This method returns a formatted string
8008 containing the printable help text
8010 It is normally not called directly,
8011 but is called by the
8012 .IR GenerateHelpText ()
8013 method to create the returned help text.
8014 It may be overridden with your own
8015 function that takes the arguments specified above
8016 and returns a string of help text formatted to your liking.
8018 .IR GenerateHelpText ()
8019 will not put any blank lines or extra
8020 characters in between the entries,
8021 so you must add those characters to the returned
8022 string if you want the entries separated.
8025 def my_format(env, opt, help, default, actual):
8026 fmt = "\n%s: default=%s actual=%s (%s)\n"
8027 return fmt % (opt, default. actual, help)
8028 opts.FormatOptionHelpText = my_format
8031 To make it more convenient to work with customizable Options,
8033 provides a number of functions
8034 that make it easy to set up
8035 various types of Options:
8038 .RI BoolOption( key ", " help ", " default )
8039 Return a tuple of arguments
8040 to set up a Boolean option.
8044 have a default value of
8046 and display the specified
8049 The option will interpret the values
8071 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
8072 Return a tuple of arguments
8074 whose value may be one
8075 of a specified list of legal enumerated values.
8079 have a default value of
8081 and display the specified
8084 The option will only support those
8090 argument is a dictionary
8091 that can be used to convert
8092 input values into specific legal values
8101 then the values are case-sensitive.
8106 then values will be matched
8112 then values will be matched
8114 and all input values will be
8115 converted to lower case.
8118 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
8119 Return a tuple of arguments
8121 whose value may be one or more
8122 of a specified list of legal enumerated values.
8126 have a default value of
8128 and display the specified
8131 The option will only support the values
8134 or the values in the
8137 More than one value may be specified,
8138 with all values separated by commas.
8139 The default may be a string of
8140 comma-separated default values,
8141 or a list of the default values.
8144 argument is a dictionary
8145 that can be used to convert
8146 input values into specific legal values
8152 .RI PackageOption( key ", " help ", " default )
8153 Return a tuple of arguments
8155 whose value is a path name
8156 of a package that may be
8157 enabled, disabled or
8158 given an explicit path name.
8162 have a default value of
8164 and display the specified
8167 The option will support the values
8174 in which case the specified
8177 or the option may be set to an
8179 (typically the path name to a package
8180 that is being enabled).
8181 The option will also support the values
8187 to disable use of the specified option.
8190 .RI PathOption( key ", " help ", " default ", [" validator ])
8191 Return a tuple of arguments
8193 whose value is expected to be a path name.
8197 have a default value of
8199 and display the specified
8205 that will be called to
8206 verify that the specified path
8209 following ready-made validators:
8210 .BR PathOption.PathExists
8212 which verifies that the specified path exists;
8213 .BR PathOption.PathIsFile ,
8214 which verifies that the specified path is an existing file;
8215 .BR PathOption.PathIsDir ,
8216 which verifies that the specified path is an existing directory;
8218 .BR PathOption.PathIsDirCreate ,
8219 which verifies that the specified path is a directory,
8220 and will create the specified directory if the path does not exist.
8221 You may supply your own
8224 which must take three arguments
8226 the name of the options variable to be set;
8228 the specified value being checked;
8231 the construction environment)
8232 and should raise an exception
8233 if the specified value is not acceptable.
8236 These functions make it
8237 convenient to create a number
8238 of options with consistent behavior
8239 in a single call to the
8245 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
8246 EnumOption('debug', 'debug output and symbols', 'no'
8247 allowed_values=('yes', 'no', 'full'),
8248 map={}, ignorecase=0), # case sensitive
8249 ListOption('shared',
8250 'libraries to build as shared libraries',
8252 names = list_of_libs),
8253 PackageOption('x11',
8254 'use X11 installed here (yes = search some places)',
8256 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
8257 PathOption('foopath', 'where the foo library is installed', foopath,
8258 PathOption.PathIsDir),
8263 .SS File and Directory Nodes
8273 Nodes, respectively.
8274 python objects, respectively.
8275 Those objects have several user-visible attributes
8276 and methods that are often useful:
8282 This path is relative to the top-level directory
8286 The build path is the same as the source path if
8291 The absolute build path of the given file or directory.
8301 object representing the
8310 # Get the current build dir's path, relative to top.
8312 # Current dir's absolute path
8314 # Next line is always '.', because it is the top dir's path relative to itself.
8316 File('foo.c').srcnode().path # source path of the given source file.
8318 # Builders also return File objects:
8319 foo = env.Program('foo.c')
8320 print "foo will be built in %s"%foo.path
8326 can be extended to build different types of targets
8327 by adding new Builder objects
8328 to a construction environment.
8330 you should only need to add a new Builder object
8331 when you want to build a new type of file or other external target.
8332 If you just want to invoke a different compiler or other tool
8333 to build a Program, Object, Library, or any other
8334 type of output file for which
8336 already has an existing Builder,
8337 it is generally much easier to
8338 use those existing Builders
8339 in a construction environment
8340 that sets the appropriate construction variables
8343 Builder objects are created
8349 function accepts the following arguments:
8352 The command line string used to build the target from the source.
8355 a list of strings representing the command
8356 to be executed and its arguments
8357 (suitable for enclosing white space in an argument),
8359 mapping source file name suffixes to
8360 any combination of command line strings
8361 (if the builder should accept multiple source file extensions),
8364 (see the next section);
8365 or a list of any of the above.
8368 takes three arguments:
8370 - a list of source nodes,
8372 - a list of target nodes,
8374 - the construction environment.
8377 The prefix that will be prepended to the target file name.
8378 This may be specified as a:
8388 - a function or other callable that takes
8389 two arguments (a construction environment and a list of sources)
8390 and returns a prefix,
8395 - specifies a mapping from a specific source suffix (of the first
8396 source specified) to a corresponding target prefix. Both the source
8397 suffix and target prefix specifications may use environment variable
8398 substitution, and the target prefix (the 'value' entries in the
8399 dictionary) may also be a callable object. The default target prefix
8400 may be indicated by a dictionary entry with a key value of None.
8405 b = Builder("build_it < $SOURCE > $TARGET"
8408 def gen_prefix(env, sources):
8409 return "file-" + env['PLATFORM'] + '-'
8410 b = Builder("build_it < $SOURCE > $TARGET",
8411 prefix = gen_prefix)
8413 b = Builder("build_it < $SOURCE > $TARGET",
8414 suffix = { None: "file-",
8415 "$SRC_SFX_A": gen_prefix })
8419 The suffix that will be appended to the target file name.
8420 This may be specified in the same manner as the prefix above.
8421 If the suffix is a string, then
8423 will append a '.' to the beginning of the suffix if it's not already
8424 there. The string returned by callable object (or obtained from the
8425 dictionary) is untouched and must append its own '.' to the beginning
8429 b = Builder("build_it < $SOURCE > $TARGET"
8432 def gen_suffix(env, sources):
8433 return "." + env['PLATFORM'] + "-file"
8434 b = Builder("build_it < $SOURCE > $TARGET",
8435 suffix = gen_suffix)
8437 b = Builder("build_it < $SOURCE > $TARGET",
8438 suffix = { None: ".sfx1",
8439 "$SRC_SFX_A": gen_suffix })
8443 The expected source file name suffix. This may be a string or a list
8447 A Scanner object that
8448 will be invoked to find
8449 implicit dependencies for this target file.
8450 This keyword argument should be used
8451 for Scanner objects that find
8452 implicit dependencies
8453 based only on the target file
8454 and the construction environment,
8457 (See the section "Scanner Objects," below,
8458 for information about creating Scanner objects.)
8461 A Scanner object that
8463 find implicit dependences in
8465 used to build this target file.
8466 This is where you would
8467 specify a scanner to
8470 lines in source files.
8473 Scanner object may be used to
8474 indicate that this Builder
8475 should scan directory trees
8476 for on-disk changes to files
8479 does not know about from other Builder or function calls.
8480 (See the section "Scanner Objects," below,
8481 for information about creating your own Scanner objects.)
8484 A factory function that the Builder will use
8485 to turn any targets specified as strings into SCons Nodes.
8487 SCons assumes that all targets are files.
8488 Other useful target_factory
8491 for when a Builder creates a directory target,
8494 for when a Builder can create either a file
8495 or directory target.
8500 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8502 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8503 env.MakeDirectory('new_directory', [])
8506 Note that the call to the MakeDirectory Builder
8507 needs to specify an empty source list
8508 to make the string represent the builder's target;
8509 without that, it would assume the argument is the source,
8510 and would try to deduce the target name from it,
8511 which in the absence of an automatically-added prefix or suffix
8512 would lead to a matching target and source name
8513 and a circular dependency.
8516 A factory function that the Builder will use
8517 to turn any sources specified as strings into SCons Nodes.
8519 SCons assumes that all source are files.
8520 Other useful source_factory
8523 for when a Builder uses a directory as a source,
8526 for when a Builder can use files
8527 or directories (or both) as sources.
8532 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8534 env.Append(BUILDERS = {'Collect':CollectBuilder})
8535 env.Collect('archive', ['directory_name', 'file_name'])
8539 A function or list of functions to manipulate the target and source
8540 lists before dependencies are established
8541 and the target(s) are actually built.
8543 can also be a string containing a construction variable to expand
8544 to an emitter function or list of functions,
8545 or a dictionary mapping source file suffixes
8546 to emitter functions.
8547 (Only the suffix of the first source file
8548 is used to select the actual emitter function
8549 from an emitter dictionary.)
8552 takes three arguments:
8554 - a list of source nodes,
8556 - a list of target nodes,
8558 - the construction environment.
8559 An emitter must return a tuple containing two lists,
8560 the list of targets to be built by this builder,
8561 and the list of sources for this builder.
8566 def e(target, source, env):
8567 return (target + ['foo.foo'], source + ['foo.src'])
8569 # Simple association of an emitter function with a Builder.
8570 b = Builder("my_build < $TARGET > $SOURCE",
8573 def e2(target, source, env):
8574 return (target + ['bar.foo'], source + ['bar.src'])
8576 # Simple association of a list of emitter functions with a Builder.
8577 b = Builder("my_build < $TARGET > $SOURCE",
8580 # Calling an emitter function through a construction variable.
8581 env = Environment(MY_EMITTER = e)
8582 b = Builder("my_build < $TARGET > $SOURCE",
8583 emitter = '$MY_EMITTER')
8585 # Calling a list of emitter functions through a construction variable.
8586 env = Environment(EMITTER_LIST = [e, e2])
8587 b = Builder("my_build < $TARGET > $SOURCE",
8588 emitter = '$EMITTER_LIST')
8590 # Associating multiple emitters with different file
8591 # suffixes using a dictionary.
8592 def e_suf1(target, source, env):
8593 return (target + ['another_target_file'], source)
8594 def e_suf2(target, source, env):
8595 return (target, source + ['another_source_file'])
8596 b = Builder("my_build < $TARGET > $SOURCE",
8597 emitter = {'.suf1' : e_suf1,
8602 Specifies whether this builder is allowed to be called multiple times for
8603 the same target file(s). The default is 0, which means the builder
8604 can not be called multiple times for the same target file(s). Calling a
8605 builder multiple times for the same target simply adds additional source
8606 files to the target; it is not allowed to change the environment associated
8607 with the target, specify addition environment overrides, or associate a different
8608 builder with the target.
8611 A construction environment that can be used
8612 to fetch source code using this Builder.
8613 (Note that this environment is
8615 used for normal builds of normal target files,
8616 which use the environment that was
8617 used to call the Builder for the target file.)
8620 A function that returns a list of actions that will be executed to build
8621 the target(s) from the source(s).
8622 The returned action(s) may be
8623 an Action object, or anything that
8624 can be converted into an Action object
8625 (see the next section).
8627 The generator function
8628 takes four arguments:
8630 - a list of source nodes,
8632 - a list of target nodes,
8634 - the construction environment,
8636 - a Boolean value that specifies
8637 whether the generator is being called
8638 for generating a build signature
8639 (as opposed to actually executing the command).
8643 def g(source, target, env, for_signature):
8644 return [["gcc", "-c", "-o"] + target + source]
8646 b = Builder(generator=g)
8654 arguments must not both be used for the same Builder.
8657 Specifies a builder to use when a source file name suffix does not match
8658 any of the suffixes of the builder. Using this argument produces a
8659 multi-stage builder.
8662 Specifies that this builder expects exactly one source file per call. Giving
8663 more than one source files without target files results in implicitely calling
8664 the builder multiple times (once for each source given). Giving multiple
8665 source files together with target files results in a UserError exception.
8673 arguments must not both be used for the same Builder.
8676 A construction environment that can be used
8677 to fetch source code using this Builder.
8678 (Note that this environment is
8680 used for normal builds of normal target files,
8681 which use the environment that was
8682 used to call the Builder for the target file.)
8685 b = Builder(action="build < $SOURCE > $TARGET")
8686 env = Environment(BUILDERS = {'MyBuild' : b})
8687 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8691 A directory from which scons
8698 a string or a directory Node,
8699 scons will change to the specified directory.
8702 is not a string or Node
8704 then scons will change to the
8705 target file's directory.
8707 Note that scons will
8709 automatically modify
8711 construction variables like
8715 when using the chdir
8716 keyword argument--that is,
8717 the expanded file names
8718 will still be relative to
8719 the top-level SConstruct directory,
8720 and consequently incorrect
8721 relative to the chdir directory.
8722 Builders created using chdir keyword argument,
8723 will need to use construction variable
8728 to use just the filename portion of the
8732 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8734 env = Environment(BUILDERS = {'MyBuild' : b})
8735 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8739 Any additional keyword arguments supplied
8740 when a Builder object is created
8741 (that is, when the Builder() function is called)
8742 will be set in the executing construction
8743 environment when the Builder object is called.
8744 The canonical example here would be
8745 to set a construction variable to
8746 the repository of a source code system.
8748 Any additional keyword arguments supplied
8752 will only be associated with the target
8753 created by that particular Builder call
8754 (and any other files built as a
8755 result of the call).
8757 These extra keyword arguments are passed to the
8758 following functions:
8759 command generator functions,
8761 and emitter functions.
8767 function will turn its
8769 keyword argument into an appropriate
8770 internal Action object.
8771 You can also explicity create Action objects
8775 which can then be passed to the
8778 This can be used to configure
8779 an Action object more flexibly,
8780 or it may simply be more efficient
8781 than letting each separate Builder object
8782 create a separate Action
8784 Builder objects need to do the same thing.
8789 returns an appropriate object for the action
8790 represented by the type of the first argument:
8793 If the first argument is already an Action object,
8794 the object is simply returned.
8797 If the first argument is a string,
8798 a command-line Action is returned.
8799 Note that the command line string
8800 may be preceded by an
8803 to suppress printing of the
8804 specified command line,
8808 to ignore the exit status from
8809 the specified command.
8813 Action('$CC -c -o $TARGET $SOURCES')
8815 # Doesn't print the line being executed.
8816 Action('@build $TARGET $SOURCES')
8819 Action('-build $TARGET $SOURCES')
8822 .\" XXX From Gary Ruben, 23 April 2002:
8823 .\" What would be useful is a discussion of how you execute command
8824 .\" shell commands ie. what is the process used to spawn the shell, pass
8825 .\" environment variables to it etc., whether there is one shell per
8826 .\" environment or one per command etc. It might help to look at the Gnu
8827 .\" make documentation to see what they think is important to discuss about
8828 .\" a build system. I'm sure you can do a better job of organising the
8829 .\" documentation than they have :-)
8833 If the first argument is a list,
8834 then a list of Action objects is returned.
8835 An Action object is created as necessary
8836 for each element in the list.
8839 the list is itself a list,
8840 the internal list is the
8841 command and arguments to be executed via
8843 This allows white space to be enclosed
8844 in an argument by defining
8845 a command in a list within a list:
8848 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8852 If the first argument is a Python function,
8853 a function Action is returned.
8854 The Python function takes three keyword arguments,
8856 (a Node object representing the target file),
8858 (a Node object representing the source file)
8861 (the construction environment
8862 used for building the target file).
8867 arguments may be lists of Node objects if there is
8868 more than one target file or source file.
8869 The actual target and source file name(s) may
8870 be retrieved from their Node objects
8871 via the built-in Python str() function:
8874 target_file_name = str(target)
8875 source_file_names = map(lambda x: str(x), source)
8878 The function should return
8882 to indicate a successful build of the target file(s).
8883 The function may raise an exception
8884 or return a non-zero exit status
8885 to indicate an unsuccessful build.
8888 def build_it(target = None, source = None, env = None):
8889 # build the target from the source
8892 a = Action(build_it)
8895 If the action argument is not one of the above,
8898 The second, optional argument
8899 is a Python function that returns
8900 a string to be printed to describe the action being executed.
8901 Like a function to build a file,
8902 this function takes three arguments:
8904 (a Node object representing the target file),
8906 (a Node object representing the source file)
8909 (a construction environment).
8914 arguments may be lists of Node objects if there is
8915 more than one target file or source file.
8919 def build_it(target, source, env):
8920 # build the target from the source
8923 def string_it(target, source, env):
8924 return "building '%s' from '%s'" % (target[0], source[0])
8926 # Use a positional argument.
8927 a = Action(build_it, string_it)
8929 # Alternatively, use a keyword argument.
8930 a = Action(build_it, strfunction=string_it)
8933 The third, also optional argument
8934 is a list of construction variables
8935 whose values will be included
8936 in the signature of the Action
8937 when deciding whether a target should
8938 be rebuilt because the action changed.
8939 This is necessary whenever you want a target to
8940 be rebuilt when a specific
8941 construction variable changes,
8942 because the underlying Python code for a function
8943 will not change when the value of the construction variable does.
8946 def build_it(target, source, env):
8947 # build the target from the 'XXX' construction variable
8948 open(target[0], 'w').write(env['XXX'])
8951 def string_it(target, source):
8952 return "building '%s' from '%s'" % (target[0], source[0])
8954 # Use positional arguments.
8955 a = Action(build_it, string_it, ['XXX'])
8957 # Alternatively, use a keyword argument.
8958 a = Action(build_it, varlist=['XXX'])
8968 which specifies that
8969 scons will execute the action
8970 after changing to the specified directory.
8971 If the chdir argument is
8972 a string or a directory Node,
8973 scons will change to the specified directory.
8974 If the chdir argument
8975 is not a string or Node
8977 then scons will change to the
8978 target file's directory.
8980 Note that scons will
8982 automatically modify
8984 construction variables like
8988 when using the chdir
8989 keyword argument--that is,
8990 the expanded file names
8991 will still be relative to
8992 the top-level SConstruct directory,
8993 and consequently incorrect
8994 relative to the chdir directory.
8995 Builders created using chdir keyword argument,
8996 will need to use construction variable
9001 to use just the filename portion of the
9005 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9015 which specifies a function
9016 that is passed the exit status
9018 from the specified action
9019 and can return an arbitrary
9021 This can be used, for example,
9022 to specify that an Action object's
9023 return value should be ignored
9024 and SCons should, therefore,
9025 consider that the action always suceeds:
9028 def always_succeed(s):
9029 # Always return 0, which indicates success.
9031 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9032 exitstatfunc=always_succeed)
9035 .SS Miscellaneous Action Functions
9038 supplies a number of functions
9039 that arrange for various common
9040 file and directory manipulations
9042 These are similar in concept to "tasks" in the
9044 although the implementation is slightly different.
9045 These functions do not actually
9046 perform the specified action
9047 at the time the function is called,
9048 but instead return an Action object
9049 that can be executed at the
9051 (In Object-Oriented terminology,
9056 that return Action objects.)
9059 there are two natural ways
9062 are intended to be used.
9066 to perform the action
9067 at the time the SConscript
9071 global function to do so:
9073 Execute(Touch('file'))
9077 you can use these functions
9078 to supply Actions in a list
9082 This can allow you to
9083 perform more complicated
9084 sequences of file manipulation
9086 on platform-specific
9090 env = Environment(TMPBUILD = '/tmp/builddir')
9091 env.Command('foo.out', 'foo.in',
9092 [Mkdir('$TMPBUILD'),
9093 Copy('$TMPBUILD', '${SOURCE.dir}')
9094 "cd $TMPBUILD && make",
9095 Delete('$TMPBUILD')])
9099 .RI Chmod( dest ", " mode )
9100 Returns an Action object that
9101 changes the permissions on the specified
9103 file or directory to the specified
9108 Execute(Chmod('file', 0755))
9110 env.Command('foo.out', 'foo.in',
9111 [Copy('$TARGET', '$SOURCE'),
9112 Chmod('$TARGET', 0755)])
9116 .RI Copy( dest ", " src )
9117 Returns an Action object
9120 source file or directory to the
9122 destination file or directory.
9126 Execute(Copy('foo.output', 'foo.input'))
9128 env.Command('bar.out', 'bar.in',
9129 Copy('$TARGET', '$SOURCE'))
9133 .RI Delete( entry ", [" must_exist ])
9134 Returns an Action that
9135 deletes the specified
9137 which may be a file or a directory tree.
9138 If a directory is specified,
9139 the entire directory tree
9144 then a Python error will be thrown
9145 if the specified entry does not exist;
9148 that is, the Action will silently do nothing
9149 if the entry does not exist.
9153 Execute(Delete('/tmp/buildroot'))
9155 env.Command('foo.out', 'foo.in',
9156 [Delete('${TARGET.dir}'),
9159 Execute(Delete('file_that_must_exist', must_exist=1))
9165 that creates the specified
9171 Execute(Mkdir('/tmp/outputdir'))
9173 env.Command('foo.out', 'foo.in',
9174 [Mkdir('/tmp/builddir',
9175 Copy('$SOURCE', '/tmp/builddir')
9176 "cd /tmp/builddir && ])
9181 .RI Move( dest ", " src )
9183 that moves the specified
9185 file or directory to
9192 Execute(Move('file.destination', 'file.source'))
9194 env.Command('output_file', 'input_file',
9196 Move('$TARGET', 'file_created_by_MyBuildAction')])
9202 that updates the modification time
9208 Execute(Touch('file_to_be_touched'))
9210 env.Command('marker', 'input_file',
9215 .SS Variable Substitution
9217 Before executing a command,
9219 performs construction variable interpolation on the strings that make up
9220 the command line of builders.
9221 Variables are introduced by a
9224 Besides construction variables, scons provides the following
9225 variables for each command execution:
9228 The file name of the target being built, or the file name of the first
9229 target if multiple targets are being built.
9232 The file names of all targets being built.
9235 The file name of the source of the build command, or the file name of the
9236 first source if multiple sources are being built.
9239 The file names of the sources of the build command.
9241 (Note that the above variables are reserved
9242 and may not be set in a construction environment.)
9245 For example, given the construction variable CC='cc', targets=['foo'], and
9246 sources=['foo.c', 'bar.c']:
9249 action='$CC -c -o $TARGET $SOURCES'
9252 would produce the command line:
9255 cc -c -o foo foo.c bar.c
9258 Variable names may be surrounded by curly braces ({})
9259 to separate the name from the trailing characters.
9260 Within the curly braces, a variable name may have
9261 a Python slice subscript appended to select one
9262 or more items from a list.
9263 In the previous example, the string:
9275 Additionally, a variable name may
9276 have the following special
9277 modifiers appended within the enclosing curly braces
9278 to modify the interpolated string:
9281 The base path of the file name,
9282 including the directory path
9283 but excluding any suffix.
9286 The name of the directory in which the file exists.
9290 minus any directory portion.
9293 Just the basename of the file,
9295 and minus the directory.
9298 Just the file suffix.
9301 The absolute path name of the file.
9304 The POSIX form of the path,
9305 with directories separated by
9309 This is sometimes necessary on Win32 systems
9310 when a path references a file on other (POSIX) systems.
9313 The directory and file name to the source file linked to this file
9314 through BuildDir. If this file isn't linked, it just returns the
9315 directory and filename unchanged.
9318 The directory containing the source file linked to this file
9319 through BuildDir. If this file isn't linked, it just returns the
9320 directory part of the filename.
9323 The directory and file name to the source file linked to this file
9324 through BuildDir. If the file does not exist locally but exists in
9325 a Repository, the path in the Repository is returned.
9326 If this file isn't linked, it just returns the
9327 directory and filename unchanged.
9330 The Repository directory containing the source file linked to this file
9331 through BuildDir. If this file isn't linked, it just returns the
9332 directory part of the filename.
9335 For example, the specified target will
9336 expand as follows for the corresponding modifiers:
9339 $TARGET => sub/dir/file.x
9340 ${TARGET.base} => sub/dir/file
9341 ${TARGET.dir} => sub/dir
9342 ${TARGET.file} => file.x
9343 ${TARGET.filebase} => file
9344 ${TARGET.suffix} => .x
9345 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9347 SConscript('src/SConscript', build_dir='sub/dir')
9348 $SOURCE => sub/dir/file.x
9349 ${SOURCE.srcpath} => src/file.x
9350 ${SOURCE.srcdir} => src
9352 Repository('/usr/repository')
9353 $SOURCE => sub/dir/file.x
9354 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9355 ${SOURCE.rsrcdir} => /usr/repository/src
9358 Lastly, a variable name
9359 may be a callable Python function
9361 construction variable in the environment.
9363 take four arguments:
9365 - a list of target nodes,
9367 - a list of source nodes,
9369 - the construction environment,
9371 - a Boolean value that specifies
9372 whether the function is being called
9373 for generating a build signature.
9374 SCons will insert whatever
9375 the called function returns
9376 into the expanded string:
9379 def foo(target, source, env, for_signature):
9382 # Will expand $BAR to "bar baz"
9383 env=Environment(FOO=foo, BAR="$FOO baz")
9386 You can use this feature to pass arguments to a
9387 Python function by creating a callable class
9388 that stores one or more arguments in an object,
9389 and then uses them when the
9392 Note that in this case,
9393 the entire variable expansion must
9394 be enclosed by curly braces
9395 so that the arguments will
9396 be associated with the
9397 instantiation of the class:
9401 def __init__(self, arg):
9404 def __call__(self, target, source, env, for_signature):
9407 # Will expand $BAR to "my argument bar baz"
9408 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9412 The special pseudo-variables
9416 may be used to surround parts of a command line
9419 causing a rebuild--that is,
9420 which are not included in the signature
9421 of target files built with this command.
9426 will be removed from the command line
9427 before it is added to file signatures,
9432 will be removed before the command is executed.
9433 For example, the command line:
9436 echo Last build occurred $( $TODAY $). > $TARGET
9440 would execute the command:
9443 echo Last build occurred $TODAY. > $TARGET
9447 but the command signature added to any target files would be:
9450 echo Last build occurred . > $TARGET
9453 SCons uses the following rules when converting construction variables into
9457 When the value is a string it is interpreted as a space delimited list of
9458 command line arguments.
9461 When the value is a list it is interpreted as a list of command line
9462 arguments. Each element of the list is converted to a string.
9465 Anything that is not a list or string is converted to a string and
9466 interpreted as a single command line argument.
9469 Newline characters (\\n) delimit lines. The newline parsing is done after
9470 all other parsing, so it is not possible for arguments (e.g. file names) to
9471 contain embedded newline characters. This limitation will likely go away in
9472 a future version of SCons.
9480 new file types for implicit dependencies.
9481 Scanner accepts the following arguments:
9484 A Python function that will process
9486 and return a list of strings (file names)
9487 representing the implicit
9488 dependencies found in the contents.
9489 The function takes three or four arguments:
9491 def scanner_function(node, env, path):
9493 def scanner_function(node, env, path, arg):
9497 argument is the internal
9498 SCons node representing the file.
9501 to fetch the name of the file, and
9502 .B node.get_contents()
9503 to fetch contents of the file.
9507 argument is the construction environment for the scan.
9508 Fetch values from it using the
9514 argument is a tuple (or list)
9515 of directories that can be searched
9517 This will usually be the tuple returned by the
9519 argument (see below).
9523 argument is the argument supplied
9524 when the scanner was created, if any.
9527 The name of the Scanner.
9529 to identify the Scanner internally.
9532 An optional argument that, if specified,
9533 will be passed to the scanner function
9535 and the path function
9539 An optional list that can be used to
9540 determine which scanner should be used for
9542 In the usual case of scanning for file names,
9543 this argument will be a list of suffixes
9544 for the different file types that this
9545 Scanner knows how to scan.
9546 If the argument is a string,
9547 then it will be expanded
9548 into a list by the current environment.
9551 A Python function that takes
9552 two or three arguments:
9553 a construction environment, directory Node,
9554 and optional argument supplied
9555 when the scanner was created.
9558 returns a tuple of directories
9559 that can be searched for files to be returned
9560 by this Scanner object.
9563 The class of Node that should be returned
9564 by this Scanner object.
9565 Any strings or other objects returned
9566 by the scanner function
9567 that are not of this class
9568 will be run through the
9573 A Python function that will take a string
9575 and turn it into the appropriate class of Node
9576 to be returned by this Scanner object.
9579 An optional Python function that takes two arguments,
9580 a Node (file) and a construction environment,
9581 and returns whether the
9582 Node should, in fact,
9583 be scanned for dependencies.
9584 This check can be used to eliminate unnecessary
9585 calls to the scanner function when,
9586 for example, the underlying file
9587 represented by a Node does not yet exist.
9590 An optional flag that
9591 specifies whether this scanner should be re-invoked
9592 on the dependency files returned by the scanner.
9593 When this flag is not set,
9594 the Node subsystem will
9595 only invoke the scanner on the file being scanned,
9596 and not (for example) also on the files
9597 specified by the #include lines
9598 in the file being scanned.
9600 may be a callable function,
9601 in which case it will be called with a list of
9603 should return a list of Nodes
9604 that should be scanned recursively;
9605 this can be used to select a specific subset of
9606 Nodes for additional scanning.
9611 .B SourceFileScanner
9612 object that is used by
9615 .BR SharedObject (),
9619 which scanner should be used
9620 for different file extensions.
9622 .BR SourceFileScanner.add_scanner ()
9623 method to add your own Scanner object
9627 that builds target programs or
9628 libraries from a list of
9629 source files of different types:
9632 def xyz_scan(node, env, path):
9633 contents = node.get_contents()
9634 # Scan the contents and return the included files.
9636 XYZScanner = Scanner(xyz_scan)
9638 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9640 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9643 .SH SYSTEM-SPECIFIC BEHAVIOR
9644 SCons and its configuration files are very portable,
9645 due largely to its implementation in Python.
9646 There are, however, a few portability
9647 issues waiting to trap the unwary.
9649 SCons handles the upper-case
9651 file suffix differently,
9652 depending on the capabilities of
9653 the underlying system.
9654 On a case-sensitive system
9655 such as Linux or UNIX,
9656 SCons treats a file with a
9658 suffix as a C++ source file.
9659 On a case-insensitive system
9661 SCons treats a file with a
9663 suffix as a C source file.
9665 SCons handles the upper-case
9667 file suffix differently,
9668 depending on the capabilities of
9669 the underlying system.
9670 On a case-sensitive system
9671 such as Linux or UNIX,
9672 SCons treats a file with a
9674 suffix as a Fortran source file
9675 that is to be first run through
9676 the standard C preprocessor.
9677 On a case-insensitive system
9679 SCons treats a file with a
9681 suffix as a Fortran source file that should
9683 be run through the C preprocessor.
9684 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9685 Cygwin supplies a set of tools and utilities
9686 that let users work on a
9687 Windows system using a more POSIX-like environment.
9688 The Cygwin tools, including Cygwin Python,
9690 by sharing an ability to interpret UNIX-like path names.
9691 For example, the Cygwin tools
9692 will internally translate a Cygwin path name
9693 like /cygdrive/c/mydir
9694 to an equivalent Windows pathname
9695 of C:/mydir (equivalent to C:\\mydir).
9698 that are built for native Windows execution,
9699 such as the python.org and ActiveState versions,
9700 do not have the Cygwin path name semantics.
9701 This means that using a native Windows version of Python
9702 to build compiled programs using Cygwin tools
9703 (such as gcc, bison, and flex)
9704 may yield unpredictable results.
9705 "Mixing and matching" in this way
9706 can be made to work,
9707 but it requires careful attention to the use of path names
9708 in your SConscript files.
9710 In practice, users can sidestep
9711 the issue by adopting the following rules:
9713 use the Cygwin-supplied Python interpreter
9715 when using Microsoft Visual C/C++
9716 (or some other Windows compiler)
9717 use the python.org or ActiveState version of Python
9719 .SS WIN32: scons.bat file
9721 SCons is executed via a wrapper
9724 This has (at least) two ramifications:
9726 First, Windows command-line users
9727 that want to use variable assignment
9729 may have to put double quotes
9730 around the assignments:
9733 scons "FOO=BAR" "BAZ=BLEH"
9736 Second, the Cygwin shell does not
9737 recognize this file as being the same
9740 command issued at the command-line prompt.
9741 You can work around this either by
9744 from the Cygwin command line,
9745 or by creating a wrapper shell
9751 The MinGW bin directory must be in your PATH environment variable or the
9752 PATH variable under the ENV construction variable for SCons
9753 to detect and use the MinGW tools. When running under the native Windows
9754 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9755 tools, if they are both installed, regardless of the order of the bin
9756 directories in the PATH variable. If you have both MSVC and MinGW
9757 installed and you want to use MinGW instead of MSVC,
9758 then you must explictly tell SCons to use MinGW by passing
9764 to the Environment() function, because SCons will prefer the MSVC tools
9765 over the MinGW tools.
9769 To help you get started using SCons,
9770 this section contains a brief overview of some common tasks.
9772 .SS Basic Compilation From a Single Source File
9776 env.Program(target = 'foo', source = 'foo.c')
9779 Note: Build the file by specifying
9780 the target as an argument
9781 ("scons foo" or "scons foo.exe").
9782 or by specifying a dot ("scons .").
9784 .SS Basic Compilation From Multiple Source Files
9788 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9791 .SS Setting a Compilation Flag
9794 env = Environment(CCFLAGS = '-g')
9795 env.Program(target = 'foo', source = 'foo.c')
9798 .SS Search The Local Directory For .h Files
9802 need to set CCFLAGS to specify -I options by hand.
9803 SCons will construct the right -I options from CPPPATH.
9806 env = Environment(CPPPATH = ['.'])
9807 env.Program(target = 'foo', source = 'foo.c')
9810 .SS Search Multiple Directories For .h Files
9813 env = Environment(CPPPATH = ['include1', 'include2'])
9814 env.Program(target = 'foo', source = 'foo.c')
9817 .SS Building a Static Library
9821 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9822 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9825 .SS Building a Shared Library
9829 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9830 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9833 .SS Linking a Local Library Into a Program
9836 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9837 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9838 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9841 .SS Defining Your Own Builder Object
9843 Notice that when you invoke the Builder,
9844 you can leave off the target file suffix,
9845 and SCons will add it automatically.
9848 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9850 src_suffix = '.tex')
9851 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9852 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9854 # The following creates "bar.pdf" from "bar.tex"
9855 env.PDFBuilder(target = 'bar', source = 'bar')
9858 Note also that the above initialization
9859 overwrites the default Builder objects,
9860 so the Environment created above
9861 can not be used call Builders like env.Program(),
9862 env.Object(), env.StaticLibrary(), etc.
9864 .SS Adding Your Own Builder Object to an Environment
9867 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9869 src_suffix = '.tex')
9871 env.Append(BUILDERS = {'PDFBuilder' : bld})
9872 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9873 env.Program(target = 'bar', source = 'bar.c')
9876 You also can use other Pythonic techniques to add
9877 to the BUILDERS construction variable, such as:
9881 env['BUILDERS]['PDFBuilder'] = bld
9884 .SS Defining Your Own Scanner Object
9889 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9890 '\" not inappropriate doubled escape characters within the r'' raw string.
9891 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9893 def kfile_scan(node, env, path, arg):
9894 contents = node.get_contents()
9895 includes = include_re.findall(contents)
9898 kscan = Scanner(name = 'kfile',
9899 function = kfile_scan,
9902 scanners = Environment().Dictionary('SCANNERS')
9903 env = Environment(SCANNERS = scanners + [kscan])
9905 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9907 bar_in = File('bar.in')
9908 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9909 bar_in.target_scanner = kscan
9912 .SS Creating a Hierarchical Build
9914 Notice that the file names specified in a subdirectory's
9916 file are relative to that subdirectory.
9922 env.Program(target = 'foo', source = 'foo.c')
9924 SConscript('sub/SConscript')
9929 # Builds sub/foo from sub/foo.c
9930 env.Program(target = 'foo', source = 'foo.c')
9932 SConscript('dir/SConscript')
9937 # Builds sub/dir/foo from sub/dir/foo.c
9938 env.Program(target = 'foo', source = 'foo.c')
9941 .SS Sharing Variables Between SConscript Files
9943 You must explicitly Export() and Import() variables that
9944 you want to share between SConscript files.
9950 env.Program(target = 'foo', source = 'foo.c')
9953 SConscript('subdirectory/SConscript')
9955 subdirectory/SConscript:
9958 env.Program(target = 'foo', source = 'foo.c')
9961 .SS Building Multiple Variants From the Same Source
9963 Use the build_dir keyword argument to
9964 the SConscript function to establish
9965 one or more separate build directories for
9966 a given source directory:
9971 cppdefines = ['FOO']
9972 Export("cppdefines")
9973 SConscript('src/SConscript', build_dir='foo')
9975 cppdefines = ['BAR']
9976 Export("cppdefines")
9977 SConscript('src/SConscript', build_dir='bar')
9981 Import("cppdefines")
9982 env = Environment(CPPDEFINES = cppdefines)
9983 env.Program(target = 'src', source = 'src.c')
9986 Note the use of the Export() method
9987 to set the "cppdefines" variable to a different
9988 value each time we call the SConscript function.
9990 .SS Hierarchical Build of Two Libraries Linked With a Program
9995 env = Environment(LIBPATH = ['#libA', '#libB'])
9997 SConscript('libA/SConscript')
9998 SConscript('libB/SConscript')
9999 SConscript('Main/SConscript')
10004 env.Library('a', Split('a1.c a2.c a3.c'))
10009 env.Library('b', Split('b1.c b2.c b3.c'))
10014 e = env.Copy(LIBS = ['a', 'b'])
10015 e.Program('foo', Split('m1.c m2.c m3.c'))
10018 The '#' in the LIBPATH directories specify that they're relative to the
10019 top-level directory, so they don't turn into "Main/libA" when they're
10020 used in Main/SConscript.
10022 Specifying only 'a' and 'b' for the library names
10023 allows SCons to append the appropriate library
10024 prefix and suffix for the current platform
10025 (for example, 'liba.a' on POSIX systems,
10026 'a.lib' on Windows).
10028 .SS Customizing contruction variables from the command line.
10030 The following would allow the C compiler to be specified on the command
10031 line or in the file custom.py.
10034 opts = Options('custom.py')
10035 opts.Add('CC', 'The C compiler.')
10036 env = Environment(options=opts)
10037 Help(opts.GenerateHelpText(env))
10040 The user could specify the C compiler on the command line:
10046 or in the custom.py file:
10052 or get documentation on the options:
10057 CC: The C compiler.
10063 .SS Using Microsoft Visual C++ precompiled headers
10065 Since windows.h includes everything and the kitchen sink, it can take quite
10066 some time to compile it over and over again for a bunch of object files, so
10067 Microsoft provides a mechanism to compile a set of headers once and then
10068 include the previously compiled headers in any object file. This
10069 technology is called precompiled headers. The general recipe is to create a
10070 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
10071 then include every header you want to precompile in "StdAfx.h", and finally
10072 include "StdAfx.h" as the first header in all the source files you are
10073 compiling to object files. For example:
10077 #include <windows.h>
10078 #include <my_big_header.h>
10083 #include <StdAfx.h>
10088 #include <StdAfx.h>
10090 /* do some stuff */
10095 #include <StdAfx.h>
10097 /* do some other stuff */
10103 env['PCHSTOP'] = 'StdAfx.h'
10104 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10105 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10108 For more information see the document for the PCH builder, and the PCH and
10109 PCHSTOP construction variables. To learn about the details of precompiled
10110 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10112 .SS Using Microsoft Visual C++ external debugging information
10114 Since including debugging information in programs and shared libraries can
10115 cause their size to increase significantly, Microsoft provides a mechanism
10116 for including the debugging information in an external file called a PDB
10117 file. SCons supports PDB files through the PDB construction
10123 env['PDB'] = 'MyApp.pdb'
10124 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10127 For more information see the document for the PDB construction variable.
10132 Specifies the directory that contains the SCons Python module directory
10133 (e.g. /home/aroach/scons-src-0.01/src/engine).
10136 A string of options that will be used by scons in addition to those passed
10137 on the command line.
10148 Steven Knight <knight@baldmt.com>
10150 Anthony Roach <aroach@electriceyeball.com>