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 Prints a list of the various objects
557 of the various classes used internally by SCons.
558 This only works when run under Python 2.1 or later.
562 Re-run SCons under the control of the
569 Print the raw command line used to build each target
570 before the construction environment variables are substituted.
571 Also shows which targets are being built by this command.
572 Output looks something like this:
574 $ scons --debug=presub
575 Building myprog.o with action(s):
576 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
582 Prints an internal Python stack trace
583 when encountering an otherwise unexplained error.
587 Print the dependency tree along with status information. This is the
588 same as the debug=tree option, but additional status information is
589 provided for each node in the tree.
593 Prints various time profiling information: the time spent
594 executing each build command, the total build time, the total time spent
595 executing build commands, the total time spent executing SConstruct and
596 SConscript files, and the total time spent executing SCons itself.
600 Print the dependency tree
601 after each top-level target is built. This prints out the complete
602 dependency tree including implicit dependencies and ignored
606 .\" -e, --environment-overrides
607 .\" Variables from the execution environment override construction
608 .\" variables from the SConscript files.
611 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
614 as the initial SConscript file.
618 Print a local help message for this build, if one is defined in
619 the SConscript file(s), plus a line that describes the
621 option for command-line option help. If no local help message
622 is defined, prints the standard help message about command-line
623 options. Exits after displaying the appropriate message.
627 Print the standard help message about command-line options and
632 Ignore all errors from commands executed to rebuild files.
635 .RI -I " directory" ", --include-dir=" directory
639 imported Python modules. If several
642 are used, the directories are searched in the order specified.
646 Cache implicit dependencies. This can cause
648 to miss changes in the implicit dependencies in cases where a new implicit
649 dependency is added earlier in the implicit dependency search path
650 (e.g. CPPPATH) than a current implicit dependency with the same name.
653 --implicit-deps-changed
654 Force SCons to ignore the cached implicit dependencies. This causes the
655 implicit dependencies to be rescanned and recached. This implies
656 .BR --implicit-cache .
659 --implicit-deps-unchanged
660 Force SCons to ignore changes in the implicit dependencies.
661 This causes cached implicit dependencies to always be used.
663 .BR --implicit-cache .
666 .RI -j " N" ", --jobs=" N
667 Specifies the number of jobs (commands) to run simultaneously.
668 If there is more than one
670 option, the last one is effective.
674 .\" is specified without an argument,
676 .\" will not limit the number of
677 .\" simultaneous jobs.
681 Continue as much as possible after an error. The target that
682 failed and those that depend on it will not be remade, but other
683 targets specified on the command line will still be processed.
686 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
687 .\" No new jobs (commands) will be started if
688 .\" there are other jobs running and the system load
689 .\" average is at least
691 .\" (a floating-point number).
694 .RI --duplicate= ORDER
695 There are three ways to duplicate files in a build tree: hard links,
696 soft (symbolic) links and copies. The default behaviour of SCons is to
697 prefer hard links to soft links to copies. You can specify different
698 behaviours with this option.
708 SCons will attempt to duplicate files using
709 the mechanisms in the specified order.
714 .\" List derived files (targets, dependencies) that would be built,
715 .\" but do not build them.
716 .\" [XXX This can probably go away with the right
717 .\" combination of other options. Revisit this issue.]
721 .\" List derived files that would be built, with the actions
722 .\" (commands) that build them. Does not build the files.
723 .\" [XXX This can probably go away with the right
724 .\" combination of other options. Revisit this issue.]
728 .\" List derived files that would be built, plus where the file is
729 .\" defined (file name and line number). Does not build the files.
730 .\" [XXX This can probably go away with the right
731 .\" combination of other options. Revisit this issue.]
735 Ignored for compatibility with non-GNU versions of
739 .RI --max-drift= SECONDS
740 Set the maximum expected drift in the modification time of files to
742 This value determines how old a file must be before its content signature
743 is cached. The default value is 2 days, which means a file must have a
744 modification time of at least two days ago in order to have its content
745 signature cached. A negative value means to never cache the content
746 signature and to ignore the cached value if there already is one. A value
747 of 0 means to always cache the signature, no matter how old the file is.
750 -n, --just-print, --dry-run, --recon
751 No execute. Print the commands that would be executed to build
752 any out-of-date target files, but do not execute the commands.
755 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
759 .\" not rebuild anything due to changes in the contents of
762 .\" .RI --override " file"
763 .\" Read values to override specific build environment variables
764 .\" from the specified
768 .\" Print the data base (construction environments,
769 .\" Builder and Scanner objects) that are defined
770 .\" after reading the SConscript files.
771 .\" After printing, a normal build is performed
772 .\" as usual, as specified by other command-line options.
773 .\" This also prints version information
778 .\" To print the database without performing a build do:
786 Run SCons under the Python profiler
787 and save the results in the specified
789 The results may be analyzed using the Python
793 Do not run any commands, or print anything. Just return an exit
794 status that is zero if the specified targets are already up to
795 date, non-zero otherwise.
798 Quiets SCons status messages about
799 reading SConscript files,
801 and entering directories.
802 Commands that are executed
803 to rebuild target files are still printed.
806 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
807 .\" Clear the default construction variables. Construction
808 .\" environments that are created will be completely empty.
812 Build dependencies in a random order. This is useful when
813 building multiple trees simultaneously with caching enabled,
814 to prevent multiple builds from simultaneously trying to build
815 or retrieve the same target files.
818 -s, --silent, --quiet
819 Silent. Do not print commands that are executed to rebuild
821 Also suppresses SCons status messages.
824 -S, --no-keep-going, --stop
825 Ignored for compatibility with GNU
830 Ignored for compatibility with GNU
832 (Touching a file to make it
833 appear up-to-date is unnecessary when using
837 -u, --up, --search-up
838 Walks up the directory structure until an
843 file is found, and uses that
844 as the top of the directory tree.
845 If no targets are specified on the command line,
846 only targets at or below the
847 current directory will be built.
851 Works exactly the same way as the
853 option except for the way default targets are handled.
854 When this option is used and no targets are specified on the command line,
855 all default targets that are defined in the SConscript(s) in the current
856 directory are built, regardless of what directory the resultant targets end
863 version, copyright information,
864 list of authors, and any other relevant information.
868 -w, --print-directory
869 Print a message containing the working directory before and
870 after other processing.
873 .RI --warn= type ", --warn=no-" type
874 Enable or disable warnings.
876 specifies the type of warnings to be enabled or disabled:
879 --warn=all, --warn=no-all
880 Enables or disables all warnings.
883 --warn=dependency, --warn=no-dependency
884 Enables or disables warnings about dependencies.
885 These warnings are disabled by default.
888 --warn=deprecated, --warn=no-deprecated
889 Enables or disables warnings about use of deprecated features.
890 These warnings are enabled by default.
893 --warn=missing-sconscript, --warn=no-missing-sconscript
894 Enables or disables warnings about missing SConscript files.
895 These warnings are enabled by default.
899 Turn off -w, even if it was turned on implicitly.
902 .\" .RI --write-filenames= file
903 .\" Write all filenames considered into
907 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
908 .\" Pretend that the target
911 .\" modified. When used with the
914 .\" show you what would be rebuilt if you were to modify that file.
920 .\" --warn-undefined-variables
921 .\" Warn when an undefined variable is referenced.
924 .RI -Y " repository" ", --repository=" repository
925 Search the specified repository for any input and target
926 files not found in the local directory hierarchy. Multiple
928 options may specified, in which case the
929 repositories are searched in the order specified.
931 .SH CONFIGURATION FILE REFERENCE
932 .\" .SS Python Basics
933 .\" XXX Adding this in the future would be a help.
934 .SS Construction Environments
935 A construction environment is the basic means by which the SConscript
936 files communicate build information to
938 A new construction environment is created using the
946 By default, a new construction environment is
947 initialized with a set of builder methods
948 and construction variables that are appropriate
949 for the current platform.
950 An optional platform keyword argument may be
951 used to specify that an environment should
952 be initialized for a different platform:
955 env = Environment(platform = 'cygwin')
956 env = Environment(platform = 'os2')
957 env = Environment(platform = 'posix')
958 env = Environment(platform = 'win32')
961 Specifying a platform initializes the appropriate
962 construction variables in the environment
963 to use and generate file names with prefixes
964 and suffixes appropriate for the platform.
970 variable from the user's external environment
971 to the construction environment's
974 This is so that any executed commands
975 that use sockets to connect with other systems
976 (such as fetching source files from
977 external CVS repository specifications like
978 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
979 will work on Win32 systems.
981 The platform argument may be function or callable object,
982 in which case the Environment() method
983 will call the specified argument to update
984 the new construction environment:
987 def my_platform(env):
990 env = Environment(platform = my_platform)
993 Additionally, a specific set of tools
994 with which to initialize the environment
995 may specified as an optional keyword argument:
998 env = Environment(tools = ['msvc', 'lex'])
1001 Non-built-in tools may be specified using the toolpath argument:
1004 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1007 This looks for a tool specification in tools/foo.py (as well as
1008 using the ordinary default tools for the platform). foo.py should
1009 have two functions: generate(env, **kw) and exists(env).
1013 modifies the passed-in environment
1014 to set up variables so that the tool
1016 it may use any keyword arguments
1017 that the user supplies (see below)
1018 to vary its initialization.
1021 function should return a true
1022 value if the tool is available.
1023 Tools in the toolpath are used before
1024 any of the built-in ones. For example, adding gcc.py to the toolpath
1025 would override the built-in gcc tool.
1026 Also note that the toolpath is
1027 stored in the environment for use
1035 base = Environment(toolpath=['custom_path'])
1036 derived = base.Copy(tools=['custom_tool'])
1037 derived.CustomBuilder()
1040 The elements of the tools list may also
1041 be functions or callable objects,
1042 in which case the Environment() method
1043 will call the specified elements
1044 to update the new construction environment:
1048 env['XYZZY'] = 'xyzzy'
1050 env = Environment(tools = [my_tool])
1053 The individual elements of the tools list
1054 may also themselves be two-element lists of the form
1055 .RI ( toolname ", " kw_dict ).
1056 SCons searches for the
1058 specification file as described above, and
1061 which must be a dictionary, as keyword arguments to the tool's
1066 function can use the arguments to modify the tool's behavior
1067 by setting up the environment in different ways
1068 or otherwise changing its initialization.
1071 # in tools/my_tool.py:
1072 def generate(env, **kw):
1073 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1074 env['MY_TOOL'] = kw.get('arg1', '1')
1079 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1083 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1084 the environment it receives to customize the tool for different platforms.
1086 If no tool list is specified, then SCons will auto-detect the installed
1087 tools using the PATH variable in the ENV construction variable and the
1088 platform name when the Environment is constructed. Changing the PATH
1089 variable after the Environment is constructed will not cause the tools to
1092 SCons supports the following tool specifications out of the box:
1168 Additionally, there is a "tool" named
1170 which configures the
1171 environment with a default set of tools for the current platform.
1173 On posix and cygwin platforms
1174 the GNU tools (e.g. gcc) are preferred by SCons,
1175 on win32 the Microsoft tools (e.g. msvc)
1176 followed by MinGW are preferred by SCons,
1177 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1181 Build rules are specified by calling a construction
1182 environment's builder methods.
1183 The arguments to the builder methods are
1185 (a list of target files)
1188 (a list of source files).
1190 Because long lists of file names
1191 can lead to a lot of quoting,
1196 and a same-named environment method
1197 that split a single string
1198 into a list, separated on
1199 strings of white-space characters.
1200 (These are similar to the
1201 string.split() method
1202 from the standard Python library,
1203 but work even if the input isn't a string.)
1205 Like all Python arguments,
1206 the target and source arguments to a builder method
1207 can be specified either with or without
1208 the "target" and "source" keywords.
1209 When the keywords are omitted,
1210 the target is first,
1211 followed by the source.
1212 The following are equivalent examples of calling the Program builder method:
1215 env.Program('bar', ['bar.c', 'foo.c'])
1216 env.Program('bar', Split('bar.c foo.c'))
1217 env.Program('bar', env.Split('bar.c foo.c'))
1218 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1219 env.Program(target = 'bar', Split('bar.c foo.c'))
1220 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1221 env.Program('bar', source = string.split('bar.c foo.c'))
1224 When the target shares the same base name
1225 as the source and only the suffix varies,
1226 and if the builder method has a suffix defined for the target file type,
1227 then the target argument may be omitted completely,
1230 will deduce the target file name from
1231 the source file name.
1232 The following examples all build the
1238 (on Windows systems)
1239 from the bar.c source file:
1242 env.Program(target = 'bar', source = 'bar.c')
1243 env.Program('bar', source = 'bar.c')
1244 env.Program(source = 'bar.c')
1245 env.Program('bar.c')
1248 It is possible to override or add construction variables when calling a
1249 builder method by passing additional keyword arguments.
1250 These overridden or added
1251 variables will only be in effect when building the target, so they will not
1252 affect other parts of the build. For example, if you want to add additional
1253 libraries for just one program:
1256 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1259 or generate a shared library with a nonstandard suffix:
1262 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1265 Although the builder methods defined by
1268 methods of a construction environment object,
1269 they may also be called without an explicit environment:
1272 Program('hello', 'hello.c')
1273 SharedLibrary('word', 'word.cpp')
1277 the methods are called internally using a default construction
1278 environment that consists of the tools and values that
1280 has determined are appropriate for the local system.
1282 Builder methods that can be called without an explicit
1283 environment may be called from custom Python modules that you
1284 import into an SConscript file by adding the following
1285 to the Python module:
1288 from SCons.Script import *
1291 All builder methods return a list of Nodes
1292 that represent the target or targets that will be built.
1295 is an internal SCons object
1297 build targets or sources.
1299 The returned Node(s)
1300 can be passed to other builder methods as source(s)
1301 or passed to any SCons function or method
1302 where a filename would normally be accepted.
1303 For example, if it were necessary
1306 flag when compiling one specific object file:
1309 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1310 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1313 Using a Node in this way
1314 makes for a more portable build
1315 by avoiding having to specify
1316 a platform-specific object suffix
1317 when calling the Program() builder method.
1319 Note that Builder calls will automatically "flatten"
1320 the source and target file lists,
1321 so it's all right to have the bar_obj list
1322 return by the StaticObject() call
1323 in the middle of the source file list.
1324 If you need to manipulate a list of lists returned by Builders
1325 directly using Python,
1326 you can either build the list by hand:
1329 foo = Object('foo.c')
1330 bar = Object('bar.c')
1331 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1332 for object in objects:
1339 to create a list containing just the Nodes,
1340 which may be more convenient:
1343 foo = Object('foo.c')
1344 bar = Object('bar.c')
1345 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1346 for object in objects:
1350 The path name for a Node's file may be used
1351 by passing the Node to the Python-builtin
1356 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1357 print "The path to bar_obj is:", str(bar_obj_list[0])
1360 Note again that because the Builder call returns a list,
1361 we have to access the first element in the list
1362 .B (bar_obj_list[0])
1363 to get at the Node that actually represents
1366 Builder calls support a
1368 keyword argument that
1369 specifies that the Builder's action(s)
1371 after changing directory.
1375 a string or a directory Node,
1376 scons will change to the specified directory.
1379 is not a string or Node
1381 then scons will change to the
1382 target file's directory.
1385 # scons will change to the "sub" subdirectory
1386 # before executing the "cp" command.
1387 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1388 "cp dir/foo.in dir/foo.out",
1391 # Because chdir is not a string, scons will change to the
1392 # target's directory ("sub/dir") before executing the
1394 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1395 "cp foo.in foo.out",
1399 Note that scons will
1401 automatically modify
1403 construction variables like
1407 when using the chdir
1408 keyword argument--that is,
1409 the expanded file names
1410 will still be relative to
1411 the top-level SConstruct directory,
1412 and consequently incorrect
1413 relative to the chdir directory.
1414 If you use the chdir keyword argument,
1415 you will typically need to supply a different
1421 to use just the filename portion of the
1425 provides the following builder methods:
1427 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1430 Builds a C source file given a lex (.l) or yacc (.y) input file.
1431 The suffix specified by the $CFILESUFFIX construction variable
1433 is automatically added to the target
1434 if it is not already present. Example:
1438 env.CFile(target = 'foo.c', source = 'foo.l')
1440 env.CFile(target = 'bar', source = 'bar.y')
1443 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1446 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1448 The suffix specified by the $CXXFILESUFFIX construction variable
1450 is automatically added to the target
1451 if it is not already present. Example:
1455 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1457 env.CXXFile(target = 'bar', source = 'bar.yy')
1460 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1463 Builds a .dvi file from a .tex, .ltx or .latex input file.
1464 If the source file suffix is .tex,
1466 will examine the contents of the file;
1471 is found, the file is assumed to be a LaTeX file and
1472 the target is built by invoking the $LATEXCOM command line;
1473 otherwise, the $TEXCOM command line is used.
1474 If the file is a LaTeX file,
1477 builder method will also examine the contents
1480 and invoke the $BIBTEX command line
1484 and will examine the contents
1486 file and re-run the $LATEXCOM command
1487 if the log file says it is necessary.
1490 (hard-coded within TeX itself)
1491 is automatically added to the target
1492 if it is not already present. Examples:
1495 # builds from aaa.tex
1496 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1498 env.DVI(target = 'bbb', source = 'bbb.ltx')
1499 # builds from ccc.latex
1500 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1503 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1506 Builds a Java archive (.jar) file
1507 from a source tree of .class files.
1508 If the $JARCHDIR value is set, the
1510 command will change to the specified directory using the
1513 If the contents any of the source files begin with the string
1514 .BR Manifest-Version ,
1515 the file is assumed to be a manifest
1516 and is passed to the
1523 env.Jar(target = 'foo.jar', source = 'classes')
1526 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1529 Builds one or more Java class files
1530 from one or more source trees of .java files.
1531 The class files will be placed underneath
1532 the specified target directory.
1533 SCons will parse each source .java file
1535 (including inner classes)
1536 defined within that file,
1537 and from that figure out the
1538 target .class files that will be created.
1539 SCons will also search each Java file
1540 for the Java package name,
1541 which it assumes can be found on a line
1542 beginning with the string
1544 in the first column;
1545 the resulting .class files
1546 will be placed in a directory reflecting
1547 the specified package name.
1551 defining a single public
1554 containing a package name of
1556 will generate a corresponding
1557 .IR sub/dir/Foo.class
1563 env.Java(target = 'classes', source = 'src')
1564 env.Java(target = 'classes', source = ['src1', 'src2'])
1567 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1570 Builds C header and source files for
1571 implementing Java native methods.
1572 The target can be either a directory
1573 in which the header files will be written,
1574 or a header file name which
1575 will contain all of the definitions.
1576 The source can be either the names of .class files,
1577 or the objects returned from the
1581 If the construction variable
1583 is set, either in the environment
1584 or in the call to the
1586 builder method itself,
1587 then the value of the variable
1588 will be stripped from the
1589 beginning of any .class file names.
1594 # builds java_native.h
1595 classes = env.Java(target = 'classdir', source = 'src')
1596 env.JavaH(target = 'java_native.h', source = classes)
1598 # builds include/package_foo.h and include/package_bar.h
1599 env.JavaH(target = 'include',
1600 source = ['package/foo.class', 'package/bar.class'])
1602 # builds export/foo.h and export/bar.h
1603 env.JavaH(target = 'export',
1604 source = ['classes/foo.class', 'classes/bar.class'],
1605 JAVACLASSDIR = 'classes')
1608 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1615 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1616 .IP LoadableModule()
1617 .IP env.LoadableModule()
1620 .BR SharedLibrary ().
1621 On Mac OS X (Darwin) platforms,
1622 this creates a loadable module bundle.
1625 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1628 Builds an output file from an M4 input file.
1629 This uses a default $M4FLAGS value of
1631 which considers all warnings to be fatal
1632 and stops on the first warning
1633 when using the GNU version of m4.
1637 env.M4(target = 'foo.c', source = 'foo.c.m4')
1640 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1643 Builds an output file from a moc input file. Moc input files are either
1644 header files or cxx files. This builder is only available after using the
1645 tool 'qt'. See the QTDIR variable for more information.
1649 env.Moc('foo.h') # generates moc_foo.cc
1650 env.Moc('foo.cpp') # generates foo.moc
1653 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1655 .IP env.MSVSProject()
1656 Builds Microsoft Visual Studio project files.
1657 This builds a Visual Studio project file, based on the version of
1658 Visual Studio that is configured (either the latest installed version,
1659 or the version set by
1661 in the Environment constructor).
1662 For VS 6, it will generate
1666 files, for VS 7, it will
1673 It takes several lists of filenames to be placed into the project
1674 file, currently these are limited to
1675 .B srcs, incs, localincs, resources,
1678 These are pretty self explanatory, but it
1679 should be noted that the 'srcs' list is NOT added to the $SOURCES
1680 environment variable. This is because it represents a list of files
1681 to be added to the project file, not the source used to build the
1682 project file (in this case, the 'source' is the SConscript file used
1683 to call MSVSProject).
1685 In addition to these values (which are all optional, although not
1686 specifying any of them results in an empty project file), the
1687 following values must be specified:
1689 target: The name of the target .dsp or .vcproj file. The correct
1690 suffix for the version of Visual Studio must be used, but the value
1692 env['MSVSPROJECTSUFFIX']
1694 will be defined to the correct value (see example below).
1696 variant: The name of this particular variant. These are typically
1697 things like "Debug" or "Release", but really can be anything you want.
1698 Multiple calls to MSVSProject with different variants are allowed: all
1699 variants will be added to the project file with their appropriate
1700 build targets and sources.
1702 buildtarget: A list of SCons.Node.FS objects which is returned from
1703 the command which builds the target. This is used to tell SCons what
1704 to build when the 'build' button is pressed inside of the IDE.
1709 barsrcs = ['bar.cpp'],
1710 barincs = ['bar.h'],
1711 barlocalincs = ['StdAfx.h']
1712 barresources = ['bar.rc','resource.h']
1713 barmisc = ['bar_readme.txt']
1715 dll = local.SharedLibrary(target = 'bar.dll',
1718 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1721 localincs = barlocalincs,
1722 resources = barresources,
1725 variant = 'Release')
1728 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1735 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1738 Builds a Microsoft Visual C++ precompiled header.
1739 Calling this builder method
1740 returns a list of two targets: the PCH as the first element, and the object
1741 file as the second element. Normally the object file is ignored.
1742 This builder method is only
1743 provided when Microsoft Visual C++ is being used as the compiler.
1744 The PCH builder method is generally used in
1745 conjuction with the PCH construction variable to force object files to use
1746 the precompiled header:
1749 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1752 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1755 Builds a .pdf file from a .dvi input file
1756 (or, by extension, a .tex, .ltx, or .latex input file).
1757 The suffix specified by the $PDFSUFFIX construction variable
1759 is added automatically to the target
1760 if it is not already present. Example:
1763 # builds from aaa.tex
1764 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1765 # builds bbb.pdf from bbb.dvi
1766 env.PDF(target = 'bbb', source = 'bbb.dvi')
1769 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1771 .IP env.PostScript()
1772 Builds a .ps file from a .dvi input file
1773 (or, by extension, a .tex, .ltx, or .latex input file).
1774 The suffix specified by the $PSSUFFIX construction variable
1776 is added automatically to the target
1777 if it is not already present. Example:
1780 # builds from aaa.tex
1781 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1782 # builds bbb.ps from bbb.dvi
1783 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1786 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1789 Builds an executable given one or more object files
1790 or C, C++, D, or Fortran source files.
1791 If any C, C++, D or Fortran source files are specified,
1792 then they will be automatically
1793 compiled to object files using the
1796 see that builder method's description for
1797 a list of legal source file suffixes
1798 and how they are interpreted.
1799 The target executable file prefix
1800 (specified by the $PROGPREFIX construction variable; nothing by default)
1802 (specified by the $PROGSUFFIX construction variable;
1803 by default, .exe on Windows systems, nothing on POSIX systems)
1804 are automatically added to the target if not already present.
1808 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1811 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1814 Builds a Microsoft Visual C++ resource file.
1815 This builder method is only provided
1816 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1820 for MinGW) suffix is added to the target name if no other suffix is given. The source
1821 file is scanned for implicit dependencies as though it were a C file. Example:
1824 env.RES('resource.rc')
1827 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1830 Builds stub and skeleton class files
1832 from Java .class files.
1833 The target is a directory
1834 relative to which the stub
1835 and skeleton class files will be written.
1836 The source can be the names of .class files,
1837 or the objects return from the
1841 If the construction variable
1843 is set, either in the environment
1844 or in the call to the
1846 builder method itself,
1847 then the value of the variable
1848 will be stripped from the
1849 beginning of any .class file names.
1852 classes = env.Java(target = 'classdir', source = 'src')
1853 env.RMIC(target = 'outdir1', source = classes)
1855 env.RMIC(target = 'outdir2',
1856 source = ['package/foo.class', 'package/bar.class'])
1858 env.RMIC(target = 'outdir3',
1859 source = ['classes/foo.class', 'classes/bar.class'],
1860 JAVACLASSDIR = 'classes')
1863 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1865 .IP env.RPCGenClient()
1866 Generates an RPC client stub (_clnt.c) file
1867 from a specified RPC (.x) source file.
1868 Because rpcgen only builds output files
1869 in the local directory,
1870 the command will be executed
1871 in the source file's directory by default.
1874 # Builds src/rpcif_clnt.c
1875 env.RPCGenClient('src/rpcif.x')
1878 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1880 .IP env.RPCGenHeader()
1881 Generates an RPC header (.h) file
1882 from a specified RPC (.x) source file.
1883 Because rpcgen only builds output files
1884 in the local directory,
1885 the command will be executed
1886 in the source file's directory by default.
1889 # Builds src/rpcif.h
1890 env.RPCGenHeader('src/rpcif.x')
1893 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1895 .IP env.RPCGenService()
1896 Generates an RPC server-skeleton (_svc.c) file
1897 from a specified RPC (.x) source file.
1898 Because rpcgen only builds output files
1899 in the local directory,
1900 the command will be executed
1901 in the source file's directory by default.
1904 # Builds src/rpcif_svc.c
1905 env.RPCGenClient('src/rpcif.x')
1908 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1911 Generates an RPC XDR routine (_xdr.c) file
1912 from a specified RPC (.x) source file.
1913 Because rpcgen only builds output files
1914 in the local directory,
1915 the command will be executed
1916 in the source file's directory by default.
1919 # Builds src/rpcif_xdr.c
1920 env.RPCGenClient('src/rpcif.x')
1923 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1925 .IP env.SharedLibrary()
1926 Builds a shared library
1927 (.so on a POSIX system, .dll on WIN32)
1928 given one or more object files
1929 or C, C++, D or Fortran source files.
1930 If any source files are given,
1931 then they will be automatically
1932 compiled to object files.
1933 The static library prefix and suffix (if any)
1934 are automatically added to the target.
1935 The target library file prefix
1936 (specified by the $SHLIBPREFIX construction variable;
1937 by default, lib on POSIX systems, nothing on Windows systems)
1939 (specified by the $SHLIBSUFFIX construction variable;
1940 by default, .dll on Windows systems, .so on POSIX systems)
1941 are automatically added to the target if not already present.
1945 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1948 On WIN32 systems, the
1950 builder method will always build an import (.lib) library
1951 in addition to the shared (.dll) library,
1952 adding a .lib library with the same basename
1953 if there is not already a .lib file explicitly
1954 listed in the targets.
1956 Any object files listed in the
1958 must have been built for a shared library
1963 will raise an error if there is any mismatch.
1965 On WIN32 systems, specifying "register=1" will cause the dll to be
1966 registered after it is built using REGSVR32. The command that is run
1967 ("regsvr32" by default) is determined by $REGSVR construction
1968 variable, and the flags passed are determined by $REGSVRFLAGS. By
1969 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1970 up and requiring user attention when it is run. If you change
1971 $REGSVRFLAGS, be sure to include "/s". For example,
1974 env.SharedLibrary(target = 'bar',
1975 source = ['bar.cxx', 'foo.obj'],
1980 will register "bar.dll" as a COM object when it is done linking it.
1982 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1984 .IP env.SharedObject()
1985 Builds an object file for
1986 inclusion in a shared library.
1987 Source files must have one of the same set of extensions
1988 specified above for the
1991 On some platforms building a shared object requires additional
1992 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1993 normal (static) object, but on some platforms there is no difference between a
1994 shared object and a normal (static) one. When there is a difference, SCons
1995 will only allow shared objects to be linked into a shared library, and will
1996 use a different suffix for shared objects. On platforms where there is no
1997 difference, SCons will allow both normal (static)
1998 and shared objects to be linked into a
1999 shared library, and will use the same suffix for shared and normal
2001 The target object file prefix
2002 (specified by the $SHOBJPREFIX construction variable;
2003 by default, the same as $OBJPREFIX)
2005 (specified by the $SHOBJSUFFIX construction variable)
2006 are automatically added to the target if not already present.
2010 env.SharedObject(target = 'ddd', source = 'ddd.c')
2011 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2012 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2015 Note that the source files will be scanned
2016 according to the suffix mappings in
2017 .B SourceFileScanner
2019 See the section "Scanner Objects,"
2020 below, for a more information.
2022 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2024 .IP env.StaticLibrary()
2025 Builds a static library given one or more object files
2026 or C, C++, D or Fortran source files.
2027 If any source files are given,
2028 then they will be automatically
2029 compiled to object files.
2030 The static library prefix and suffix (if any)
2031 are automatically added to the target.
2032 The target library file prefix
2033 (specified by the $LIBPREFIX construction variable;
2034 by default, lib on POSIX systems, nothing on Windows systems)
2036 (specified by the $LIBSUFFIX construction variable;
2037 by default, .lib on Windows systems, .a on POSIX systems)
2038 are automatically added to the target if not already present.
2042 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2046 Any object files listed in the
2048 must have been built for a static library
2053 will raise an error if there is any mismatch.
2055 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2057 .IP env.StaticObject()
2058 Builds a static object file
2059 from one or more C, C++, D, or Fortran source files.
2060 Source files must have one of the following extensions:
2063 .asm assembly language file
2064 .ASM assembly language file
2076 .F WIN32: Fortran file
2077 POSIX: Fortran file + C pre-processor
2080 .fpp Fortran file + C pre-processor
2081 .FPP Fortran file + C pre-processor
2083 .mm Objective C++ file
2084 .s assembly language file
2085 .S WIN32: assembly language file
2086 POSIX: assembly language file + C pre-processor
2087 .spp assembly language file + C pre-processor
2088 .SPP assembly language file + C pre-processor
2091 The target object file prefix
2092 (specified by the $OBJPREFIX construction variable; nothing by default)
2094 (specified by the $OBJSUFFIX construction variable;
2095 \.obj on Windows systems, .o on POSIX systems)
2096 are automatically added to the target if not already present.
2100 env.StaticObject(target = 'aaa', source = 'aaa.c')
2101 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2102 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2105 Note that the source files will be scanned
2106 according to the suffix mappings in
2107 .B SourceFileScanner
2109 See the section "Scanner Objects,"
2110 below, for a more information.
2112 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2115 Builds a tar archive of the specified files
2117 Unlike most builder methods,
2120 builder method may be called multiple times
2122 each additional call
2123 adds to the list of entries
2124 that will be built into the archive.
2125 Any source directories will
2126 be scanned for changes to
2128 regardless of whether or not
2130 knows about them from other Builder or function calls.
2133 env.Tar('src.tar', 'src')
2135 # Create the stuff.tar file.
2136 env.Tar('stuff', ['subdir1', 'subdir2'])
2137 # Also add "another" to the stuff.tar file.
2138 env.Tar('stuff', 'another')
2140 # Set TARFLAGS to create a gzip-filtered archive.
2141 env = Environment(TARFLAGS = '-c -z')
2142 env.Tar('foo.tar.gz', 'foo')
2144 # Also set the suffix to .tgz.
2145 env = Environment(TARFLAGS = '-c -z',
2150 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2152 .IP env.TypeLibrary()
2153 Builds a Windows type library (.tlb) file from and input IDL file
2154 (.idl). In addition, it will build the associated inteface stub and
2155 proxy source files. It names them according to the base name of the .idl file.
2160 env.TypeLibrary(source="foo.idl")
2163 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2165 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2168 Builds a header file, an implementation file and a moc file from an ui file.
2169 and returns the corresponding nodes in the above order.
2170 This builder is only available after using the tool 'qt'. Note: you can
2171 specify .ui files directly as inputs for Program, Library and SharedLibrary
2172 without using this builder. Using the builder lets you override the standard
2173 naming conventions (be careful: prefixes are always prepended to names of
2174 built files; if you don't want prefixes, you may set them to ``).
2175 See the QTDIR variable for more information.
2179 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2180 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2181 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2184 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2187 Builds a zip archive of the specified files
2189 Unlike most builder methods,
2192 builder method may be called multiple times
2194 each additional call
2195 adds to the list of entries
2196 that will be built into the archive.
2197 Any source directories will
2198 be scanned for changes to
2200 regardless of whether or not
2202 knows about them from other Builder or function calls.
2205 env.Zip('src.zip', 'src')
2207 # Create the stuff.zip file.
2208 env.Zip('stuff', ['subdir1', 'subdir2'])
2209 # Also add "another" to the stuff.tar file.
2210 env.Zip('stuff', 'another')
2214 targets of builder methods automatically depend on their sources.
2215 An explicit dependency can
2216 be specified using the
2218 method of a construction environment (see below).
2223 source files for various programming languages,
2224 so the dependencies do not need to be specified explicitly.
2225 By default, SCons can
2228 Fortran source files with
2230 (POSIX systems only),
2235 and assembly language files with
2237 (POSIX systems only),
2242 for C preprocessor dependencies.
2243 SCons also has default support
2244 for scanning D source files,
2245 You can also write your own Scanners
2246 to add support for additional source file types.
2247 These can be added to the default
2248 Scanner object used by
2254 Builders by adding them
2256 .B SourceFileScanner
2259 See the section "Scanner Objects,"
2260 below, for a more information about
2261 defining your own Scanner objects.
2263 .SS Methods and Functions to Do Things
2264 In addition to Builder methods,
2266 provides a number of other construction environment methods
2267 and global functions to
2268 manipulate the build configuration.
2270 Usually, a construction environment method
2271 and global function with the same name both exist
2272 so that you don't have to remember whether
2273 to a specific bit of functionality
2274 must be called with or without a construction environment.
2275 In the following list,
2276 if you call something as a global function
2279 .RI Function( arguments )
2281 and if you call something through a construction
2282 environment it looks like:
2284 .RI env.Function( arguments )
2286 If you can call the functionality in both ways,
2287 then both forms are listed.
2289 Global functions may be called from custom Python modules that you
2290 import into an SConscript file by adding the following
2291 to the Python module:
2294 from SCons.Script import *
2297 Except where otherwise noted,
2299 construction environment method
2301 provide the exact same functionality.
2302 The only difference is that,
2304 calling the functionality through a construction environment will
2305 substitute construction variables into
2306 any supplied strings.
2309 env = Environment(FOO = 'foo')
2313 the first call to the global
2315 function will actually add a target named
2317 to the list of default targets,
2318 while the second call to the
2320 construction environment method
2321 will expand the value
2322 and add a target named
2324 to the list of default targets.
2325 For more on construction variable expansion,
2326 see the next section on
2327 construction variables.
2329 Construction environment methods
2330 and global functions supported by
2334 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2336 .RI Action( action ", [" strfunction ", " varlist ])
2338 .RI env.Action( action ", [" strfunction ", " varlist ])
2339 Creates an Action object for
2342 See the section "Action Objects,"
2343 below, for a complete explanation of the arguments and behavior.
2345 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2347 .RI AddPostAction( target ", " action )
2349 .RI env.AddPostAction( target ", " action )
2350 Arranges for the specified
2356 The specified action(s) may be
2357 an Action object, or anything that
2358 can be converted into an Action object
2361 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2363 .RI AddPreAction( target ", " action )
2365 .RI env.AddPreAction( target ", " action )
2366 Arranges for the specified
2369 before the specified
2372 The specified action(s) may be
2373 an Action object, or anything that
2374 can be converted into an Action object
2377 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2379 .RI Alias( alias ", [" targets ", [" action ]])
2381 .RI env.Alias( alias ", [" targets ", [" action ]])
2382 Creates one or more phony targets that
2383 expand to one or more other targets.
2388 can be specified that will be executed
2389 whenever the any of the alias targets are out-of-date.
2390 Returns the Node object representing the alias,
2391 which exists outside of any file system.
2392 This Node object, or the alias name,
2393 may be used as a dependency of any other target,
2394 including another alias.
2396 can be called multiple times for the same
2397 alias to add additional targets to the alias,
2398 or additional actions to the list for this alias.
2402 Alias('install', '/usr/bin')
2403 Alias(['install', 'install-lib'], '/usr/local/lib')
2405 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2406 env.Alias('install', ['/usr/local/man'])
2408 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2411 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2413 .RI AlwaysBuild( target ", ...)"
2415 .RI env.AlwaysBuild( target ", ...)"
2418 so that it is always assumed to be out of date,
2419 and will always be rebuilt if needed.
2422 does not add its target(s) to the default target list,
2423 so the targets will only be built
2424 if they are specified on the command line,
2425 or are a dependent of a target specified on the command line--but
2428 be built if so specified.
2429 Multiple targets can be passed in to a single call to
2432 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2434 .RI env.Append( key = val ", [...])"
2435 Appends the specified keyword arguments
2436 to the end of construction variables in the environment.
2437 If the Environment does not have
2438 the specified construction variable,
2439 it is simply added to the environment.
2440 If the values of the construction variable
2441 and the keyword argument are the same type,
2442 then the two values will be simply added together.
2443 Otherwise, the construction variable
2444 and the value of the keyword argument
2445 are both coerced to lists,
2446 and the lists are added together.
2447 (See also the Prepend method, below.)
2450 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2453 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2455 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2456 This appends new path elements to the given path in the
2457 specified external environment
2461 any particular path once (leaving the last one it encounters and
2462 ignoring the rest, to preserve path order),
2463 and to help assure this,
2464 will normalize all paths (using
2467 .BR os.path.normcase ).
2468 This can also handle the
2469 case where the given old path variable is a list instead of a
2470 string, in which case a list will be returned instead of a string.
2474 print 'before:',env['ENV']['INCLUDE']
2475 include_path = '/foo/bar:/foo'
2476 env.PrependENVPath('INCLUDE', include_path)
2477 print 'after:',env['ENV']['INCLUDE']
2481 after: /biz:/foo/bar:/foo
2484 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2486 .RI env.AppendUnique( key = val ", [...])"
2487 Appends the specified keyword arguments
2488 to the end of construction variables in the environment.
2489 If the Environment does not have
2490 the specified construction variable,
2491 it is simply added to the environment.
2492 If the construction variable being appended to is a list,
2493 then any value(s) that already exist in the
2494 construction variable will
2496 be added again to the list.
2499 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2502 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2505 A factory function that
2506 returns a Builder object
2507 to be used to fetch source files
2509 The returned Builder
2510 is intended to be passed to the
2515 env.SourceCode('.', env.BitKeeper())
2518 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2520 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2522 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2523 This specifies a build directory
2525 in which to build all derived files
2526 that would normally be built under
2528 Multiple build directories can be set up for multiple build variants, for
2531 must be underneath the SConstruct file's directory,
2534 may not be underneath the
2537 The default behavior is for
2539 to duplicate all of the files in the tree underneath
2543 and then build the derived files within the copied tree.
2544 (The duplication is performed by
2546 depending on the platform; see also the
2549 This guarantees correct builds
2550 regardless of whether intermediate source files
2551 are generated during the build,
2552 where preprocessors or other scanners search
2554 or whether individual compilers or other invoked tools
2555 are hard-coded to put derived files in the same directory as source files.
2557 This behavior of making a complete copy of the source tree
2558 may be disabled by setting
2563 to invoke Builders using the
2564 path names of source files in
2566 and the path names of derived files within
2568 This is always more efficient than
2570 and is usually safe for most builds.
2574 may cause build problems
2575 if source files are generated during the build,
2576 if any invoked tools are hard-coded to
2577 put derived files in the same directory as the source files.
2579 Note that specifying a
2581 works most naturally
2582 with a subsidiary SConscript file
2583 in the source directory.
2585 you would then call the subsidiary SConscript file
2586 not in the source directory,
2591 had made a virtual copy of the source tree
2592 regardless of the value of
2594 This is how you tell
2596 which variant of a source tree to build.
2600 BuildDir('build-variant1', 'src')
2601 SConscript('build-variant1/SConscript')
2602 BuildDir('build-variant2', 'src')
2603 SConscript('build-variant2/SConscript')
2609 function, described below,
2611 specify a build directory
2612 in conjunction with calling a subsidiary
2615 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2617 .RI Builder( action ", [" arguments ])
2619 .RI env.Builder( action ", [" arguments ])
2620 Creates a Builder object for
2623 See the section "Builder Objects,"
2624 below, for a complete explanation of the arguments and behavior.
2626 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2628 .RI CacheDir( cache_dir )
2630 .RI env.CacheDir( cache_dir )
2633 will maintain a cache of derived files in
2635 The derived files in the cache will be shared
2636 among all the builds using the same
2644 finds a derived file that needs to be rebuilt,
2645 it will first look in the cache to see if a
2646 derived file has already been built
2647 from identical input files and an identical build action
2648 (as incorporated into the MD5 build signature).
2651 will retrieve the file from the cache.
2652 If the derived file is not present in the cache,
2655 then place a copy of the built file in the cache
2656 (identified by its MD5 build signature),
2657 so that it may be retrieved by other
2658 builds that need to build the same derived file
2659 from identical inputs.
2663 may be disabled for any invocation
2672 will place a copy of
2674 derived files in the cache,
2675 even if they already existed
2676 and were not built by this invocation.
2677 This is useful to populate a cache
2680 is added to a build,
2689 "Retrieved `file' from cache,"
2692 option is being used.
2697 will print the action that
2699 have been used to build the file,
2700 without any indication that
2701 the file was actually retrieved from the cache.
2702 This is useful to generate build logs
2703 that are equivalent regardless of whether
2704 a given derived file has been built in-place
2705 or retrieved from the cache.
2707 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2709 .RI Clean( targets ", " files_or_dirs )
2711 .RI env.Clean( targets ", " files_or_dirs )
2712 This specifies a list of files or directories which should be removed
2713 whenever the targets are specified with the
2715 command line option.
2716 The specified targets may be a list
2717 or an individual target.
2721 and create new targets or add files and directories to the
2722 clean list for the specified targets.
2724 Multiple files or directories should be specified
2725 either as separate arguments to the
2727 method, or as a list.
2729 will also accept the return value of any of the construction environment
2734 Clean('foo', ['bar', 'baz'])
2735 Clean('dist', env.Program('hello', 'hello.c'))
2736 Clean(['foo', 'bar'], 'something_else_to_clean')
2739 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2741 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2743 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2744 Executes a specific action
2745 (or list of actions)
2746 to build a target file or files.
2747 This is more convenient
2748 than defining a separate Builder object
2749 for a single special-case build.
2751 As a special case, the
2753 keyword argument can
2756 that will be used to scan the sources.
2760 if any of the sources will be directories
2761 that must be scanned on-disk for
2762 changes to files that aren't
2763 already specified in other Builder of function calls.)
2765 Any other keyword arguments specified override any
2766 same-named existing construction variables.
2768 Note that an action can be an external command,
2769 specified as a string,
2770 or a callable Python object;
2771 see "Action Objects," below.
2775 env.Command('foo.out', 'foo.in',
2776 "$FOO_BUILD < $SOURCES > $TARGET")
2778 env.Command('bar.out', 'bar.in',
2780 "$BAR_BUILD < $SOURCES > $TARGET"],
2781 ENV = {'PATH' : '/usr/local/bin/'})
2783 def rename(env, target, source):
2785 os.rename('.tmp', str(target[0]))
2787 env.Command('baz.out', 'baz.in',
2788 ["$BAZ_BUILD < $SOURCES > .tmp",
2792 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2794 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2796 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2797 Creates a Configure object for integrated
2798 functionality similar to GNU autoconf.
2799 See the section "Configure Contexts,"
2800 below, for a complete explanation of the arguments and behavior.
2802 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2804 .RI env.Copy([ key = val ", ...])"
2805 Return a separate copy of a construction environment.
2806 If there are any keyword arguments specified,
2807 they are added to the returned copy,
2808 overwriting any existing values
2813 env3 = env.Copy(CCFLAGS = '-g')
2816 Additionally, a list of tools and a toolpath may be specified, as in
2817 the Environment constructor:
2820 def MyTool(env): env['FOO'] = 'bar'
2821 env4 = env.Copy(tools = ['msvc', MyTool])
2824 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2826 .RI env.CVS( repository ", " module )
2827 A factory function that
2828 returns a Builder object
2829 to be used to fetch source files
2833 The returned Builder
2834 is intended to be passed to the
2838 The optional specified
2840 will be added to the beginning
2841 of all repository path names;
2842 this can be used, in essence,
2843 to strip initial directory names
2844 from the repository path names,
2845 so that you only have to
2846 replicate part of the repository
2847 directory hierarchy in your
2848 local build directory:
2851 # Will fetch foo/bar/src.c
2852 # from /usr/local/CVSROOT/foo/bar/src.c.
2853 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2855 # Will fetch bar/src.c
2856 # from /usr/local/CVSROOT/foo/bar/src.c.
2857 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2860 # from /usr/local/CVSROOT/foo/bar/src.c.
2861 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2864 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2866 .RI Default( targets )
2868 .RI env.Default( targets )
2869 This specifies a list of default targets,
2870 which will be built by
2872 if no explicit targets are given on the command line.
2876 and add to the list of default targets.
2878 Multiple targets should be specified as
2879 separate arguments to the
2881 method, or as a list.
2883 will also accept the Node returned by any
2884 of a construction environment's
2889 Default('foo', 'bar', 'baz')
2890 env.Default(['a', 'b', 'c'])
2891 hello = env.Program('hello', 'hello.c')
2899 will clear all default targets.
2902 will add to the (now empty) default-target list
2905 The current list of targets added using the
2907 function or method is available in the
2912 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2914 .RI DefaultEnvironment([ args ])
2915 Creates and returns a default construction environment object.
2916 This construction environment is used internally by SCons
2917 in order to execute many of the global functions in this list,
2918 and to fetch source files transparently
2919 from source code management systems.
2921 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2923 .RI Depends( target ", " dependency )
2925 .RI env.Depends( target ", " dependency )
2926 Specifies an explicit dependency;
2927 the target file(s) will be rebuilt
2928 whenever the dependency file(s) has changed.
2929 This should only be necessary
2930 for cases where the dependency
2931 is not caught by a Scanner
2935 env.Depends('foo', 'other-input-file-for-foo')
2938 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2940 .RI env.Dictionary([ vars ])
2941 Returns a dictionary object
2942 containing copies of all of the
2943 construction variables in the environment.
2944 If there are any variable names specified,
2945 only the specified construction
2946 variables are returned in the dictionary.
2949 dict = env.Dictionary()
2950 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2953 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2955 .RI Dir( name ", [" directory ])
2957 .RI env.Dir( name ", [" directory ])
2958 This returns a Directory Node,
2959 an object that represents the specified directory
2962 can be a relative or absolute path.
2964 is an optional directory that will be used as the parent directory.
2967 is specified, the current script's directory is used as the parent.
2969 Directory Nodes can be used anywhere you
2970 would supply a string as a directory name
2971 to a Builder method or function.
2972 Directory Nodes have attributes and methods
2973 that are useful in many situations;
2974 see "File and Directory Nodes," below.
2976 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2978 .RI env.Dump([ key ])
2979 Returns a pretty printable representation of the environment.
2983 should be a string containing the name of the variable of interest.
2988 print env.Dump('CCCOM')
2992 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3002 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3005 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3012 .RI EnsurePythonVersion( major ", " minor )
3014 .RI env.EnsurePythonVersion( major ", " minor )
3015 Ensure that the Python version is at least
3018 print out an error message and exit SCons with a non-zero exit code if the
3019 actual Python version is not late enough.
3022 EnsurePythonVersion(2,2)
3025 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3027 .RI EnsureSConsVersion( major ", " minor )
3029 .RI env.EnsureSConsVersion( major ", " minor )
3030 Ensure that the SCons version is at least
3033 print out an error message and exit SCons with a non-zero exit code if the
3034 actual SCons version is not late enough.
3037 EnsureSConsVersion(0,9)
3040 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3042 .RI Environment([ key = value ", ...])"
3044 .RI env.Environment([ key = value ", ...])"
3045 Return a new construction environment
3046 initialized with the specified
3050 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3052 .RI Execute( action ", [" strfunction ", " varlist ])
3054 .RI env.Execute( action ", [" strfunction ", " varlist ])
3055 Executes an Action object.
3058 may be an Action object
3059 (see the section "Action Objects,"
3060 below, for a complete explanation of the arguments and behavior),
3061 or it may be a command-line string,
3063 or executable Python function,
3064 each of which will be converted
3065 into an Action object
3067 The exit value of the command
3068 or return value of the Python function
3071 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3075 .RI env.Exit([ value ])
3081 A default exit value of
3084 is used if no value is specified.
3086 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3090 .RI env.Export( vars )
3093 to export a list of variables from the current
3094 SConscript file to all other SConscript files.
3095 The exported variables are kept in a global collection,
3096 so subsequent calls to
3098 will over-write previous exports that have the same name.
3099 Multiple variable names can be passed to
3101 as separate arguments or as a list. A dictionary can be used to map
3102 variables to a different name when exported. Both local variables and
3103 global variables can be exported.
3108 # Make env available for all SConscript files to Import().
3112 # Make env and package available for all SConscript files:.
3113 Export("env", "package")
3115 # Make env and package available for all SConscript files:
3116 Export(["env", "package"])
3118 # Make env available using the name debug:.
3119 Export({"debug":env})
3125 function supports an
3127 argument that makes it easier to to export a variable or
3128 set of variables to a single SConscript file.
3129 See the description of the
3133 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3135 .RI File( name ", [" directory ])
3137 .RI env.File( name ", [" directory ])
3140 an object that represents the specified file
3143 can be a relative or absolute path.
3145 is an optional directory that will be used as the parent directory.
3147 File Nodes can be used anywhere you
3148 would supply a string as a file name
3149 to a Builder method or function.
3150 File Nodes have attributes and methods
3151 that are useful in many situations;
3152 see "File and Directory Nodes," below.
3154 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3156 .RI FindFile( file ", " dirs )
3158 .RI env.FindFile( file ", " dirs )
3161 in the path specified by
3164 may be a list of file names or a single file name. In addition to searching
3165 for files that exist in the filesytem, this function also searches for
3166 derived files that have not yet been built.
3169 foo = env.FindFile('foo', ['dir1', 'dir2'])
3172 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3174 .RI Flatten( sequence )
3176 .RI env.Flatten( sequence )
3177 Takes a sequence (that is, a Python list or tuple)
3178 that may contain nested sequences
3179 and returns a flattened list containing
3180 all of the individual elements in any sequence.
3181 This can be helpful for collecting
3182 the lists returned by calls to Builders;
3183 other Builders will automatically
3184 flatten lists specified as input,
3185 but direct Python manipulation of
3186 these lists does not:
3189 foo = Object('foo.c')
3190 bar = Object('bar.c')
3192 # Because `foo' and `bar' are lists returned by the Object() Builder,
3193 # `objects' will be a list containing nested lists:
3194 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3196 # Passing such a list to another Builder is all right because
3197 # the Builder will flatten the list automatically:
3198 Program(source = objects)
3200 # If you need to manipulate the list directly using Python, you need to
3201 # call Flatten() yourself, or otherwise handle nested lists:
3202 for object in Flatten(objects):
3206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3208 .RI GetBuildPath( file ", [" ... ])
3210 .RI env.GetBuildPath( file ", [" ... ])
3213 path name (or names) for the specified
3221 Nodes or strings representing path names.
3223 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3227 .RI env.GetLaunchDir()
3228 Returns the absolute path name of the directory from which
3231 was initially invoked.
3232 This can be useful when using the
3237 options, which internally
3238 change to the directory in which the
3242 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3244 .RI GetOption( name )
3246 .RI env.GetOption( name )
3247 This function provides a way to query a select subset of the scons command line
3248 options from a SConscript file. See
3250 for a description of the options available.
3252 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3254 '\".RI GlobalBuilders( flag )
3258 '\"adds the names of the default builders
3259 '\"(Program, Library, etc.)
3260 '\"to the global name space
3261 '\"so they can be called without an explicit construction environment.
3262 '\"(This is the default.)
3266 '\"the names of the default builders are removed
3267 '\"from the global name space
3268 '\"so that an explicit construction environment is required
3269 '\"to call all builders.
3271 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3275 .RI env.Help( text )
3276 This specifies help text to be printed if the
3278 argument is given to
3282 is called multiple times, the text is appended together in the order
3287 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3289 .RI Ignore( target ", " dependency )
3291 .RI env.Ignore( target ", " dependency )
3292 The specified dependency file(s)
3293 will be ignored when deciding if
3294 the target file(s) need to be rebuilt.
3297 env.Ignore('foo', 'foo.c')
3298 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3301 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3305 .RI env.Import( vars )
3308 to import a list of variables into the current SConscript file. This
3309 will import variables that were exported with
3315 Variables exported by
3318 Multiple variable names can be passed to
3320 as separate arguments or as a list. The variable "*" can be used
3321 to import all variables.
3326 Import("env", "variable")
3327 Import(["env", "variable"])
3331 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3333 .RI Install( dir ", " source )
3335 .RI env.Install( dir ", " source )
3336 Installs one or more files in a destination directory.
3337 The file names remain the same.
3340 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3343 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3345 .RI InstallAs( target ", " source )
3347 .RI env.InstallAs( target ", " source )
3348 Installs one or more files as specific file names,
3349 allowing changing a file name as part of the
3351 It is an error if the target and source
3352 list different numbers of files.
3355 env.InstallAs(target = '/usr/local/bin/foo',
3356 source = 'foo_debug')
3357 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3358 source = ['libFOO.a', 'libBAR.a'])
3361 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3363 .RI Literal( string )
3365 .RI env.Literal( string )
3368 will be preserved as-is
3369 and not have construction variables expanded.
3371 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3373 .RI Local( targets )
3375 .RI env.Local( targets )
3378 will have copies made in the local tree,
3379 even if an already up-to-date copy
3380 exists in a repository.
3381 Returns a list of the target Node or Nodes.
3383 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3385 .RI env.ParseConfig( command ", [" function ", " unique ])
3388 to modify the environment as specified by the output of
3392 expects the output of a typical
3396 and adds the options
3397 to the appropriate construction variables.
3399 duplicate values are not
3400 added to any construction variables;
3423 construction variables,
3427 option gets added to both the
3434 option gets added to the
3437 Any other strings not associated with options
3438 are assumed to be the names of libraries
3441 construction variable.
3443 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3445 .RI ParseDepends( filename ", [" must_exist ])
3447 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3448 Parses the contents of the specified
3450 as a list of dependencies in the style of
3454 and explicitly establishes all of the listed dependencies.
3463 argument may be set to a non-zero
3466 throw an exception and
3467 generate an error if the file does not exist,
3468 or is otherwise inaccessible.
3472 argument may be set to a non-zero
3475 thrown an exception and
3477 if the file contains dependency
3478 information for more than one target.
3479 This can provide a small sanity check
3480 for files intended to be generated
3481 by, for example, the
3484 which should typically only
3485 write dependency information for
3486 one output file into a corresponding
3492 and all of the files listed therein
3493 will be interpreted relative to
3494 the directory of the
3496 file which calls the
3500 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3503 A factory function that
3504 returns a Builder object
3505 to be used to fetch source files
3506 from the Perforce source code management system.
3507 The returned Builder
3508 is intended to be passed to the
3513 env.SourceCode('.', env.Perforce())
3516 Perforce uses a number of external
3517 environment variables for its operation.
3518 Consequently, this function adds the
3519 following variables from the user's external environment
3520 to the construction environment's
3533 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3535 .RI Platform( string )
3536 Returns a callable object
3537 that can be used to initialize
3538 a construction environment using the
3539 platform keyword of the Environment() method:
3542 env = Environment(platform = Platform('win32'))
3545 .RI env.Platform( string )
3546 Applies the callable object for the specified platform
3548 to the environment through which the method was called.
3551 env.Platform('posix')
3558 variable from the user's external environment
3559 to the construction environment's
3562 This is so that any executed commands
3563 that use sockets to connect with other systems
3564 (such as fetching source files from
3565 external CVS repository specifications like
3566 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3567 will work on Win32 systems.
3569 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3571 .RI Precious( target ", ...)"
3573 .RI env.Precious( target ", ...)"
3576 as precious so it is not deleted before it is rebuilt. Normally
3578 deletes a target before building it.
3579 Multiple targets can be passed in to a single call to
3582 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3584 .RI env.Prepend( key = val ", [...])"
3585 Appends the specified keyword arguments
3586 to the beginning of construction variables in the environment.
3587 If the Environment does not have
3588 the specified construction variable,
3589 it is simply added to the environment.
3590 If the values of the construction variable
3591 and the keyword argument are the same type,
3592 then the two values will be simply added together.
3593 Otherwise, the construction variable
3594 and the value of the keyword argument
3595 are both coerced to lists,
3596 and the lists are added together.
3597 (See also the Append method, above.)
3600 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3603 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3605 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3606 This appends new path elements to the given path in the
3607 specified external environment
3611 any particular path once (leaving the first one it encounters and
3612 ignoring the rest, to preserve path order),
3613 and to help assure this,
3614 will normalize all paths (using
3617 .BR os.path.normcase ).
3618 This can also handle the
3619 case where the given old path variable is a list instead of a
3620 string, in which case a list will be returned instead of a string.
3624 print 'before:',env['ENV']['INCLUDE']
3625 include_path = '/foo/bar:/foo'
3626 env.PrependENVPath('INCLUDE', include_path)
3627 print 'after:',env['ENV']['INCLUDE']
3631 after: /foo/bar:/foo:/biz
3634 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3636 .RI env.AppendUnique( key = val ", [...])"
3637 Appends the specified keyword arguments
3638 to the beginning of construction variables in the environment.
3639 If the Environment does not have
3640 the specified construction variable,
3641 it is simply added to the environment.
3642 If the construction variable being appended to is a list,
3643 then any value(s) that already exist in the
3644 construction variable will
3646 be added again to the list.
3649 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3652 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3655 A factory function that
3656 returns a Builder object
3657 to be used to fetch source files
3659 The returned Builder
3660 is intended to be passed to the
3665 env.SourceCode('.', env.RCS())
3670 will fetch source files
3671 from RCS subdirectories automatically,
3673 as demonstrated in the above example
3674 should only be necessary if
3675 you are fetching from
3678 directory as the source files,
3679 or if you need to explicitly specify RCS
3680 for a specific subdirectory.
3682 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3684 .RI env.Replace( key = val ", [...])"
3685 Replaces construction variables in the Environment
3686 with the specified keyword arguments.
3689 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3692 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3694 .RI Repository( directory )
3696 .RI env.Repository( directory )
3699 is a repository to be searched for files.
3703 and each one adds to the list of
3704 repositories that will be searched.
3708 a repository is a copy of the source tree,
3709 from the top-level directory on down,
3711 both source files and derived files
3712 that can be used to build targets in
3713 the local source tree.
3714 The canonical example would be an
3715 official source tree maintained by an integrator.
3716 If the repository contains derived files,
3717 then the derived files should have been built using
3719 so that the repository contains the necessary
3720 signature information to allow
3722 to figure out when it is appropriate to
3723 use the repository copy of a derived file,
3724 instead of building one locally.
3726 Note that if an up-to-date derived file
3727 already exists in a repository,
3731 make a copy in the local directory tree.
3732 In order to guarantee that a local copy
3738 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3743 what variable(s) to use as the return value(s) of the current SConscript
3744 file. These variables will be returned to the "calling" SConscript file
3745 as the return value(s) of
3747 Multiple variable names should be passed to
3753 Return(["foo", "bar"])
3756 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3758 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3760 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3761 Creates a Scanner object for
3764 See the section "Scanner Objects,"
3765 below, for a complete explanation of the arguments and behavior.
3767 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3770 A factory function that
3771 returns a Builder object
3772 to be used to fetch source files
3774 The returned Builder
3775 is intended to be passed to the
3780 env.SourceCode('.', env.SCCS())
3785 will fetch source files
3786 from SCCS subdirectories automatically,
3788 as demonstrated in the above example
3789 should only be necessary if
3790 you are fetching from
3793 directory as the source files,
3794 or if you need to explicitly specify SCCS
3795 for a specific subdirectory.
3797 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3799 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3801 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3803 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3805 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3809 one or more subsidiary SConscript (configuration) files.
3810 There are two ways to call the
3814 The first way you can call
3816 is to explicitly specify one or more
3818 as the first argument.
3819 A single script may be specified as a string;
3820 multiple scripts must be specified as a list
3821 (either explicitly or as created by
3825 The second way you can call
3827 is to specify a list of (sub)directory names
3834 execute a subsidiary configuration file named
3836 in each of the specified directories.
3837 You may specify a name other than
3839 by supplying an optional
3845 argument provides a list of variable names or a dictionary of
3846 named values to export to the
3848 These variables are locally exported only to the specified
3850 and do not affect the
3851 global pool of variables used by
3855 '\"If multiple dirs are provided,
3856 '\"each script gets a fresh export.
3861 function to import the variables.
3865 argument specifies that all of the target files
3866 (for example, object files and executables)
3867 that would normally be built in the subdirectory in which
3869 resides should actually
3873 is interpreted relative to the directory
3874 of the calling SConscript file.
3878 argument specifies that the
3879 source files from which
3880 the target files should be built
3884 is interpreted relative to the directory
3885 of the calling SConscript file.
3889 will link or copy (depending on the platform)
3890 all the source files into the build directory.
3891 This behavior may be disabled by
3892 setting the optional
3895 (it is set to 1 by default),
3898 will refer directly to
3899 the source files in their source directory
3900 when building target files.
3903 is usually safe, and always more efficient
3906 but it may cause build problems in certain end-cases,
3907 such as compiling from source files that
3908 are generated by the build.)
3910 Any variables returned by
3914 will be returned by the call to
3920 SConscript('subdir/SConscript')
3921 foo = SConscript('sub/SConscript', exports='env')
3922 SConscript('dir/SConscript', exports=['env', 'variable'])
3923 SConscript('src/SConscript', build_dir='build', duplicate=0)
3924 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3925 SConscript(dirs=['sub1', 'sub2'])
3926 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3929 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3931 .RI SConscriptChdir( value )
3933 .RI env.SConscriptChdir( value )
3936 changes its working directory
3937 to the directory in which each
3938 subsidiary SConscript file lives.
3939 This behavior may be disabled
3940 by specifying either:
3944 env.SConscriptChdir(0)
3949 will stay in the top-level directory
3950 while reading all SConscript files.
3951 (This may be necessary when building from repositories,
3952 when all the directories in which SConscript files may be found
3953 don't necessarily exist locally.)
3955 You may enable and disable
3956 this ability by calling
3963 SConscript('foo/SConscript') # will not chdir to foo
3964 env.SConscriptChdir(1)
3965 SConscript('bar/SConscript') # will chdir to bar
3968 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3970 .RI SConsignFile([ file , dbm_module ])
3972 .RI env.SConsignFile([ file , dbm_module ])
3975 to store all file signatures
3985 is not an absolute path name,
3986 the file is placed in the same directory as the top-level
3992 argument can be used to specify
3993 which Python database module
3994 The default is to use a custom
3996 module that uses pickled
3997 Python data structures,
3998 and which works on all Python versions from 1.5.2 on.
4003 # Stores signatures in ".sconsign.dbm"
4004 # in the top-level SConstruct directory.
4007 # Stores signatures in the file "etc/scons-signatures"
4008 # relative to the top-level SConstruct directory.
4009 SConsignFile("etc/scons-signatures")
4011 # Stores signatures in the specified absolute file name.
4012 SConsignFile("/home/me/SCons/signatures")
4015 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4017 .RI env.SetDefault(key = val ", [...])"
4018 Sets construction variables to default values specified with the keyword
4019 arguments if (and only if) the variables are not already set.
4020 The following statements are equivalent:
4023 env.SetDefault(FOO = 'foo')
4025 if not env.has_key('FOO'): env['FOO'] = 'foo'
4028 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4030 .RI SetOption( name ", " value )
4032 .RI env.SetOption( name ", " value )
4033 This function provides a way to set a select subset of the scons command
4034 line options from a SConscript file. The options supported are:
4036 which corresponds to -c, --clean, and --remove;
4039 corresponds to --duplicate;
4041 which corresponds to --implicit-cache;
4043 which corresponds to --max-drift;
4045 which corresponds to -j and --jobs.
4046 See the documentation for the
4047 corresponding command line object for information about each specific
4051 SetOption('max_drift', 1)
4054 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4056 .RI SideEffect( side_effect ", " target )
4058 .RI env.SideEffect( side_effect ", " target )
4061 as a side effect of building
4067 can be a list, a file name, or a node.
4068 A side effect is a target that is created
4069 as a side effect of building other targets.
4070 For example, a Windows PDB
4071 file is created as a side effect of building the .obj
4072 files for a static library.
4073 If a target is a side effect of multiple build commands,
4075 will ensure that only one set of commands
4076 is executed at a time.
4077 Consequently, you only need to use this method
4078 for side-effect targets that are built as a result of
4079 multiple build commands.
4081 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4083 .RI SourceCode( entries ", " builder )
4085 .RI env.SourceCode( entries ", " builder )
4086 Arrange for non-existent source files to
4087 be fetched from a source code management system
4092 may be a Node, string or list of both,
4093 and may represent either individual
4094 source files or directories in which
4095 source files can be found.
4097 For any non-existent source files,
4099 will search up the directory tree
4109 will not use a builder to fetch
4110 source files for the specified
4114 builder has been specified
4115 for a directory higher up the tree.
4119 fetch files from SCCS or RCS subdirectories
4120 without explicit configuration.
4121 This takes some extra processing time
4122 to search for the necessary
4123 source code management files on disk.
4124 You can avoid these extra searches
4125 and speed up your build a little
4126 by disabling these searches as follows:
4129 env.SourceCode('.', None)
4133 Note that if the specified
4135 is one you create by hand,
4136 it must have an associated
4137 construction environment to use
4138 when fetching a source file.
4141 provides a set of canned factory
4142 functions that return appropriate
4143 Builders for various popular
4144 source code management systems.
4145 Canonical examples of invocation include:
4148 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4149 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4150 env.SourceCode('/', env.RCS())
4151 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4152 env.SourceCode('no_source.c', None)
4154 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4156 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4158 '\".RI Subversion( repository ", " module )
4159 '\"A factory function that
4160 '\"returns a Builder object
4161 '\"to be used to fetch source files
4162 '\"from the specified Subversion
4164 '\"The returned Builder
4165 '\"is intended to be passed to the
4169 '\"The optional specified
4171 '\"will be added to the beginning
4172 '\"of all repository path names;
4173 '\"this can be used, in essence,
4174 '\"to strip initial directory names
4175 '\"from the repository path names,
4176 '\"so that you only have to
4177 '\"replicate part of the repository
4178 '\"directory hierarchy in your
4179 '\"local build directory:
4182 '\"# Will fetch foo/bar/src.c
4183 '\"# from /usr/local/Subversion/foo/bar/src.c.
4184 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4186 '\"# Will fetch bar/src.c
4187 '\"# from /usr/local/Subversion/foo/bar/src.c.
4188 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4190 '\"# Will fetch src.c
4191 '\"# from /usr/local/Subversion/foo/bar/src.c.
4192 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4195 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4197 .RI SourceSignatures( type )
4199 .RI env.SourceSignatures( type )
4200 This function tells SCons what type of signature to use for source files:
4204 If the environment method is used,
4205 the specified type of source signature
4206 is only used when deciding whether targets
4207 built with that environment are up-to-date or must be rebuilt.
4208 If the global function is used,
4209 the specified type of source signature becomes the default
4210 used for all decisions
4211 about whether targets are up-to-date.
4213 "MD5" means the signature of a source file
4214 is the MD5 checksum of its contents.
4215 "timestamp" means the signature of a source file
4216 is its timestamp (modification time).
4217 There is no different between the two behaviors
4221 "MD5" signatures take longer to compute,
4222 but are more accurate than "timestamp" signatures.
4223 The default is "MD5".
4225 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4229 .RI env.Split( arg )
4230 Returns a list of file names or other objects.
4232 it will be split on strings of white-space characters
4234 making it easier to write long lists of file names.
4235 If arg is already a list,
4236 the list will be returned untouched.
4237 If arg is any other type of object,
4238 it will be returned as a list
4239 containing just the object.
4242 files = Split("f1.c f2.c f3.c")
4243 files = env.Split("f4.c f5.c f6.c")
4251 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4253 .RI TargetSignatures( type )
4255 .RI env.TargetSignatures( type )
4256 This function tells SCons what type of signatures to use
4261 If the environment method is used,
4262 the specified type of signature is only used
4263 for targets built with that environment.
4264 If the global function is used,
4265 the specified type of signature becomes the default
4266 used for all target files that
4267 don't have an explicit target signature type
4268 specified for their environments.
4270 "build" means the signature of a target file
4271 is made by concatenating all of the
4272 signatures of all its source files.
4273 "content" means the signature of a target
4274 file is an MD5 checksum of its contents.
4275 "build" signatures are usually faster to compute,
4276 but "content" signatures can prevent unnecessary rebuilds
4277 when a target file is rebuilt to the exact same contents
4278 as the previous build.
4279 The default is "build".
4281 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4283 .RI Tool( string [, toolpath ", " **kw ])
4284 Returns a callable object
4285 that can be used to initialize
4286 a construction environment using the
4287 tools keyword of the Environment() method.
4288 The object may be called with a construction
4289 environment as an argument,
4290 in which case the object will
4291 add the necessary variables
4292 to the construction environment
4293 and the name of the tool will be added to the
4295 construction variable.
4297 Additional keyword arguments are passed to the tool's
4302 env = Environment(tools = [ Tool('msvc') ])
4306 t(env) # adds 'msvc' to the TOOLS variable
4307 u = Tool('opengl', toolpath = ['tools'])
4308 u(env) # adds 'opengl' to the TOOLS variable
4311 .RI env.Tool( string [, toolpath ", " **kw ])
4312 Applies the callable object for the specified tool
4314 to the environment through which the method was called.
4316 Additional keyword arguments are passed to the tool's
4322 env.Tool('opengl', toolpath = ['build/tools'])
4325 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4329 .RI env.Value( value )
4330 Returns a Node object representing the specified Python value. Value
4331 nodes can be used as dependencies of targets. If the result of
4334 changes between SCons runs, any targets depending on
4336 will be rebuilt. When using timestamp source signatures, Value nodes'
4337 timestamps are equal to the system time when the node is created.
4340 def create(target, source, env):
4341 f = open(str(target[0]), 'wb')
4342 f.write('prefix=' + source[0].get_contents())
4344 prefix = ARGUMENTS.get('prefix', '/usr/local')
4346 env['BUILDERS']['Config'] = Builder(action = create)
4347 env.Config(target = 'package-config', source = Value(prefix))
4350 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4352 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4354 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4356 Searches for the specified executable
4358 returning the full path name to the program
4360 and returning None if not.
4361 Searches the specified
4363 the value of the calling environment's PATH
4364 (env['ENV']['PATH']),
4365 or the user's current external PATH
4366 (os.environ['PATH'])
4368 On Win32 systems, searches for executable
4369 programs with any of the file extensions
4370 listed in the specified
4372 the calling environment's PATHEXT
4373 (env['ENV']['PATHEXT'])
4374 or the user's current PATHEXT
4375 (os.environ['PATHEXT'])
4383 .SS SConscript Variables
4384 In addition to the global functions and methods,
4386 supports a number of Python variables
4387 that can be used in SConscript files
4388 to affect how you want the build to be performed.
4389 These variables may be accessed from custom Python modules that you
4390 import into an SConscript file by adding the following
4391 to the Python module:
4394 from SCons.Script import *
4397 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4402 arguments specified on the command line.
4403 Each element in the list is a tuple
4405 .RI ( keyword , value )
4411 elements of the tuple
4413 subscripting for element
4417 of the tuple, respectively.
4420 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4421 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4422 third_tuple = ARGLIST[2]
4423 print "third keyword, value =", third_tuple[0], third_tuple[1]
4424 for key, value in ARGLIST:
4425 # process key and value
4428 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4431 A dictionary of all the
4433 arguments specified on the command line.
4434 The dictionary is not in order,
4435 and if a given keyword has
4436 more than one value assigned to it
4437 on the command line,
4438 the last (right-most) value is
4444 if ARGUMENTS.get('debug', 0):
4445 env = Environment(CCFLAGS = '-g')
4450 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4453 A list of the targets which
4455 will actually try to build,
4456 regardless of whether they were specified on
4457 the command line or via the
4460 The elements of this list may be strings
4462 nodes, so you should run the list through the Python
4464 function to make sure any Node path names
4465 are converted to strings.
4467 Because this list may be taken from the
4468 list of targets specified using the
4471 the contents of the list may change
4472 on each successive call to
4477 for additional information.
4480 if 'foo' in BUILD_TARGETS:
4481 print "Don't forget to test the `foo' program!"
4482 if 'special/program' in BUILD_TARGETS:
4483 SConscript('special')
4488 list only contains targets expected listed
4489 on the command line or via calls to the
4494 contain all dependent targets that will be built as
4495 a result of making the sure the explicitly-specified
4496 targets are up to date.
4498 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4500 COMMAND_LINE_TARGETS
4501 A list of the targets explicitly specified on
4503 If there are no targets specified on the command line,
4505 This can be used, for example,
4506 to take specific actions only
4507 when a certain target or targets
4508 is explicitly being built:
4511 if 'foo' in COMMAND_LINE_TARGETS:
4512 print "Don't forget to test the `foo' program!"
4513 if 'special/program' in COMMAND_LINE_TARGETS:
4514 SConscript('special')
4517 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4520 A list of the target
4522 that have been specified using the
4525 The elements of the list are nodes,
4526 so you need to run them through the Python
4528 function to get at the path name for each Node.
4531 print str(DEFAULT_TARGETS[0])
4532 if 'foo' in map(str, DEFAULT_TARGETS):
4533 print "Don't forget to test the `foo' program!"
4538 list change on on each successive call to the
4543 print map(str, DEFAULT_TARGETS) # originally []
4545 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4547 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4549 print map(str, DEFAULT_TARGETS) # back to []
4552 Consequently, be sure to use
4554 only after you've made all of your
4557 or else simply be careful of the order
4558 of these statements in your SConscript files
4559 so that you don't look for a specific
4560 default target before it's actually been added to the list.
4562 .SS Construction Variables
4563 .\" XXX From Gary Ruben, 23 April 2002:
4564 .\" I think it would be good to have an example with each construction
4565 .\" variable description in the documentation.
4567 .\" CC The C compiler
4568 .\" Example: env["CC"] = "c68x"
4569 .\" Default: env["CC"] = "cc"
4571 .\" CCCOM The command line ...
4573 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4574 .\" env["CC"] = "c68x"
4575 .\" env["CFLAGS"] = "-ps -qq -mr"
4576 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4578 .\" (I dunno what this is ;-)
4579 A construction environment has an associated dictionary of
4580 .I construction variables
4581 that are used by built-in or user-supplied build rules.
4582 Construction variables must follow the same rules for
4584 the initial character must be an underscore or letter,
4585 followed by any number of underscores, letters, or digits.
4587 A number of useful construction variables are automatically defined by
4588 scons for each supported platform, and additional construction variables
4589 can be defined by the user. The following is a list of the automatically
4590 defined construction variables:
4593 The static library archiver.
4596 The command line used to generate a static library from object files.
4599 The string displayed when an object file
4600 is generated from an assembly-language source file.
4601 If this is not set, then $ARCOM (the command line) is displayed.
4604 env = Environment(ARCOMSTR = "Archiving $TARGET")
4608 General options passed to the static library archiver.
4614 The command line used to generate an object file
4615 from an assembly-language source file.
4618 The string displayed when an object file
4619 is generated from an assembly-language source file.
4620 If this is not set, then $ASCOM (the command line) is displayed.
4623 env = Environment(ASCOMSTR = "Assembling $TARGET")
4627 General options passed to the assembler.
4630 The command line used to assemble an assembly-language
4631 source file into an object file
4632 after first running the file through the C preprocessor.
4633 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4634 are included on this command line.
4637 The string displayed when an object file
4638 is generated from an assembly-language source file
4639 after first running the file through the C preprocessor.
4640 If this is not set, then $ASPPCOM (the command line) is displayed.
4643 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4647 General options when an assembling an assembly-language
4648 source file into an object file
4649 after first running the file through the C preprocessor.
4650 The default is to use the value of $ASFLAGS.
4653 The bibliography generator for the TeX formatter and typesetter and the
4654 LaTeX structured formatter and typesetter.
4657 The command line used to call the bibliography generator for the
4658 TeX formatter and typesetter and the LaTeX structured formatter and
4662 The string displayed when generating a bibliography
4664 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4667 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4672 General options passed to the bibliography generator for the TeX formatter
4673 and typesetter and the LaTeX structured formatter and typesetter.
4676 The BitKeeper executable.
4679 The command line for
4680 fetching source files using BitKeeper.
4683 The string displayed when fetching
4684 a source file using BitKeeper.
4685 If this is not set, then $BITKEEPERCOM
4686 (the command line) is displayed.
4689 The command ($BITKEEPER) and subcommand
4690 for fetching source files using BitKeeper.
4692 .IP BITKEEPERGETFLAGS
4693 Options that are passed to the BitKeeper
4698 A dictionary mapping the names of the builders
4699 available through this environment
4700 to underlying Builder objects.
4702 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4703 are available by default.
4704 If you initialize this variable when an
4705 Environment is created:
4708 env = Environment(BUILDERS = {'NewBuilder' : foo})
4711 the default Builders will no longer be available.
4712 To use a new Builder object in addition to the default Builders,
4713 add your new Builder object like this:
4717 env.Append(BUILDERS = {'NewBuilder' : foo})
4724 env['BUILDERS]['NewBuilder'] = foo
4731 The command line used to compile a C source file to a (static) object file.
4732 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4733 are included on this command line.
4736 The string displayed when a C source file
4737 is compiled to a (static) object file.
4738 If this is not set, then $CCCOM (the command line) is displayed.
4741 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4745 General options that are passed to the C compiler.
4748 The suffix for C source files.
4749 This is used by the internal CFile builder
4750 when generating C files from Lex (.l) or YACC (.y) input files.
4751 The default suffix, of course, is
4754 On case-insensitive systems (like Win32),
4761 The version number of the C compiler.
4762 This may or may not be set,
4763 depending on the specific C compiler being used.
4766 A function used to produce variables like $_CPPINCFLAGS. It takes
4768 arguments: a prefix to concatenate onto each element, a list of
4769 elements, a suffix to concatenate onto each element, an environment
4770 for variable interpolation, and an optional function that will be
4771 called to transform the list before concatenation.
4774 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4778 A platform independent specification of C preprocessor definitions.
4779 The definitions will be added to command lines
4780 through the automatically-generated
4781 $_CPPDEFFLAGS construction variable (see below),
4782 which is constructed according to
4783 the type of value of $CPPDEFINES:
4786 If $CPPDEFINES is a string,
4788 $CPPDEFPREFIX and $CPPDEFSUFFIX
4789 construction variables
4790 will be added to the beginning and end.
4793 # Will add -Dxyz to POSIX compiler command lines,
4794 # and /Dxyz to Microsoft Visual C++ command lines.
4795 env = Environment(CPPDEFINES='xyz')
4799 If $CPPDEFINES is a list,
4801 $CPPDEFPREFIX and $CPPDEFSUFFIX
4802 construction variables
4803 will be appended to the beginning and end
4804 of each element in the list.
4805 If any element is a list or tuple,
4806 then the first item is the name being
4807 defined and the second item is its value:
4810 # Will add -DB=2 -DA to POSIX compiler command lines,
4811 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4812 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4816 If $CPPDEFINES is a dictionary,
4818 $CPPDEFPREFIX and $CPPDEFSUFFIX
4819 construction variables
4820 will be appended to the beginning and end
4821 of each item from the dictionary.
4822 The key of each dictionary item
4823 is a name being defined
4824 to the dictionary item's corresponding value;
4827 then the name is defined without an explicit value.
4828 Note that the resulting flags are sorted by keyword
4829 to ensure that the order of the options on the
4830 command line is consistent each time
4835 # Will add -DA -DB=2 to POSIX compiler command lines,
4836 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4837 env = Environment(CPPDEFINES={'B':2, 'A':None})
4841 An automatically-generated construction variable
4842 containing the C preprocessor command-line options
4844 The value of $_CPPDEFFLAGS is created
4845 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4846 to the beginning and end
4847 of each directory in $CPPDEFINES.
4850 The prefix used to specify preprocessor definitions
4851 on the C compiler command line.
4852 This will be appended to the beginning of each definition
4853 in the $CPPDEFINES construction variable
4854 when the $_CPPDEFFLAGS variable is automatically generated.
4857 The suffix used to specify preprocessor definitions
4858 on the C compiler command line.
4859 This will be appended to the end of each definition
4860 in the $CPPDEFINES construction variable
4861 when the $_CPPDEFFLAGS variable is automatically generated.
4864 User-specified C preprocessor options.
4865 These will be included in any command that uses the C preprocessor,
4866 including not just compilation of C and C++ source files
4867 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4868 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4869 $F77PPCOM and $SHF77PPCOM command lines
4870 used to compile a Fortran source file,
4871 and the $ASPPCOM command line
4872 used to assemble an assembly language source file,
4873 after first running each file through the C preprocessor.
4874 Note that this variable does
4878 (or similar) include search path options
4879 that scons generates automatically from $CPPPATH.
4883 for the variable that expands to those options.
4886 An automatically-generated construction variable
4887 containing the C preprocessor command-line options
4888 for specifying directories to be searched for include files.
4889 The value of $_CPPINCFLAGS is created
4890 by appending $INCPREFIX and $INCSUFFIX
4891 to the beginning and end
4892 of each directory in $CPPPATH.
4895 The list of directories that the C preprocessor will search for include
4896 directories. The C/C++ implicit dependency scanner will search these
4897 directories for include files. Don't explicitly put include directory
4898 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4899 and the directories will not be searched by the dependency scanner. Note:
4900 directory names in CPPPATH will be looked-up relative to the SConscript
4901 directory when they are used in a command. To force
4903 to look-up a directory relative to the root of the source tree use #:
4906 env = Environment(CPPPATH='#/include')
4910 The directory look-up can also be forced using the
4915 include = Dir('include')
4916 env = Environment(CPPPATH=include)
4920 The directory list will be added to command lines
4921 through the automatically-generated
4923 construction variable,
4924 which is constructed by
4925 appending the values of the
4926 $INCPREFIX and $INCSUFFIX
4927 construction variables
4928 to the beginning and end
4929 of each directory in $CPPPATH.
4930 Any command lines you define that need
4931 the CPPPATH directory list should
4932 include $_CPPINCFLAGS:
4935 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4939 The list of suffixes of files that will be scanned
4940 for C preprocessor implicit dependencies
4942 The default list is:
4945 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4946 ".h", ".H", ".hxx", ".hpp", ".hh",
4947 ".F", ".fpp", ".FPP",
4949 ".S", ".spp", ".SPP"]
4956 Options that are passed to the CVS checkout subcommand.
4959 The command line used to
4960 fetch source files from a CVS repository.
4963 The string displayed when fetching
4964 a source file from a CVS repository.
4965 If this is not set, then $CVSCOM
4966 (the command line) is displayed.
4969 General options that are passed to CVS.
4970 By default, this is set to
4972 to specify from where the files must be fetched.
4975 The path to the CVS repository.
4976 This is referenced in the default
4983 The suffix for C++ source files.
4984 This is used by the internal CXXFile builder
4985 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4986 The default suffix is
4988 SCons also treats files with the suffixes
4997 suffixes as Objective C++ files.
4998 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5005 The command line used to compile a C++ source file to an object file.
5006 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
5007 are included on this command line.
5010 The string displayed when a C++ source file
5011 is compiled to a (static) object file.
5012 If this is not set, then $CXXCOM (the command line) is displayed.
5015 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5019 General options that are passed to the C++ compiler.
5020 By default, this includes the value of $CCFLAGS,
5021 so that setting $CCFLAGS affects both C and C++ compilation.
5022 If you want to add C++-specific flags,
5023 you must set or override the value of $CXXFLAGS.
5026 The version number of the C++ compiler.
5027 This may or may not be set,
5028 depending on the specific C++ compiler being used.
5031 A function that converts a file name into a Dir instance relative to the
5035 The list of suffixes of files that will be scanned
5036 for imported D package files.
5037 The default list is:
5044 The TeX DVI file to PDF file converter.
5047 General options passed to the TeX DVI file to PDF file converter.
5050 The command line used to convert TeX DVI files into a PDF file.
5053 The string displayed when a TeX DVI file
5054 is converted into a PDF file.
5055 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5058 The TeX DVI file to PostScript converter.
5061 General options passed to the TeX DVI file to PostScript converter.
5064 A dictionary of environment variables
5065 to use when invoking commands. When ENV is used in a command all list
5066 values will be joined using the path separator and any other non-string
5067 values will simply be coerced to a string.
5068 Note that, by default,
5072 propagate the environment in force when you
5075 to the commands used to build target files.
5076 This is so that builds will be guaranteed
5077 repeatable regardless of the environment
5078 variables set at the time
5082 If you want to propagate your
5083 environment variables
5084 to the commands executed
5085 to build target files,
5086 you must do so explicitly:
5090 env = Environment(ENV = os.environ)
5094 Note that you can choose only to propagate
5095 certain environment variables.
5099 environment variable,
5102 uses the same utilities
5103 as the invoking shell (or other process):
5108 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5112 A function that will be called to escape shell special characters in
5113 command lines. The function should take one argument: the command line
5114 string to escape; and should return the escaped command line.
5117 The Fortran 77 compiler.
5118 You should normally set the $FORTRAN variable,
5119 which specifies the default Fortran compiler
5120 for all Fortran versions.
5121 You only need to set $F77 if you need to use a specific compiler
5122 or compiler version for Fortran 77 files.
5125 The command line used to compile a Fortran 77 source file to an object file.
5126 You only need to set $F77COM if you need to use a specific
5127 command line for Fortran 77 files.
5128 You should normally set the $FORTRANCOM variable,
5129 which specifies the default command line
5130 for all Fortran versions.
5133 The string displayed when a Fortran 77 source file
5134 is compiled to an object file.
5135 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5138 General user-specified options that are passed to the Fortran 77 compiler.
5139 Note that this variable does
5143 (or similar) include search path options
5144 that scons generates automatically from $F77PATH.
5148 for the variable that expands to those options.
5149 You only need to set $F77FLAGS if you need to define specific
5150 user options for Fortran 77 files.
5151 You should normally set the $FORTRANFLAGS variable,
5152 which specifies the user-specified options
5153 passed to the default Fortran compiler
5154 for all Fortran versions.
5157 An automatically-generated construction variable
5158 containing the Fortran 77 compiler command-line options
5159 for specifying directories to be searched for include files.
5160 The value of $_F77INCFLAGS is created
5161 by appending $INCPREFIX and $INCSUFFIX
5162 to the beginning and end
5163 of each directory in $F77PATH.
5166 The list of directories that the Fortran 77 compiler will search for include
5167 directories. The implicit dependency scanner will search these
5168 directories for include files. Don't explicitly put include directory
5169 arguments in $F77FLAGS because the result will be non-portable
5170 and the directories will not be searched by the dependency scanner. Note:
5171 directory names in $F77PATH will be looked-up relative to the SConscript
5172 directory when they are used in a command. To force
5174 to look-up a directory relative to the root of the source tree use #:
5175 You only need to set $F77PATH if you need to define a specific
5176 include path for Fortran 77 files.
5177 You should normally set the $FORTRANPATH variable,
5178 which specifies the include path
5179 for the default Fortran compiler
5180 for all Fortran versions.
5183 env = Environment(F77PATH='#/include')
5187 The directory look-up can also be forced using the
5192 include = Dir('include')
5193 env = Environment(F77PATH=include)
5197 The directory list will be added to command lines
5198 through the automatically-generated
5200 construction variable,
5201 which is constructed by
5202 appending the values of the
5203 $INCPREFIX and $INCSUFFIX
5204 construction variables
5205 to the beginning and end
5206 of each directory in $F77PATH.
5207 Any command lines you define that need
5208 the F77PATH directory list should
5209 include $_F77INCFLAGS:
5212 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5216 The command line used to compile a Fortran 77 source file to an object file
5217 after first running the file through the C preprocessor.
5218 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5219 are included on this command line.
5220 You only need to set $F77PPCOM if you need to use a specific
5221 C-preprocessor command line for Fortran 77 files.
5222 You should normally set the $FORTRANPPCOM variable,
5223 which specifies the default C-preprocessor command line
5224 for all Fortran versions.
5227 The Fortran 90 compiler.
5228 You should normally set the $FORTRAN variable,
5229 which specifies the default Fortran compiler
5230 for all Fortran versions.
5231 You only need to set $F90 if you need to use a specific compiler
5232 or compiler version for Fortran 90 files.
5235 The command line used to compile a Fortran 90 source file to an object file.
5236 You only need to set $F90COM if you need to use a specific
5237 command line for Fortran 90 files.
5238 You should normally set the $FORTRANCOM variable,
5239 which specifies the default command line
5240 for all Fortran versions.
5243 The string displayed when a Fortran 90 source file
5244 is compiled to an object file.
5245 If this is not set, then $F90COM or $FORTRANCOM
5246 (the command line) is displayed.
5249 General user-specified options that are passed to the Fortran 90 compiler.
5250 Note that this variable does
5254 (or similar) include search path options
5255 that scons generates automatically from $F90PATH.
5259 for the variable that expands to those options.
5260 You only need to set $F90FLAGS if you need to define specific
5261 user options for Fortran 90 files.
5262 You should normally set the $FORTRANFLAGS variable,
5263 which specifies the user-specified options
5264 passed to the default Fortran compiler
5265 for all Fortran versions.
5268 An automatically-generated construction variable
5269 containing the Fortran 90 compiler command-line options
5270 for specifying directories to be searched for include files.
5271 The value of $_F90INCFLAGS is created
5272 by appending $INCPREFIX and $INCSUFFIX
5273 to the beginning and end
5274 of each directory in $F90PATH.
5277 The list of directories that the Fortran 90 compiler will search for include
5278 directories. The implicit dependency scanner will search these
5279 directories for include files. Don't explicitly put include directory
5280 arguments in $F90FLAGS because the result will be non-portable
5281 and the directories will not be searched by the dependency scanner. Note:
5282 directory names in $F90PATH will be looked-up relative to the SConscript
5283 directory when they are used in a command. To force
5285 to look-up a directory relative to the root of the source tree use #:
5286 You only need to set $F90PATH if you need to define a specific
5287 include path for Fortran 90 files.
5288 You should normally set the $FORTRANPATH variable,
5289 which specifies the include path
5290 for the default Fortran compiler
5291 for all Fortran versions.
5294 env = Environment(F90PATH='#/include')
5298 The directory look-up can also be forced using the
5303 include = Dir('include')
5304 env = Environment(F90PATH=include)
5308 The directory list will be added to command lines
5309 through the automatically-generated
5311 construction variable,
5312 which is constructed by
5313 appending the values of the
5314 $INCPREFIX and $INCSUFFIX
5315 construction variables
5316 to the beginning and end
5317 of each directory in $F90PATH.
5318 Any command lines you define that need
5319 the F90PATH directory list should
5320 include $_F90INCFLAGS:
5323 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5327 The command line used to compile a Fortran 90 source file to an object file
5328 after first running the file through the C preprocessor.
5329 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5330 are included on this command line.
5331 You only need to set $F90PPCOM if you need to use a specific
5332 C-preprocessor command line for Fortran 90 files.
5333 You should normally set the $FORTRANPPCOM variable,
5334 which specifies the default C-preprocessor command line
5335 for all Fortran versions.
5338 The Fortran 95 compiler.
5339 You should normally set the $FORTRAN variable,
5340 which specifies the default Fortran compiler
5341 for all Fortran versions.
5342 You only need to set $F95 if you need to use a specific compiler
5343 or compiler version for Fortran 95 files.
5346 The command line used to compile a Fortran 95 source file to an object file.
5347 You only need to set $F95COM if you need to use a specific
5348 command line for Fortran 95 files.
5349 You should normally set the $FORTRANCOM variable,
5350 which specifies the default command line
5351 for all Fortran versions.
5354 The string displayed when a Fortran 95 source file
5355 is compiled to an object file.
5356 If this is not set, then $F95COM or $FORTRANCOM
5357 (the command line) is displayed.
5360 General user-specified options that are passed to the Fortran 95 compiler.
5361 Note that this variable does
5365 (or similar) include search path options
5366 that scons generates automatically from $F95PATH.
5370 for the variable that expands to those options.
5371 You only need to set $F95FLAGS if you need to define specific
5372 user options for Fortran 95 files.
5373 You should normally set the $FORTRANFLAGS variable,
5374 which specifies the user-specified options
5375 passed to the default Fortran compiler
5376 for all Fortran versions.
5379 An automatically-generated construction variable
5380 containing the Fortran 95 compiler command-line options
5381 for specifying directories to be searched for include files.
5382 The value of $_F95INCFLAGS is created
5383 by appending $INCPREFIX and $INCSUFFIX
5384 to the beginning and end
5385 of each directory in $F95PATH.
5388 The list of directories that the Fortran 95 compiler will search for include
5389 directories. The implicit dependency scanner will search these
5390 directories for include files. Don't explicitly put include directory
5391 arguments in $F95FLAGS because the result will be non-portable
5392 and the directories will not be searched by the dependency scanner. Note:
5393 directory names in $F95PATH will be looked-up relative to the SConscript
5394 directory when they are used in a command. To force
5396 to look-up a directory relative to the root of the source tree use #:
5397 You only need to set $F95PATH if you need to define a specific
5398 include path for Fortran 95 files.
5399 You should normally set the $FORTRANPATH variable,
5400 which specifies the include path
5401 for the default Fortran compiler
5402 for all Fortran versions.
5405 env = Environment(F95PATH='#/include')
5409 The directory look-up can also be forced using the
5414 include = Dir('include')
5415 env = Environment(F95PATH=include)
5419 The directory list will be added to command lines
5420 through the automatically-generated
5422 construction variable,
5423 which is constructed by
5424 appending the values of the
5425 $INCPREFIX and $INCSUFFIX
5426 construction variables
5427 to the beginning and end
5428 of each directory in $F95PATH.
5429 Any command lines you define that need
5430 the F95PATH directory list should
5431 include $_F95INCFLAGS:
5434 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5438 The command line used to compile a Fortran 95 source file to an object file
5439 after first running the file through the C preprocessor.
5440 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5441 are included on this command line.
5442 You only need to set $F95PPCOM if you need to use a specific
5443 C-preprocessor command line for Fortran 95 files.
5444 You should normally set the $FORTRANPPCOM variable,
5445 which specifies the default C-preprocessor command line
5446 for all Fortran versions.
5449 The default Fortran compiler
5450 for all versions of Fortran.
5453 The command line used to compile a Fortran source file to an object file.
5454 By default, any options specified
5455 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5456 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5457 are included on this command line.
5460 The string displayed when a Fortran source file
5461 is compiled to an object file.
5462 If this is not set, then $FORTRANCOM
5463 (the command line) is displayed.
5466 General user-specified options that are passed to the Fortran compiler.
5467 Note that this variable does
5471 (or similar) include or module search path options
5472 that scons generates automatically from $FORTRANPATH.
5474 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5476 for the variables that expand those options.
5478 .IP _FORTRANINCFLAGS
5479 An automatically-generated construction variable
5480 containing the Fortran compiler command-line options
5481 for specifying directories to be searched for include
5482 files and module files.
5483 The value of $_FORTRANINCFLAGS is created
5484 by prepending/appending $INCPREFIX and $INCSUFFIX
5485 to the beginning and end
5486 of each directory in $FORTRANPATH.
5489 Directory location where the Fortran compiler should place
5490 any module files it generates. This variable is empty, by default. Some
5491 Fortran compilers will internally append this directory in the search path
5492 for module files, as well
5494 .IP FORTRANMODDIRPREFIX
5495 The prefix used to specify a module directory on the Fortran compiler command
5497 This will be appended to the beginning of the directory
5498 in the $FORTRANMODDIR construction variables
5499 when the $_FORTRANMODFLAG variables is automatically generated.
5501 .IP FORTRANMODDIRSUFFIX
5502 The suffix used to specify a module directory on the Fortran compiler command
5504 This will be appended to the beginning of the directory
5505 in the $FORTRANMODDIR construction variables
5506 when the $_FORTRANMODFLAG variables is automatically generated.
5509 An automatically-generated construction variable
5510 containing the Fortran compiler command-line option
5511 for specifying the directory location where the Fortran
5512 compiler should place any module files that happen to get
5513 generated during compilation.
5514 The value of $_FORTRANMODFLAG is created
5515 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5516 to the beginning and end of the directory in $FORTRANMODDIR.
5518 .IP FORTRANMODPREFIX
5519 The module file prefix used by the Fortran compiler. SCons assumes that
5520 the Fortran compiler follows the quasi-standard naming convention for
5522 .I <module_name>.mod.
5523 As a result, this variable is left empty, by default. For situations in
5524 which the compiler does not necessarily follow the normal convention,
5525 the user may use this variable. Its value will be appended to every
5526 module file name as scons attempts to resolve dependencies.
5528 .IP FORTRANMODSUFFIX
5529 The module file suffix used by the Fortran compiler. SCons assumes that
5530 the Fortran compiler follows the quasi-standard naming convention for
5532 .I <module_name>.mod.
5533 As a result, this variable is set to ".mod", by default. For situations
5534 in which the compiler does not necessarily follow the normal convention,
5535 the user may use this variable. Its value will be appended to every
5536 module file name as scons attempts to resolve dependencies.
5539 The list of directories that the Fortran compiler will search for
5540 include files and (for some compilers) module files. The Fortran implicit
5541 dependency scanner will search these directories for include files (but
5542 not module files since they are autogenerated and, as such, may not
5543 actually exist at the time the scan takes place). Don't explicitly put
5544 include directory arguments in FORTRANFLAGS because the result will be
5545 non-portable and the directories will not be searched by the dependency
5546 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5547 to the SConscript directory when they are used in a command. To force
5549 to look-up a directory relative to the root of the source tree use #:
5552 env = Environment(FORTRANPATH='#/include')
5556 The directory look-up can also be forced using the
5561 include = Dir('include')
5562 env = Environment(FORTRANPATH=include)
5566 The directory list will be added to command lines
5567 through the automatically-generated
5569 construction variable,
5570 which is constructed by
5571 appending the values of the
5572 $INCPREFIX and $INCSUFFIX
5573 construction variables
5574 to the beginning and end
5575 of each directory in $FORTRANPATH.
5576 Any command lines you define that need
5577 the FORTRANPATH directory list should
5578 include $_FORTRANINCFLAGS:
5581 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5585 The command line used to compile a Fortran source file to an object file
5586 after first running the file through the C preprocessor.
5587 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5588 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5589 construction variables are included on this command line.
5592 The list of suffixes of files that will be scanned
5593 for Fortran implicit dependencies
5594 (INCLUDE lines & USE statements).
5595 The default list is:
5598 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5599 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5603 A function that converts a file name into a File instance relative to the
5608 frameworks options to be added at
5609 the end of a command
5610 line building a loadable module.
5613 The Ghostscript program used to convert PostScript to PDF files.
5616 General options passed to the Ghostscript program
5617 when converting PostScript to PDF files.
5620 The Ghostscript command line used to convert PostScript to PDF files.
5623 The string displayed when
5624 Ghostscript is used to convert
5625 a PostScript file to a PDF file.
5626 If this is not set, then $GSCOM (the command line) is displayed.
5629 The list of suffixes of files that will be scanned
5630 for IDL implicit dependencies
5631 (#include or import lines).
5632 The default list is:
5639 The prefix used to specify an include directory on the C compiler command
5641 This will be appended to the beginning of each directory
5642 in the $CPPPATH and $FORTRANPATH construction variables
5643 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5644 variables are automatically generated.
5647 The suffix used to specify an include directory on the C compiler command
5649 This will be appended to the end of each directory
5650 in the $CPPPATH and $FORTRANPATH construction variables
5651 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5652 variables are automatically generated.
5655 A function to be called to install a file into a
5656 destination file name.
5657 The default function copies the file into the destination
5658 (and sets the destination file's mode and permission bits
5659 to match the source file's).
5660 The function takes the following arguments:
5663 def install(dest, source, env):
5667 is the path name of the destination file.
5669 is the path name of the source file.
5671 is the construction environment
5672 (a dictionary of construction values)
5673 in force for this file installation.
5675 .IP INTEL_C_COMPILER_VERSION
5676 Set by the "intelc" Tool
5677 to the major version number of the Intel C compiler
5681 The Java archive tool.
5684 The directory to which the Java archive tool should change
5690 The command line used to call the Java archive tool.
5693 The string displayed when the Java archive tool
5695 If this is not set, then $JARCOM (the command line) is displayed.
5698 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5702 General options passed to the Java archive tool.
5703 By default this is set to
5705 to create the necessary
5710 The suffix for Java archives:
5718 The command line used to compile a directory tree containing
5719 Java source files to
5720 corresponding Java class files.
5721 Any options specified in the $JAVACFLAGS construction variable
5722 are included on this command line.
5725 The string displayed when compiling
5726 a directory tree of Java source files to
5727 corresponding Java class files.
5728 If this is not set, then $JAVACCOM (the command line) is displayed.
5731 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5735 General options that are passed to the Java compiler.
5738 The directory in which Java class files may be found.
5739 This is stripped from the beginning of any Java .class
5740 file names supplied to the
5745 The suffix for Java class files;
5750 The Java generator for C header and stub files.
5753 The command line used to generate C header and stub files
5755 Any options specified in the $JAVAHFLAGS construction variable
5756 are included on this command line.
5759 The string displayed when C header and stub files
5760 are generated from Java classes.
5761 If this is not set, then $JAVAHCOM (the command line) is displayed.
5764 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5768 General options passed to the C header and stub file generator
5772 The suffix for Java files;
5777 The LaTeX structured formatter and typesetter.
5780 The command line used to call the LaTeX structured formatter and typesetter.
5783 The string displayed when calling
5784 the LaTeX structured formatter and typesetter.
5785 If this is not set, then $LATEXCOM (the command line) is displayed.
5788 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5792 General options passed to the LaTeX structured formatter and typesetter.
5795 The linker for building loadable modules.
5796 By default, this is the same as $SHLINK.
5799 The command line for building loadable modules.
5800 On Mac OS X, this uses the $LDMODULE,
5801 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
5802 On other systems, this is the same as $SHLINK.
5805 The string displayed when building loadable modules.
5806 If this is not set, then $LDMODULECOM (the command line) is displayed.
5809 General user options passed to the linker for building loadable modules.
5812 The prefix used for loadable module file names.
5813 On Mac OS X, this is null;
5814 on other systems, this is
5815 the same as $SHLIBPREFIX.
5818 The suffix used for loadable module file names.
5819 On Mac OS X, this is null;
5820 on other systems, this is
5821 the same as $SHLIBSUFFIX.
5824 The lexical analyzer generator.
5827 General options passed to the lexical analyzer generator.
5830 The command line used to call the lexical analyzer generator
5831 to generate a source file.
5834 The string displayed when generating a source file
5835 using the lexical analyzer generator.
5836 If this is not set, then $LEXCOM (the command line) is displayed.
5839 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5843 An automatically-generated construction variable
5844 containing the linker command-line options
5845 for specifying directories to be searched for library.
5846 The value of $_LIBDIRFLAGS is created
5847 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5848 to the beginning and end
5849 of each directory in $LIBPATH.
5852 The prefix used to specify a library directory on the linker command line.
5853 This will be appended to the beginning of each directory
5854 in the $LIBPATH construction variable
5855 when the $_LIBDIRFLAGS variable is automatically generated.
5858 The suffix used to specify a library directory on the linker command line.
5859 This will be appended to the end of each directory
5860 in the $LIBPATH construction variable
5861 when the $_LIBDIRFLAGS variable is automatically generated.
5864 An automatically-generated construction variable
5865 containing the linker command-line options
5866 for specifying libraries to be linked with the resulting target.
5867 The value of $_LIBFLAGS is created
5868 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5869 to the beginning and end
5870 of each filename in $LIBS.
5873 The prefix used to specify a library to link on the linker command line.
5874 This will be appended to the beginning of each library
5875 in the $LIBS construction variable
5876 when the $_LIBFLAGS variable is automatically generated.
5879 The suffix used to specify a library to link on the linker command line.
5880 This will be appended to the end of each library
5881 in the $LIBS construction variable
5882 when the $_LIBFLAGS variable is automatically generated.
5885 The list of directories that will be searched for libraries.
5886 The implicit dependency scanner will search these
5887 directories for include files. Don't explicitly put include directory
5888 arguments in $LINKFLAGS or $SHLINKFLAGS
5889 because the result will be non-portable
5890 and the directories will not be searched by the dependency scanner. Note:
5891 directory names in LIBPATH will be looked-up relative to the SConscript
5892 directory when they are used in a command. To force
5894 to look-up a directory relative to the root of the source tree use #:
5897 env = Environment(LIBPATH='#/libs')
5901 The directory look-up can also be forced using the
5907 env = Environment(LIBPATH=libs)
5911 The directory list will be added to command lines
5912 through the automatically-generated
5914 construction variable,
5915 which is constructed by
5916 appending the values of the
5917 $LIBDIRPREFIX and $LIBDIRSUFFIX
5918 construction variables
5919 to the beginning and end
5920 of each directory in $LIBPATH.
5921 Any command lines you define that need
5922 the LIBPATH directory list should
5923 include $_LIBDIRFLAGS:
5926 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5930 The prefix used for (static) library file names.
5931 A default value is set for each platform
5932 (posix, win32, os2, etc.),
5933 but the value is overridden by individual tools
5934 (ar, mslib, sgiar, sunar, tlib, etc.)
5935 to reflect the names of the libraries they create.
5938 An array of legal prefixes for library file names.
5941 A list of one or more libraries
5942 that will be linked with
5943 any executable programs
5944 created by this environment.
5947 The library list will be added to command lines
5948 through the automatically-generated
5950 construction variable,
5951 which is constructed by
5952 appending the values of the
5953 $LIBLINKPREFIX and $LIBLINKSUFFIX
5954 construction variables
5955 to the beginning and end
5956 of each filename in $LIBS.
5957 Any command lines you define that need
5958 the LIBS library list should
5962 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5970 list, the name of that file will be added to
5972 and thus the link line, as is, without
5978 env.Append(LIBS=File('/tmp/mylib.so'))
5982 In all cases, scons will add dependencies from the executable program to
5983 all the libraries in this list.
5986 The suffix used for (static) library file names.
5987 A default value is set for each platform
5988 (posix, win32, os2, etc.),
5989 but the value is overridden by individual tools
5990 (ar, mslib, sgiar, sunar, tlib, etc.)
5991 to reflect the names of the libraries they create.
5994 An array of legal suffixes for library file names.
6000 General user options passed to the linker.
6001 Note that this variable should
6005 (or similar) options for linking with the libraries listed in $LIBS,
6008 (or similar) library search path options
6009 that scons generates automatically from $LIBPATH.
6013 for the variable that expands to library-link options,
6017 for the variable that expands to library search path options.
6020 The command line used to link object files into an executable.
6023 The string displayed when object files
6024 are linked into an executable.
6025 If this is not set, then $LINKCOM (the command line) is displayed.
6028 env = Environment(LINKCOMSTR = "Linking $TARGET")
6032 The M4 macro preprocessor.
6035 General options passed to the M4 macro preprocessor.
6038 The command line used to pass files through the M4 macro preprocessor.
6041 The string displayed when
6042 a file is passed through the M4 macro preprocessor.
6043 If this is not set, then $M4COM (the command line) is displayed.
6046 The maximum number of characters allowed on an external command line.
6048 link lines longer than this many characters
6049 are linke via a temporary file name.
6052 When the Microsoft Visual Studio tools are initialized, they set up
6053 this dictionary with the following keys:
6056 the version of MSVS being used (can be set via
6060 the available versions of MSVS installed
6063 installed directory of Visual C++
6066 installed directory of Visual Studio
6069 installed directory of the .NET framework
6071 .B FRAMEWORKVERSIONS:
6072 list of installed versions of the .NET framework, sorted latest to oldest.
6074 .B FRAMEWORKVERSION:
6075 latest installed version of the .NET framework
6078 installed location of the .NET SDK.
6081 installed location of the Platform SDK.
6083 .B PLATFORMSDK_MODULES:
6084 dictionary of installed Platform SDK modules,
6085 where the dictionary keys are keywords for the various modules, and
6086 the values are 2-tuples where the first is the release date, and the
6087 second is the version number.
6089 If a value isn't set, it wasn't available in the registry.
6091 .IP MSVS_IGNORE_IDE_PATHS
6092 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6093 instead of the settings from the IDE.
6095 For Visual Studio, SCons will (by default) automatically determine
6096 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6097 set by the IDE. You can override this behavior by setting these
6098 variables after Environment initialization, or by setting
6099 .B MSVS_IGNORE_IDE_PATHS = 1
6100 in the Environment initialization.
6101 Specifying this will not leave these unset, but will set them to a
6102 minimal set of paths needed to run the tools successfully.
6105 For VS6, the mininimal set is:
6106 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6107 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6108 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6110 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6111 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6112 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6116 Where '<VSDir>' is the installed location of Visual Studio.
6118 .IP MSVS_USE_MFC_DIRS
6119 Tells the MS Visual Studio tool(s) to use
6120 the MFC directories in its default paths
6121 for compiling and linking.
6122 Under MSVS version 6,
6124 .B MSVS_USE_MFC_DIRS
6133 external environment variable,
6139 external environment variable.
6140 Under MSVS version 7,
6142 .B MSVS_USE_MFC_DIRS
6145 .B "atlmfc\\\\include"
6146 directory to the default
6148 external environment variable,
6151 directory to the default
6153 external environment variable.
6154 The current default value is
6156 which means these directories
6157 are added to the paths by default.
6158 This default value is likely to change
6159 in a future release,
6160 so users who want the ATL and MFC
6161 values included in their paths
6162 are encouraged to enable the
6163 .B MSVS_USE_MFC_DIRS
6165 to avoid future incompatibility.
6166 This variable has no effect if the
6170 environment variables are set explictly.
6173 Sets the preferred version of MSVS to use.
6175 SCons will (by default) select the latest version of MSVS
6176 installed on your machine. So, if you have version 6 and version 7
6177 (MSVS .NET) installed, it will prefer version 7. You can override this by
6180 variable in the Environment initialization, setting it to the
6181 appropriate version ('6.0' or '7.0', for example).
6182 If the given version isn't installed, tool initialization will fail.
6185 The action used to generate Microsoft Visual Studio
6186 project and solution files.
6188 .IP MSVSPROJECTSUFFIX
6189 The suffix used for Microsoft Visual Studio project (DSP) files.
6190 The default value is
6192 when using Visual Studio version 7.x (.NET),
6195 when using earlier versions of Visual Studio.
6197 .IP MSVSSOLUTIONSUFFIX
6198 The suffix used for Microsoft Visual Studio solution (DSW) files.
6199 The default value is
6201 when using Visual Studio version 7.x (.NET),
6204 when using earlier versions of Visual Studio.
6207 The version number of the MetroWerks CodeWarrior C compiler
6211 A list of installed versions of the MetroWerks CodeWarrior C compiler
6215 When set to non-zero,
6216 suppresses creation of a corresponding Win32 static import lib by the
6218 builder when used with
6219 MinGW or Microsoft Visual Studio.
6220 This also suppresses creation
6221 of an export (.exp) file
6222 when using Microsoft Visual Studio.
6225 The prefix used for (static) object file names.
6228 The suffix used for (static) object file names.
6231 The Perforce executable.
6234 The command line used to
6235 fetch source files from Perforce.
6238 The string displayed when
6239 fetching a source file from Perforce.
6240 If this is not set, then $P4COM (the command line) is displayed.
6243 General options that are passed to Perforce.
6246 The Microsoft Visual C++ precompiled header that will be used when compiling
6247 object files. This variable is ignored by tools other than Microsoft Visual C++.
6248 When this variable is
6249 defined SCons will add options to the compiler command line to
6250 cause it to use the precompiled header, and will also set up the
6251 dependencies for the PCH file. Example:
6254 env['PCH'] = 'StdAfx.pch'
6258 The command line used by the
6260 builder to generated a precompiled header.
6263 The string displayed when generating a precompiled header.
6264 If this is not set, then $PCHCOM (the command line) is displayed.
6267 This variable specifies how much of a source file is precompiled. This
6268 variable is ignored by tools other than Microsoft Visual C++, or when
6269 the PCH variable is not being used. When this variable is define it
6270 must be a string that is the name of the header that
6271 is included at the end of the precompiled portion of the source files, or
6272 the empty string if the "#pragma hrdstop" construct is being used:
6275 env['PCHSTOP'] = 'StdAfx.h'
6279 The Microsoft Visual C++ PDB file that will store debugging information for
6280 object files, shared libraries, and programs. This variable is ignored by
6281 tools other than Microsoft Visual C++.
6282 When this variable is
6283 defined SCons will add options to the compiler and linker command line to
6284 cause them to generate external debugging information, and will also set up the
6285 dependencies for the PDB file. Example:
6288 env['PDB'] = 'hello.pdb'
6292 A deprecated synonym for $DVIPDFCOM.
6295 The prefix used for PDF file names.
6298 The suffix used for PDF file names.
6301 The name of the platform used to create the Environment. If no platform is
6302 specified when the Environment is created,
6304 autodetects the platform.
6307 env = Environment(tools = [])
6308 if env['PLATFORM'] == 'cygwin':
6314 .IP PRINT_CMD_LINE_FUNC
6315 A Python function used to print the command lines as they are executed
6316 (assuming command printing is not disabled by the
6320 options or their equivalents).
6321 The function should take four arguments:
6323 the command being executed (a string),
6325 the target being built (file node, list, or string name(s)),
6327 the source(s) used (file node, list, or string name(s)), and
6329 the environment being used.
6331 The function must do the printing itself. The default implementation,
6332 used if this variable is not set or is None, is:
6334 def print_cmd_line(s, target, source, env):
6335 sys.stdout.write(s + "\n")
6338 Here's an example of a more interesting function:
6340 def print_cmd_line(s, target, source, env):
6341 sys.stdout.write("Building %s -> %s...\n" %
6342 (' and '.join([str(x) for x in source]),
6343 ' and '.join([str(x) for x in target])))
6344 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6345 env.Program('foo', 'foo.c')
6348 This just prints "Building <targetname> from <sourcename>..." instead
6349 of the actual commands.
6350 Such a function could also log the actual commands to a log file,
6354 The prefix used for executable file names.
6357 The suffix used for executable file names.
6360 The command line used to convert TeX DVI files into a PostScript file.
6363 The string displayed when a TeX DVI file
6364 is converted into a PostScript file.
6365 If this is not set, then $PSCOM (the command line) is displayed.
6368 The prefix used for PostScript file names.
6371 The prefix used for PostScript file names.
6374 The qt tool tries to take this from os.environ.
6375 It also initializes all QT_*
6376 construction variables listed below.
6377 (Note that all paths are constructed
6378 with python's os.path.join() method,
6379 but are listed here with the '/' separator
6380 for easier reading.)
6381 In addition, the construction environment
6382 variables CPPPATH, LIBPATH and LIBS may be modified
6384 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6385 are modified. Because the build-performance is affected when using this tool,
6386 you have to explicitly specify it at Environment creation:
6389 Environment(tools=['default','qt'])
6392 The qt tool supports the following operations:
6394 .B Automatic moc file generation from header files.
6395 You do not have to specify moc files explicitly, the tool does it for you.
6396 However, there are a few preconditions to do so: Your header file must have
6397 the same filebase as your implementation file and must stay in the same
6398 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6399 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6400 See also the corresponding builder method
6403 .B Automatic moc file generation from cxx files.
6404 As stated in the qt documentation, include the moc file at the end of
6405 the cxx file. Note that you have to include the file, which is generated
6406 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6407 <basename>.moc. A warning is generated after building the moc file, if you
6408 do not include the correct file. If you are using BuildDir, you may
6409 need to specify duplicate=1. You can turn off automatic moc file generation
6410 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6413 .B Automatic handling of .ui files.
6414 The implementation files generated from .ui files are handled much the same
6415 as yacc or lex files. Each .ui file given as a source of Program, Library or
6416 SharedLibrary will generate three files, the declaration file, the
6417 implementation file and a moc file. Because there are also generated headers,
6418 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6422 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6423 specify files to run moc on.
6426 The path where the qt binaries are installed.
6427 The default value is '$QTDIR/bin'.
6430 The path where the qt header files are installed.
6431 The default value is '$QTDIR/include'.
6432 Note: If you set this variable to None, the tool won't change the CPPPATH
6433 construction variable.
6436 Prints lots of debugging information while scanning for moc files.
6439 The path where the qt libraries are installed.
6440 The default value is '$QTDIR/lib'.
6441 Note: If you set this variable to None, the tool won't change the LIBPATH
6442 construction variable.
6445 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6446 this variable to None, the tool won't change the LIBS variable.
6449 Default value is '$QT_BINPATH/moc'.
6452 Default value is ''. Prefix for moc output files, when source is a cxx file.
6455 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6458 .IP QT_MOCFROMCPPFLAGS
6459 Default value is '-i'. These flags are passed to moc, when moccing a
6462 .IP QT_MOCFROMCXXCOM
6463 Command to generate a moc file from a cpp file.
6465 .IP QT_MOCFROMCXXCOMSTR
6466 The string displayed when generating a moc file from a cpp file.
6467 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6470 Command to generate a moc file from a header.
6472 .IP QT_MOCFROMHCOMSTR
6473 The string displayed when generating a moc file from a cpp file.
6474 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6476 .IP QT_MOCFROMHFLAGS
6477 Default value is ''. These flags are passed to moc, when moccing a header
6481 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6484 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6488 Default value is '$QT_BINPATH/uic'.
6491 Command to generate header files from .ui files.
6494 The string displayed when generating header files from .ui files.
6495 If this is not set, then $QT_UICCOM (the command line) is displayed.
6498 Default value is ''. These flags are passed to uic, when creating a a h
6499 file from a .ui file.
6501 .IP QT_UICDECLPREFIX
6502 Default value is ''. Prefix for uic generated header files.
6504 .IP QT_UICDECLSUFFIX
6505 Default value is '.h'. Suffix for uic generated header files.
6508 Default value is ''. These flags are passed to uic, when creating a cxx
6509 file from a .ui file.
6511 .IP QT_UICIMPLPREFIX
6512 Default value is 'uic_'. Prefix for uic generated implementation files.
6514 .IP QT_UICIMPLSUFFIX
6515 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6519 Default value is '.ui'. Suffix of designer input files.
6522 The archive indexer.
6525 General options passed to the archive indexer.
6528 The resource compiler used by the RES builder.
6531 The command line used by the RES builder.
6534 The string displayed when invoking the resource compiler.
6535 If this is not set, then $RCCOM (the command line) is displayed.
6538 The flags passed to the resource compiler by the RES builder.
6542 Note that this variable is not actually used
6543 for the command to fetch source files from RCS;
6546 construction variable, below.
6549 The RCS "checkout" executable,
6550 used to fetch source files from RCS.
6553 The command line used to
6554 fetch (checkout) source files from RCS.
6557 The string displayed when fetching
6558 a source file from RCS.
6559 If this is not set, then $RCS_COCOM
6560 (the command line) is displayed.
6563 Options that are passed to the $RCS_CO command.
6566 The program used to register DLLs on Windows systems.
6569 The command line used to register a newly-built DLL file
6571 Invoked when the "register=1"
6572 keyword argument is passed to the
6577 The string displayed when registering a newly-built DLL file.
6578 If this is not set, then $REGSVRCOM (the command line) is displayed.
6581 A function that converts a file name into a list of Dir instances by
6582 searching the repositories.
6585 The Java RMI stub compiler.
6588 The command line used to compile stub
6589 and skeleton class files
6590 from Java classes that contain RMI implementations.
6591 Any options specified in the $RMICFLAGS construction variable
6592 are included on this command line.
6595 The string displayed when compiling
6596 stub and skeleton class files
6597 from Java classes that contain RMI implementations.
6598 If this is not set, then $RMICCOM (the command line) is displayed.
6601 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6605 General options passed to the Java RMI stub compiler.
6608 The RPC protocol compiler.
6610 .IP RPCGENCLIENTFLAGS
6611 Options passed to the RPC protocol compiler
6612 when generating client side stubs.
6613 These are in addition to any flags specified in the
6615 construction variable.
6618 General options passed to the RPC protocol compiler.
6620 .IP RPCGENHEADERFLAGS
6621 Options passed to the RPC protocol compiler
6622 when generating a header file.
6623 These are in addition to any flags specified in the
6625 construction variable.
6627 .IP RPCGENSERVICEFLAGS
6628 Options passed to the RPC protocol compiler
6629 when generating server side stubs.
6630 These are in addition to any flags specified in the
6632 construction variable.
6635 Options passed to the RPC protocol compiler
6636 when generating XDR routines.
6637 These are in addition to any flags specified in the
6639 construction variable.
6642 A list of paths to search for shared libraries when running programs.
6643 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6644 Ignored on platforms and toolchains that don't support it.
6645 Note that the paths added to RPATH
6646 are not transformed by
6648 in any way: if you want an absolute
6649 path, you must make it absolute yourself.
6652 A list of the available implicit dependency scanners.
6653 New file scanners may be added by
6654 appending to this list,
6655 although the more flexible approach
6656 is to associate scanners
6657 with a specific Builder.
6658 See the sections "Builder Objects"
6659 and "Scanner Objects,"
6660 below, for more information.
6663 The SCCS executable.
6666 The command line used to
6667 fetch source files from SCCS.
6670 The string displayed when fetching
6671 a source file from a CVS repository.
6672 If this is not set, then $SCCSCOM
6673 (the command line) is displayed.
6676 General options that are passed to SCCS.
6679 Options that are passed specifically to the SCCS "get" subcommand.
6680 This can be set, for example, to
6682 to check out editable files from SCCS.
6685 The C compiler used for generating shared-library objects.
6688 The command line used to compile a C source file
6689 to a shared-library object file.
6690 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6691 are included on this command line.
6694 The string displayed when a C source file
6695 is compiled to a shared object file.
6696 If this is not set, then $SHCCCOM (the command line) is displayed.
6699 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6703 Options that are passed to the C compiler
6704 to generate shared-library objects.
6707 The C++ compiler used for generating shared-library objects.
6710 The command line used to compile a C++ source file
6711 to a shared-library object file.
6712 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6713 are included on this command line.
6716 The string displayed when a C++ source file
6717 is compiled to a shared object file.
6718 If this is not set, then $SHCXXCOM (the command line) is displayed.
6721 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6725 Options that are passed to the C++ compiler
6726 to generate shared-library objects.
6729 A string naming the shell program that will be passed to the
6734 construction variable for more information.
6737 The Fortran 77 compiler used for generating shared-library objects.
6738 You should normally set the $SHFORTRANC variable,
6739 which specifies the default Fortran compiler
6740 for all Fortran versions.
6741 You only need to set $SHF77 if you need to use a specific compiler
6742 or compiler version for Fortran 77 files.
6745 The command line used to compile a Fortran 77 source file
6746 to a shared-library object file.
6747 You only need to set $SHF77COM if you need to use a specific
6748 command line for Fortran 77 files.
6749 You should normally set the $SHFORTRANCOM variable,
6750 which specifies the default command line
6751 for all Fortran versions.
6754 The string displayed when a Fortran 77 source file
6755 is compiled to a shared-library object file.
6756 If this is not set, then $SHF77COM or $SHFORTRANCOM
6757 (the command line) is displayed.
6760 Options that are passed to the Fortran 77 compiler
6761 to generated shared-library objects.
6762 You only need to set $SHF77FLAGS if you need to define specific
6763 user options for Fortran 77 files.
6764 You should normally set the $SHFORTRANFLAGS variable,
6765 which specifies the user-specified options
6766 passed to the default Fortran compiler
6767 for all Fortran versions.
6770 The command line used to compile a Fortran 77 source file to a
6771 shared-library object file
6772 after first running the file through the C preprocessor.
6773 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6774 are included on this command line.
6775 You only need to set $SHF77PPCOM if you need to use a specific
6776 C-preprocessor command line for Fortran 77 files.
6777 You should normally set the $SHFORTRANPPCOM variable,
6778 which specifies the default C-preprocessor command line
6779 for all Fortran versions.
6782 The Fortran 90 compiler used for generating shared-library objects.
6783 You should normally set the $SHFORTRANC variable,
6784 which specifies the default Fortran compiler
6785 for all Fortran versions.
6786 You only need to set $SHF90 if you need to use a specific compiler
6787 or compiler version for Fortran 90 files.
6790 The command line used to compile a Fortran 90 source file
6791 to a shared-library object file.
6792 You only need to set $SHF90COM if you need to use a specific
6793 command line for Fortran 90 files.
6794 You should normally set the $SHFORTRANCOM variable,
6795 which specifies the default command line
6796 for all Fortran versions.
6799 The string displayed when a Fortran 90 source file
6800 is compiled to a shared-library object file.
6801 If this is not set, then $SHF90COM or $SHFORTRANCOM
6802 (the command line) is displayed.
6805 Options that are passed to the Fortran 90 compiler
6806 to generated shared-library objects.
6807 You only need to set $SHF90FLAGS if you need to define specific
6808 user options for Fortran 90 files.
6809 You should normally set the $SHFORTRANFLAGS variable,
6810 which specifies the user-specified options
6811 passed to the default Fortran compiler
6812 for all Fortran versions.
6815 The command line used to compile a Fortran 90 source file to a
6816 shared-library object file
6817 after first running the file through the C preprocessor.
6818 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6819 are included on this command line.
6820 You only need to set $SHF90PPCOM if you need to use a specific
6821 C-preprocessor command line for Fortran 90 files.
6822 You should normally set the $SHFORTRANPPCOM variable,
6823 which specifies the default C-preprocessor command line
6824 for all Fortran versions.
6827 The Fortran 95 compiler used for generating shared-library objects.
6828 You should normally set the $SHFORTRANC variable,
6829 which specifies the default Fortran compiler
6830 for all Fortran versions.
6831 You only need to set $SHF95 if you need to use a specific compiler
6832 or compiler version for Fortran 95 files.
6835 The command line used to compile a Fortran 95 source file
6836 to a shared-library object file.
6837 You only need to set $SHF95COM if you need to use a specific
6838 command line for Fortran 95 files.
6839 You should normally set the $SHFORTRANCOM variable,
6840 which specifies the default command line
6841 for all Fortran versions.
6844 The string displayed when a Fortran 95 source file
6845 is compiled to a shared-library object file.
6846 If this is not set, then $SHF95COM or $SHFORTRANCOM
6847 (the command line) is displayed.
6850 Options that are passed to the Fortran 95 compiler
6851 to generated shared-library objects.
6852 You only need to set $SHF95FLAGS if you need to define specific
6853 user options for Fortran 95 files.
6854 You should normally set the $SHFORTRANFLAGS variable,
6855 which specifies the user-specified options
6856 passed to the default Fortran compiler
6857 for all Fortran versions.
6860 The command line used to compile a Fortran 95 source file to a
6861 shared-library object file
6862 after first running the file through the C preprocessor.
6863 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6864 are included on this command line.
6865 You only need to set $SHF95PPCOM if you need to use a specific
6866 C-preprocessor command line for Fortran 95 files.
6867 You should normally set the $SHFORTRANPPCOM variable,
6868 which specifies the default C-preprocessor command line
6869 for all Fortran versions.
6872 The default Fortran compiler used for generating shared-library objects.
6875 The command line used to compile a Fortran source file
6876 to a shared-library object file.
6879 The string displayed when a Fortran source file
6880 is compiled to a shared-library object file.
6881 If this is not set, then $SHFORTRANCOM
6882 (the command line) is displayed.
6885 Options that are passed to the Fortran compiler
6886 to generate shared-library objects.
6889 The command line used to compile a Fortran source file to a
6890 shared-library object file
6891 after first running the file through the C preprocessor.
6892 Any options specified
6893 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6894 are included on this command line.
6897 The prefix used for shared library file names.
6900 The suffix used for shared library file names.
6903 The linker for programs that use shared libraries.
6906 The command line used to link programs using shared libaries.
6909 The string displayed when programs using shared libraries are linked.
6910 If this is not set, then $SHLINKCOM (the command line) is displayed.
6913 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6917 General user options passed to the linker for programs using shared libraries.
6918 Note that this variable should
6922 (or similar) options for linking with the libraries listed in $LIBS,
6925 (or similar) include search path options
6926 that scons generates automatically from $LIBPATH.
6930 for the variable that expands to library-link options,
6934 for the variable that expands to library search path options.
6937 The prefix used for shared object file names.
6940 The suffix used for shared object file names.
6943 A reserved variable name
6944 that may not be set or used in a construction environment.
6945 (See "Variable Substitution," below.)
6948 A reserved variable name
6949 that may not be set or used in a construction environment.
6950 (See "Variable Substitution," below.)
6953 A command interpreter function that will be called to execute command line
6954 strings. The function must expect the following arguments:
6957 def spawn(shell, escape, cmd, args, env):
6961 is a string naming the shell program to use.
6963 is a function that can be called to escape shell special characters in
6966 is the path to the command to be executed.
6968 is the arguments to the command.
6970 is a dictionary of the environment variables
6971 in which the command should be executed.
6974 '\"The Subversion executable (usually named
6978 '\"The command line used to
6979 '\"fetch source files from a Subversion repository.
6982 '\"General options that are passed to Subversion.
6985 The scripting language wrapper and interface generator.
6988 The suffix that will be used for intermediate C
6989 source files generated by
6990 the scripting language wrapper and interface generator.
6991 The default value is
6992 .BR _wrap$CFILESUFFIX .
6993 By default, this value is used whenever the
6997 specified as part of the
6999 construction variable.
7002 The command line used to call
7003 the scripting language wrapper and interface generator.
7006 The string displayed when calling
7007 the scripting language wrapper and interface generator.
7008 If this is not set, then $SWIGCOM (the command line) is displayed.
7010 .IP SWIGCXXFILESUFFIX
7011 The suffix that will be used for intermediate C++
7012 source files generated by
7013 the scripting language wrapper and interface generator.
7014 The default value is
7015 .BR _wrap$CFILESUFFIX .
7016 By default, this value is used whenever the
7018 option is specified as part of the
7020 construction variable.
7023 General options passed to
7024 the scripting language wrapper and interface generator.
7025 This is where you should set
7029 or whatever other options you want to specify to SWIG.
7032 option in this variable,
7035 generate a C++ intermediate source file
7036 with the extension that is specified as the
7044 The command line used to call the tar archiver.
7047 The string displayed when archiving files
7048 using the tar archiver.
7049 If this is not set, then $TARCOM (the command line) is displayed.
7052 env = Environment(TARCOMSTR = "Archiving $TARGET")
7056 General options passed to the tar archiver.
7059 A reserved variable name
7060 that may not be set or used in a construction environment.
7061 (See "Variable Substitution," below.)
7064 A reserved variable name
7065 that may not be set or used in a construction environment.
7066 (See "Variable Substitution," below.)
7069 The suffix used for tar file names.
7072 The TeX formatter and typesetter.
7075 The command line used to call the TeX formatter and typesetter.
7078 The string displayed when calling
7079 the TeX formatter and typesetter.
7080 If this is not set, then $TEXCOM (the command line) is displayed.
7083 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7087 General options passed to the TeX formatter and typesetter.
7090 A list of the names of the Tool specifications
7091 that are part of this construction environment.
7093 .IP WIN32_INSERT_DEF
7094 When this is set to true,
7095 a library build of a WIN32 shared library (.dll file)
7096 will also build a corresponding .def file at the same time,
7097 if a .def file is not already listed as a build target.
7098 The default is 0 (do not build a .def file).
7101 The prefix used for WIN32 .def file names.
7104 The suffix used for WIN32 .def file names.
7107 The parser generator.
7110 The command line used to call the parser generator
7111 to generate a source file.
7114 The string displayed when generating a source file
7115 using the parser generator.
7116 If this is not set, then $YACCCOM (the command line) is displayed.
7119 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7123 General options passed to the parser generator.
7124 If $YACCFLAGS contains a \-d option,
7125 SCons assumes that the call will also create a .h file
7126 (if the yacc source file ends in a .y suffix)
7128 (if the yacc source file ends in a .yy suffix)
7131 The zip compression and file packaging utility.
7134 The command line used to call the zip utility,
7135 or the internal Python function used to create a
7139 The string displayed when archiving files
7140 using the zip utility.
7141 If this is not set, then $ZIPCOM
7142 (the command line or internal Python function) is displayed.
7145 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7154 module used by the internal Python function
7155 to control whether the zip archive
7156 is compressed or not.
7157 The default value is
7158 .BR zipfile.ZIP_DEFLATED ,
7159 which creates a compressed zip archive.
7160 This value has no effect when using Python 1.5.2
7163 module is otherwise unavailable.
7166 General options passed to the zip utility.
7169 Construction variables can be retrieved and set using the
7171 method of the construction environment:
7174 dict = env.Dictionary()
7178 or using the [] operator:
7184 Construction variables can also be passed to the construction environment
7188 env = Environment(CC="cc")
7191 or when copying a construction environment using the
7196 env2 = env.Copy(CC="cl.exe")
7199 .SS Configure Contexts
7203 .I configure contexts,
7204 an integrated mechanism similar to the
7205 various AC_CHECK macros in GNU autoconf
7206 for testing for the existence of C header
7207 files, libraries, etc.
7208 In contrast to autoconf,
7210 does not maintain an explicit cache of the tested values,
7211 but uses its normal dependency tracking to keep the checked values
7212 up to date. However, users may override this behaviour with the
7214 command line option.
7216 The following methods can be used to perform checks:
7219 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7221 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7222 This creates a configure context, which can be used to perform checks.
7224 specifies the environment for building the tests.
7225 This environment may be modified when performing checks.
7227 is a dictionary containing custom tests.
7228 See also the section about custom tests below.
7229 By default, no custom tests are added to the configure context.
7231 specifies a directory where the test cases are built.
7232 Note that this directory is not used for building
7234 The default value is the directory
7237 specifies a file which collects the output from commands
7238 that are executed to check for the existence of header files, libraries, etc.
7239 The default is the file #/config.log.
7240 If you are using the
7243 you may want to specify a subdirectory under your build directory.
7245 specifies a C header file where the results of tests
7246 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7247 The default is to not write a
7250 You can specify the same
7252 file in multiple calls to Configure,
7255 will concatenate all results in the specified file.
7257 uses its normal dependency checking
7258 to decide if it's necessary to rebuild
7262 This means that the file is not necessarily re-built each
7264 but is only rebuilt if its contents will have changed
7265 and some target that depends on the
7267 file is being built.
7272 instance has the following associated methods:
7275 .RI Configure.Finish( self )
7276 This method should be called after configuration is done.
7277 It returns the environment as modified
7278 by the configuration checks performed.
7279 After this method is called, no further checks can be performed
7280 with this configuration context.
7281 However, you can create a new
7283 context to perform additional checks.
7284 Only one context should be active at a time.
7286 The following Checks are predefined.
7287 (This list will likely grow larger as time
7288 goes by and developers contribute new useful tests.)
7291 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7294 is usable in the specified language.
7297 in which case the last item in the list
7298 is the header file to be checked,
7299 and the previous list items are
7302 lines should precede the
7303 header line being checked for.
7304 The optional argument
7307 a two character string, where the first character denotes the opening
7308 quote and the second character denotes the closing quote.
7309 By default, both characters are " (double quote).
7310 The optional argument
7316 and selects the compiler to be used for the check.
7317 Returns 1 on success and 0 on failure.
7320 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7321 This is a wrapper around
7322 .B Configure.CheckHeader
7325 is usable in the C language.
7328 in which case the last item in the list
7329 is the header file to be checked,
7330 and the previous list items are
7333 lines should precede the
7334 header line being checked for.
7335 The optional argument
7338 a two character string, where the first character denotes the opening
7339 quote and the second character denotes the closing quote (both default
7341 Returns 1 on success and 0 on failure.
7344 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7345 This is a wrapper around
7346 .B Configure.CheckHeader
7349 is usable in the C++ language.
7352 in which case the last item in the list
7353 is the header file to be checked,
7354 and the previous list items are
7357 lines should precede the
7358 header line being checked for.
7359 The optional argument
7362 a two character string, where the first character denotes the opening
7363 quote and the second character denotes the closing quote (both default
7365 Returns 1 on success and 0 on failure.
7368 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7369 Checks if the specified
7370 C or C++ function is available.
7372 is the name of the function to check for.
7375 argument is a string
7379 that will be compiled
7380 to check if the function exists;
7386 char function_name();
7394 and selects the compiler to be used for the check;
7398 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
7405 is 1 and the library provides the specified
7407 appends the library to the LIBS construction environment variable.
7409 may also be None (the default),
7412 is checked with the current LIBS variable,
7413 or a list of library names,
7414 in which case each library in the list
7421 you can link against the specified
7429 and selects the compiler to be used for the check;
7431 The default value for
7434 It is assumed, that the C-language is used.
7435 This method returns 1 on success and 0 on error.
7438 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7441 .RI Configure.CheckLib
7442 call, this call provides a more sophisticated way to check against libraries.
7445 specifies the library or a list of libraries to check.
7447 specifies a header to check for.
7450 in which case the last item in the list
7451 is the header file to be checked,
7452 and the previous list items are
7455 lines should precede the
7456 header line being checked for.
7458 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7460 can be any valid expression (with a trailing ';'). The default is 'main();'.
7462 specifies whether to add the library to the environment (only if the check
7463 succeeds). This method returns 1 on success and 0 on error.
7466 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7467 Checks for the existence of a type defined by
7470 specifies the typedef name to check for.
7472 is a string containing one or more
7474 lines that will be inserted into the program
7475 that will be run to test for the existence of the type.
7482 and selects the compiler to be used for the check;
7486 Example of a typical Configure usage:
7490 conf = Configure( env )
7491 if not conf.CheckCHeader( 'math.h' ):
7492 print 'We really need math.h!'
7494 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7495 # do stuff for qt - usage, e.g.
7496 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7501 You can define your own custom checks.
7502 in addition to the predefined checks.
7503 These are passed in a dictionary to the Configure function.
7504 This dictionary maps the names of the checks
7505 to user defined Python callables
7506 (either Python functions or class instances implementing the
7509 The first argument of the call is always a
7511 instance followed by the arguments,
7512 which must be supplied by the user of the check.
7513 These CheckContext instances define the following methods:
7516 .RI CheckContext.Message( self ", " text )
7518 Usually called before the check is started.
7520 will be displayed to the user, e.g. 'Checking for library X...'
7523 .RI CheckContext.Result( self, ", " res )
7525 Usually called after the check is done.
7527 can be either an integer or a string. In the former case, 'ok' (res != 0)
7528 or 'failed' (res == 0) is displayed to the user, in the latter case the
7529 given string is displayed.
7532 .RI CheckContext.TryCompile( self ", " text ", " extension )
7533 Checks if a file with the specified
7535 (e.g. '.c') containing
7537 can be compiled using the environment's
7539 builder. Returns 1 on success and 0 on failure.
7542 .RI CheckContext.TryLink( self ", " text ", " extension )
7543 Checks, if a file with the specified
7545 (e.g. '.c') containing
7547 can be compiled using the environment's
7549 builder. Returns 1 on success and 0 on failure.
7552 .RI CheckContext.TryRun( self ", " text ", " extension )
7553 Checks, if a file with the specified
7555 (e.g. '.c') containing
7557 can be compiled using the environment's
7559 builder. On success, the program is run. If the program
7560 executes successfully
7561 (that is, its return status is 0),
7566 is the standard output of the
7568 If the program fails execution
7569 (its return status is non-zero),
7570 then (0, '') is returned.
7573 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7574 Checks if the specified
7576 with an optional source file (contents
7583 may be anything which can be converted to a
7590 is the content of the target file.
7596 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7597 Low level implementation for testing specific builds;
7598 the methods above are based on this method.
7599 Given the Builder instance
7603 of a source file with optional
7605 this method returns 1 on success and 0 on failure. In addition,
7607 is set to the build target node, if the build was successful.
7610 Example for implementing and using custom tests:
7613 def CheckQt(context, qtdir):
7614 context.Message( 'Checking for qt ...' )
7615 lastLIBS = context.env['LIBS']
7616 lastLIBPATH = context.env['LIBPATH']
7617 lastCPPPATH= context.env['CPPPATH']
7618 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7619 ret = context.TryLink("""
7621 int main(int argc, char **argv) {
7622 QApplication qapp(argc, argv);
7627 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7628 context.Result( ret )
7632 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7633 if not conf.CheckQt('/usr/lib/qt'):
7634 print 'We really need qt!'
7639 .SS Construction Variable Options
7641 Often when building software, various options need to be specified at build
7642 time that are not known when the SConstruct/SConscript files are
7643 written. For example, libraries needed for the build may be in non-standard
7644 locations, or site-specific compiler options may need to be passed to the
7647 provides a mechanism for overridding construction variables from the
7648 command line or a text-based SConscript file through an Options
7649 object. To create an Options object, call the Options() function:
7652 .RI Options([ files "], [" args ])
7653 This creates an Options object that will read construction variables from
7654 the file or list of filenames specified in
7656 If no files are specified,
7661 then no files will be read.
7662 The optional argument
7665 values that will override anything read from the specified files;
7666 it is primarily intended to be passed the
7668 dictionary that holds variables
7669 specified on the command line.
7673 opts = Options('custom.py')
7674 opts = Options('overrides.py', ARGUMENTS)
7675 opts = Options(None, {FOO:'expansion', BAR:7})
7678 Options objects have the following methods:
7681 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7682 This adds a customizable construction variable to the Options object.
7684 is the name of the variable.
7686 is the help text for the variable.
7688 is the default value of the variable;
7689 if the default value is
7691 and there is no explicit value specified,
7692 the construction variable will
7694 be added to the construction environment.
7696 is called to validate the value of the variable, and should take three
7697 arguments: key, value, and environment
7699 is called to convert the value before putting it in the environment, and
7700 should take a single argument: value. Example:
7703 opts.Add('CC', 'The C compiler')
7707 .RI AddOptions( list )
7708 A wrapper script that adds
7709 multiple customizable construction variables
7710 to an Options object.
7712 is a list of tuple or list objects
7713 that contain the arguments
7714 for an individual call to the
7721 ('CC', 'The C compiler'),
7722 ('VALIDATE', 'An option for testing validation',
7723 'notset', validator, None),
7728 .RI Update( env ", [" args ])
7729 This updates a construction environment
7731 with the customized construction variables. Normally this method is not
7732 called directly, but is called indirectly by passing the Options object to
7733 the Environment() function:
7736 env = Environment(options=opts)
7740 The text file(s) that were specified
7741 when the Options object was created
7742 are executed as Python scripts,
7743 and the values of (global) Python variables set in the file
7744 are added to the construction environment.
7752 .RI Save( filename ", " env )
7753 This saves the currently set options into a script file named
7755 that can be used on the next invocation to automatically load the current
7756 settings. This method combined with the Options method can be used to
7757 support caching of options between runs.
7761 opts = Options(['options.cache', 'custom.py'])
7764 opts.Save('options.cache', env)
7768 .RI GenerateHelpText( env ", [" sort ])
7769 This generates help text documenting the customizable construction
7770 variables suitable to passing in to the Help() function.
7772 is the construction environment that will be used to get the actual values
7773 of customizable variables. Calling with
7777 will cause the output to be sorted
7778 by the specified argument.
7782 should take two arguments
7785 (like the standard Python
7790 Help(opts.GenerateHelpText(env))
7791 Help(opts.GenerateHelpText(env, sort=cmp))
7795 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
7796 This method returns a formatted string
7797 containing the printable help text
7799 It is normally not called directly,
7800 but is called by the
7801 .IR GenerateHelpText ()
7802 method to create the returned help text.
7803 It may be overridden with your own
7804 function that takes the arguments specified above
7805 and returns a string of help text formatted to your liking.
7807 .IR GenerateHelpText ()
7808 will not put any blank lines or extra
7809 characters in between the entries,
7810 so you must add those characters to the returned
7811 string if you want the entries separated.
7814 def my_format(env, opt, help, default, actual):
7815 fmt = "\n%s: default=%s actual=%s (%s)\n"
7816 return fmt % (opt, default. actual, help)
7817 opts.FormatOptionHelpText = my_format
7820 To make it more convenient to work with customizable Options,
7822 provides a number of functions
7823 that make it easy to set up
7824 various types of Options:
7827 .RI BoolOption( key ", " help ", " default )
7828 Return a tuple of arguments
7829 to set up a Boolean option.
7833 have a default value of
7835 and display the specified
7838 The option will interpret the values
7860 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7861 Return a tuple of arguments
7863 whose value may be one
7864 of a specified list of legal enumerated values.
7868 have a default value of
7870 and display the specified
7873 The option will only support those
7879 argument is a dictionary
7880 that can be used to convert
7881 input values into specific legal values
7890 then the values are case-sensitive.
7895 then values will be matched
7901 then values will be matched
7903 and all input values will be
7904 converted to lower case.
7907 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
7908 Return a tuple of arguments
7910 whose value may be one or more
7911 of a specified list of legal enumerated values.
7915 have a default value of
7917 and display the specified
7920 The option will only support the values
7923 or the values in the
7926 More than one value may be specified,
7927 with all values separated by commas.
7928 The default may be a string of
7929 comma-separated default values,
7930 or a list of the default values.
7933 argument is a dictionary
7934 that can be used to convert
7935 input values into specific legal values
7941 .RI PackageOption( key ", " help ", " default )
7942 Return a tuple of arguments
7944 whose value is a path name
7945 of a package that may be
7946 enabled, disabled or
7947 given an explicit path name.
7951 have a default value of
7953 and display the specified
7956 The option will support the values
7963 in which case the specified
7966 or the option may be set to an
7968 (typically the path name to a package
7969 that is being enabled).
7970 The option will also support the values
7976 to disable use of the specified option.
7979 .RI PathOption( key ", " help ", " default ", [" validator ])
7980 Return a tuple of arguments
7982 whose value is expected to be a path name.
7986 have a default value of
7988 and display the specified
7994 that will be called to
7995 verify that the specified path
7998 following ready-made validators:
7999 .BR PathOption.PathExists
8001 which verifies that the specified path exists;
8002 .BR PathOption.PathIsFile ,
8003 which verifies that the specified path is an existing file;
8004 .BR PathOption.PathIsDir ,
8005 which verifies that the specified path is an existing directory;
8007 .BR PathOption.PathIsDirCreate ,
8008 which verifies that the specified path is a directory,
8009 and will create the specified directory if the path does not exist.
8010 You may supply your own
8013 which must take three arguments
8015 the name of the options variable to be set;
8017 the specified value being checked;
8020 the construction environment)
8021 and should raise an exception
8022 if the specified value is not acceptable.
8025 These functions make it
8026 convenient to create a number
8027 of options with consistent behavior
8028 in a single call to the
8034 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
8035 EnumOption('debug', 'debug output and symbols', 'no'
8036 allowed_values=('yes', 'no', 'full'),
8037 map={}, ignorecase=0), # case sensitive
8038 ListOption('shared',
8039 'libraries to build as shared libraries',
8041 names = list_of_libs),
8042 PackageOption('x11',
8043 'use X11 installed here (yes = search some places)',
8045 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
8046 PathOption('foopath', 'where the foo library is installed', foopath,
8047 PathOption.PathIsDir),
8052 .SS File and Directory Nodes
8062 Nodes, respectively.
8063 python objects, respectively.
8064 Those objects have several user-visible attributes
8065 and methods that are often useful:
8071 This path is relative to the top-level directory
8075 The build path is the same as the source path if
8080 The absolute build path of the given file or directory.
8090 object representing the
8099 # Get the current build dir's path, relative to top.
8101 # Current dir's absolute path
8103 # Next line is always '.', because it is the top dir's path relative to itself.
8105 File('foo.c').srcnode().path # source path of the given source file.
8107 # Builders also return File objects:
8108 foo = env.Program('foo.c')
8109 print "foo will be built in %s"%foo.path
8115 can be extended to build different types of targets
8116 by adding new Builder objects
8117 to a construction environment.
8119 you should only need to add a new Builder object
8120 when you want to build a new type of file or other external target.
8121 If you just want to invoke a different compiler or other tool
8122 to build a Program, Object, Library, or any other
8123 type of output file for which
8125 already has an existing Builder,
8126 it is generally much easier to
8127 use those existing Builders
8128 in a construction environment
8129 that sets the appropriate construction variables
8132 Builder objects are created
8138 function accepts the following arguments:
8141 The command line string used to build the target from the source.
8144 a list of strings representing the command
8145 to be executed and its arguments
8146 (suitable for enclosing white space in an argument),
8148 mapping source file name suffixes to
8149 any combination of command line strings
8150 (if the builder should accept multiple source file extensions),
8153 (see the next section);
8154 or a list of any of the above.
8157 takes three arguments:
8159 - a list of source nodes,
8161 - a list of target nodes,
8163 - the construction environment.
8166 The prefix that will be prepended to the target file name.
8167 This may be specified as a:
8177 - a function or other callable that takes
8178 two arguments (a construction environment and a list of sources)
8179 and returns a prefix,
8184 - specifies a mapping from a specific source suffix (of the first
8185 source specified) to a corresponding target prefix. Both the source
8186 suffix and target prefix specifications may use environment variable
8187 substitution, and the target prefix (the 'value' entries in the
8188 dictionary) may also be a callable object. The default target prefix
8189 may be indicated by a dictionary entry with a key value of None.
8194 b = Builder("build_it < $SOURCE > $TARGET"
8197 def gen_prefix(env, sources):
8198 return "file-" + env['PLATFORM'] + '-'
8199 b = Builder("build_it < $SOURCE > $TARGET",
8200 prefix = gen_prefix)
8202 b = Builder("build_it < $SOURCE > $TARGET",
8203 suffix = { None: "file-",
8204 "$SRC_SFX_A": gen_prefix })
8208 The suffix that will be appended to the target file name.
8209 This may be specified in the same manner as the prefix above.
8210 If the suffix is a string, then
8212 will append a '.' to the beginning of the suffix if it's not already
8213 there. The string returned by callable object (or obtained from the
8214 dictionary) is untouched and must append its own '.' to the beginning
8218 b = Builder("build_it < $SOURCE > $TARGET"
8221 def gen_suffix(env, sources):
8222 return "." + env['PLATFORM'] + "-file"
8223 b = Builder("build_it < $SOURCE > $TARGET",
8224 suffix = gen_suffix)
8226 b = Builder("build_it < $SOURCE > $TARGET",
8227 suffix = { None: ".sfx1",
8228 "$SRC_SFX_A": gen_suffix })
8232 The expected source file name suffix. This may be a string or a list
8236 A Scanner object that
8237 will be invoked to find
8238 implicit dependencies for this target file.
8239 This keyword argument should be used
8240 for Scanner objects that find
8241 implicit dependencies
8242 based only on the target file
8243 and the construction environment,
8246 (See the section "Scanner Objects," below,
8247 for information about creating Scanner objects.)
8250 A Scanner object that
8252 find implicit dependences in
8254 used to build this target file.
8255 This is where you would
8256 specify a scanner to
8259 lines in source files.
8262 Scanner object may be used to
8263 indicate that this Builder
8264 should scan directory trees
8265 for on-disk changes to files
8268 does not know about from other Builder or function calls.
8269 (See the section "Scanner Objects," below,
8270 for information about creating your own Scanner objects.)
8273 A factory function that the Builder will use
8274 to turn any targets specified as strings into SCons Nodes.
8276 SCons assumes that all targets are files.
8277 Other useful target_factory
8280 for when a Builder creates a directory target,
8283 for when a Builder can create either a file
8284 or directory target.
8289 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8291 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8292 env.MakeDirectory('new_directory', [])
8295 Note that the call to the MakeDirectory Builder
8296 needs to specify an empty source list
8297 to make the string represent the builder's target;
8298 without that, it would assume the argument is the source,
8299 and would try to deduce the target name from it,
8300 which in the absence of an automatically-added prefix or suffix
8301 would lead to a matching target and source name
8302 and a circular dependency.
8305 A factory function that the Builder will use
8306 to turn any sources specified as strings into SCons Nodes.
8308 SCons assumes that all source are files.
8309 Other useful source_factory
8312 for when a Builder uses a directory as a source,
8315 for when a Builder can use files
8316 or directories (or both) as sources.
8321 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8323 env.Append(BUILDERS = {'Collect':CollectBuilder})
8324 env.Collect('archive', ['directory_name', 'file_name'])
8328 A function or list of functions to manipulate the target and source
8329 lists before dependencies are established
8330 and the target(s) are actually built.
8332 can also be a string containing a construction variable to expand
8333 to an emitter function or list of functions,
8334 or a dictionary mapping source file suffixes
8335 to emitter functions.
8336 (Only the suffix of the first source file
8337 is used to select the actual emitter function
8338 from an emitter dictionary.)
8341 takes three arguments:
8343 - a list of source nodes,
8345 - a list of target nodes,
8347 - the construction environment.
8348 An emitter must return a tuple containing two lists,
8349 the list of targets to be built by this builder,
8350 and the list of sources for this builder.
8355 def e(target, source, env):
8356 return (target + ['foo.foo'], source + ['foo.src'])
8358 # Simple association of an emitter function with a Builder.
8359 b = Builder("my_build < $TARGET > $SOURCE",
8362 def e2(target, source, env):
8363 return (target + ['bar.foo'], source + ['bar.src'])
8365 # Simple association of a list of emitter functions with a Builder.
8366 b = Builder("my_build < $TARGET > $SOURCE",
8369 # Calling an emitter function through a construction variable.
8370 env = Environment(MY_EMITTER = e)
8371 b = Builder("my_build < $TARGET > $SOURCE",
8372 emitter = '$MY_EMITTER')
8374 # Calling a list of emitter functions through a construction variable.
8375 env = Environment(EMITTER_LIST = [e, e2])
8376 b = Builder("my_build < $TARGET > $SOURCE",
8377 emitter = '$EMITTER_LIST')
8379 # Associating multiple emitters with different file
8380 # suffixes using a dictionary.
8381 def e_suf1(target, source, env):
8382 return (target + ['another_target_file'], source)
8383 def e_suf2(target, source, env):
8384 return (target, source + ['another_source_file'])
8385 b = Builder("my_build < $TARGET > $SOURCE",
8386 emitter = {'.suf1' : e_suf1,
8391 Specifies whether this builder is allowed to be called multiple times for
8392 the same target file(s). The default is 0, which means the builder
8393 can not be called multiple times for the same target file(s). Calling a
8394 builder multiple times for the same target simply adds additional source
8395 files to the target; it is not allowed to change the environment associated
8396 with the target, specify addition environment overrides, or associate a different
8397 builder with the target.
8400 A construction environment that can be used
8401 to fetch source code using this Builder.
8402 (Note that this environment is
8404 used for normal builds of normal target files,
8405 which use the environment that was
8406 used to call the Builder for the target file.)
8409 A function that returns a list of actions that will be executed to build
8410 the target(s) from the source(s).
8411 The returned action(s) may be
8412 an Action object, or anything that
8413 can be converted into an Action object
8414 (see the next section).
8416 The generator function
8417 takes four arguments:
8419 - a list of source nodes,
8421 - a list of target nodes,
8423 - the construction environment,
8425 - a Boolean value that specifies
8426 whether the generator is being called
8427 for generating a build signature
8428 (as opposed to actually executing the command).
8432 def g(source, target, env, for_signature):
8433 return [["gcc", "-c", "-o"] + target + source]
8435 b = Builder(generator=g)
8443 arguments must not both be used for the same Builder.
8446 Specifies a builder to use when a source file name suffix does not match
8447 any of the suffixes of the builder. Using this argument produces a
8448 multi-stage builder.
8451 Specifies that this builder expects exactly one source file per call. Giving
8452 more than one source files without target files results in implicitely calling
8453 the builder multiple times (once for each source given). Giving multiple
8454 source files together with target files results in a UserError exception.
8462 arguments must not both be used for the same Builder.
8465 A construction environment that can be used
8466 to fetch source code using this Builder.
8467 (Note that this environment is
8469 used for normal builds of normal target files,
8470 which use the environment that was
8471 used to call the Builder for the target file.)
8474 b = Builder(action="build < $SOURCE > $TARGET")
8475 env = Environment(BUILDERS = {'MyBuild' : b})
8476 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8480 A directory from which scons
8487 a string or a directory Node,
8488 scons will change to the specified directory.
8491 is not a string or Node
8493 then scons will change to the
8494 target file's directory.
8496 Note that scons will
8498 automatically modify
8500 construction variables like
8504 when using the chdir
8505 keyword argument--that is,
8506 the expanded file names
8507 will still be relative to
8508 the top-level SConstruct directory,
8509 and consequently incorrect
8510 relative to the chdir directory.
8511 Builders created using chdir keyword argument,
8512 will need to use construction variable
8517 to use just the filename portion of the
8521 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8523 env = Environment(BUILDERS = {'MyBuild' : b})
8524 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8528 Any additional keyword arguments supplied
8529 when a Builder object is created
8530 (that is, when the Builder() function is called)
8531 will be set in the executing construction
8532 environment when the Builder object is called.
8533 The canonical example here would be
8534 to set a construction variable to
8535 the repository of a source code system.
8537 Any additional keyword arguments supplied
8541 will only be associated with the target
8542 created by that particular Builder call
8543 (and any other files built as a
8544 result of the call).
8546 These extra keyword arguments are passed to the
8547 following functions:
8548 command generator functions,
8550 and emitter functions.
8556 function will turn its
8558 keyword argument into an appropriate
8559 internal Action object.
8560 You can also explicity create Action objects
8564 which can then be passed to the
8567 This can be used to configure
8568 an Action object more flexibly,
8569 or it may simply be more efficient
8570 than letting each separate Builder object
8571 create a separate Action
8573 Builder objects need to do the same thing.
8578 returns an appropriate object for the action
8579 represented by the type of the first argument:
8582 If the first argument is already an Action object,
8583 the object is simply returned.
8586 If the first argument is a string,
8587 a command-line Action is returned.
8590 Action('$CC -c -o $TARGET $SOURCES')
8593 .\" XXX From Gary Ruben, 23 April 2002:
8594 .\" What would be useful is a discussion of how you execute command
8595 .\" shell commands ie. what is the process used to spawn the shell, pass
8596 .\" environment variables to it etc., whether there is one shell per
8597 .\" environment or one per command etc. It might help to look at the Gnu
8598 .\" make documentation to see what they think is important to discuss about
8599 .\" a build system. I'm sure you can do a better job of organising the
8600 .\" documentation than they have :-)
8604 If the first argument is a list,
8605 then a list of Action objects is returned.
8606 An Action object is created as necessary
8607 for each element in the list.
8610 the list is itself a list,
8611 the internal list is the
8612 command and arguments to be executed via
8614 This allows white space to be enclosed
8615 in an argument by defining
8616 a command in a list within a list:
8619 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8623 If the first argument is a Python function,
8624 a function Action is returned.
8625 The Python function takes three keyword arguments,
8627 (a Node object representing the target file),
8629 (a Node object representing the source file)
8632 (the construction environment
8633 used for building the target file).
8638 arguments may be lists of Node objects if there is
8639 more than one target file or source file.
8640 The actual target and source file name(s) may
8641 be retrieved from their Node objects
8642 via the built-in Python str() function:
8645 target_file_name = str(target)
8646 source_file_names = map(lambda x: str(x), source)
8649 The function should return
8653 to indicate a successful build of the target file(s).
8654 The function may raise an exception
8655 or return a non-zero exit status
8656 to indicate an unsuccessful build.
8659 def build_it(target = None, source = None, env = None):
8660 # build the target from the source
8663 a = Action(build_it)
8666 If the action argument is not one of the above,
8669 The second, optional argument
8670 is a Python function that returns
8671 a string to be printed to describe the action being executed.
8672 Like a function to build a file,
8673 this function takes three arguments:
8675 (a Node object representing the target file),
8677 (a Node object representing the source file)
8680 (a construction environment).
8685 arguments may be lists of Node objects if there is
8686 more than one target file or source file.
8690 def build_it(target, source, env):
8691 # build the target from the source
8694 def string_it(target, source, env):
8695 return "building '%s' from '%s'" % (target[0], source[0])
8697 # Use a positional argument.
8698 a = Action(build_it, string_it)
8700 # Alternatively, use a keyword argument.
8701 a = Action(build_it, strfunction=string_it)
8704 The third, also optional argument
8705 is a list of construction variables
8706 whose values will be included
8707 in the signature of the Action
8708 when deciding whether a target should
8709 be rebuilt because the action changed.
8710 This is necessary whenever you want a target to
8711 be rebuilt when a specific
8712 construction variable changes,
8713 because the underlying Python code for a function
8714 will not change when the value of the construction variable does.
8717 def build_it(target, source, env):
8718 # build the target from the 'XXX' construction variable
8719 open(target[0], 'w').write(env['XXX'])
8722 def string_it(target, source):
8723 return "building '%s' from '%s'" % (target[0], source[0])
8725 # Use positional arguments.
8726 a = Action(build_it, string_it, ['XXX'])
8728 # Alternatively, use a keyword argument.
8729 a = Action(build_it, varlist=['XXX'])
8739 which specifies that
8740 scons will execute the action
8741 after changing to the specified directory.
8742 If the chdir argument is
8743 a string or a directory Node,
8744 scons will change to the specified directory.
8745 If the chdir argument
8746 is not a string or Node
8748 then scons will change to the
8749 target file's directory.
8751 Note that scons will
8753 automatically modify
8755 construction variables like
8759 when using the chdir
8760 keyword argument--that is,
8761 the expanded file names
8762 will still be relative to
8763 the top-level SConstruct directory,
8764 and consequently incorrect
8765 relative to the chdir directory.
8766 Builders created using chdir keyword argument,
8767 will need to use construction variable
8772 to use just the filename portion of the
8776 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8780 .SS Miscellaneous Action Functions
8783 supplies a number of functions
8784 that arrange for various common
8785 file and directory manipulations
8787 These are similar in concept to "tasks" in the
8789 although the implementation is slightly different.
8790 These functions do not actually
8791 perform the specified action
8792 at the time the function is called,
8793 but instead return an Action object
8794 that can be executed at the
8796 (In Object-Oriented terminology,
8801 that return Action objects.)
8804 there are two natural ways
8807 are intended to be used.
8811 to perform the action
8812 at the time the SConscript
8816 global function to do so:
8818 Execute(Touch('file'))
8822 you can use these functions
8823 to supply Actions in a list
8827 This can allow you to
8828 perform more complicated
8829 sequences of file manipulation
8831 on platform-specific
8835 env = Environment(TMPBUILD = '/tmp/builddir')
8836 env.Command('foo.out', 'foo.in',
8837 [Mkdir('$TMPBUILD'),
8838 Copy('$TMPBUILD', '${SOURCE.dir}')
8839 "cd $TMPBUILD && make",
8840 Delete('$TMPBUILD')])
8844 .RI Chmod( dest ", " mode )
8845 Returns an Action object that
8846 changes the permissions on the specified
8848 file or directory to the specified
8853 Execute(Chmod('file', 0755))
8855 env.Command('foo.out', 'foo.in',
8856 [Copy('$TARGET', '$SOURCE'),
8857 Chmod('$TARGET', 0755)])
8861 .RI Copy( dest ", " src )
8862 Returns an Action object
8865 source file or directory to the
8867 destination file or directory.
8871 Execute(Copy('foo.output', 'foo.input'))
8873 env.Command('bar.out', 'bar.in',
8874 Copy('$TARGET', '$SOURCE'))
8878 .RI Delete( entry ", [" must_exist ])
8879 Returns an Action that
8880 deletes the specified
8882 which may be a file or a directory tree.
8883 If a directory is specified,
8884 the entire directory tree
8889 then a Python error will be thrown
8890 if the specified entry does not exist;
8893 that is, the Action will silently do nothing
8894 if the entry does not exist.
8898 Execute(Delete('/tmp/buildroot'))
8900 env.Command('foo.out', 'foo.in',
8901 [Delete('${TARGET.dir}'),
8904 Execute(Delete('file_that_must_exist', must_exist=1))
8910 that creates the specified
8916 Execute(Mkdir('/tmp/outputdir'))
8918 env.Command('foo.out', 'foo.in',
8919 [Mkdir('/tmp/builddir',
8920 Copy('$SOURCE', '/tmp/builddir')
8921 "cd /tmp/builddir && ])
8926 .RI Move( dest ", " src )
8928 that moves the specified
8930 file or directory to
8937 Execute(Move('file.destination', 'file.source'))
8939 env.Command('output_file', 'input_file',
8941 Move('$TARGET', 'file_created_by_MyBuildAction')])
8947 that updates the modification time
8953 Execute(Touch('file_to_be_touched'))
8955 env.Command('marker', 'input_file',
8960 .SS Variable Substitution
8962 Before executing a command,
8964 performs construction variable interpolation on the strings that make up
8965 the command line of builders.
8966 Variables are introduced by a
8969 Besides construction variables, scons provides the following
8970 variables for each command execution:
8973 The file name of the target being built, or the file name of the first
8974 target if multiple targets are being built.
8977 The file names of all targets being built.
8980 The file name of the source of the build command, or the file name of the
8981 first source if multiple sources are being built.
8984 The file names of the sources of the build command.
8986 (Note that the above variables are reserved
8987 and may not be set in a construction environment.)
8990 For example, given the construction variable CC='cc', targets=['foo'], and
8991 sources=['foo.c', 'bar.c']:
8994 action='$CC -c -o $TARGET $SOURCES'
8997 would produce the command line:
9000 cc -c -o foo foo.c bar.c
9003 Variable names may be surrounded by curly braces ({})
9004 to separate the name from the trailing characters.
9005 Within the curly braces, a variable name may have
9006 a Python slice subscript appended to select one
9007 or more items from a list.
9008 In the previous example, the string:
9020 Additionally, a variable name may
9021 have the following special
9022 modifiers appended within the enclosing curly braces
9023 to modify the interpolated string:
9026 The base path of the file name,
9027 including the directory path
9028 but excluding any suffix.
9031 The name of the directory in which the file exists.
9035 minus any directory portion.
9038 Just the basename of the file,
9040 and minus the directory.
9043 Just the file suffix.
9046 The absolute path name of the file.
9049 The POSIX form of the path,
9050 with directories separated by
9054 This is sometimes necessary on Win32 systems
9055 when a path references a file on other (POSIX) systems.
9058 The directory and file name to the source file linked to this file
9059 through BuildDir. If this file isn't linked, it just returns the
9060 directory and filename unchanged.
9063 The directory containing the source file linked to this file
9064 through BuildDir. If this file isn't linked, it just returns the
9065 directory part of the filename.
9068 The directory and file name to the source file linked to this file
9069 through BuildDir. If the file does not exist locally but exists in
9070 a Repository, the path in the Repository is returned.
9071 If this file isn't linked, it just returns the
9072 directory and filename unchanged.
9075 The Repository directory containing the source file linked to this file
9076 through BuildDir. If this file isn't linked, it just returns the
9077 directory part of the filename.
9080 For example, the specified target will
9081 expand as follows for the corresponding modifiers:
9084 $TARGET => sub/dir/file.x
9085 ${TARGET.base} => sub/dir/file
9086 ${TARGET.dir} => sub/dir
9087 ${TARGET.file} => file.x
9088 ${TARGET.filebase} => file
9089 ${TARGET.suffix} => .x
9090 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9092 SConscript('src/SConscript', build_dir='sub/dir')
9093 $SOURCE => sub/dir/file.x
9094 ${SOURCE.srcpath} => src/file.x
9095 ${SOURCE.srcdir} => src
9097 Repository('/usr/repository')
9098 $SOURCE => sub/dir/file.x
9099 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9100 ${SOURCE.rsrcdir} => /usr/repository/src
9103 Lastly, a variable name
9104 may be a callable Python function
9106 construction variable in the environment.
9108 take four arguments:
9110 - a list of target nodes,
9112 - a list of source nodes,
9114 - the construction environment,
9116 - a Boolean value that specifies
9117 whether the function is being called
9118 for generating a build signature.
9119 SCons will insert whatever
9120 the called function returns
9121 into the expanded string:
9124 def foo(target, source, env, for_signature):
9127 # Will expand $BAR to "bar baz"
9128 env=Environment(FOO=foo, BAR="$FOO baz")
9131 You can use this feature to pass arguments to a
9132 Python function by creating a callable class
9133 that stores one or more arguments in an object,
9134 and then uses them when the
9137 Note that in this case,
9138 the entire variable expansion must
9139 be enclosed by curly braces
9140 so that the arguments will
9141 be associated with the
9142 instantiation of the class:
9146 def __init__(self, arg):
9149 def __call__(self, target, source, env, for_signature):
9152 # Will expand $BAR to "my argument bar baz"
9153 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9157 The special pseudo-variables
9161 may be used to surround parts of a command line
9164 causing a rebuild--that is,
9165 which are not included in the signature
9166 of target files built with this command.
9171 will be removed from the command line
9172 before it is added to file signatures,
9177 will be removed before the command is executed.
9178 For example, the command line:
9181 echo Last build occurred $( $TODAY $). > $TARGET
9185 would execute the command:
9188 echo Last build occurred $TODAY. > $TARGET
9192 but the command signature added to any target files would be:
9195 echo Last build occurred . > $TARGET
9198 SCons uses the following rules when converting construction variables into
9202 When the value is a string it is interpreted as a space delimited list of
9203 command line arguments.
9206 When the value is a list it is interpreted as a list of command line
9207 arguments. Each element of the list is converted to a string.
9210 Anything that is not a list or string is converted to a string and
9211 interpreted as a single command line argument.
9214 Newline characters (\\n) delimit lines. The newline parsing is done after
9215 all other parsing, so it is not possible for arguments (e.g. file names) to
9216 contain embedded newline characters. This limitation will likely go away in
9217 a future version of SCons.
9225 new file types for implicit dependencies.
9226 Scanner accepts the following arguments:
9229 A Python function that will process
9231 and return a list of strings (file names)
9232 representing the implicit
9233 dependencies found in the contents.
9234 The function takes three or four arguments:
9236 def scanner_function(node, env, path):
9238 def scanner_function(node, env, path, arg):
9242 argument is the internal
9243 SCons node representing the file.
9246 to fetch the name of the file, and
9247 .B node.get_contents()
9248 to fetch contents of the file.
9252 argument is the construction environment for the scan.
9253 Fetch values from it using the
9259 argument is a tuple (or list)
9260 of directories that can be searched
9262 This will usually be the tuple returned by the
9264 argument (see below).
9268 argument is the argument supplied
9269 when the scanner was created, if any.
9272 The name of the Scanner.
9274 to identify the Scanner internally.
9277 An optional argument that, if specified,
9278 will be passed to the scanner function
9280 and the path function
9284 An optional list that can be used to
9285 determine which scanner should be used for
9287 In the usual case of scanning for file names,
9288 this argument will be a list of suffixes
9289 for the different file types that this
9290 Scanner knows how to scan.
9291 If the argument is a string,
9292 then it will be expanded
9293 into a list by the current environment.
9296 A Python function that takes
9297 two or three arguments:
9298 a construction environment, directory Node,
9299 and optional argument supplied
9300 when the scanner was created.
9303 returns a tuple of directories
9304 that can be searched for files to be returned
9305 by this Scanner object.
9308 The class of Node that should be returned
9309 by this Scanner object.
9310 Any strings or other objects returned
9311 by the scanner function
9312 that are not of this class
9313 will be run through the
9318 A Python function that will take a string
9320 and turn it into the appropriate class of Node
9321 to be returned by this Scanner object.
9324 An optional Python function that takes two arguments,
9325 a Node (file) and a construction environment,
9326 and returns whether the
9327 Node should, in fact,
9328 be scanned for dependencies.
9329 This check can be used to eliminate unnecessary
9330 calls to the scanner function when,
9331 for example, the underlying file
9332 represented by a Node does not yet exist.
9335 An optional flag that
9336 specifies whether this scanner should be re-invoked
9337 on the dependency files returned by the scanner.
9338 When this flag is not set,
9339 the Node subsystem will
9340 only invoke the scanner on the file being scanned,
9341 and not (for example) also on the files
9342 specified by the #include lines
9343 in the file being scanned.
9345 may be a callable function,
9346 in which case it will be called with a list of
9348 should return a list of Nodes
9349 that should be scanned recursively;
9350 this can be used to select a specific subset of
9351 Nodes for additional scanning.
9356 .B SourceFileScanner
9357 object that is used by
9360 .BR SharedObject (),
9364 which scanner should be used
9365 for different file extensions.
9367 .BR SourceFileScanner.add_scanner ()
9368 method to add your own Scanner object
9372 that builds target programs or
9373 libraries from a list of
9374 source files of different types:
9377 def xyz_scan(node, env, path):
9378 contents = node.get_contents()
9379 # Scan the contents and return the included files.
9381 XYZScanner = Scanner(xyz_scan)
9383 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9385 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9388 .SH SYSTEM-SPECIFIC BEHAVIOR
9389 SCons and its configuration files are very portable,
9390 due largely to its implementation in Python.
9391 There are, however, a few portability
9392 issues waiting to trap the unwary.
9394 SCons handles the upper-case
9396 file suffix differently,
9397 depending on the capabilities of
9398 the underlying system.
9399 On a case-sensitive system
9400 such as Linux or UNIX,
9401 SCons treats a file with a
9403 suffix as a C++ source file.
9404 On a case-insensitive system
9406 SCons treats a file with a
9408 suffix as a C source file.
9410 SCons handles the upper-case
9412 file suffix differently,
9413 depending on the capabilities of
9414 the underlying system.
9415 On a case-sensitive system
9416 such as Linux or UNIX,
9417 SCons treats a file with a
9419 suffix as a Fortran source file
9420 that is to be first run through
9421 the standard C preprocessor.
9422 On a case-insensitive system
9424 SCons treats a file with a
9426 suffix as a Fortran source file that should
9428 be run through the C preprocessor.
9429 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9430 Cygwin supplies a set of tools and utilities
9431 that let users work on a
9432 Windows system using a more POSIX-like environment.
9433 The Cygwin tools, including Cygwin Python,
9435 by sharing an ability to interpret UNIX-like path names.
9436 For example, the Cygwin tools
9437 will internally translate a Cygwin path name
9438 like /cygdrive/c/mydir
9439 to an equivalent Windows pathname
9440 of C:/mydir (equivalent to C:\\mydir).
9443 that are built for native Windows execution,
9444 such as the python.org and ActiveState versions,
9445 do not have the Cygwin path name semantics.
9446 This means that using a native Windows version of Python
9447 to build compiled programs using Cygwin tools
9448 (such as gcc, bison, and flex)
9449 may yield unpredictable results.
9450 "Mixing and matching" in this way
9451 can be made to work,
9452 but it requires careful attention to the use of path names
9453 in your SConscript files.
9455 In practice, users can sidestep
9456 the issue by adopting the following rules:
9458 use the Cygwin-supplied Python interpreter
9460 when using Microsoft Visual C/C++
9461 (or some other Windows compiler)
9462 use the python.org or ActiveState version of Python
9464 .SS WIN32: scons.bat file
9466 SCons is executed via a wrapper
9469 This has (at least) two ramifications:
9471 First, Windows command-line users
9472 that want to use variable assignment
9474 may have to put double quotes
9475 around the assignments:
9478 scons "FOO=BAR" "BAZ=BLEH"
9481 Second, the Cygwin shell does not
9482 recognize this file as being the same
9485 command issued at the command-line prompt.
9486 You can work around this either by
9489 from the Cygwin command line,
9490 or by creating a wrapper shell
9496 The MinGW bin directory must be in your PATH environment variable or the
9497 PATH variable under the ENV construction variable for SCons
9498 to detect and use the MinGW tools. When running under the native Windows
9499 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9500 tools, if they are both installed, regardless of the order of the bin
9501 directories in the PATH variable. If you have both MSVC and MinGW
9502 installed and you want to use MinGW instead of MSVC,
9503 then you must explictly tell SCons to use MinGW by passing
9509 to the Environment() function, because SCons will prefer the MSVC tools
9510 over the MinGW tools.
9514 To help you get started using SCons,
9515 this section contains a brief overview of some common tasks.
9517 .SS Basic Compilation From a Single Source File
9521 env.Program(target = 'foo', source = 'foo.c')
9524 Note: Build the file by specifying
9525 the target as an argument
9526 ("scons foo" or "scons foo.exe").
9527 or by specifying a dot ("scons .").
9529 .SS Basic Compilation From Multiple Source Files
9533 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9536 .SS Setting a Compilation Flag
9539 env = Environment(CCFLAGS = '-g')
9540 env.Program(target = 'foo', source = 'foo.c')
9543 .SS Search The Local Directory For .h Files
9547 need to set CCFLAGS to specify -I options by hand.
9548 SCons will construct the right -I options from CPPPATH.
9551 env = Environment(CPPPATH = ['.'])
9552 env.Program(target = 'foo', source = 'foo.c')
9555 .SS Search Multiple Directories For .h Files
9558 env = Environment(CPPPATH = ['include1', 'include2'])
9559 env.Program(target = 'foo', source = 'foo.c')
9562 .SS Building a Static Library
9566 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9567 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9570 .SS Building a Shared Library
9574 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9575 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9578 .SS Linking a Local Library Into a Program
9581 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9582 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9583 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9586 .SS Defining Your Own Builder Object
9588 Notice that when you invoke the Builder,
9589 you can leave off the target file suffix,
9590 and SCons will add it automatically.
9593 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9595 src_suffix = '.tex')
9596 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9597 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9599 # The following creates "bar.pdf" from "bar.tex"
9600 env.PDFBuilder(target = 'bar', source = 'bar')
9603 Note also that the above initialization
9604 overwrites the default Builder objects,
9605 so the Environment created above
9606 can not be used call Builders like env.Program(),
9607 env.Object(), env.StaticLibrary(), etc.
9609 .SS Adding Your Own Builder Object to an Environment
9612 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9614 src_suffix = '.tex')
9616 env.Append(BUILDERS = {'PDFBuilder' : bld})
9617 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9618 env.Program(target = 'bar', source = 'bar.c')
9621 You also can use other Pythonic techniques to add
9622 to the BUILDERS construction variable, such as:
9626 env['BUILDERS]['PDFBuilder'] = bld
9629 .SS Defining Your Own Scanner Object
9634 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9636 def kfile_scan(node, env, path, arg):
9637 contents = node.get_contents()
9638 includes = include_re.findall(contents)
9641 kscan = Scanner(name = 'kfile',
9642 function = kfile_scan,
9645 scanners = Environment().Dictionary('SCANNERS')
9646 env = Environment(SCANNERS = scanners + [kscan])
9648 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9650 bar_in = File('bar.in')
9651 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9652 bar_in.target_scanner = kscan
9655 .SS Creating a Hierarchical Build
9657 Notice that the file names specified in a subdirectory's
9659 file are relative to that subdirectory.
9665 env.Program(target = 'foo', source = 'foo.c')
9667 SConscript('sub/SConscript')
9672 # Builds sub/foo from sub/foo.c
9673 env.Program(target = 'foo', source = 'foo.c')
9675 SConscript('dir/SConscript')
9680 # Builds sub/dir/foo from sub/dir/foo.c
9681 env.Program(target = 'foo', source = 'foo.c')
9684 .SS Sharing Variables Between SConscript Files
9686 You must explicitly Export() and Import() variables that
9687 you want to share between SConscript files.
9693 env.Program(target = 'foo', source = 'foo.c')
9696 SConscript('subdirectory/SConscript')
9698 subdirectory/SConscript:
9701 env.Program(target = 'foo', source = 'foo.c')
9704 .SS Building Multiple Variants From the Same Source
9706 Use the build_dir keyword argument to
9707 the SConscript function to establish
9708 one or more separate build directories for
9709 a given source directory:
9714 cppdefines = ['FOO']
9715 Export("cppdefines")
9716 SConscript('src/SConscript', build_dir='foo')
9718 cppdefines = ['BAR']
9719 Export("cppdefines")
9720 SConscript('src/SConscript', build_dir='bar')
9724 Import("cppdefines")
9725 env = Environment(CPPDEFINES = cppdefines)
9726 env.Program(target = 'src', source = 'src.c')
9729 Note the use of the Export() method
9730 to set the "cppdefines" variable to a different
9731 value each time we call the SConscript function.
9733 .SS Hierarchical Build of Two Libraries Linked With a Program
9738 env = Environment(LIBPATH = ['#libA', '#libB'])
9740 SConscript('libA/SConscript')
9741 SConscript('libB/SConscript')
9742 SConscript('Main/SConscript')
9747 env.Library('a', Split('a1.c a2.c a3.c'))
9752 env.Library('b', Split('b1.c b2.c b3.c'))
9757 e = env.Copy(LIBS = ['a', 'b'])
9758 e.Program('foo', Split('m1.c m2.c m3.c'))
9761 The '#' in the LIBPATH directories specify that they're relative to the
9762 top-level directory, so they don't turn into "Main/libA" when they're
9763 used in Main/SConscript.
9765 Specifying only 'a' and 'b' for the library names
9766 allows SCons to append the appropriate library
9767 prefix and suffix for the current platform
9768 (for example, 'liba.a' on POSIX systems,
9769 'a.lib' on Windows).
9771 .SS Customizing contruction variables from the command line.
9773 The following would allow the C compiler to be specified on the command
9774 line or in the file custom.py.
9777 opts = Options('custom.py')
9778 opts.Add('CC', 'The C compiler.')
9779 env = Environment(options=opts)
9780 Help(opts.GenerateHelpText(env))
9783 The user could specify the C compiler on the command line:
9789 or in the custom.py file:
9795 or get documentation on the options:
9806 .SS Using Microsoft Visual C++ precompiled headers
9808 Since windows.h includes everything and the kitchen sink, it can take quite
9809 some time to compile it over and over again for a bunch of object files, so
9810 Microsoft provides a mechanism to compile a set of headers once and then
9811 include the previously compiled headers in any object file. This
9812 technology is called precompiled headers. The general recipe is to create a
9813 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9814 then include every header you want to precompile in "StdAfx.h", and finally
9815 include "StdAfx.h" as the first header in all the source files you are
9816 compiling to object files. For example:
9820 #include <windows.h>
9821 #include <my_big_header.h>
9840 /* do some other stuff */
9846 env['PCHSTOP'] = 'StdAfx.h'
9847 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9848 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9851 For more information see the document for the PCH builder, and the PCH and
9852 PCHSTOP construction variables. To learn about the details of precompiled
9853 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9855 .SS Using Microsoft Visual C++ external debugging information
9857 Since including debugging information in programs and shared libraries can
9858 cause their size to increase significantly, Microsoft provides a mechanism
9859 for including the debugging information in an external file called a PDB
9860 file. SCons supports PDB files through the PDB construction
9866 env['PDB'] = 'MyApp.pdb'
9867 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9870 For more information see the document for the PDB construction variable.
9875 Specifies the directory that contains the SCons Python module directory
9876 (e.g. /home/aroach/scons-src-0.01/src/engine).
9879 A string of options that will be used by scons in addition to those passed
9880 on the command line.
9891 Steven Knight <knight@baldmt.com>
9893 Anthony Roach <aroach@electriceyeball.com>