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 "October 2004"
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.
1027 The elements of the tools list may also
1028 be functions or callable objects,
1029 in which case the Environment() method
1030 will call the specified elements
1031 to update the new construction environment:
1035 env['XYZZY'] = 'xyzzy'
1037 env = Environment(tools = [my_tool])
1040 The individual elements of the tools list
1041 may also themselves be two-element lists of the form
1042 .RI ( toolname ", " kw_dict ).
1043 SCons searches for the
1045 specification file as described above, and
1048 which must be a dictionary, as keyword arguments to the tool's
1053 function can use the arguments to modify the tool's behavior
1054 by setting up the environment in different ways
1055 or otherwise changing its initialization.
1058 # in tools/my_tool.py:
1059 def generate(env, **kw):
1060 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1061 env['MY_TOOL'] = kw.get('arg1', '1')
1066 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1070 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1071 the environment it receives to customize the tool for different platforms.
1073 If no tool list is specified, then SCons will auto-detect the installed
1074 tools using the PATH variable in the ENV construction variable and the
1075 platform name when the Environment is constructed. Changing the PATH
1076 variable after the Environment is constructed will not cause the tools to
1079 SCons supports the following tool specifications out of the box:
1155 Additionally, there is a "tool" named
1157 which configures the
1158 environment with a default set of tools for the current platform.
1160 On posix and cygwin platforms
1161 the GNU tools (e.g. gcc) are preferred by SCons,
1162 on win32 the Microsoft tools (e.g. msvc)
1163 followed by MinGW are preferred by SCons,
1164 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1168 Build rules are specified by calling a construction
1169 environment's builder methods.
1170 The arguments to the builder methods are
1172 (a list of target files)
1175 (a list of source files).
1177 Because long lists of file names
1178 can lead to a lot of quoting,
1183 and a same-named environment method
1184 that split a single string
1185 into a list, separated on
1186 strings of white-space characters.
1187 (These are similar to the
1188 string.split() method
1189 from the standard Python library,
1190 but work even if the input isn't a string.)
1192 Like all Python arguments,
1193 the target and source arguments to a builder method
1194 can be specified either with or without
1195 the "target" and "source" keywords.
1196 When the keywords are omitted,
1197 the target is first,
1198 followed by the source.
1199 The following are equivalent examples of calling the Program builder method:
1202 env.Program('bar', ['bar.c', 'foo.c'])
1203 env.Program('bar', Split('bar.c foo.c'))
1204 env.Program('bar', env.Split('bar.c foo.c'))
1205 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1206 env.Program(target = 'bar', Split('bar.c foo.c'))
1207 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1208 env.Program('bar', source = string.split('bar.c foo.c'))
1211 When the target shares the same base name
1212 as the source and only the suffix varies,
1213 and if the builder method has a suffix defined for the target file type,
1214 then the target argument may be omitted completely,
1217 will deduce the target file name from
1218 the source file name.
1219 The following examples all build the
1225 (on Windows systems)
1226 from the bar.c source file:
1229 env.Program(target = 'bar', source = 'bar.c')
1230 env.Program('bar', source = 'bar.c')
1231 env.Program(source = 'bar.c')
1232 env.Program('bar.c')
1235 It is possible to override or add construction variables when calling a
1236 builder method by passing additional keyword arguments.
1237 These overridden or added
1238 variables will only be in effect when building the target, so they will not
1239 affect other parts of the build. For example, if you want to add additional
1240 libraries for just one program:
1243 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1246 or generate a shared library with a nonstandard suffix:
1249 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1252 Although the builder methods defined by
1255 methods of a construction environment object,
1256 they may also be called without an explicit environment:
1259 Program('hello', 'hello.c')
1260 SharedLibrary('word', 'word.cpp')
1264 the methods are called internally using a default construction
1265 environment that consists of the tools and values that
1267 has determined are appropriate for the local system.
1269 Builder methods that can be called without an explicit
1270 environment may be called from custom Python modules that you
1271 import into an SConscript file by adding the following
1272 to the Python module:
1275 from SCons.Script import *
1278 All builder methods return a list of Nodes
1279 that represent the target or targets that will be built.
1282 is an internal SCons object
1284 build targets or sources.
1286 The returned Node(s)
1287 can be passed to other builder methods as source(s)
1288 or passed to any SCons function or method
1289 where a filename would normally be accepted.
1290 For example, if it were necessary
1293 flag when compiling one specific object file:
1296 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1297 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1300 Using a Node in this way
1301 makes for a more portable build
1302 by avoiding having to specify
1303 a platform-specific object suffix
1304 when calling the Program() builder method.
1306 Note that Builder calls will automatically "flatten"
1307 the source and target file lists,
1308 so it's all right to have the bar_obj list
1309 return by the StaticObject() call
1310 in the middle of the source file list.
1311 If you need to manipulate a list of lists returned by Builders
1312 directly using Python,
1313 you can either build the list by hand:
1316 foo = Object('foo.c')
1317 bar = Object('bar.c')
1318 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1319 for object in objects:
1326 to create a list containing just the Nodes,
1327 which may be more convenient:
1330 foo = Object('foo.c')
1331 bar = Object('bar.c')
1332 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1333 for object in objects:
1337 The path name for a Node's file may be used
1338 by passing the Node to the Python-builtin
1343 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1344 print "The path to bar_obj is:", str(bar_obj_list[0])
1347 Note again that because the Builder call returns a list,
1348 we have to access the first element in the list
1349 .B (bar_obj_list[0])
1350 to get at the Node that actually represents
1353 Builder calls support a
1355 keyword argument that
1356 specifies that the Builder's action(s)
1358 after changing directory.
1362 a string or a directory Node,
1363 scons will change to the specified directory.
1366 is not a string or Node
1368 then scons will change to the
1369 target file's directory.
1372 # scons will change to the "sub" subdirectory
1373 # before executing the "cp" command.
1374 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1375 "cp dir/foo.in dir/foo.out",
1378 # Because chdir is not a string, scons will change to the
1379 # target's directory ("sub/dir") before executing the
1381 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1382 "cp foo.in foo.out",
1386 Note that scons will
1388 automatically modify
1390 construction variables like
1394 when using the chdir
1395 keyword argument--that is,
1396 the expanded file names
1397 will still be relative to
1398 the top-level SConstruct directory,
1399 and consequently incorrect
1400 relative to the chdir directory.
1401 If you use the chdir keyword argument,
1402 you will typically need to supply a different
1408 to use just the filename portion of the
1412 provides the following builder methods:
1414 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1417 Builds a C source file given a lex (.l) or yacc (.y) input file.
1418 The suffix specified by the $CFILESUFFIX construction variable
1420 is automatically added to the target
1421 if it is not already present. Example:
1425 env.CFile(target = 'foo.c', source = 'foo.l')
1427 env.CFile(target = 'bar', source = 'bar.y')
1430 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1433 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1435 The suffix specified by the $CXXFILESUFFIX construction variable
1437 is automatically added to the target
1438 if it is not already present. Example:
1442 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1444 env.CXXFile(target = 'bar', source = 'bar.yy')
1447 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1450 Builds a .dvi file from a .tex, .ltx or .latex input file.
1451 If the source file suffix is .tex,
1453 will examine the contents of the file;
1458 is found, the file is assumed to be a LaTeX file and
1459 the target is built by invoking the $LATEXCOM command line;
1460 otherwise, the $TEXCOM command line is used.
1461 If the file is a LaTeX file,
1464 builder method will also examine the contents
1467 and invoke the $BIBTEX command line
1471 and will examine the contents
1473 file and re-run the $LATEXCOM command
1474 if the log file says it is necessary.
1477 (hard-coded within TeX itself)
1478 is automatically added to the target
1479 if it is not already present. Examples:
1482 # builds from aaa.tex
1483 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1485 env.DVI(target = 'bbb', source = 'bbb.ltx')
1486 # builds from ccc.latex
1487 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1490 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1493 Builds a Java archive (.jar) file
1494 from a source tree of .class files.
1495 If the $JARCHDIR value is set, the
1497 command will change to the specified directory using the
1500 If the contents any of the source files begin with the string
1501 .BR Manifest-Version ,
1502 the file is assumed to be a manifest
1503 and is passed to the
1510 env.Jar(target = 'foo.jar', source = 'classes')
1513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1516 Builds one or more Java class files
1517 from one or more source trees of .java files.
1518 The class files will be placed underneath
1519 the specified target directory.
1520 SCons will parse each source .java file
1522 (including inner classes)
1523 defined within that file,
1524 and from that figure out the
1525 target .class files that will be created.
1526 SCons will also search each Java file
1527 for the Java package name,
1528 which it assumes can be found on a line
1529 beginning with the string
1531 in the first column;
1532 the resulting .class files
1533 will be placed in a directory reflecting
1534 the specified package name.
1538 defining a single public
1541 containing a package name of
1543 will generate a corresponding
1544 .IR sub/dir/Foo.class
1550 env.Java(target = 'classes', source = 'src')
1551 env.Java(target = 'classes', source = ['src1', 'src2'])
1554 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1557 Builds C header and source files for
1558 implementing Java native methods.
1559 The target can be either a directory
1560 in which the header files will be written,
1561 or a header file name which
1562 will contain all of the definitions.
1563 The source can be either the names of .class files,
1564 or the objects returned from the
1568 If the construction variable
1570 is set, either in the environment
1571 or in the call to the
1573 builder method itself,
1574 then the value of the variable
1575 will be stripped from the
1576 beginning of any .class file names.
1581 # builds java_native.h
1582 classes = env.Java(target = 'classdir', source = 'src')
1583 env.JavaH(target = 'java_native.h', source = classes)
1585 # builds include/package_foo.h and include/package_bar.h
1586 env.JavaH(target = 'include',
1587 source = ['package/foo.class', 'package/bar.class'])
1589 # builds export/foo.h and export/bar.h
1590 env.JavaH(target = 'export',
1591 source = ['classes/foo.class', 'classes/bar.class'],
1592 JAVACLASSDIR = 'classes')
1595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1602 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1603 .IP LoadableModule()
1604 .IP env.LoadableModule()
1607 .BR SharedLibrary ().
1608 On Mac OS X (Darwin) platforms,
1609 this creates a loadable module bundle.
1612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1615 Builds an output file from an M4 input file.
1616 This uses a default $M4FLAGS value of
1618 which considers all warnings to be fatal
1619 and stops on the first warning
1620 when using the GNU version of m4.
1624 env.M4(target = 'foo.c', source = 'foo.c.m4')
1627 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1630 Builds an output file from a moc input file. Moc input files are either
1631 header files or cxx files. This builder is only available after using the
1632 tool 'qt'. See the QTDIR variable for more information.
1636 env.Moc('foo.h') # generates moc_foo.cc
1637 env.Moc('foo.cpp') # generates foo.moc
1640 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1642 .IP env.MSVSProject()
1643 Builds Microsoft Visual Studio project files.
1644 This builds a Visual Studio project file, based on the version of
1645 Visual Studio that is configured (either the latest installed version,
1646 or the version set by
1648 in the Environment constructor).
1649 For VS 6, it will generate
1653 files, for VS 7, it will
1660 It takes several lists of filenames to be placed into the project
1661 file, currently these are limited to
1662 .B srcs, incs, localincs, resources,
1665 These are pretty self explanatory, but it
1666 should be noted that the 'srcs' list is NOT added to the $SOURCES
1667 environment variable. This is because it represents a list of files
1668 to be added to the project file, not the source used to build the
1669 project file (in this case, the 'source' is the SConscript file used
1670 to call MSVSProject).
1672 In addition to these values (which are all optional, although not
1673 specifying any of them results in an empty project file), the
1674 following values must be specified:
1676 target: The name of the target .dsp or .vcproj file. The correct
1677 suffix for the version of Visual Studio must be used, but the value
1679 env['MSVSPROJECTSUFFIX']
1681 will be defined to the correct value (see example below).
1683 variant: The name of this particular variant. These are typically
1684 things like "Debug" or "Release", but really can be anything you want.
1685 Multiple calls to MSVSProject with different variants are allowed: all
1686 variants will be added to the project file with their appropriate
1687 build targets and sources.
1689 buildtarget: A list of SCons.Node.FS objects which is returned from
1690 the command which builds the target. This is used to tell SCons what
1691 to build when the 'build' button is pressed inside of the IDE.
1696 barsrcs = ['bar.cpp'],
1697 barincs = ['bar.h'],
1698 barlocalincs = ['StdAfx.h']
1699 barresources = ['bar.rc','resource.h']
1700 barmisc = ['bar_readme.txt']
1702 dll = local.SharedLibrary(target = 'bar.dll',
1705 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1708 localincs = barlocalincs,
1709 resources = barresources,
1712 variant = 'Release')
1715 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1722 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1725 Builds a Microsoft Visual C++ precompiled header.
1726 Calling this builder method
1727 returns a list of two targets: the PCH as the first element, and the object
1728 file as the second element. Normally the object file is ignored.
1729 This builder method is only
1730 provided when Microsoft Visual C++ is being used as the compiler.
1731 The PCH builder method is generally used in
1732 conjuction with the PCH construction variable to force object files to use
1733 the precompiled header:
1736 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1739 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1742 Builds a .pdf file from a .dvi input file
1743 (or, by extension, a .tex, .ltx, or .latex input file).
1744 The suffix specified by the $PDFSUFFIX construction variable
1746 is added automatically to the target
1747 if it is not already present. Example:
1750 # builds from aaa.tex
1751 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1752 # builds bbb.pdf from bbb.dvi
1753 env.PDF(target = 'bbb', source = 'bbb.dvi')
1756 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1758 .IP env.PostScript()
1759 Builds a .ps file from a .dvi input file
1760 (or, by extension, a .tex, .ltx, or .latex input file).
1761 The suffix specified by the $PSSUFFIX construction variable
1763 is added automatically to the target
1764 if it is not already present. Example:
1767 # builds from aaa.tex
1768 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1769 # builds bbb.ps from bbb.dvi
1770 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1773 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1776 Builds an executable given one or more object files
1777 or C, C++, D, or Fortran source files.
1778 If any C, C++, D or Fortran source files are specified,
1779 then they will be automatically
1780 compiled to object files using the
1783 see that builder method's description for
1784 a list of legal source file suffixes
1785 and how they are interpreted.
1786 The target executable file prefix
1787 (specified by the $PROGPREFIX construction variable; nothing by default)
1789 (specified by the $PROGSUFFIX construction variable;
1790 by default, .exe on Windows systems, nothing on POSIX systems)
1791 are automatically added to the target if not already present.
1795 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1798 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1801 Builds a Microsoft Visual C++ resource file.
1802 This builder method is only provided
1803 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1807 for MinGW) suffix is added to the target name if no other suffix is given. The source
1808 file is scanned for implicit dependencies as though it were a C file. Example:
1811 env.RES('resource.rc')
1814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1817 Builds stub and skeleton class files
1819 from Java .class files.
1820 The target is a directory
1821 relative to which the stub
1822 and skeleton class files will be written.
1823 The source can be the names of .class files,
1824 or the objects return from the
1828 If the construction variable
1830 is set, either in the environment
1831 or in the call to the
1833 builder method itself,
1834 then the value of the variable
1835 will be stripped from the
1836 beginning of any .class file names.
1839 classes = env.Java(target = 'classdir', source = 'src')
1840 env.RMIC(target = 'outdir1', source = classes)
1842 env.RMIC(target = 'outdir2',
1843 source = ['package/foo.class', 'package/bar.class'])
1845 env.RMIC(target = 'outdir3',
1846 source = ['classes/foo.class', 'classes/bar.class'],
1847 JAVACLASSDIR = 'classes')
1850 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1852 .IP env.RPCGenClient()
1853 Generates an RPC client stub (_clnt.c) file
1854 from a specified RPC (.x) source file.
1855 Because rpcgen only builds output files
1856 in the local directory,
1857 the command will be executed
1858 in the source file's directory by default.
1861 # Builds src/rpcif_clnt.c
1862 env.RPCGenClient('src/rpcif.x')
1865 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1867 .IP env.RPCGenHeader()
1868 Generates an RPC header (.h) file
1869 from a specified RPC (.x) source file.
1870 Because rpcgen only builds output files
1871 in the local directory,
1872 the command will be executed
1873 in the source file's directory by default.
1876 # Builds src/rpcif.h
1877 env.RPCGenHeader('src/rpcif.x')
1880 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1882 .IP env.RPCGenService()
1883 Generates an RPC server-skeleton (_svc.c) file
1884 from a specified RPC (.x) source file.
1885 Because rpcgen only builds output files
1886 in the local directory,
1887 the command will be executed
1888 in the source file's directory by default.
1891 # Builds src/rpcif_svc.c
1892 env.RPCGenClient('src/rpcif.x')
1895 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1898 Generates an RPC XDR routine (_xdr.c) file
1899 from a specified RPC (.x) source file.
1900 Because rpcgen only builds output files
1901 in the local directory,
1902 the command will be executed
1903 in the source file's directory by default.
1906 # Builds src/rpcif_xdr.c
1907 env.RPCGenClient('src/rpcif.x')
1910 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1912 .IP env.SharedLibrary()
1913 Builds a shared library
1914 (.so on a POSIX system, .dll on WIN32)
1915 given one or more object files
1916 or C, C++, D or Fortran source files.
1917 If any source files are given,
1918 then they will be automatically
1919 compiled to object files.
1920 The static library prefix and suffix (if any)
1921 are automatically added to the target.
1922 The target library file prefix
1923 (specified by the $SHLIBPREFIX construction variable;
1924 by default, lib on POSIX systems, nothing on Windows systems)
1926 (specified by the $SHLIBSUFFIX construction variable;
1927 by default, .dll on Windows systems, .so on POSIX systems)
1928 are automatically added to the target if not already present.
1932 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1935 On WIN32 systems, the
1937 builder method will always build an import (.lib) library
1938 in addition to the shared (.dll) library,
1939 adding a .lib library with the same basename
1940 if there is not already a .lib file explicitly
1941 listed in the targets.
1943 Any object files listed in the
1945 must have been built for a shared library
1950 will raise an error if there is any mismatch.
1952 On WIN32 systems, specifying "register=1" will cause the dll to be
1953 registered after it is built using REGSVR32. The command that is run
1954 ("regsvr32" by default) is determined by $REGSVR construction
1955 variable, and the flags passed are determined by $REGSVRFLAGS. By
1956 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1957 up and requiring user attention when it is run. If you change
1958 $REGSVRFLAGS, be sure to include "/s". For example,
1961 env.SharedLibrary(target = 'bar',
1962 source = ['bar.cxx', 'foo.obj'],
1967 will register "bar.dll" as a COM object when it is done linking it.
1969 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1971 .IP env.SharedObject()
1972 Builds an object file for
1973 inclusion in a shared library.
1974 Source files must have one of the same set of extensions
1975 specified above for the
1978 On some platforms building a shared object requires additional
1979 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1980 normal (static) object, but on some platforms there is no difference between a
1981 shared object and a normal (static) one. When there is a difference, SCons
1982 will only allow shared objects to be linked into a shared library, and will
1983 use a different suffix for shared objects. On platforms where there is no
1984 difference, SCons will allow both normal (static)
1985 and shared objects to be linked into a
1986 shared library, and will use the same suffix for shared and normal
1988 The target object file prefix
1989 (specified by the $SHOBJPREFIX construction variable;
1990 by default, the same as $OBJPREFIX)
1992 (specified by the $SHOBJSUFFIX construction variable)
1993 are automatically added to the target if not already present.
1997 env.SharedObject(target = 'ddd', source = 'ddd.c')
1998 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1999 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2002 Note that the source files will be scanned
2003 according to the suffix mappings in
2004 .B SourceFileScanner
2006 See the section "Scanner Objects,"
2007 below, for a more information.
2009 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2011 .IP env.StaticLibrary()
2012 Builds a static library given one or more object files
2013 or C, C++, D or Fortran source files.
2014 If any source files are given,
2015 then they will be automatically
2016 compiled to object files.
2017 The static library prefix and suffix (if any)
2018 are automatically added to the target.
2019 The target library file prefix
2020 (specified by the $LIBPREFIX construction variable;
2021 by default, lib on POSIX systems, nothing on Windows systems)
2023 (specified by the $LIBSUFFIX construction variable;
2024 by default, .lib on Windows systems, .a on POSIX systems)
2025 are automatically added to the target if not already present.
2029 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2033 Any object files listed in the
2035 must have been built for a static library
2040 will raise an error if there is any mismatch.
2042 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2044 .IP env.StaticObject()
2045 Builds a static object file
2046 from one or more C, C++, D, or Fortran source files.
2047 Source files must have one of the following extensions:
2050 .asm assembly language file
2051 .ASM assembly language file
2063 .F WIN32: Fortran file
2064 POSIX: Fortran file + C pre-processor
2067 .fpp Fortran file + C pre-processor
2068 .FPP Fortran file + C pre-processor
2069 .s assembly language file
2070 .S WIN32: assembly language file
2071 POSIX: assembly language file + C pre-processor
2072 .spp assembly language file + C pre-processor
2073 .SPP assembly language file + C pre-processor
2076 The target object file prefix
2077 (specified by the $OBJPREFIX construction variable; nothing by default)
2079 (specified by the $OBJSUFFIX construction variable;
2080 \.obj on Windows systems, .o on POSIX systems)
2081 are automatically added to the target if not already present.
2085 env.StaticObject(target = 'aaa', source = 'aaa.c')
2086 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2087 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2090 Note that the source files will be scanned
2091 according to the suffix mappings in
2092 .B SourceFileScanner
2094 See the section "Scanner Objects,"
2095 below, for a more information.
2097 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2100 Builds a tar archive of the specified files
2102 Unlike most builder methods,
2105 builder method may be called multiple times
2107 each additional call
2108 adds to the list of entries
2109 that will be built into the archive.
2110 Any source directories will
2111 be scanned for changes to
2113 regardless of whether or not
2115 knows about them from other Builder or function calls.
2118 env.Tar('src.tar', 'src')
2120 # Create the stuff.tar file.
2121 env.Tar('stuff', ['subdir1', 'subdir2'])
2122 # Also add "another" to the stuff.tar file.
2123 env.Tar('stuff', 'another')
2125 # Set TARFLAGS to create a gzip-filtered archive.
2126 env = Environment(TARFLAGS = '-c -z')
2127 env.Tar('foo.tar.gz', 'foo')
2129 # Also set the suffix to .tgz.
2130 env = Environment(TARFLAGS = '-c -z',
2135 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2137 .IP env.TypeLibrary()
2138 Builds a Windows type library (.tlb) file from and input IDL file
2139 (.idl). In addition, it will build the associated inteface stub and
2140 proxy source files. It names them according to the base name of the .idl file.
2145 env.TypeLibrary(source="foo.idl")
2148 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2150 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2153 Builds a header file, an implementation file and a moc file from an ui file.
2154 and returns the corresponding nodes in the above order.
2155 This builder is only available after using the tool 'qt'. Note: you can
2156 specify .ui files directly as inputs for Program, Library and SharedLibrary
2157 without using this builder. Using the builder lets you override the standard
2158 naming conventions (be careful: prefixes are always prepended to names of
2159 built files; if you don't want prefixes, you may set them to ``).
2160 See the QTDIR variable for more information.
2164 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2165 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2166 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2169 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2172 Builds a zip archive of the specified files
2174 Unlike most builder methods,
2177 builder method may be called multiple times
2179 each additional call
2180 adds to the list of entries
2181 that will be built into the archive.
2182 Any source directories will
2183 be scanned for changes to
2185 regardless of whether or not
2187 knows about them from other Builder or function calls.
2190 env.Zip('src.zip', 'src')
2192 # Create the stuff.zip file.
2193 env.Zip('stuff', ['subdir1', 'subdir2'])
2194 # Also add "another" to the stuff.tar file.
2195 env.Zip('stuff', 'another')
2199 targets of builder methods automatically depend on their sources.
2200 An explicit dependency can
2201 be specified using the
2203 method of a construction environment (see below).
2208 source files for various programming languages,
2209 so the dependencies do not need to be specified explicitly.
2210 By default, SCons can
2213 Fortran source files with
2215 (POSIX systems only),
2220 and assembly language files with
2222 (POSIX systems only),
2227 for C preprocessor dependencies.
2228 SCons also has default support
2229 for scanning D source files,
2230 You can also write your own Scanners
2231 to add support for additional source file types.
2232 These can be added to the default
2233 Scanner object used by
2239 Builders by adding them
2241 .B SourceFileScanner
2244 See the section "Scanner Objects,"
2245 below, for a more information about
2246 defining your own Scanner objects.
2248 .SS Methods and Functions to Do Things
2249 In addition to Builder methods,
2251 provides a number of other construction environment methods
2252 and global functions to
2253 manipulate the build configuration.
2255 Usually, a construction environment method
2256 and global function with the same name both exist
2257 so that you don't have to remember whether
2258 to a specific bit of functionality
2259 must be called with or without a construction environment.
2260 In the following list,
2261 if you call something as a global function
2264 .RI Function( arguments )
2266 and if you call something through a construction
2267 environment it looks like:
2269 .RI env.Function( arguments )
2271 If you can call the functionality in both ways,
2272 then both forms are listed.
2274 Global functions may be called from custom Python modules that you
2275 import into an SConscript file by adding the following
2276 to the Python module:
2279 from SCons.Script import *
2282 Except where otherwise noted,
2284 construction environment method
2286 provide the exact same functionality.
2287 The only difference is that,
2289 calling the functionality through a construction environment will
2290 substitute construction variables into
2291 any supplied strings.
2294 env = Environment(FOO = 'foo')
2298 the first call to the global
2300 function will actually add a target named
2302 to the list of default targets,
2303 while the second call to the
2305 construction environment method
2306 will expand the value
2307 and add a target named
2309 to the list of default targets.
2310 For more on construction variable expansion,
2311 see the next section on
2312 construction variables.
2314 Construction environment methods
2315 and global functions supported by
2319 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2321 .RI Action( action ", [" strfunction ", " varlist ])
2323 .RI env.Action( action ", [" strfunction ", " varlist ])
2324 Creates an Action object for
2327 See the section "Action Objects,"
2328 below, for a complete explanation of the arguments and behavior.
2330 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2332 .RI AddPostAction( target ", " action )
2334 .RI env.AddPostAction( target ", " action )
2335 Arranges for the specified
2341 The specified action(s) may be
2342 an Action object, or anything that
2343 can be converted into an Action object
2346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2348 .RI AddPreAction( target ", " action )
2350 .RI env.AddPreAction( target ", " action )
2351 Arranges for the specified
2354 before the specified
2357 The specified action(s) may be
2358 an Action object, or anything that
2359 can be converted into an Action object
2362 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2364 .RI Alias( alias ", [" targets ", [" action ]])
2366 .RI env.Alias( alias ", [" targets ", [" action ]])
2367 Creates one or more phony targets that
2368 expand to one or more other targets.
2373 can be specified that will be executed
2374 whenever the any of the alias targets are out-of-date.
2375 Returns the Node object representing the alias,
2376 which exists outside of any file system.
2377 This Node object, or the alias name,
2378 may be used as a dependency of any other target,
2379 including another alias.
2381 can be called multiple times for the same
2382 alias to add additional targets to the alias,
2383 or additional actions to the list for this alias.
2387 Alias('install', '/usr/bin')
2388 Alias(['install', 'install-lib'], '/usr/local/lib')
2390 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2391 env.Alias('install', ['/usr/local/man'])
2393 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2396 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2398 .RI AlwaysBuild( target ", ...)"
2400 .RI env.AlwaysBuild( target ", ...)"
2403 so that it is always assumed to be out of date,
2404 and will always be rebuilt if needed.
2407 does not add its target(s) to the default target list,
2408 so the targets will only be built
2409 if they are specified on the command line,
2410 or are a dependent of a target specified on the command line--but
2413 be built if so specified.
2414 Multiple targets can be passed in to a single call to
2417 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2419 .RI env.Append( key = val ", [...])"
2420 Appends the specified keyword arguments
2421 to the end of construction variables in the environment.
2422 If the Environment does not have
2423 the specified construction variable,
2424 it is simply added to the environment.
2425 If the values of the construction variable
2426 and the keyword argument are the same type,
2427 then the two values will be simply added together.
2428 Otherwise, the construction variable
2429 and the value of the keyword argument
2430 are both coerced to lists,
2431 and the lists are added together.
2432 (See also the Prepend method, below.)
2435 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2438 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2440 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2441 This appends new path elements to the given path in the
2442 specified external environment
2446 any particular path once (leaving the last one it encounters and
2447 ignoring the rest, to preserve path order),
2448 and to help assure this,
2449 will normalize all paths (using
2452 .BR os.path.normcase ).
2453 This can also handle the
2454 case where the given old path variable is a list instead of a
2455 string, in which case a list will be returned instead of a string.
2459 print 'before:',env['ENV']['INCLUDE']
2460 include_path = '/foo/bar:/foo'
2461 env.PrependENVPath('INCLUDE', include_path)
2462 print 'after:',env['ENV']['INCLUDE']
2466 after: /biz:/foo/bar:/foo
2469 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2471 .RI env.AppendUnique( key = val ", [...])"
2472 Appends the specified keyword arguments
2473 to the end of construction variables in the environment.
2474 If the Environment does not have
2475 the specified construction variable,
2476 it is simply added to the environment.
2477 If the construction variable being appended to is a list,
2478 then any value(s) that already exist in the
2479 construction variable will
2481 be added again to the list.
2484 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2487 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2490 A factory function that
2491 returns a Builder object
2492 to be used to fetch source files
2494 The returned Builder
2495 is intended to be passed to the
2500 env.SourceCode('.', env.BitKeeper())
2503 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2505 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2507 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2508 This specifies a build directory
2510 in which to build all derived files
2511 that would normally be built under
2513 Multiple build directories can be set up for multiple build variants, for
2516 must be underneath the SConstruct file's directory,
2519 may not be underneath the
2522 The default behavior is for
2524 to duplicate all of the files in the tree underneath
2528 and then build the derived files within the copied tree.
2529 (The duplication is performed by
2531 depending on the platform; see also the
2534 This guarantees correct builds
2535 regardless of whether intermediate source files
2536 are generated during the build,
2537 where preprocessors or other scanners search
2539 or whether individual compilers or other invoked tools
2540 are hard-coded to put derived files in the same directory as source files.
2542 This behavior of making a complete copy of the source tree
2543 may be disabled by setting
2548 to invoke Builders using the
2549 path names of source files in
2551 and the path names of derived files within
2553 This is always more efficient than
2555 and is usually safe for most builds.
2559 may cause build problems
2560 if source files are generated during the build,
2561 if any invoked tools are hard-coded to
2562 put derived files in the same directory as the source files.
2564 Note that specifying a
2566 works most naturally
2567 with a subsidiary SConscript file
2568 in the source directory.
2570 you would then call the subsidiary SConscript file
2571 not in the source directory,
2576 had made a virtual copy of the source tree
2577 regardless of the value of
2579 This is how you tell
2581 which variant of a source tree to build.
2585 BuildDir('build-variant1', 'src')
2586 SConscript('build-variant1/SConscript')
2587 BuildDir('build-variant2', 'src')
2588 SConscript('build-variant2/SConscript')
2594 function, described below,
2596 specify a build directory
2597 in conjunction with calling a subsidiary
2600 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2602 .RI Builder( action ", [" arguments ])
2604 .RI env.Builder( action ", [" arguments ])
2605 Creates a Builder object for
2608 See the section "Builder Objects,"
2609 below, for a complete explanation of the arguments and behavior.
2611 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2613 .RI CacheDir( cache_dir )
2615 .RI env.CacheDir( cache_dir )
2618 will maintain a cache of derived files in
2620 The derived files in the cache will be shared
2621 among all the builds using the same
2629 finds a derived file that needs to be rebuilt,
2630 it will first look in the cache to see if a
2631 derived file has already been built
2632 from identical input files and an identical build action
2633 (as incorporated into the MD5 build signature).
2636 will retrieve the file from the cache.
2637 If the derived file is not present in the cache,
2640 then place a copy of the built file in the cache
2641 (identified by its MD5 build signature),
2642 so that it may be retrieved by other
2643 builds that need to build the same derived file
2644 from identical inputs.
2648 may be disabled for any invocation
2657 will place a copy of
2659 derived files in the cache,
2660 even if they already existed
2661 and were not built by this invocation.
2662 This is useful to populate a cache
2665 is added to a build,
2674 "Retrieved `file' from cache,"
2677 option is being used.
2682 will print the action that
2684 have been used to build the file,
2685 without any indication that
2686 the file was actually retrieved from the cache.
2687 This is useful to generate build logs
2688 that are equivalent regardless of whether
2689 a given derived file has been built in-place
2690 or retrieved from the cache.
2692 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2694 .RI Clean( targets ", " files_or_dirs )
2696 .RI env.Clean( targets ", " files_or_dirs )
2697 This specifies a list of files or directories which should be removed
2698 whenever the targets are specified with the
2700 command line option.
2701 The specified targets may be a list
2702 or an individual target.
2706 and create new targets or add files and directories to the
2707 clean list for the specified targets.
2709 Multiple files or directories should be specified
2710 either as separate arguments to the
2712 method, or as a list.
2714 will also accept the return value of any of the construction environment
2719 Clean('foo', ['bar', 'baz'])
2720 Clean('dist', env.Program('hello', 'hello.c'))
2721 Clean(['foo', 'bar'], 'something_else_to_clean')
2724 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2726 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2728 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2729 Executes a specific action
2730 (or list of actions)
2731 to build a target file or files.
2732 This is more convenient
2733 than defining a separate Builder object
2734 for a single special-case build.
2736 As a special case, the
2738 keyword argument can
2741 that will be used to scan the sources.
2745 if any of the sources will be directories
2746 that must be scanned on-disk for
2747 changes to files that aren't
2748 already specified in other Builder of function calls.)
2750 Any other keyword arguments specified override any
2751 same-named existing construction variables.
2753 Note that an action can be an external command,
2754 specified as a string,
2755 or a callable Python object;
2756 see "Action Objects," below.
2760 env.Command('foo.out', 'foo.in',
2761 "$FOO_BUILD < $SOURCES > $TARGET")
2763 env.Command('bar.out', 'bar.in',
2765 "$BAR_BUILD < $SOURCES > $TARGET"],
2766 ENV = {'PATH' : '/usr/local/bin/'})
2768 def rename(env, target, source):
2770 os.rename('.tmp', str(target[0]))
2772 env.Command('baz.out', 'baz.in',
2773 ["$BAZ_BUILD < $SOURCES > .tmp",
2777 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2779 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2781 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2782 Creates a Configure object for integrated
2783 functionality similar to GNU autoconf.
2784 See the section "Configure Contexts,"
2785 below, for a complete explanation of the arguments and behavior.
2787 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2789 .RI env.Copy([ key = val ", ...])"
2790 Return a separate copy of a construction environment.
2791 If there are any keyword arguments specified,
2792 they are added to the returned copy,
2793 overwriting any existing values
2798 env3 = env.Copy(CCFLAGS = '-g')
2801 Additionally, a list of tools and a toolpath may be specified, as in
2802 the Environment constructor:
2805 def MyTool(env): env['FOO'] = 'bar'
2806 env4 = env.Copy(tools = ['msvc', MyTool])
2809 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2811 .RI env.CVS( repository ", " module )
2812 A factory function that
2813 returns a Builder object
2814 to be used to fetch source files
2818 The returned Builder
2819 is intended to be passed to the
2823 The optional specified
2825 will be added to the beginning
2826 of all repository path names;
2827 this can be used, in essence,
2828 to strip initial directory names
2829 from the repository path names,
2830 so that you only have to
2831 replicate part of the repository
2832 directory hierarchy in your
2833 local build directory:
2836 # Will fetch foo/bar/src.c
2837 # from /usr/local/CVSROOT/foo/bar/src.c.
2838 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2840 # Will fetch bar/src.c
2841 # from /usr/local/CVSROOT/foo/bar/src.c.
2842 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2845 # from /usr/local/CVSROOT/foo/bar/src.c.
2846 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2849 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2851 .RI Default( targets )
2853 .RI env.Default( targets )
2854 This specifies a list of default targets,
2855 which will be built by
2857 if no explicit targets are given on the command line.
2861 and add to the list of default targets.
2863 Multiple targets should be specified as
2864 separate arguments to the
2866 method, or as a list.
2868 will also accept the Node returned by any
2869 of a construction environment's
2874 Default('foo', 'bar', 'baz')
2875 env.Default(['a', 'b', 'c'])
2876 hello = env.Program('hello', 'hello.c')
2884 will clear all default targets.
2887 will add to the (now empty) default-target list
2890 The current list of targets added using the
2892 function or method is available in the
2897 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2899 .RI DefaultEnvironment([ args ])
2900 Creates and returns a default construction environment object.
2901 This construction environment is used internally by SCons
2902 in order to execute many of the global functions in this list,
2903 and to fetch source files transparently
2904 from source code management systems.
2906 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2908 .RI Depends( target ", " dependency )
2910 .RI env.Depends( target ", " dependency )
2911 Specifies an explicit dependency;
2912 the target file(s) will be rebuilt
2913 whenever the dependency file(s) has changed.
2914 This should only be necessary
2915 for cases where the dependency
2916 is not caught by a Scanner
2920 env.Depends('foo', 'other-input-file-for-foo')
2923 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2925 .RI env.Dictionary([ vars ])
2926 Returns a dictionary object
2927 containing copies of all of the
2928 construction variables in the environment.
2929 If there are any variable names specified,
2930 only the specified construction
2931 variables are returned in the dictionary.
2934 dict = env.Dictionary()
2935 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2938 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2940 .RI Dir( name ", [" directory ])
2942 .RI env.Dir( name ", [" directory ])
2943 This returns a Directory Node,
2944 an object that represents the specified directory
2947 can be a relative or absolute path.
2949 is an optional directory that will be used as the parent directory.
2952 is specified, the current script's directory is used as the parent.
2954 Directory Nodes can be used anywhere you
2955 would supply a string as a directory name
2956 to a Builder method or function.
2957 Directory Nodes have attributes and methods
2958 that are useful in many situations;
2959 see "File and Directory Nodes," below.
2961 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2963 .RI env.Dump([ key ])
2964 Returns a pretty printable representation of the environment.
2968 should be a string containing the name of the variable of interest.
2973 print env.Dump('CCCOM')
2977 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2987 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2990 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2995 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2997 .RI EnsurePythonVersion( major ", " minor )
2999 .RI env.EnsurePythonVersion( major ", " minor )
3000 Ensure that the Python version is at least
3003 print out an error message and exit SCons with a non-zero exit code if the
3004 actual Python version is not late enough.
3007 EnsurePythonVersion(2,2)
3010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3012 .RI EnsureSConsVersion( major ", " minor )
3014 .RI env.EnsureSConsVersion( major ", " minor )
3015 Ensure that the SCons version is at least
3018 print out an error message and exit SCons with a non-zero exit code if the
3019 actual SCons version is not late enough.
3022 EnsureSConsVersion(0,9)
3025 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3027 .RI Environment([ key = value ", ...])"
3029 .RI env.Environment([ key = value ", ...])"
3030 Return a new construction environment
3031 initialized with the specified
3035 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3037 .RI Execute( action ", [" strfunction ", " varlist ])
3039 .RI env.Execute( action ", [" strfunction ", " varlist ])
3040 Executes an Action object.
3043 may be an Action object
3044 (see the section "Action Objects,"
3045 below, for a complete explanation of the arguments and behavior),
3046 or it may be a command-line string,
3048 or executable Python function,
3049 each of which will be converted
3050 into an Action object
3052 The exit value of the command
3053 or return value of the Python function
3056 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3060 .RI env.Exit([ value ])
3066 A default exit value of
3069 is used if no value is specified.
3071 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3075 .RI env.Export( vars )
3078 to export a list of variables from the current
3079 SConscript file to all other SConscript files.
3080 The exported variables are kept in a global collection,
3081 so subsequent calls to
3083 will over-write previous exports that have the same name.
3084 Multiple variable names can be passed to
3086 as separate arguments or as a list. A dictionary can be used to map
3087 variables to a different name when exported. Both local variables and
3088 global variables can be exported.
3093 # Make env available for all SConscript files to Import().
3097 # Make env and package available for all SConscript files:.
3098 Export("env", "package")
3100 # Make env and package available for all SConscript files:
3101 Export(["env", "package"])
3103 # Make env available using the name debug:.
3104 Export({"debug":env})
3110 function supports an
3112 argument that makes it easier to to export a variable or
3113 set of variables to a single SConscript file.
3114 See the description of the
3118 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3120 .RI File( name ", [" directory ])
3122 .RI env.File( name ", [" directory ])
3125 an object that represents the specified file
3128 can be a relative or absolute path.
3130 is an optional directory that will be used as the parent directory.
3132 File Nodes can be used anywhere you
3133 would supply a string as a file name
3134 to a Builder method or function.
3135 File Nodes have attributes and methods
3136 that are useful in many situations;
3137 see "File and Directory Nodes," below.
3139 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3141 .RI FindFile( file ", " dirs )
3143 .RI env.FindFile( file ", " dirs )
3146 in the path specified by
3149 may be a list of file names or a single file name. In addition to searching
3150 for files that exist in the filesytem, this function also searches for
3151 derived files that have not yet been built.
3154 foo = env.FindFile('foo', ['dir1', 'dir2'])
3157 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3159 .RI Flatten( sequence )
3161 .RI env.Flatten( sequence )
3162 Takes a sequence (that is, a Python list or tuple)
3163 that may contain nested sequences
3164 and returns a flattened list containing
3165 all of the individual elements in any sequence.
3166 This can be helpful for collecting
3167 the lists returned by calls to Builders;
3168 other Builders will automatically
3169 flatten lists specified as input,
3170 but direct Python manipulation of
3171 these lists does not:
3174 foo = Object('foo.c')
3175 bar = Object('bar.c')
3177 # Because `foo' and `bar' are lists returned by the Object() Builder,
3178 # `objects' will be a list containing nested lists:
3179 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3181 # Passing such a list to another Builder is all right because
3182 # the Builder will flatten the list automatically:
3183 Program(source = objects)
3185 # If you need to manipulate the list directly using Python, you need to
3186 # call Flatten() yourself, or otherwise handle nested lists:
3187 for object in Flatten(objects):
3191 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3193 .RI GetBuildPath( file ", [" ... ])
3195 .RI env.GetBuildPath( file ", [" ... ])
3198 path name (or names) for the specified
3206 Nodes or strings representing path names.
3208 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3212 .RI env.GetLaunchDir()
3213 Returns the absolute path name of the directory from which
3216 was initially invoked.
3217 This can be useful when using the
3222 options, which internally
3223 change to the directory in which the
3227 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3229 .RI GetOption( name )
3231 .RI env.GetOption( name )
3232 This function provides a way to query a select subset of the scons command line
3233 options from a SConscript file. See
3235 for a description of the options available.
3237 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3239 '\".RI GlobalBuilders( flag )
3243 '\"adds the names of the default builders
3244 '\"(Program, Library, etc.)
3245 '\"to the global name space
3246 '\"so they can be called without an explicit construction environment.
3247 '\"(This is the default.)
3251 '\"the names of the default builders are removed
3252 '\"from the global name space
3253 '\"so that an explicit construction environment is required
3254 '\"to call all builders.
3256 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3260 .RI env.Help( text )
3261 This specifies help text to be printed if the
3263 argument is given to
3267 is called multiple times, the text is appended together in the order
3272 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3274 .RI Ignore( target ", " dependency )
3276 .RI env.Ignore( target ", " dependency )
3277 The specified dependency file(s)
3278 will be ignored when deciding if
3279 the target file(s) need to be rebuilt.
3282 env.Ignore('foo', 'foo.c')
3283 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3286 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3290 .RI env.Import( vars )
3293 to import a list of variables into the current SConscript file. This
3294 will import variables that were exported with
3300 Variables exported by
3303 Multiple variable names can be passed to
3305 as separate arguments or as a list. The variable "*" can be used
3306 to import all variables.
3311 Import("env", "variable")
3312 Import(["env", "variable"])
3316 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3318 .RI Install( dir ", " source )
3320 .RI env.Install( dir ", " source )
3321 Installs one or more files in a destination directory.
3322 The file names remain the same.
3325 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3328 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3330 .RI InstallAs( target ", " source )
3332 .RI env.InstallAs( target ", " source )
3333 Installs one or more files as specific file names,
3334 allowing changing a file name as part of the
3336 It is an error if the target and source
3337 list different numbers of files.
3340 env.InstallAs(target = '/usr/local/bin/foo',
3341 source = 'foo_debug')
3342 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3343 source = ['libFOO.a', 'libBAR.a'])
3346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3348 .RI Literal( string )
3350 .RI env.Literal( string )
3353 will be preserved as-is
3354 and not have construction variables expanded.
3356 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3358 .RI Local( targets )
3360 .RI env.Local( targets )
3363 will have copies made in the local tree,
3364 even if an already up-to-date copy
3365 exists in a repository.
3366 Returns a list of the target Node or Nodes.
3368 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3370 .RI env.ParseConfig( command ", [" function ", " unique ])
3373 to modify the environment as specified by the output of
3377 expects the output of a typical
3381 and adds the options
3382 to the appropriate construction variables.
3384 duplicate values are not
3385 added to any construction variables;
3408 construction variables,
3412 option gets added to both the
3419 option gets added to the
3422 Any other strings not associated with options
3423 are assumed to be the names of libraries
3426 construction variable.
3428 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3430 .RI ParseDepends( filename ", [" must_exist ])
3432 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3433 Parses the contents of the specified
3435 as a list of dependencies in the style of
3439 and explicitly establishes all of the listed dependencies.
3448 argument may be set to a non-zero
3451 throw an exception and
3452 generate an error if the file does not exist,
3453 or is otherwise inaccessible.
3457 argument may be set to a non-zero
3460 thrown an exception and
3462 if the file contains dependency
3463 information for more than one target.
3464 This can provide a small sanity check
3465 for files intended to be generated
3466 by, for example, the
3469 which should typically only
3470 write dependency information for
3471 one output file into a corresponding
3477 and all of the files listed therein
3478 will be interpreted relative to
3479 the directory of the
3481 file which calls the
3485 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3488 A factory function that
3489 returns a Builder object
3490 to be used to fetch source files
3491 from the Perforce source code management system.
3492 The returned Builder
3493 is intended to be passed to the
3498 env.SourceCode('.', env.Perforce())
3501 Perforce uses a number of external
3502 environment variables for its operation.
3503 Consequently, this function adds the
3504 following variables from the user's external environment
3505 to the construction environment's
3518 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3520 .RI Platform( string )
3521 Returns a callable object
3522 that can be used to initialize
3523 a construction environment using the
3524 platform keyword of the Environment() method:
3527 env = Environment(platform = Platform('win32'))
3530 .RI env.Platform( string )
3531 Applies the callable object for the specified platform
3533 to the environment through which the method was called.
3536 env.Platform('posix')
3543 variable from the user's external environment
3544 to the construction environment's
3547 This is so that any executed commands
3548 that use sockets to connect with other systems
3549 (such as fetching source files from
3550 external CVS repository specifications like
3551 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3552 will work on Win32 systems.
3554 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3556 .RI Precious( target ", ...)"
3558 .RI env.Precious( target ", ...)"
3561 as precious so it is not deleted before it is rebuilt. Normally
3563 deletes a target before building it.
3564 Multiple targets can be passed in to a single call to
3567 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3569 .RI env.Prepend( key = val ", [...])"
3570 Appends the specified keyword arguments
3571 to the beginning of construction variables in the environment.
3572 If the Environment does not have
3573 the specified construction variable,
3574 it is simply added to the environment.
3575 If the values of the construction variable
3576 and the keyword argument are the same type,
3577 then the two values will be simply added together.
3578 Otherwise, the construction variable
3579 and the value of the keyword argument
3580 are both coerced to lists,
3581 and the lists are added together.
3582 (See also the Append method, above.)
3585 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3588 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3590 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3591 This appends new path elements to the given path in the
3592 specified external environment
3596 any particular path once (leaving the first one it encounters and
3597 ignoring the rest, to preserve path order),
3598 and to help assure this,
3599 will normalize all paths (using
3602 .BR os.path.normcase ).
3603 This can also handle the
3604 case where the given old path variable is a list instead of a
3605 string, in which case a list will be returned instead of a string.
3609 print 'before:',env['ENV']['INCLUDE']
3610 include_path = '/foo/bar:/foo'
3611 env.PrependENVPath('INCLUDE', include_path)
3612 print 'after:',env['ENV']['INCLUDE']
3616 after: /foo/bar:/foo:/biz
3619 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3621 .RI env.AppendUnique( key = val ", [...])"
3622 Appends the specified keyword arguments
3623 to the beginning of construction variables in the environment.
3624 If the Environment does not have
3625 the specified construction variable,
3626 it is simply added to the environment.
3627 If the construction variable being appended to is a list,
3628 then any value(s) that already exist in the
3629 construction variable will
3631 be added again to the list.
3634 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3637 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3640 A factory function that
3641 returns a Builder object
3642 to be used to fetch source files
3644 The returned Builder
3645 is intended to be passed to the
3650 env.SourceCode('.', env.RCS())
3655 will fetch source files
3656 from RCS subdirectories automatically,
3658 as demonstrated in the above example
3659 should only be necessary if
3660 you are fetching from
3663 directory as the source files,
3664 or if you need to explicitly specify RCS
3665 for a specific subdirectory.
3667 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3669 .RI env.Replace( key = val ", [...])"
3670 Replaces construction variables in the Environment
3671 with the specified keyword arguments.
3674 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3677 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3679 .RI Repository( directory )
3681 .RI env.Repository( directory )
3684 is a repository to be searched for files.
3688 and each one adds to the list of
3689 repositories that will be searched.
3693 a repository is a copy of the source tree,
3694 from the top-level directory on down,
3696 both source files and derived files
3697 that can be used to build targets in
3698 the local source tree.
3699 The canonical example would be an
3700 official source tree maintained by an integrator.
3701 If the repository contains derived files,
3702 then the derived files should have been built using
3704 so that the repository contains the necessary
3705 signature information to allow
3707 to figure out when it is appropriate to
3708 use the repository copy of a derived file,
3709 instead of building one locally.
3711 Note that if an up-to-date derived file
3712 already exists in a repository,
3716 make a copy in the local directory tree.
3717 In order to guarantee that a local copy
3723 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3728 what variable(s) to use as the return value(s) of the current SConscript
3729 file. These variables will be returned to the "calling" SConscript file
3730 as the return value(s) of
3732 Multiple variable names should be passed to
3738 Return(["foo", "bar"])
3741 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3743 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3745 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3746 Creates a Scanner object for
3749 See the section "Scanner Objects,"
3750 below, for a complete explanation of the arguments and behavior.
3752 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3755 A factory function that
3756 returns a Builder object
3757 to be used to fetch source files
3759 The returned Builder
3760 is intended to be passed to the
3765 env.SourceCode('.', env.SCCS())
3770 will fetch source files
3771 from SCCS subdirectories automatically,
3773 as demonstrated in the above example
3774 should only be necessary if
3775 you are fetching from
3778 directory as the source files,
3779 or if you need to explicitly specify SCCS
3780 for a specific subdirectory.
3782 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3784 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3786 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3788 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3790 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3794 one or more subsidiary SConscript (configuration) files.
3795 There are two ways to call the
3799 The first way you can call
3801 is to explicitly specify one or more
3803 as the first argument.
3804 A single script may be specified as a string;
3805 multiple scripts must be specified as a list
3806 (either explicitly or as created by
3810 The second way you can call
3812 is to specify a list of (sub)directory names
3819 execute a subsidiary configuration file named
3821 in each of the specified directories.
3822 You may specify a name other than
3824 by supplying an optional
3830 argument provides a list of variable names or a dictionary of
3831 named values to export to the
3833 These variables are locally exported only to the specified
3835 and do not affect the
3836 global pool of variables used by
3840 '\"If multiple dirs are provided,
3841 '\"each script gets a fresh export.
3846 function to import the variables.
3850 argument specifies that all of the target files
3851 (for example, object files and executables)
3852 that would normally be built in the subdirectory in which
3854 resides should actually
3858 is interpreted relative to the directory
3859 of the calling SConscript file.
3863 argument specifies that the
3864 source files from which
3865 the target files should be built
3869 is interpreted relative to the directory
3870 of the calling SConscript file.
3874 will link or copy (depending on the platform)
3875 all the source files into the build directory.
3876 This behavior may be disabled by
3877 setting the optional
3880 (it is set to 1 by default),
3883 will refer directly to
3884 the source files in their source directory
3885 when building target files.
3888 is usually safe, and always more efficient
3891 but it may cause build problems in certain end-cases,
3892 such as compiling from source files that
3893 are generated by the build.)
3895 Any variables returned by
3899 will be returned by the call to
3905 SConscript('subdir/SConscript')
3906 foo = SConscript('sub/SConscript', exports='env')
3907 SConscript('dir/SConscript', exports=['env', 'variable'])
3908 SConscript('src/SConscript', build_dir='build', duplicate=0)
3909 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3910 SConscript(dirs=['sub1', 'sub2'])
3911 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3914 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3916 .RI SConscriptChdir( value )
3918 .RI env.SConscriptChdir( value )
3921 changes its working directory
3922 to the directory in which each
3923 subsidiary SConscript file lives.
3924 This behavior may be disabled
3925 by specifying either:
3929 env.SConscriptChdir(0)
3934 will stay in the top-level directory
3935 while reading all SConscript files.
3936 (This may be necessary when building from repositories,
3937 when all the directories in which SConscript files may be found
3938 don't necessarily exist locally.)
3940 You may enable and disable
3941 this ability by calling
3948 SConscript('foo/SConscript') # will not chdir to foo
3949 env.SConscriptChdir(1)
3950 SConscript('bar/SConscript') # will chdir to bar
3953 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3955 .RI SConsignFile([ file , dbm_module ])
3957 .RI env.SConsignFile([ file , dbm_module ])
3960 to store all file signatures
3970 is not an absolute path name,
3971 the file is placed in the same directory as the top-level
3977 argument can be used to specify
3978 which Python database module
3979 The default is to use a custom
3981 module that uses pickled
3982 Python data structures,
3983 and which works on all Python versions from 1.5.2 on.
3988 # Stores signatures in ".sconsign.dbm"
3989 # in the top-level SConstruct directory.
3992 # Stores signatures in the file "etc/scons-signatures"
3993 # relative to the top-level SConstruct directory.
3994 SConsignFile("etc/scons-signatures")
3996 # Stores signatures in the specified absolute file name.
3997 SConsignFile("/home/me/SCons/signatures")
4000 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4002 .RI env.SetDefault(key = val ", [...])"
4003 Sets construction variables to default values specified with the keyword
4004 arguments if (and only if) the variables are not already set.
4005 The following statements are equivalent:
4008 env.SetDefault(FOO = 'foo')
4010 if not env.has_key('FOO'): env['FOO'] = 'foo'
4013 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4015 .RI SetOption( name ", " value )
4017 .RI env.SetOption( name ", " value )
4018 This function provides a way to set a select subset of the scons command
4019 line options from a SConscript file. The options supported are:
4021 which corresponds to -c, --clean, and --remove;
4024 corresponds to --duplicate;
4026 which corresponds to --implicit-cache;
4028 which corresponds to --max-drift;
4030 which corresponds to -j and --jobs.
4031 See the documentation for the
4032 corresponding command line object for information about each specific
4036 SetOption('max_drift', 1)
4039 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4041 .RI SideEffect( side_effect ", " target )
4043 .RI env.SideEffect( side_effect ", " target )
4046 as a side effect of building
4052 can be a list, a file name, or a node.
4053 A side effect is a target that is created
4054 as a side effect of building other targets.
4055 For example, a Windows PDB
4056 file is created as a side effect of building the .obj
4057 files for a static library.
4058 If a target is a side effect of multiple build commands,
4060 will ensure that only one set of commands
4061 is executed at a time.
4062 Consequently, you only need to use this method
4063 for side-effect targets that are built as a result of
4064 multiple build commands.
4066 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4068 .RI SourceCode( entries ", " builder )
4070 .RI env.SourceCode( entries ", " builder )
4071 Arrange for non-existent source files to
4072 be fetched from a source code management system
4077 may be a Node, string or list of both,
4078 and may represent either individual
4079 source files or directories in which
4080 source files can be found.
4082 For any non-existent source files,
4084 will search up the directory tree
4094 will not use a builder to fetch
4095 source files for the specified
4099 builder has been specified
4100 for a directory higher up the tree.
4104 fetch files from SCCS or RCS subdirectories
4105 without explicit configuration.
4106 This takes some extra processing time
4107 to search for the necessary
4108 source code management files on disk.
4109 You can avoid these extra searches
4110 and speed up your build a little
4111 by disabling these searches as follows:
4114 env.SourceCode('.', None)
4118 Note that if the specified
4120 is one you create by hand,
4121 it must have an associated
4122 construction environment to use
4123 when fetching a source file.
4126 provides a set of canned factory
4127 functions that return appropriate
4128 Builders for various popular
4129 source code management systems.
4130 Canonical examples of invocation include:
4133 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4134 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4135 env.SourceCode('/', env.RCS())
4136 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4137 env.SourceCode('no_source.c', None)
4139 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4141 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4143 '\".RI Subversion( repository ", " module )
4144 '\"A factory function that
4145 '\"returns a Builder object
4146 '\"to be used to fetch source files
4147 '\"from the specified Subversion
4149 '\"The returned Builder
4150 '\"is intended to be passed to the
4154 '\"The optional specified
4156 '\"will be added to the beginning
4157 '\"of all repository path names;
4158 '\"this can be used, in essence,
4159 '\"to strip initial directory names
4160 '\"from the repository path names,
4161 '\"so that you only have to
4162 '\"replicate part of the repository
4163 '\"directory hierarchy in your
4164 '\"local build directory:
4167 '\"# Will fetch foo/bar/src.c
4168 '\"# from /usr/local/Subversion/foo/bar/src.c.
4169 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4171 '\"# Will fetch bar/src.c
4172 '\"# from /usr/local/Subversion/foo/bar/src.c.
4173 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4175 '\"# Will fetch src.c
4176 '\"# from /usr/local/Subversion/foo/bar/src.c.
4177 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4180 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4182 .RI SourceSignatures( type )
4184 .RI env.SourceSignatures( type )
4185 This function tells SCons what type of signature to use for source files:
4189 If the environment method is used,
4190 the specified type of source signature
4191 is only used when deciding whether targets
4192 built with that environment are up-to-date or must be rebuilt.
4193 If the global function is used,
4194 the specified type of source signature becomes the default
4195 used for all decisions
4196 about whether targets are up-to-date.
4198 "MD5" means the signature of a source file
4199 is the MD5 checksum of its contents.
4200 "timestamp" means the signature of a source file
4201 is its timestamp (modification time).
4202 There is no different between the two behaviors
4206 "MD5" signatures take longer to compute,
4207 but are more accurate than "timestamp" signatures.
4208 The default is "MD5".
4210 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4214 .RI env.Split( arg )
4215 Returns a list of file names or other objects.
4217 it will be split on strings of white-space characters
4219 making it easier to write long lists of file names.
4220 If arg is already a list,
4221 the list will be returned untouched.
4222 If arg is any other type of object,
4223 it will be returned as a list
4224 containing just the object.
4227 files = Split("f1.c f2.c f3.c")
4228 files = env.Split("f4.c f5.c f6.c")
4236 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4238 .RI TargetSignatures( type )
4240 .RI env.TargetSignatures( type )
4241 This function tells SCons what type of signatures to use
4246 If the environment method is used,
4247 the specified type of signature is only used
4248 for targets built with that environment.
4249 If the global function is used,
4250 the specified type of signature becomes the default
4251 used for all target files that
4252 don't have an explicit target signature type
4253 specified for their environments.
4255 "build" means the signature of a target file
4256 is made by concatenating all of the
4257 signatures of all its source files.
4258 "content" means the signature of a target
4259 file is an MD5 checksum of its contents.
4260 "build" signatures are usually faster to compute,
4261 but "content" signatures can prevent unnecessary rebuilds
4262 when a target file is rebuilt to the exact same contents
4263 as the previous build.
4264 The default is "build".
4266 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4268 .RI Tool( string [, toolpath ", " **kw ])
4269 Returns a callable object
4270 that can be used to initialize
4271 a construction environment using the
4272 tools keyword of the Environment() method.
4273 The object may be called with a construction
4274 environment as an argument,
4275 in which case the object will
4276 add the necessary variables
4277 to the construction environment
4278 and the name of the tool will be added to the
4280 construction variable.
4282 Additional keyword arguments are passed to the tool's
4287 env = Environment(tools = [ Tool('msvc') ])
4291 t(env) # adds 'msvc' to the TOOLS variable
4292 u = Tool('opengl', toolpath = ['tools'])
4293 u(env) # adds 'opengl' to the TOOLS variable
4296 .RI env.Tool( string [, toolpath ", " **kw ])
4297 Applies the callable object for the specified tool
4299 to the environment through which the method was called.
4301 Additional keyword arguments are passed to the tool's
4307 env.Tool('opengl', toolpath = ['build/tools'])
4310 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4314 .RI env.Value( value )
4315 Returns a Node object representing the specified Python value. Value
4316 nodes can be used as dependencies of targets. If the result of
4319 changes between SCons runs, any targets depending on
4321 will be rebuilt. When using timestamp source signatures, Value nodes'
4322 timestamps are equal to the system time when the node is created.
4325 def create(target, source, env):
4326 f = open(str(target[0]), 'wb')
4327 f.write('prefix=' + source[0].get_contents())
4329 prefix = ARGUMENTS.get('prefix', '/usr/local')
4331 env['BUILDERS']['Config'] = Builder(action = create)
4332 env.Config(target = 'package-config', source = Value(prefix))
4335 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4337 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4339 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4341 Searches for the specified executable
4343 returning the full path name to the program
4345 and returning None if not.
4346 Searches the specified
4348 the value of the calling environment's PATH
4349 (env['ENV']['PATH']),
4350 or the user's current external PATH
4351 (os.environ['PATH'])
4353 On Win32 systems, searches for executable
4354 programs with any of the file extensions
4355 listed in the specified
4357 the calling environment's PATHEXT
4358 (env['ENV']['PATHEXT'])
4359 or the user's current PATHEXT
4360 (os.environ['PATHEXT'])
4368 .SS SConscript Variables
4369 In addition to the global functions and methods,
4371 supports a number of Python variables
4372 that can be used in SConscript files
4373 to affect how you want the build to be performed.
4374 These variables may be accessed from custom Python modules that you
4375 import into an SConscript file by adding the following
4376 to the Python module:
4379 from SCons.Script import *
4382 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4387 arguments specified on the command line.
4388 Each element in the list is a tuple
4390 .RI ( keyword , value )
4396 elements of the tuple
4398 subscripting for element
4402 of the tuple, respectively.
4405 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4406 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4407 third_tuple = ARGLIST[2]
4408 print "third keyword, value =", third_tuple[0], third_tuple[1]
4409 for key, value in ARGLIST:
4410 # process key and value
4413 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4416 A dictionary of all the
4418 arguments specified on the command line.
4419 The dictionary is not in order,
4420 and if a given keyword has
4421 more than one value assigned to it
4422 on the command line,
4423 the last (right-most) value is
4429 if ARGUMENTS.get('debug', 0):
4430 env = Environment(CCFLAGS = '-g')
4435 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4438 A list of the targets which
4440 will actually try to build,
4441 regardless of whether they were specified on
4442 the command line or via the
4445 The elements of this list may be strings
4447 nodes, so you should run the list through the Python
4449 function to make sure any Node path names
4450 are converted to strings.
4452 Because this list may be taken from the
4453 list of targets specified using the
4456 the contents of the list may change
4457 on each successive call to
4462 for additional information.
4465 if 'foo' in BUILD_TARGETS:
4466 print "Don't forget to test the `foo' program!"
4467 if 'special/program' in BUILD_TARGETS:
4468 SConscript('special')
4473 list only contains targets expected listed
4474 on the command line or via calls to the
4479 contain all dependent targets that will be built as
4480 a result of making the sure the explicitly-specified
4481 targets are up to date.
4483 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4485 COMMAND_LINE_TARGETS
4486 A list of the targets explicitly specified on
4488 If there are no targets specified on the command line,
4490 This can be used, for example,
4491 to take specific actions only
4492 when a certain target or targets
4493 is explicitly being built:
4496 if 'foo' in COMMAND_LINE_TARGETS:
4497 print "Don't forget to test the `foo' program!"
4498 if 'special/program' in COMMAND_LINE_TARGETS:
4499 SConscript('special')
4502 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4505 A list of the target
4507 that have been specified using the
4510 The elements of the list are nodes,
4511 so you need to run them through the Python
4513 function to get at the path name for each Node.
4516 print str(DEFAULT_TARGETS[0])
4517 if 'foo' in map(str, DEFAULT_TARGETS):
4518 print "Don't forget to test the `foo' program!"
4523 list change on on each successive call to the
4528 print map(str, DEFAULT_TARGETS) # originally []
4530 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4532 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4534 print map(str, DEFAULT_TARGETS) # back to []
4537 Consequently, be sure to use
4539 only after you've made all of your
4542 or else simply be careful of the order
4543 of these statements in your SConscript files
4544 so that you don't look for a specific
4545 default target before it's actually been added to the list.
4547 .SS Construction Variables
4548 .\" XXX From Gary Ruben, 23 April 2002:
4549 .\" I think it would be good to have an example with each construction
4550 .\" variable description in the documentation.
4552 .\" CC The C compiler
4553 .\" Example: env["CC"] = "c68x"
4554 .\" Default: env["CC"] = "cc"
4556 .\" CCCOM The command line ...
4558 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4559 .\" env["CC"] = "c68x"
4560 .\" env["CFLAGS"] = "-ps -qq -mr"
4561 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4563 .\" (I dunno what this is ;-)
4564 A construction environment has an associated dictionary of
4565 .I construction variables
4566 that are used by built-in or user-supplied build rules.
4567 Construction variables must follow the same rules for
4569 the initial character must be an underscore or letter,
4570 followed by any number of underscores, letters, or digits.
4572 A number of useful construction variables are automatically defined by
4573 scons for each supported platform, and additional construction variables
4574 can be defined by the user. The following is a list of the automatically
4575 defined construction variables:
4578 The static library archiver.
4581 The command line used to generate a static library from object files.
4584 The string displayed when an object file
4585 is generated from an assembly-language source file.
4586 If this is not set, then $ARCOM (the command line) is displayed.
4589 env = Environment(ARCOMSTR = "Archiving $TARGET")
4593 General options passed to the static library archiver.
4599 The command line used to generate an object file
4600 from an assembly-language source file.
4603 The string displayed when an object file
4604 is generated from an assembly-language source file.
4605 If this is not set, then $ASCOM (the command line) is displayed.
4608 env = Environment(ASCOMSTR = "Assembling $TARGET")
4612 General options passed to the assembler.
4615 The command line used to assemble an assembly-language
4616 source file into an object file
4617 after first running the file through the C preprocessor.
4618 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4619 are included on this command line.
4622 The string displayed when an object file
4623 is generated from an assembly-language source file
4624 after first running the file through the C preprocessor.
4625 If this is not set, then $ASPPCOM (the command line) is displayed.
4628 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4632 General options when an assembling an assembly-language
4633 source file into an object file
4634 after first running the file through the C preprocessor.
4635 The default is to use the value of $ASFLAGS.
4638 The bibliography generator for the TeX formatter and typesetter and the
4639 LaTeX structured formatter and typesetter.
4642 The command line used to call the bibliography generator for the
4643 TeX formatter and typesetter and the LaTeX structured formatter and
4647 The string displayed when generating a bibliography
4649 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4652 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4657 General options passed to the bibliography generator for the TeX formatter
4658 and typesetter and the LaTeX structured formatter and typesetter.
4661 The BitKeeper executable.
4664 The command line for
4665 fetching source files using BitKeeper.
4668 The string displayed when fetching
4669 a source file using BitKeeper.
4670 If this is not set, then $BITKEEPERCOM
4671 (the command line) is displayed.
4674 The command ($BITKEEPER) and subcommand
4675 for fetching source files using BitKeeper.
4677 .IP BITKEEPERGETFLAGS
4678 Options that are passed to the BitKeeper
4683 A dictionary mapping the names of the builders
4684 available through this environment
4685 to underlying Builder objects.
4687 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4688 are available by default.
4689 If you initialize this variable when an
4690 Environment is created:
4693 env = Environment(BUILDERS = {'NewBuilder' : foo})
4696 the default Builders will no longer be available.
4697 To use a new Builder object in addition to the default Builders,
4698 add your new Builder object like this:
4702 env.Append(BUILDERS = {'NewBuilder' : foo})
4709 env['BUILDERS]['NewBuilder'] = foo
4716 The command line used to compile a C source file to a (static) object file.
4717 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4718 are included on this command line.
4721 The string displayed when a C source file
4722 is compiled to a (static) object file.
4723 If this is not set, then $CCCOM (the command line) is displayed.
4726 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4730 General options that are passed to the C compiler.
4733 The suffix for C source files.
4734 This is used by the internal CFile builder
4735 when generating C files from Lex (.l) or YACC (.y) input files.
4736 The default suffix, of course, is
4739 On case-insensitive systems (like Win32),
4746 The version number of the C compiler.
4747 This may or may not be set,
4748 depending on the specific C compiler being used.
4751 A function used to produce variables like $_CPPINCFLAGS. It takes
4753 arguments: a prefix to concatenate onto each element, a list of
4754 elements, a suffix to concatenate onto each element, an environment
4755 for variable interpolation, and an optional function that will be
4756 called to transform the list before concatenation.
4759 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4763 A platform independent specification of C preprocessor definitions.
4764 The definitions will be added to command lines
4765 through the automatically-generated
4766 $_CPPDEFFLAGS construction variable (see below),
4767 which is constructed according to
4768 the type of value of $CPPDEFINES:
4771 If $CPPDEFINES is a string,
4773 $CPPDEFPREFIX and $CPPDEFSUFFIX
4774 construction variables
4775 will be added to the beginning and end.
4778 # Will add -Dxyz to POSIX compiler command lines,
4779 # and /Dxyz to Microsoft Visual C++ command lines.
4780 env = Environment(CPPDEFINES='xyz')
4784 If $CPPDEFINES is a list,
4786 $CPPDEFPREFIX and $CPPDEFSUFFIX
4787 construction variables
4788 will be appended to the beginning and end
4789 of each element in the list.
4790 If any element is a list or tuple,
4791 then the first item is the name being
4792 defined and the second item is its value:
4795 # Will add -DB=2 -DA to POSIX compiler command lines,
4796 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4797 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4801 If $CPPDEFINES is a dictionary,
4803 $CPPDEFPREFIX and $CPPDEFSUFFIX
4804 construction variables
4805 will be appended to the beginning and end
4806 of each item from the dictionary.
4807 The key of each dictionary item
4808 is a name being defined
4809 to the dictionary item's corresponding value;
4812 then the name is defined without an explicit value.
4813 Note that the resulting flags are sorted by keyword
4814 to ensure that the order of the options on the
4815 command line is consistent each time
4820 # Will add -DA -DB=2 to POSIX compiler command lines,
4821 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4822 env = Environment(CPPDEFINES={'B':2, 'A':None})
4826 An automatically-generated construction variable
4827 containing the C preprocessor command-line options
4829 The value of $_CPPDEFFLAGS is created
4830 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4831 to the beginning and end
4832 of each directory in $CPPDEFINES.
4835 The prefix used to specify preprocessor definitions
4836 on the C compiler command line.
4837 This will be appended to the beginning of each definition
4838 in the $CPPDEFINES construction variable
4839 when the $_CPPDEFFLAGS variable is automatically generated.
4842 The suffix used to specify preprocessor definitions
4843 on the C compiler command line.
4844 This will be appended to the end of each definition
4845 in the $CPPDEFINES construction variable
4846 when the $_CPPDEFFLAGS variable is automatically generated.
4849 User-specified C preprocessor options.
4850 These will be included in any command that uses the C preprocessor,
4851 including not just compilation of C and C++ source files
4852 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4853 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4854 $F77PPCOM and $SHF77PPCOM command lines
4855 used to compile a Fortran source file,
4856 and the $ASPPCOM command line
4857 used to assemble an assembly language source file,
4858 after first running each file through the C preprocessor.
4859 Note that this variable does
4863 (or similar) include search path options
4864 that scons generates automatically from $CPPPATH.
4868 for the variable that expands to those options.
4871 An automatically-generated construction variable
4872 containing the C preprocessor command-line options
4873 for specifying directories to be searched for include files.
4874 The value of $_CPPINCFLAGS is created
4875 by appending $INCPREFIX and $INCSUFFIX
4876 to the beginning and end
4877 of each directory in $CPPPATH.
4880 The list of directories that the C preprocessor will search for include
4881 directories. The C/C++ implicit dependency scanner will search these
4882 directories for include files. Don't explicitly put include directory
4883 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4884 and the directories will not be searched by the dependency scanner. Note:
4885 directory names in CPPPATH will be looked-up relative to the SConscript
4886 directory when they are used in a command. To force
4888 to look-up a directory relative to the root of the source tree use #:
4891 env = Environment(CPPPATH='#/include')
4895 The directory look-up can also be forced using the
4900 include = Dir('include')
4901 env = Environment(CPPPATH=include)
4905 The directory list will be added to command lines
4906 through the automatically-generated
4908 construction variable,
4909 which is constructed by
4910 appending the values of the
4911 $INCPREFIX and $INCSUFFIX
4912 construction variables
4913 to the beginning and end
4914 of each directory in $CPPPATH.
4915 Any command lines you define that need
4916 the CPPPATH directory list should
4917 include $_CPPINCFLAGS:
4920 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4924 The list of suffixes of files that will be scanned
4925 for C preprocessor implicit dependencies
4927 The default list is:
4930 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4931 ".h", ".H", ".hxx", ".hpp", ".hh",
4932 ".F", ".fpp", ".FPP",
4933 ".S", ".spp", ".SPP"]
4940 Options that are passed to the CVS checkout subcommand.
4943 The command line used to
4944 fetch source files from a CVS repository.
4947 The string displayed when fetching
4948 a source file from a CVS repository.
4949 If this is not set, then $CVSCOM
4950 (the command line) is displayed.
4953 General options that are passed to CVS.
4954 By default, this is set to
4956 to specify from where the files must be fetched.
4959 The path to the CVS repository.
4960 This is referenced in the default
4967 The suffix for C++ source files.
4968 This is used by the internal CXXFile builder
4969 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4970 The default suffix is
4972 SCons also treats files with the suffixes
4979 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4986 The command line used to compile a C++ source file to an object file.
4987 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4988 are included on this command line.
4991 The string displayed when a C++ source file
4992 is compiled to a (static) object file.
4993 If this is not set, then $CXXCOM (the command line) is displayed.
4996 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5000 General options that are passed to the C++ compiler.
5003 The version number of the C++ compiler.
5004 This may or may not be set,
5005 depending on the specific C++ compiler being used.
5008 A function that converts a file name into a Dir instance relative to the
5012 The list of suffixes of files that will be scanned
5013 for imported D package files.
5014 The default list is:
5021 The TeX DVI file to PDF file converter.
5024 General options passed to the TeX DVI file to PDF file converter.
5027 The command line used to convert TeX DVI files into a PDF file.
5030 The string displayed when a TeX DVI file
5031 is converted into a PDF file.
5032 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5035 The TeX DVI file to PostScript converter.
5038 General options passed to the TeX DVI file to PostScript converter.
5041 A dictionary of environment variables
5042 to use when invoking commands. When ENV is used in a command all list
5043 values will be joined using the path separator and any other non-string
5044 values will simply be coerced to a string.
5045 Note that, by default,
5049 propagate the environment in force when you
5052 to the commands used to build target files.
5053 This is so that builds will be guaranteed
5054 repeatable regardless of the environment
5055 variables set at the time
5059 If you want to propagate your
5060 environment variables
5061 to the commands executed
5062 to build target files,
5063 you must do so explicitly:
5067 env = Environment(ENV = os.environ)
5071 Note that you can choose only to propagate
5072 certain environment variables.
5076 environment variable,
5079 uses the same utilities
5080 as the invoking shell (or other process):
5085 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5089 A function that will be called to escape shell special characters in
5090 command lines. The function should take one argument: the command line
5091 string to escape; and should return the escaped command line.
5094 The Fortran 77 compiler.
5095 You should normally set the $FORTRAN variable,
5096 which specifies the default Fortran compiler
5097 for all Fortran versions.
5098 You only need to set $F77 if you need to use a specific compiler
5099 or compiler version for Fortran 77 files.
5102 The command line used to compile a Fortran 77 source file to an object file.
5103 You only need to set $F77COM if you need to use a specific
5104 command line for Fortran 77 files.
5105 You should normally set the $FORTRANCOM variable,
5106 which specifies the default command line
5107 for all Fortran versions.
5110 The string displayed when a Fortran 77 source file
5111 is compiled to an object file.
5112 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5115 General user-specified options that are passed to the Fortran 77 compiler.
5116 Note that this variable does
5120 (or similar) include search path options
5121 that scons generates automatically from $F77PATH.
5125 for the variable that expands to those options.
5126 You only need to set $F77FLAGS if you need to define specific
5127 user options for Fortran 77 files.
5128 You should normally set the $FORTRANFLAGS variable,
5129 which specifies the user-specified options
5130 passed to the default Fortran compiler
5131 for all Fortran versions.
5134 An automatically-generated construction variable
5135 containing the Fortran 77 compiler command-line options
5136 for specifying directories to be searched for include files.
5137 The value of $_F77INCFLAGS is created
5138 by appending $INCPREFIX and $INCSUFFIX
5139 to the beginning and end
5140 of each directory in $F77PATH.
5143 The list of directories that the Fortran 77 compiler will search for include
5144 directories. The implicit dependency scanner will search these
5145 directories for include files. Don't explicitly put include directory
5146 arguments in $F77FLAGS because the result will be non-portable
5147 and the directories will not be searched by the dependency scanner. Note:
5148 directory names in $F77PATH will be looked-up relative to the SConscript
5149 directory when they are used in a command. To force
5151 to look-up a directory relative to the root of the source tree use #:
5152 You only need to set $F77PATH if you need to define a specific
5153 include path for Fortran 77 files.
5154 You should normally set the $FORTRANPATH variable,
5155 which specifies the include path
5156 for the default Fortran compiler
5157 for all Fortran versions.
5160 env = Environment(F77PATH='#/include')
5164 The directory look-up can also be forced using the
5169 include = Dir('include')
5170 env = Environment(F77PATH=include)
5174 The directory list will be added to command lines
5175 through the automatically-generated
5177 construction variable,
5178 which is constructed by
5179 appending the values of the
5180 $INCPREFIX and $INCSUFFIX
5181 construction variables
5182 to the beginning and end
5183 of each directory in $F77PATH.
5184 Any command lines you define that need
5185 the F77PATH directory list should
5186 include $_F77INCFLAGS:
5189 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5193 The command line used to compile a Fortran 77 source file to an object file
5194 after first running the file through the C preprocessor.
5195 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5196 are included on this command line.
5197 You only need to set $F77PPCOM if you need to use a specific
5198 C-preprocessor command line for Fortran 77 files.
5199 You should normally set the $FORTRANPPCOM variable,
5200 which specifies the default C-preprocessor command line
5201 for all Fortran versions.
5204 The Fortran 90 compiler.
5205 You should normally set the $FORTRAN variable,
5206 which specifies the default Fortran compiler
5207 for all Fortran versions.
5208 You only need to set $F90 if you need to use a specific compiler
5209 or compiler version for Fortran 90 files.
5212 The command line used to compile a Fortran 90 source file to an object file.
5213 You only need to set $F90COM if you need to use a specific
5214 command line for Fortran 90 files.
5215 You should normally set the $FORTRANCOM variable,
5216 which specifies the default command line
5217 for all Fortran versions.
5220 The string displayed when a Fortran 90 source file
5221 is compiled to an object file.
5222 If this is not set, then $F90COM or $FORTRANCOM
5223 (the command line) is displayed.
5226 General user-specified options that are passed to the Fortran 90 compiler.
5227 Note that this variable does
5231 (or similar) include search path options
5232 that scons generates automatically from $F90PATH.
5236 for the variable that expands to those options.
5237 You only need to set $F90FLAGS if you need to define specific
5238 user options for Fortran 90 files.
5239 You should normally set the $FORTRANFLAGS variable,
5240 which specifies the user-specified options
5241 passed to the default Fortran compiler
5242 for all Fortran versions.
5245 An automatically-generated construction variable
5246 containing the Fortran 90 compiler command-line options
5247 for specifying directories to be searched for include files.
5248 The value of $_F90INCFLAGS is created
5249 by appending $INCPREFIX and $INCSUFFIX
5250 to the beginning and end
5251 of each directory in $F90PATH.
5254 The list of directories that the Fortran 90 compiler will search for include
5255 directories. The implicit dependency scanner will search these
5256 directories for include files. Don't explicitly put include directory
5257 arguments in $F90FLAGS because the result will be non-portable
5258 and the directories will not be searched by the dependency scanner. Note:
5259 directory names in $F90PATH will be looked-up relative to the SConscript
5260 directory when they are used in a command. To force
5262 to look-up a directory relative to the root of the source tree use #:
5263 You only need to set $F90PATH if you need to define a specific
5264 include path for Fortran 90 files.
5265 You should normally set the $FORTRANPATH variable,
5266 which specifies the include path
5267 for the default Fortran compiler
5268 for all Fortran versions.
5271 env = Environment(F90PATH='#/include')
5275 The directory look-up can also be forced using the
5280 include = Dir('include')
5281 env = Environment(F90PATH=include)
5285 The directory list will be added to command lines
5286 through the automatically-generated
5288 construction variable,
5289 which is constructed by
5290 appending the values of the
5291 $INCPREFIX and $INCSUFFIX
5292 construction variables
5293 to the beginning and end
5294 of each directory in $F90PATH.
5295 Any command lines you define that need
5296 the F90PATH directory list should
5297 include $_F90INCFLAGS:
5300 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5304 The command line used to compile a Fortran 90 source file to an object file
5305 after first running the file through the C preprocessor.
5306 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5307 are included on this command line.
5308 You only need to set $F90PPCOM if you need to use a specific
5309 C-preprocessor command line for Fortran 90 files.
5310 You should normally set the $FORTRANPPCOM variable,
5311 which specifies the default C-preprocessor command line
5312 for all Fortran versions.
5315 The Fortran 95 compiler.
5316 You should normally set the $FORTRAN variable,
5317 which specifies the default Fortran compiler
5318 for all Fortran versions.
5319 You only need to set $F95 if you need to use a specific compiler
5320 or compiler version for Fortran 95 files.
5323 The command line used to compile a Fortran 95 source file to an object file.
5324 You only need to set $F95COM if you need to use a specific
5325 command line for Fortran 95 files.
5326 You should normally set the $FORTRANCOM variable,
5327 which specifies the default command line
5328 for all Fortran versions.
5331 The string displayed when a Fortran 95 source file
5332 is compiled to an object file.
5333 If this is not set, then $F95COM or $FORTRANCOM
5334 (the command line) is displayed.
5337 General user-specified options that are passed to the Fortran 95 compiler.
5338 Note that this variable does
5342 (or similar) include search path options
5343 that scons generates automatically from $F95PATH.
5347 for the variable that expands to those options.
5348 You only need to set $F95FLAGS if you need to define specific
5349 user options for Fortran 95 files.
5350 You should normally set the $FORTRANFLAGS variable,
5351 which specifies the user-specified options
5352 passed to the default Fortran compiler
5353 for all Fortran versions.
5356 An automatically-generated construction variable
5357 containing the Fortran 95 compiler command-line options
5358 for specifying directories to be searched for include files.
5359 The value of $_F95INCFLAGS is created
5360 by appending $INCPREFIX and $INCSUFFIX
5361 to the beginning and end
5362 of each directory in $F95PATH.
5365 The list of directories that the Fortran 95 compiler will search for include
5366 directories. The implicit dependency scanner will search these
5367 directories for include files. Don't explicitly put include directory
5368 arguments in $F95FLAGS because the result will be non-portable
5369 and the directories will not be searched by the dependency scanner. Note:
5370 directory names in $F95PATH will be looked-up relative to the SConscript
5371 directory when they are used in a command. To force
5373 to look-up a directory relative to the root of the source tree use #:
5374 You only need to set $F95PATH if you need to define a specific
5375 include path for Fortran 95 files.
5376 You should normally set the $FORTRANPATH variable,
5377 which specifies the include path
5378 for the default Fortran compiler
5379 for all Fortran versions.
5382 env = Environment(F95PATH='#/include')
5386 The directory look-up can also be forced using the
5391 include = Dir('include')
5392 env = Environment(F95PATH=include)
5396 The directory list will be added to command lines
5397 through the automatically-generated
5399 construction variable,
5400 which is constructed by
5401 appending the values of the
5402 $INCPREFIX and $INCSUFFIX
5403 construction variables
5404 to the beginning and end
5405 of each directory in $F95PATH.
5406 Any command lines you define that need
5407 the F95PATH directory list should
5408 include $_F95INCFLAGS:
5411 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5415 The command line used to compile a Fortran 95 source file to an object file
5416 after first running the file through the C preprocessor.
5417 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5418 are included on this command line.
5419 You only need to set $F95PPCOM if you need to use a specific
5420 C-preprocessor command line for Fortran 95 files.
5421 You should normally set the $FORTRANPPCOM variable,
5422 which specifies the default C-preprocessor command line
5423 for all Fortran versions.
5426 The default Fortran compiler
5427 for all versions of Fortran.
5430 The command line used to compile a Fortran source file to an object file.
5431 By default, any options specified
5432 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5433 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5434 are included on this command line.
5437 The string displayed when a Fortran source file
5438 is compiled to an object file.
5439 If this is not set, then $FORTRANCOM
5440 (the command line) is displayed.
5443 General user-specified options that are passed to the Fortran compiler.
5444 Note that this variable does
5448 (or similar) include or module search path options
5449 that scons generates automatically from $FORTRANPATH.
5451 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5453 for the variables that expand those options.
5455 .IP _FORTRANINCFLAGS
5456 An automatically-generated construction variable
5457 containing the Fortran compiler command-line options
5458 for specifying directories to be searched for include
5459 files and module files.
5460 The value of $_FORTRANINCFLAGS is created
5461 by prepending/appending $INCPREFIX and $INCSUFFIX
5462 to the beginning and end
5463 of each directory in $FORTRANPATH.
5466 Directory location where the Fortran compiler should place
5467 any module files it generates. This variable is empty, by default. Some
5468 Fortran compilers will internally append this directory in the search path
5469 for module files, as well
5471 .IP FORTRANMODDIRPREFIX
5472 The prefix used to specify a module directory on the Fortran compiler command
5474 This will be appended to the beginning of the directory
5475 in the $FORTRANMODDIR construction variables
5476 when the $_FORTRANMODFLAG variables is automatically generated.
5478 .IP FORTRANMODDIRSUFFIX
5479 The suffix used to specify a module directory on the Fortran compiler command
5481 This will be appended to the beginning of the directory
5482 in the $FORTRANMODDIR construction variables
5483 when the $_FORTRANMODFLAG variables is automatically generated.
5486 An automatically-generated construction variable
5487 containing the Fortran compiler command-line option
5488 for specifying the directory location where the Fortran
5489 compiler should place any module files that happen to get
5490 generated during compilation.
5491 The value of $_FORTRANMODFLAG is created
5492 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5493 to the beginning and end of the directory in $FORTRANMODDIR.
5495 .IP FORTRANMODPREFIX
5496 The module file prefix used by the Fortran compiler. SCons assumes that
5497 the Fortran compiler follows the quasi-standard naming convention for
5499 .I <module_name>.mod.
5500 As a result, this variable is left empty, by default. For situations in
5501 which the compiler does not necessarily follow the normal convention,
5502 the user may use this variable. Its value will be appended to every
5503 module file name as scons attempts to resolve dependencies.
5505 .IP FORTRANMODSUFFIX
5506 The module file suffix used by the Fortran compiler. SCons assumes that
5507 the Fortran compiler follows the quasi-standard naming convention for
5509 .I <module_name>.mod.
5510 As a result, this variable is set to ".mod", by default. For situations
5511 in which the compiler does not necessarily follow the normal convention,
5512 the user may use this variable. Its value will be appended to every
5513 module file name as scons attempts to resolve dependencies.
5516 The list of directories that the Fortran compiler will search for
5517 include files and (for some compilers) module files. The Fortran implicit
5518 dependency scanner will search these directories for include files (but
5519 not module files since they are autogenerated and, as such, may not
5520 actually exist at the time the scan takes place). Don't explicitly put
5521 include directory arguments in FORTRANFLAGS because the result will be
5522 non-portable and the directories will not be searched by the dependency
5523 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5524 to the SConscript directory when they are used in a command. To force
5526 to look-up a directory relative to the root of the source tree use #:
5529 env = Environment(FORTRANPATH='#/include')
5533 The directory look-up can also be forced using the
5538 include = Dir('include')
5539 env = Environment(FORTRANPATH=include)
5543 The directory list will be added to command lines
5544 through the automatically-generated
5546 construction variable,
5547 which is constructed by
5548 appending the values of the
5549 $INCPREFIX and $INCSUFFIX
5550 construction variables
5551 to the beginning and end
5552 of each directory in $FORTRANPATH.
5553 Any command lines you define that need
5554 the FORTRANPATH directory list should
5555 include $_FORTRANINCFLAGS:
5558 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5562 The command line used to compile a Fortran source file to an object file
5563 after first running the file through the C preprocessor.
5564 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5565 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5566 construction variables are included on this command line.
5569 The list of suffixes of files that will be scanned
5570 for Fortran implicit dependencies
5571 (INCLUDE lines & USE statements).
5572 The default list is:
5575 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5576 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5580 A function that converts a file name into a File instance relative to the
5585 frameworks options to be addad at
5586 the end of a command
5587 line building a loadable module.
5590 The Ghostscript program used to convert PostScript to PDF files.
5593 General options passed to the Ghostscript program
5594 when converting PostScript to PDF files.
5597 The Ghostscript command line used to convert PostScript to PDF files.
5600 The string displayed when
5601 Ghostscript is used to convert
5602 a PostScript file to a PDF file.
5603 If this is not set, then $GSCOM (the command line) is displayed.
5606 The list of suffixes of files that will be scanned
5607 for IDL implicit dependencies
5608 (#include or import lines).
5609 The default list is:
5616 The prefix used to specify an include directory on the C compiler command
5618 This will be appended to the beginning of each directory
5619 in the $CPPPATH and $FORTRANPATH construction variables
5620 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5621 variables are automatically generated.
5624 The suffix used to specify an include directory on the C compiler command
5626 This will be appended to the end of each directory
5627 in the $CPPPATH and $FORTRANPATH construction variables
5628 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5629 variables are automatically generated.
5632 A function to be called to install a file into a
5633 destination file name.
5634 The default function copies the file into the destination
5635 (and sets the destination file's mode and permission bits
5636 to match the source file's).
5637 The function takes the following arguments:
5640 def install(dest, source, env):
5644 is the path name of the destination file.
5646 is the path name of the source file.
5648 is the construction environment
5649 (a dictionary of construction values)
5650 in force for this file installation.
5652 .IP INTEL_C_COMPILER_VERSION
5653 Set by the "intelc" Tool
5654 to the major version number of the Intel C compiler
5658 The Java archive tool.
5661 The directory to which the Java archive tool should change
5667 The command line used to call the Java archive tool.
5670 The string displayed when the Java archive tool
5672 If this is not set, then $JARCOM (the command line) is displayed.
5675 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5679 General options passed to the Java archive tool.
5680 By default this is set to
5682 to create the necessary
5687 The suffix for Java archives:
5695 The command line used to compile a directory tree containing
5696 Java source files to
5697 corresponding Java class files.
5698 Any options specified in the $JAVACFLAGS construction variable
5699 are included on this command line.
5702 The string displayed when compiling
5703 a directory tree of Java source files to
5704 corresponding Java class files.
5705 If this is not set, then $JAVACCOM (the command line) is displayed.
5708 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5712 General options that are passed to the Java compiler.
5715 The directory in which Java class files may be found.
5716 This is stripped from the beginning of any Java .class
5717 file names supplied to the
5722 The suffix for Java class files;
5727 The Java generator for C header and stub files.
5730 The command line used to generate C header and stub files
5732 Any options specified in the $JAVAHFLAGS construction variable
5733 are included on this command line.
5736 The string displayed when C header and stub files
5737 are generated from Java classes.
5738 If this is not set, then $JAVAHCOM (the command line) is displayed.
5741 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5745 General options passed to the C header and stub file generator
5749 The suffix for Java files;
5754 The LaTeX structured formatter and typesetter.
5757 The command line used to call the LaTeX structured formatter and typesetter.
5760 The string displayed when calling
5761 the LaTeX structured formatter and typesetter.
5762 If this is not set, then $LATEXCOM (the command line) is displayed.
5765 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5769 General options passed to the LaTeX structured formatter and typesetter.
5772 The linker for building loadable modules.
5773 By default, this is the same as $SHLINK.
5776 The command line for building loadable modules.
5777 On Mac OS X, this uses the $LDMODULE,
5778 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
5779 On other systems, this is the same as $SHLINK.
5782 The string displayed when building loadable modules.
5783 If this is not set, then $LDMODULECOM (the command line) is displayed.
5786 General user options passed to the linker for building loadable modules.
5789 The prefix used for loadable module file names.
5790 On Mac OS X, this is null;
5791 on other systems, this is
5792 the same $SHLIBPREFIX.
5795 The suffix used for loadable module file names.
5796 On Mac OS X, this is null;
5797 on other systems, this is
5798 the same $SHLIBSUFFIX.
5801 The lexical analyzer generator.
5804 General options passed to the lexical analyzer generator.
5807 The command line used to call the lexical analyzer generator
5808 to generate a source file.
5811 The string displayed when generating a source file
5812 using the lexical analyzer generator.
5813 If this is not set, then $LEXCOM (the command line) is displayed.
5816 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5820 An automatically-generated construction variable
5821 containing the linker command-line options
5822 for specifying directories to be searched for library.
5823 The value of $_LIBDIRFLAGS is created
5824 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5825 to the beginning and end
5826 of each directory in $LIBPATH.
5829 The prefix used to specify a library directory on the linker command line.
5830 This will be appended to the beginning of each directory
5831 in the $LIBPATH construction variable
5832 when the $_LIBDIRFLAGS variable is automatically generated.
5835 The suffix used to specify a library directory on the linker command line.
5836 This will be appended to the end of each directory
5837 in the $LIBPATH construction variable
5838 when the $_LIBDIRFLAGS variable is automatically generated.
5841 An automatically-generated construction variable
5842 containing the linker command-line options
5843 for specifying libraries to be linked with the resulting target.
5844 The value of $_LIBFLAGS is created
5845 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5846 to the beginning and end
5847 of each directory in $LIBS.
5850 The prefix used to specify a library to link on the linker command line.
5851 This will be appended to the beginning of each library
5852 in the $LIBS construction variable
5853 when the $_LIBFLAGS variable is automatically generated.
5856 The suffix used to specify a library to link on the linker command line.
5857 This will be appended to the end of each library
5858 in the $LIBS construction variable
5859 when the $_LIBFLAGS variable is automatically generated.
5862 The list of directories that will be searched for libraries.
5863 The implicit dependency scanner will search these
5864 directories for include files. Don't explicitly put include directory
5865 arguments in $LINKFLAGS or $SHLINKFLAGS
5866 because the result will be non-portable
5867 and the directories will not be searched by the dependency scanner. Note:
5868 directory names in LIBPATH will be looked-up relative to the SConscript
5869 directory when they are used in a command. To force
5871 to look-up a directory relative to the root of the source tree use #:
5874 env = Environment(LIBPATH='#/libs')
5878 The directory look-up can also be forced using the
5884 env = Environment(LIBPATH=libs)
5888 The directory list will be added to command lines
5889 through the automatically-generated
5891 construction variable,
5892 which is constructed by
5893 appending the values of the
5894 $LIBDIRPREFIX and $LIBDIRSUFFIX
5895 construction variables
5896 to the beginning and end
5897 of each directory in $LIBPATH.
5898 Any command lines you define that need
5899 the LIBPATH directory list should
5900 include $_LIBDIRFLAGS:
5903 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5907 The prefix used for (static) library file names.
5908 A default value is set for each platform
5909 (posix, win32, os2, etc.),
5910 but the value is overridden by individual tools
5911 (ar, mslib, sgiar, sunar, tlib, etc.)
5912 to reflect the names of the libraries they create.
5915 An array of legal prefixes for library file names.
5918 A list of one or more libraries
5919 that will be linked with
5920 any executable programs
5921 created by this environment.
5924 The library list will be added to command lines
5925 through the automatically-generated
5927 construction variable,
5928 which is constructed by
5929 appending the values of the
5930 $LIBLINKPREFIX and $LIBLINKSUFFIX
5931 construction variables
5932 to the beginning and end
5933 of each directory in $LIBS.
5934 Any command lines you define that need
5935 the LIBS library list should
5939 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5943 The suffix used for (static) library file names.
5944 A default value is set for each platform
5945 (posix, win32, os2, etc.),
5946 but the value is overridden by individual tools
5947 (ar, mslib, sgiar, sunar, tlib, etc.)
5948 to reflect the names of the libraries they create.
5951 An array of legal suffixes for library file names.
5957 General user options passed to the linker.
5958 Note that this variable should
5962 (or similar) options for linking with the libraries listed in $LIBS,
5965 (or similar) library search path options
5966 that scons generates automatically from $LIBPATH.
5970 for the variable that expands to library-link options,
5974 for the variable that expands to library search path options.
5977 The command line used to link object files into an executable.
5980 The string displayed when object files
5981 are linked into an executable.
5982 If this is not set, then $LINKCOM (the command line) is displayed.
5985 env = Environment(LINKCOMSTR = "Linking $TARGET")
5989 The M4 macro preprocessor.
5992 General options passed to the M4 macro preprocessor.
5995 The command line used to pass files through the M4 macro preprocessor.
5998 The string displayed when
5999 a file is passed through the M4 macro preprocessor.
6000 If this is not set, then $M4COM (the command line) is displayed.
6003 The maximum number of characters allowed on an external command line.
6005 link lines longer than this many characters
6006 are linke via a temporary file name.
6009 When the Microsoft Visual Studio tools are initialized, they set up
6010 this dictionary with the following keys:
6013 the version of MSVS being used (can be set via
6017 the available versions of MSVS installed
6020 installed directory of Visual C++
6023 installed directory of Visual Studio
6026 installed directory of the .NET framework
6028 .B FRAMEWORKVERSIONS:
6029 list of installed versions of the .NET framework, sorted latest to oldest.
6031 .B FRAMEWORKVERSION:
6032 latest installed version of the .NET framework
6035 installed location of the .NET SDK.
6038 installed location of the Platform SDK.
6040 .B PLATFORMSDK_MODULES:
6041 dictionary of installed Platform SDK modules,
6042 where the dictionary keys are keywords for the various modules, and
6043 the values are 2-tuples where the first is the release date, and the
6044 second is the version number.
6046 If a value isn't set, it wasn't available in the registry.
6048 .IP MSVS_IGNORE_IDE_PATHS
6049 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6050 instead of the settings from the IDE.
6052 For Visual Studio, SCons will (by default) automatically determine
6053 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6054 set by the IDE. You can override this behavior by setting these
6055 variables after Environment initialization, or by setting
6056 .B MSVS_IGNORE_IDE_PATHS = 1
6057 in the Environment initialization.
6058 Specifying this will not leave these unset, but will set them to a
6059 minimal set of paths needed to run the tools successfully.
6062 For VS6, the mininimal set is:
6063 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6064 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6065 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6067 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6068 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6069 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6073 Where '<VSDir>' is the installed location of Visual Studio.
6075 .IP MSVS_USE_MFC_DIRS
6076 Tells the MS Visual Studio tool(s) to use
6077 the MFC directories in its default paths
6078 for compiling and linking.
6079 Under MSVS version 6,
6081 .B MSVS_USE_MFC_DIRS
6090 external environment variable,
6096 external environment variable.
6097 Under MSVS version 7,
6099 .B MSVS_USE_MFC_DIRS
6102 .B "atlmfc\\\\include"
6103 directory to the default
6105 external environment variable,
6108 directory to the default
6110 external environment variable.
6111 The current default value is
6113 which means these directories
6114 are added to the paths by default.
6115 This default value is likely to change
6116 in a future release,
6117 so users who want the ATL and MFC
6118 values included in their paths
6119 are encouraged to enable the
6120 .B MSVS_USE_MFC_DIRS
6122 to avoid future incompatibility.
6123 This variable has no effect if the
6127 environment variables are set explictly.
6130 Sets the preferred version of MSVS to use.
6132 SCons will (by default) select the latest version of MSVS
6133 installed on your machine. So, if you have version 6 and version 7
6134 (MSVS .NET) installed, it will prefer version 7. You can override this by
6137 variable in the Environment initialization, setting it to the
6138 appropriate version ('6.0' or '7.0', for example).
6139 If the given version isn't installed, tool initialization will fail.
6142 The action used to generate Microsoft Visual Studio
6143 project and solution files.
6145 .IP MSVSPROJECTSUFFIX
6146 The suffix used for Microsoft Visual Studio project (DSP) files.
6147 The default value is
6149 when using Visual Studio version 7.x (.NET),
6152 when using earlier versions of Visual Studio.
6154 .IP MSVSSOLUTIONSUFFIX
6155 The suffix used for Microsoft Visual Studio solution (DSW) files.
6156 The default value is
6158 when using Visual Studio version 7.x (.NET),
6161 when using earlier versions of Visual Studio.
6164 The version number of the MetroWerks CodeWarrior C compiler
6168 A list of installed versions of the MetroWerks CodeWarrior C compiler
6172 When set to non-zero,
6173 suppresses creation of a corresponding Win32 static import lib by the
6175 builder when used with
6176 MinGW or Microsoft Visual Studio.
6177 This also suppresses creation
6178 of an export (.exp) file
6179 when using Microsoft Visual Studio.
6182 The prefix used for (static) object file names.
6185 The suffix used for (static) object file names.
6188 The Perforce executable.
6191 The command line used to
6192 fetch source files from Perforce.
6195 The string displayed when
6196 fetching a source file from Perforce.
6197 If this is not set, then $P4COM (the command line) is displayed.
6200 General options that are passed to Perforce.
6203 The Microsoft Visual C++ precompiled header that will be used when compiling
6204 object files. This variable is ignored by tools other than Microsoft Visual C++.
6205 When this variable is
6206 defined SCons will add options to the compiler command line to
6207 cause it to use the precompiled header, and will also set up the
6208 dependencies for the PCH file. Example:
6211 env['PCH'] = 'StdAfx.pch'
6215 The command line used by the
6217 builder to generated a precompiled header.
6220 The string displayed when generating a precompiled header.
6221 If this is not set, then $PCHCOM (the command line) is displayed.
6224 This variable specifies how much of a source file is precompiled. This
6225 variable is ignored by tools other than Microsoft Visual C++, or when
6226 the PCH variable is not being used. When this variable is define it
6227 must be a string that is the name of the header that
6228 is included at the end of the precompiled portion of the source files, or
6229 the empty string if the "#pragma hrdstop" construct is being used:
6232 env['PCHSTOP'] = 'StdAfx.h'
6236 The Microsoft Visual C++ PDB file that will store debugging information for
6237 object files, shared libraries, and programs. This variable is ignored by
6238 tools other than Microsoft Visual C++.
6239 When this variable is
6240 defined SCons will add options to the compiler and linker command line to
6241 cause them to generate external debugging information, and will also set up the
6242 dependencies for the PDB file. Example:
6245 env['PDB'] = 'hello.pdb'
6249 A deprecated synonym for $DVIPDFCOM.
6252 The prefix used for PDF file names.
6255 The suffix used for PDF file names.
6258 The name of the platform used to create the Environment. If no platform is
6259 specified when the Environment is created,
6261 autodetects the platform.
6264 env = Environment(tools = [])
6265 if env['PLATFORM'] == 'cygwin':
6271 .IP PRINT_CMD_LINE_FUNC
6272 A Python function used to print the command lines as they are executed
6273 (assuming command printing is not disabled by the
6277 options or their equivalents).
6278 The function should take four arguments:
6280 the command being executed (a string),
6282 the target being built (file node, list, or string name(s)),
6284 the source(s) used (file node, list, or string name(s)), and
6286 the environment being used.
6288 The function must do the printing itself. The default implementation,
6289 used if this variable is not set or is None, is:
6291 def print_cmd_line(s, target, source, env):
6292 sys.stdout.write(s + "\n")
6295 Here's an example of a more interesting function:
6297 def print_cmd_line(s, target, source, env):
6298 sys.stdout.write("Building %s -> %s...\n" %
6299 (' and '.join([str(x) for x in source]),
6300 ' and '.join([str(x) for x in target])))
6301 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6302 env.Program('foo', 'foo.c')
6305 This just prints "Building <targetname> from <sourcename>..." instead
6306 of the actual commands.
6307 Such a function could also log the actual commands to a log file,
6311 The prefix used for executable file names.
6314 The suffix used for executable file names.
6317 The command line used to convert TeX DVI files into a PostScript file.
6320 The string displayed when a TeX DVI file
6321 is converted into a PostScript file.
6322 If this is not set, then $PSCOM (the command line) is displayed.
6325 The prefix used for PostScript file names.
6328 The prefix used for PostScript file names.
6331 The qt tool tries to take this from os.environ.
6332 It also initializes all QT_*
6333 construction variables listed below.
6334 (Note that all paths are constructed
6335 with python's os.path.join() method,
6336 but are listed here with the '/' separator
6337 for easier reading.)
6338 In addition, the construction environment
6339 variables CPPPATH, LIBPATH and LIBS may be modified
6341 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6342 are modified. Because the build-performance is affected when using this tool,
6343 you have to explicitly specify it at Environment creation:
6346 Environment(tools=['default','qt'])
6349 The qt tool supports the following operations:
6351 .B Automatic moc file generation from header files.
6352 You do not have to specify moc files explicitly, the tool does it for you.
6353 However, there are a few preconditions to do so: Your header file must have
6354 the same filebase as your implementation file and must stay in the same
6355 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6356 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6357 See also the corresponding builder method
6360 .B Automatic moc file generation from cxx files.
6361 As stated in the qt documentation, include the moc file at the end of
6362 the cxx file. Note that you have to include the file, which is generated
6363 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6364 <basename>.moc. A warning is generated after building the moc file, if you
6365 do not include the correct file. If you are using BuildDir, you may
6366 need to specify duplicate=1. You can turn off automatic moc file generation
6367 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6370 .B Automatic handling of .ui files.
6371 The implementation files generated from .ui files are handled much the same
6372 as yacc or lex files. Each .ui file given as a source of Program, Library or
6373 SharedLibrary will generate three files, the declaration file, the
6374 implementation file and a moc file. Because there are also generated headers,
6375 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6379 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6380 specify files to run moc on.
6383 The path where the qt binaries are installed.
6384 The default value is '$QTDIR/bin'.
6387 The path where the qt header files are installed.
6388 The default value is '$QTDIR/include'.
6389 Note: If you set this variable to None, the tool won't change the CPPPATH
6390 construction variable.
6393 Prints lots of debugging information while scanning for moc files.
6396 The path where the qt libraries are installed.
6397 The default value is '$QTDIR/lib'.
6398 Note: If you set this variable to None, the tool won't change the LIBPATH
6399 construction variable.
6402 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6403 this variable to None, the tool won't change the LIBS variable.
6406 Default value is '$QT_BINPATH/moc'.
6409 Default value is ''. Prefix for moc output files, when source is a cxx file.
6412 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6415 .IP QT_MOCFROMCPPFLAGS
6416 Default value is '-i'. These flags are passed to moc, when moccing a
6419 .IP QT_MOCFROMCXXCOM
6420 Command to generate a moc file from a cpp file.
6422 .IP QT_MOCFROMCXXCOMSTR
6423 The string displayed when generating a moc file from a cpp file.
6424 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6427 Command to generate a moc file from a header.
6429 .IP QT_MOCFROMHCOMSTR
6430 The string displayed when generating a moc file from a cpp file.
6431 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6433 .IP QT_MOCFROMHFLAGS
6434 Default value is ''. These flags are passed to moc, when moccing a header
6438 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6441 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6445 Default value is '$QT_BINPATH/uic'.
6448 Command to generate header files from .ui files.
6451 The string displayed when generating header files from .ui files.
6452 If this is not set, then $QT_UICCOM (the command line) is displayed.
6455 Default value is ''. These flags are passed to uic, when creating a a h
6456 file from a .ui file.
6458 .IP QT_UICDECLPREFIX
6459 Default value is ''. Prefix for uic generated header files.
6461 .IP QT_UICDECLSUFFIX
6462 Default value is '.h'. Suffix for uic generated header files.
6465 Default value is ''. These flags are passed to uic, when creating a cxx
6466 file from a .ui file.
6468 .IP QT_UICIMPLPREFIX
6469 Default value is 'uic_'. Prefix for uic generated implementation files.
6471 .IP QT_UICIMPLSUFFIX
6472 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6476 Default value is '.ui'. Suffix of designer input files.
6479 The archive indexer.
6482 General options passed to the archive indexer.
6485 The resource compiler used by the RES builder.
6488 The command line used by the RES builder.
6491 The string displayed when invoking the resource compiler.
6492 If this is not set, then $RCCOM (the command line) is displayed.
6495 The flags passed to the resource compiler by the RES builder.
6499 Note that this variable is not actually used
6500 for the command to fetch source files from RCS;
6503 construction variable, below.
6506 The RCS "checkout" executable,
6507 used to fetch source files from RCS.
6510 The command line used to
6511 fetch (checkout) source files from RCS.
6514 The string displayed when fetching
6515 a source file from RCS.
6516 If this is not set, then $RCS_COCOM
6517 (the command line) is displayed.
6520 Options that are passed to the $RCS_CO command.
6523 The program used to register DLLs on Windows systems.
6526 The command line used to register a newly-built DLL file
6528 Invoked when the "register=1"
6529 keyword argument is passed to the
6534 The string displayed when registering a newly-built DLL file.
6535 If this is not set, then $REGSVRCOM (the command line) is displayed.
6538 A function that converts a file name into a list of Dir instances by
6539 searching the repositories.
6542 The Java RMI stub compiler.
6545 The command line used to compile stub
6546 and skeleton class files
6547 from Java classes that contain RMI implementations.
6548 Any options specified in the $RMICFLAGS construction variable
6549 are included on this command line.
6552 The string displayed when compiling
6553 stub and skeleton class files
6554 from Java classes that contain RMI implementations.
6555 If this is not set, then $RMICCOM (the command line) is displayed.
6558 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6562 General options passed to the Java RMI stub compiler.
6565 The RPC protocol compiler.
6567 .IP RPCGENCLIENTFLAGS
6568 Options passed to the RPC protocol compiler
6569 when generating client side stubs.
6570 These are in addition to any flags specified in the
6572 construction variable.
6575 General options passed to the RPC protocol compiler.
6577 .IP RPCGENHEADERFLAGS
6578 Options passed to the RPC protocol compiler
6579 when generating a header file.
6580 These are in addition to any flags specified in the
6582 construction variable.
6584 .IP RPCGENSERVICEFLAGS
6585 Options passed to the RPC protocol compiler
6586 when generating server side stubs.
6587 These are in addition to any flags specified in the
6589 construction variable.
6592 Options passed to the RPC protocol compiler
6593 when generating XDR routines.
6594 These are in addition to any flags specified in the
6596 construction variable.
6599 A list of paths to search for shared libraries when running programs.
6600 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6601 Ignored on platforms and toolchains that don't support it.
6602 Note that the paths added to RPATH
6603 are not transformed by
6605 in any way: if you want an absolute
6606 path, you must make it absolute yourself.
6609 A list of the available implicit dependency scanners.
6610 New file scanners may be added by
6611 appending to this list,
6612 although the more flexible approach
6613 is to associate scanners
6614 with a specific Builder.
6615 See the sections "Builder Objects"
6616 and "Scanner Objects,"
6617 below, for more information.
6620 The SCCS executable.
6623 The command line used to
6624 fetch source files from SCCS.
6627 The string displayed when fetching
6628 a source file from a CVS repository.
6629 If this is not set, then $SCCSCOM
6630 (the command line) is displayed.
6633 General options that are passed to SCCS.
6636 Options that are passed specifically to the SCCS "get" subcommand.
6637 This can be set, for example, to
6639 to check out editable files from SCCS.
6642 The C compiler used for generating shared-library objects.
6645 The command line used to compile a C source file
6646 to a shared-library object file.
6647 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6648 are included on this command line.
6651 The string displayed when a C source file
6652 is compiled to a shared object file.
6653 If this is not set, then $SHCCCOM (the command line) is displayed.
6656 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6660 Options that are passed to the C compiler
6661 to generate shared-library objects.
6664 The C++ compiler used for generating shared-library objects.
6667 The command line used to compile a C++ source file
6668 to a shared-library object file.
6669 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6670 are included on this command line.
6673 The string displayed when a C++ source file
6674 is compiled to a shared object file.
6675 If this is not set, then $SHCXXCOM (the command line) is displayed.
6678 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6682 Options that are passed to the C++ compiler
6683 to generate shared-library objects.
6686 A string naming the shell program that will be passed to the
6691 construction variable for more information.
6694 The Fortran 77 compiler used for generating shared-library objects.
6695 You should normally set the $SHFORTRANC variable,
6696 which specifies the default Fortran compiler
6697 for all Fortran versions.
6698 You only need to set $SHF77 if you need to use a specific compiler
6699 or compiler version for Fortran 77 files.
6702 The command line used to compile a Fortran 77 source file
6703 to a shared-library object file.
6704 You only need to set $SHF77COM if you need to use a specific
6705 command line for Fortran 77 files.
6706 You should normally set the $SHFORTRANCOM variable,
6707 which specifies the default command line
6708 for all Fortran versions.
6711 The string displayed when a Fortran 77 source file
6712 is compiled to a shared-library object file.
6713 If this is not set, then $SHF77COM or $SHFORTRANCOM
6714 (the command line) is displayed.
6717 Options that are passed to the Fortran 77 compiler
6718 to generated shared-library objects.
6719 You only need to set $SHF77FLAGS if you need to define specific
6720 user options for Fortran 77 files.
6721 You should normally set the $SHFORTRANFLAGS variable,
6722 which specifies the user-specified options
6723 passed to the default Fortran compiler
6724 for all Fortran versions.
6727 The command line used to compile a Fortran 77 source file to a
6728 shared-library object file
6729 after first running the file through the C preprocessor.
6730 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6731 are included on this command line.
6732 You only need to set $SHF77PPCOM if you need to use a specific
6733 C-preprocessor command line for Fortran 77 files.
6734 You should normally set the $SHFORTRANPPCOM variable,
6735 which specifies the default C-preprocessor command line
6736 for all Fortran versions.
6739 The Fortran 90 compiler used for generating shared-library objects.
6740 You should normally set the $SHFORTRANC variable,
6741 which specifies the default Fortran compiler
6742 for all Fortran versions.
6743 You only need to set $SHF90 if you need to use a specific compiler
6744 or compiler version for Fortran 90 files.
6747 The command line used to compile a Fortran 90 source file
6748 to a shared-library object file.
6749 You only need to set $SHF90COM if you need to use a specific
6750 command line for Fortran 90 files.
6751 You should normally set the $SHFORTRANCOM variable,
6752 which specifies the default command line
6753 for all Fortran versions.
6756 The string displayed when a Fortran 90 source file
6757 is compiled to a shared-library object file.
6758 If this is not set, then $SHF90COM or $SHFORTRANCOM
6759 (the command line) is displayed.
6762 Options that are passed to the Fortran 90 compiler
6763 to generated shared-library objects.
6764 You only need to set $SHF90FLAGS if you need to define specific
6765 user options for Fortran 90 files.
6766 You should normally set the $SHFORTRANFLAGS variable,
6767 which specifies the user-specified options
6768 passed to the default Fortran compiler
6769 for all Fortran versions.
6772 The command line used to compile a Fortran 90 source file to a
6773 shared-library object file
6774 after first running the file through the C preprocessor.
6775 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6776 are included on this command line.
6777 You only need to set $SHF90PPCOM if you need to use a specific
6778 C-preprocessor command line for Fortran 90 files.
6779 You should normally set the $SHFORTRANPPCOM variable,
6780 which specifies the default C-preprocessor command line
6781 for all Fortran versions.
6784 The Fortran 95 compiler used for generating shared-library objects.
6785 You should normally set the $SHFORTRANC variable,
6786 which specifies the default Fortran compiler
6787 for all Fortran versions.
6788 You only need to set $SHF95 if you need to use a specific compiler
6789 or compiler version for Fortran 95 files.
6792 The command line used to compile a Fortran 95 source file
6793 to a shared-library object file.
6794 You only need to set $SHF95COM if you need to use a specific
6795 command line for Fortran 95 files.
6796 You should normally set the $SHFORTRANCOM variable,
6797 which specifies the default command line
6798 for all Fortran versions.
6801 The string displayed when a Fortran 95 source file
6802 is compiled to a shared-library object file.
6803 If this is not set, then $SHF95COM or $SHFORTRANCOM
6804 (the command line) is displayed.
6807 Options that are passed to the Fortran 95 compiler
6808 to generated shared-library objects.
6809 You only need to set $SHF95FLAGS if you need to define specific
6810 user options for Fortran 95 files.
6811 You should normally set the $SHFORTRANFLAGS variable,
6812 which specifies the user-specified options
6813 passed to the default Fortran compiler
6814 for all Fortran versions.
6817 The command line used to compile a Fortran 95 source file to a
6818 shared-library object file
6819 after first running the file through the C preprocessor.
6820 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6821 are included on this command line.
6822 You only need to set $SHF95PPCOM if you need to use a specific
6823 C-preprocessor command line for Fortran 95 files.
6824 You should normally set the $SHFORTRANPPCOM variable,
6825 which specifies the default C-preprocessor command line
6826 for all Fortran versions.
6829 The default Fortran compiler used for generating shared-library objects.
6832 The command line used to compile a Fortran source file
6833 to a shared-library object file.
6836 The string displayed when a Fortran source file
6837 is compiled to a shared-library object file.
6838 If this is not set, then $SHFORTRANCOM
6839 (the command line) is displayed.
6842 Options that are passed to the Fortran compiler
6843 to generate shared-library objects.
6846 The command line used to compile a Fortran source file to a
6847 shared-library object file
6848 after first running the file through the C preprocessor.
6849 Any options specified
6850 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6851 are included on this command line.
6854 The prefix used for shared library file names.
6857 The suffix used for shared library file names.
6860 The linker for programs that use shared libraries.
6863 The command line used to link programs using shared libaries.
6866 The string displayed when programs using shared libraries are linked.
6867 If this is not set, then $SHLINKCOM (the command line) is displayed.
6870 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6874 General user options passed to the linker for programs using shared libraries.
6875 Note that this variable should
6879 (or similar) options for linking with the libraries listed in $LIBS,
6882 (or similar) include search path options
6883 that scons generates automatically from $LIBPATH.
6887 for the variable that expands to library-link options,
6891 for the variable that expands to library search path options.
6894 The prefix used for shared object file names.
6897 The suffix used for shared object file names.
6900 A reserved variable name
6901 that may not be set or used in a construction environment.
6902 (See "Variable Substitution," below.)
6905 A reserved variable name
6906 that may not be set or used in a construction environment.
6907 (See "Variable Substitution," below.)
6910 A command interpreter function that will be called to execute command line
6911 strings. The function must expect the following arguments:
6914 def spawn(shell, escape, cmd, args, env):
6918 is a string naming the shell program to use.
6920 is a function that can be called to escape shell special characters in
6923 is the path to the command to be executed.
6925 is the arguments to the command.
6927 is a dictionary of the environment variables
6928 in which the command should be executed.
6931 '\"The Subversion executable (usually named
6935 '\"The command line used to
6936 '\"fetch source files from a Subversion repository.
6939 '\"General options that are passed to Subversion.
6942 The scripting language wrapper and interface generator.
6945 The suffix that will be used for intermediate C
6946 source files generated by
6947 the scripting language wrapper and interface generator.
6948 The default value is
6949 .BR _wrap$CFILESUFFIX .
6950 By default, this value is used whenever the
6954 specified as part of the
6956 construction variable.
6959 The command line used to call
6960 the scripting language wrapper and interface generator.
6963 The string displayed when calling
6964 the scripting language wrapper and interface generator.
6965 If this is not set, then $SWIGCOM (the command line) is displayed.
6967 .IP SWIGCXXFILESUFFIX
6968 The suffix that will be used for intermediate C++
6969 source files generated by
6970 the scripting language wrapper and interface generator.
6971 The default value is
6972 .BR _wrap$CFILESUFFIX .
6973 By default, this value is used whenever the
6975 option is specified as part of the
6977 construction variable.
6980 General options passed to
6981 the scripting language wrapper and interface generator.
6982 This is where you should set
6986 or whatever other options you want to specify to SWIG.
6989 option in this variable,
6992 generate a C++ intermediate source file
6993 with the extension that is specified as the
7001 The command line used to call the tar archiver.
7004 The string displayed when archiving files
7005 using the tar archiver.
7006 If this is not set, then $TARCOM (the command line) is displayed.
7009 env = Environment(TARCOMSTR = "Archiving $TARGET")
7013 General options passed to the tar archiver.
7016 A reserved variable name
7017 that may not be set or used in a construction environment.
7018 (See "Variable Substitution," below.)
7021 A reserved variable name
7022 that may not be set or used in a construction environment.
7023 (See "Variable Substitution," below.)
7026 The suffix used for tar file names.
7029 The TeX formatter and typesetter.
7032 The command line used to call the TeX formatter and typesetter.
7035 The string displayed when calling
7036 the TeX formatter and typesetter.
7037 If this is not set, then $TEXCOM (the command line) is displayed.
7040 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7044 General options passed to the TeX formatter and typesetter.
7047 A list of the names of the Tool specifications
7048 that are part of this construction environment.
7050 .IP WIN32_INSERT_DEF
7051 When this is set to true,
7052 a library build of a WIN32 shared library (.dll file)
7053 will also build a corresponding .def file at the same time,
7054 if a .def file is not already listed as a build target.
7055 The default is 0 (do not build a .def file).
7058 The prefix used for WIN32 .def file names.
7061 The suffix used for WIN32 .def file names.
7064 The parser generator.
7067 The command line used to call the parser generator
7068 to generate a source file.
7071 The string displayed when generating a source file
7072 using the parser generator.
7073 If this is not set, then $YACCCOM (the command line) is displayed.
7076 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7080 General options passed to the parser generator.
7081 If $YACCFLAGS contains a \-d option,
7082 SCons assumes that the call will also create a .h file
7083 (if the yacc source file ends in a .y suffix)
7085 (if the yacc source file ends in a .yy suffix)
7088 The zip compression and file packaging utility.
7091 The command line used to call the zip utility,
7092 or the internal Python function used to create a
7096 The string displayed when archiving files
7097 using the zip utility.
7098 If this is not set, then $ZIPCOM
7099 (the command line or internal Python function) is displayed.
7102 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7111 module used by the internal Python function
7112 to control whether the zip archive
7113 is compressed or not.
7114 The default value is
7115 .BR zipfile.ZIP_DEFLATED ,
7116 which creates a compressed zip archive.
7117 This value has no effect when using Python 1.5.2
7120 module is otherwise unavailable.
7123 General options passed to the zip utility.
7126 Construction variables can be retrieved and set using the
7128 method of the construction environment:
7131 dict = env.Dictionary()
7135 or using the [] operator:
7141 Construction variables can also be passed to the construction environment
7145 env = Environment(CC="cc")
7148 or when copying a construction environment using the
7153 env2 = env.Copy(CC="cl.exe")
7156 .SS Configure Contexts
7160 .I configure contexts,
7161 an integrated mechanism similar to the
7162 various AC_CHECK macros in GNU autoconf
7163 for testing for the existence of C header
7164 files, libraries, etc.
7165 In contrast to autoconf,
7167 does not maintain an explicit cache of the tested values,
7168 but uses its normal dependency tracking to keep the checked values
7169 up to date. However, users may override this behaviour with the
7171 command line option.
7173 The following methods can be used to perform checks:
7176 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7178 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7179 This creates a configure context, which can be used to perform checks.
7181 specifies the environment for building the tests.
7182 This environment may be modified when performing checks.
7184 is a dictionary containing custom tests.
7185 See also the section about custom tests below.
7186 By default, no custom tests are added to the configure context.
7188 specifies a directory where the test cases are built.
7189 Note that this directory is not used for building
7191 The default value is the directory
7194 specifies a file which collects the output from commands
7195 that are executed to check for the existence of header files, libraries, etc.
7196 The default is the file #/config.log.
7197 If you are using the
7200 you may want to specify a subdirectory under your build directory.
7202 specifies a C header file where the results of tests
7203 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7204 The default is to not write a
7207 You can specify the same
7209 file in multiple calls to Configure,
7212 will concatenate all results in the specified file.
7214 uses its normal dependency checking
7215 to decide if it's necessary to rebuild
7219 This means that the file is not necessarily re-built each
7221 but is only rebuilt if its contents will have changed
7222 and some target that depends on the
7224 file is being built.
7229 instance has the following associated methods:
7232 .RI Configure.Finish( self )
7233 This method should be called after configuration is done.
7234 It returns the environment as modified
7235 by the configuration checks performed.
7236 After this method is called, no further checks can be performed
7237 with this configuration context.
7238 However, you can create a new
7240 context to perform additional checks.
7241 Only one context should be active at a time.
7243 The following Checks are predefined.
7244 (This list will likely grow larger as time
7245 goes by and developers contribute new useful tests.)
7248 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7251 is usable in the specified language.
7254 in which case the last item in the list
7255 is the header file to be checked,
7256 and the previous list items are
7259 lines should precede the
7260 header line being checked for.
7261 The optional argument
7264 a two character string, where the first character denotes the opening
7265 quote and the second character denotes the closing quote.
7266 By default, both characters are " (double quote).
7267 The optional argument
7273 and selects the compiler to be used for the check.
7274 Returns 1 on success and 0 on failure.
7277 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7278 This is a wrapper around
7279 .B Configure.CheckHeader
7282 is usable in the C language.
7285 in which case the last item in the list
7286 is the header file to be checked,
7287 and the previous list items are
7290 lines should precede the
7291 header line being checked for.
7292 The optional argument
7295 a two character string, where the first character denotes the opening
7296 quote and the second character denotes the closing quote (both default
7298 Returns 1 on success and 0 on failure.
7301 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7302 This is a wrapper around
7303 .B Configure.CheckHeader
7306 is usable in the C++ language.
7309 in which case the last item in the list
7310 is the header file to be checked,
7311 and the previous list items are
7314 lines should precede the
7315 header line being checked for.
7316 The optional argument
7319 a two character string, where the first character denotes the opening
7320 quote and the second character denotes the closing quote (both default
7322 Returns 1 on success and 0 on failure.
7325 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7326 Checks if the specified
7327 C or C++ function is available.
7329 is the name of the function to check for.
7332 argument is a string
7336 that will be compiled
7337 to check if the function exists;
7343 char function_name();
7351 and selects the compiler to be used for the check;
7355 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
7362 is 1 and the library provides the specified
7364 appends the library to the LIBS construction environment variable.
7366 may also be None (the default),
7369 is checked with the current LIBS variable,
7370 or a list of library names,
7371 in which case each library in the list
7378 you can link against the specified
7386 and selects the compiler to be used for the check;
7388 The default value for
7391 It is assumed, that the C-language is used.
7392 This method returns 1 on success and 0 on error.
7395 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7398 .RI Configure.CheckLib
7399 call, this call provides a more sophisticated way to check against libraries.
7402 specifies the library or a list of libraries to check.
7404 specifies a header to check for.
7407 in which case the last item in the list
7408 is the header file to be checked,
7409 and the previous list items are
7412 lines should precede the
7413 header line being checked for.
7415 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7417 can be any valid expression (with a trailing ';'). The default is 'main();'.
7419 specifies whether to add the library to the environment (only if the check
7420 succeeds). This method returns 1 on success and 0 on error.
7423 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7424 Checks for the existence of a type defined by
7427 specifies the typedef name to check for.
7429 is a string containing one or more
7431 lines that will be inserted into the program
7432 that will be run to test for the existence of the type.
7439 and selects the compiler to be used for the check;
7443 Example of a typical Configure usage:
7447 conf = Configure( env )
7448 if not conf.CheckCHeader( 'math.h' ):
7449 print 'We really need math.h!'
7451 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7452 # do stuff for qt - usage, e.g.
7453 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7458 You can define your own custom checks.
7459 in addition to the predefined checks.
7460 These are passed in a dictionary to the Configure function.
7461 This dictionary maps the names of the checks
7462 to user defined Python callables
7463 (either Python functions or class instances implementing the
7466 The first argument of the call is always a
7468 instance followed by the arguments,
7469 which must be supplied by the user of the check.
7470 These CheckContext instances define the following methods:
7473 .RI CheckContext.Message( self ", " text )
7475 Usually called before the check is started.
7477 will be displayed to the user, e.g. 'Checking for library X...'
7480 .RI CheckContext.Result( self, ", " res )
7482 Usually called after the check is done.
7484 can be either an integer or a string. In the former case, 'ok' (res != 0)
7485 or 'failed' (res == 0) is displayed to the user, in the latter case the
7486 given string is displayed.
7489 .RI CheckContext.TryCompile( self ", " text ", " extension )
7490 Checks if a file with the specified
7492 (e.g. '.c') containing
7494 can be compiled using the environment's
7496 builder. Returns 1 on success and 0 on failure.
7499 .RI CheckContext.TryLink( self ", " text ", " extension )
7500 Checks, if a file with the specified
7502 (e.g. '.c') containing
7504 can be compiled using the environment's
7506 builder. Returns 1 on success and 0 on failure.
7509 .RI CheckContext.TryRun( self ", " text ", " extension )
7510 Checks, if a file with the specified
7512 (e.g. '.c') containing
7514 can be compiled using the environment's
7516 builder. On success, the program is run. If the program
7517 executes successfully
7518 (that is, its return status is 0),
7523 is the standard output of the
7525 If the program fails execution
7526 (its return status is non-zero),
7527 then (0, '') is returned.
7530 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7531 Checks if the specified
7533 with an optional source file (contents
7540 may be anything which can be converted to a
7547 is the content of the target file.
7553 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7554 Low level implementation for testing specific builds;
7555 the methods above are based on this method.
7556 Given the Builder instance
7560 of a source file with optional
7562 this method returns 1 on success and 0 on failure. In addition,
7564 is set to the build target node, if the build was successful.
7567 Example for implementing and using custom tests:
7570 def CheckQt(context, qtdir):
7571 context.Message( 'Checking for qt ...' )
7572 lastLIBS = context.env['LIBS']
7573 lastLIBPATH = context.env['LIBPATH']
7574 lastCPPPATH= context.env['CPPPATH']
7575 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7576 ret = context.TryLink("""
7578 int main(int argc, char **argv) {
7579 QApplication qapp(argc, argv);
7584 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7585 context.Result( ret )
7589 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7590 if not conf.CheckQt('/usr/lib/qt'):
7591 print 'We really need qt!'
7596 .SS Construction Variable Options
7598 Often when building software, various options need to be specified at build
7599 time that are not known when the SConstruct/SConscript files are
7600 written. For example, libraries needed for the build may be in non-standard
7601 locations, or site-specific compiler options may need to be passed to the
7604 provides a mechanism for overridding construction variables from the
7605 command line or a text-based SConscript file through an Options
7606 object. To create an Options object, call the Options() function:
7609 .RI Options([ files "], [" args ])
7610 This creates an Options object that will read construction variables from
7611 the file or list of filenames specified in
7613 If no files are specified,
7618 then no files will be read.
7619 The optional argument
7622 values that will override anything read from the specified files;
7623 it is primarily intended to be passed the
7625 dictionary that holds variables
7626 specified on the command line.
7630 opts = Options('custom.py')
7631 opts = Options('overrides.py', ARGUMENTS)
7632 opts = Options(None, {FOO:'expansion', BAR:7})
7635 Options objects have the following methods:
7638 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7639 This adds a customizable construction variable to the Options object.
7641 is the name of the variable.
7643 is the help text for the variable.
7645 is the default value of the variable;
7646 if the default value is
7648 and there is no explicit value specified,
7649 the construction variable will
7651 be added to the construction environment.
7653 is called to validate the value of the variable, and should take three
7654 arguments: key, value, and environment
7656 is called to convert the value before putting it in the environment, and
7657 should take a single argument: value. Example:
7660 opts.Add('CC', 'The C compiler')
7664 .RI AddOptions( list )
7665 A wrapper script that adds
7666 multiple customizable construction variables
7667 to an Options object.
7669 is a list of tuple or list objects
7670 that contain the arguments
7671 for an individual call to the
7678 ('CC', 'The C compiler'),
7679 ('VALIDATE', 'An option for testing validation',
7680 'notset', validator, None),
7685 .RI Update( env ", [" args ])
7686 This updates a construction environment
7688 with the customized construction variables. Normally this method is not
7689 called directly, but is called indirectly by passing the Options object to
7690 the Environment() function:
7693 env = Environment(options=opts)
7697 .RI Save( filename ", " env )
7698 This saves the currently set options into a script file named
7700 that can be used on the next invocation to automatically load the current
7701 settings. This method combined with the Options method can be used to
7702 support caching of options between runs.
7706 opts = Options(['options.cache', 'custom.py'])
7709 opts.Save('options.cache', env)
7713 .RI GenerateHelpText( env ", [" sort ])
7714 This generates help text documenting the customizable construction
7715 variables suitable to passing in to the Help() function.
7717 is the construction environment that will be used to get the actual values
7718 of customizable variables. Calling with
7722 will cause the output to be sorted
7723 by the specified argument.
7727 should take two arguments
7730 (like the standard Python
7735 Help(opts.GenerateHelpText(env))
7736 Help(opts.GenerateHelpText(env, sort=cmp))
7739 The text based SConscript file is executed as a Python script, and the
7740 global variables are queried for customizable construction
7747 To make it more convenient to work with customizable Options,
7749 provides a number of functions
7750 that make it easy to set up
7751 various types of Options:
7754 .RI BoolOption( key ", " help ", " default )
7755 Return a tuple of arguments
7756 to set up a Boolean option.
7760 have a default value of
7762 and display the specified
7765 The option will interpret the values
7787 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7788 Return a tuple of arguments
7790 whose value may be one
7791 of a specified list of legal enumerated values.
7795 have a default value of
7797 and display the specified
7800 The option will only support those
7806 argument is a dictionary
7807 that can be used to convert
7808 input values into specific legal values
7817 then the values are case-sensitive.
7822 then values will be matched
7828 then values will be matched
7830 and all input values will be
7831 converted to lower case.
7834 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
7835 Return a tuple of arguments
7837 whose value may be one or more
7838 of a specified list of legal enumerated values.
7842 have a default value of
7844 and display the specified
7847 The option will only support the values
7850 or the values in the
7853 More than one value may be specified,
7854 with all values separated by commas.
7855 The default may be a string of
7856 comma-separated default values,
7857 or a list of the default values.
7860 argument is a dictionary
7861 that can be used to convert
7862 input values into specific legal values
7868 .RI PackageOption( key ", " help ", " default )
7869 Return a tuple of arguments
7871 whose value is a path name
7872 of a package that may be
7873 enabled, disabled or
7874 given an explicit path name.
7878 have a default value of
7880 and display the specified
7883 The option will support the values
7890 in which case the specified
7893 or the option may be set to an
7895 (typically the path name to a package
7896 that is being enabled).
7897 The option will also support the values
7903 to disable use of the specified option.
7906 .RI PathOption( key ", " help ", " default ", [" validator ])
7907 Return a tuple of arguments
7909 whose value is expected to be a path name.
7913 have a default value of
7915 and display the specified
7921 that will be called to
7922 verify that the specified path
7925 following ready-made validators:
7926 .BR PathOption.PathExists
7928 which verifies that the specified path exists;
7929 .BR PathOption.PathIsFile ,
7930 which verifies that the specified path is an existing file;
7931 .BR PathOption.PathIsDir ,
7932 which verifies that the specified path is an existing directory;
7934 .BR PathOption.PathIsDirCreate ,
7935 which verifies that the specified path is a directory,
7936 and will create the specified directory if the path exist.
7937 You may supply your own
7940 which must take three arguments
7942 the name of the options variable to be set;
7944 the specified value being checked;
7947 the construction environment)
7948 and should raise an exception
7949 if the specified value is not acceptable.
7952 These functions make it
7953 convenient to create a number
7954 of options with consistent behavior
7955 in a single call to the
7961 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7962 EnumOption('debug', 'debug output and symbols', 'no'
7963 allowed_values=('yes', 'no', 'full'),
7964 map={}, ignorecase=0), # case sensitive
7965 ListOption('shared',
7966 'libraries to build as shared libraries',
7968 names = list_of_libs),
7969 PackageOption('x11',
7970 'use X11 installed here (yes = search some places)',
7972 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7973 PathOption('foopath', 'where the foo library is installed', foopath,
7974 PathOption.PathIsDir),
7979 .SS File and Directory Nodes
7989 Nodes, respectively.
7990 python objects, respectively.
7991 Those objects have several user-visible attributes
7992 and methods that are often useful:
7998 This path is relative to the top-level directory
8002 The build path is the same as the source path if
8007 The absolute build path of the given file or directory.
8017 object representing the
8026 # Get the current build dir's path, relative to top.
8028 # Current dir's absolute path
8030 # Next line is always '.', because it is the top dir's path relative to itself.
8032 File('foo.c').srcnode().path # source path of the given source file.
8034 # Builders also return File objects:
8035 foo = env.Program('foo.c')
8036 print "foo will be built in %s"%foo.path
8042 can be extended to build different types of targets
8043 by adding new Builder objects
8044 to a construction environment.
8046 you should only need to add a new Builder object
8047 when you want to build a new type of file or other external target.
8048 If you just want to invoke a different compiler or other tool
8049 to build a Program, Object, Library, or any other
8050 type of output file for which
8052 already has an existing Builder,
8053 it is generally much easier to
8054 use those existing Builders
8055 in a construction environment
8056 that sets the appropriate construction variables
8059 Builder objects are created
8065 function accepts the following arguments:
8068 The command line string used to build the target from the source.
8071 a list of strings representing the command
8072 to be executed and its arguments
8073 (suitable for enclosing white space in an argument),
8075 mapping source file name suffixes to
8076 any combination of command line strings
8077 (if the builder should accept multiple source file extensions),
8080 (see the next section);
8081 or a list of any of the above.
8084 takes three arguments:
8086 - a list of source nodes,
8088 - a list of target nodes,
8090 - the construction environment.
8093 The prefix that will be prepended to the target file name.
8094 This may be specified as a:
8104 - a function or other callable that takes
8105 two arguments (a construction environment and a list of sources)
8106 and returns a prefix,
8111 - specifies a mapping from a specific source suffix (of the first
8112 source specified) to a corresponding target prefix. Both the source
8113 suffix and target prefix specifications may use environment variable
8114 substitution, and the target prefix (the 'value' entries in the
8115 dictionary) may also be a callable object. The default target prefix
8116 may be indicated by a dictionary entry with a key value of None.
8121 b = Builder("build_it < $SOURCE > $TARGET"
8124 def gen_prefix(env, sources):
8125 return "file-" + env['PLATFORM'] + '-'
8126 b = Builder("build_it < $SOURCE > $TARGET",
8127 prefix = gen_prefix)
8129 b = Builder("build_it < $SOURCE > $TARGET",
8130 suffix = { None: "file-",
8131 "$SRC_SFX_A": gen_prefix })
8135 The suffix that will be appended to the target file name.
8136 This may be specified in the same manner as the prefix above.
8137 If the suffix is a string, then
8139 will append a '.' to the beginning of the suffix if it's not already
8140 there. The string returned by callable object (or obtained from the
8141 dictionary) is untouched and must append its own '.' to the beginning
8145 b = Builder("build_it < $SOURCE > $TARGET"
8148 def gen_suffix(env, sources):
8149 return "." + env['PLATFORM'] + "-file"
8150 b = Builder("build_it < $SOURCE > $TARGET",
8151 suffix = gen_suffix)
8153 b = Builder("build_it < $SOURCE > $TARGET",
8154 suffix = { None: ".sfx1",
8155 "$SRC_SFX_A": gen_suffix })
8159 The expected source file name suffix. This may be a string or a list
8163 A Scanner object that
8164 will be invoked to find
8165 implicit dependencies for this target file.
8166 This keyword argument should be used
8167 for Scanner objects that find
8168 implicit dependencies
8169 based only on the target file
8170 and the construction environment,
8173 (See the section "Scanner Objects," below,
8174 for information about creating Scanner objects.)
8177 A Scanner object that
8179 find implicit dependences in
8181 used to build this target file.
8182 This is where you would
8183 specify a scanner to
8186 lines in source files.
8189 Scanner object may be used to
8190 indicate that this Builder
8191 should scan directory trees
8192 for on-disk changes to files
8195 does not know about from other Builder or function calls.
8196 (See the section "Scanner Objects," below,
8197 for information about creating your own Scanner objects.)
8200 A factory function that the Builder will use
8201 to turn any targets specified as strings into SCons Nodes.
8203 SCons assumes that all targets are files.
8204 Other useful target_factory
8207 for when a Builder creates a directory target,
8210 for when a Builder can create either a file
8211 or directory target.
8216 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8218 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8219 env.MakeDirectory('new_directory', [])
8223 A factory function that the Builder will use
8224 to turn any sources specified as strings into SCons Nodes.
8226 SCons assumes that all source are files.
8227 Other useful source_factory
8230 for when a Builder uses a directory as a source,
8233 for when a Builder can use files
8234 or directories (or both) as sources.
8239 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8241 env.Append(BUILDERS = {'Collect':CollectBuilder})
8242 env.Collect('archive', ['directory_name', 'file_name'])
8246 A function or list of functions to manipulate the target and source
8247 lists before dependencies are established
8248 and the target(s) are actually built.
8250 can also be a string containing a construction variable to expand
8251 to an emitter function or list of functions,
8252 or a dictionary mapping source file suffixes
8253 to emitter functions.
8254 (Only the suffix of the first source file
8255 is used to select the actual emitter function
8256 from an emitter dictionary.)
8259 takes three arguments:
8261 - a list of source nodes,
8263 - a list of target nodes,
8265 - the construction environment.
8266 An emitter must return a tuple containing two lists,
8267 the list of targets to be built by this builder,
8268 and the list of sources for this builder.
8273 def e(target, source, env):
8274 return (target + ['foo.foo'], source + ['foo.src'])
8276 # Simple association of an emitter function with a Builder.
8277 b = Builder("my_build < $TARGET > $SOURCE",
8280 def e2(target, source, env):
8281 return (target + ['bar.foo'], source + ['bar.src'])
8283 # Simple association of a list of emitter functions with a Builder.
8284 b = Builder("my_build < $TARGET > $SOURCE",
8287 # Calling an emitter function through a construction variable.
8288 env = Environment(MY_EMITTER = e)
8289 b = Builder("my_build < $TARGET > $SOURCE",
8290 emitter = '$MY_EMITTER')
8292 # Calling a list of emitter functions through a construction variable.
8293 env = Environment(EMITTER_LIST = [e, e2])
8294 b = Builder("my_build < $TARGET > $SOURCE",
8295 emitter = '$EMITTER_LIST')
8297 # Associating multiple emitters with different file
8298 # suffixes using a dictionary.
8299 def e_suf1(target, source, env):
8300 return (target + ['another_target_file'], source)
8301 def e_suf2(target, source, env):
8302 return (target, source + ['another_source_file'])
8303 b = Builder("my_build < $TARGET > $SOURCE",
8304 emitter = {'.suf1' : e_suf1,
8312 arguments must not both be used for the same Builder.
8315 Specifies whether this builder is allowed to be called multiple times for
8316 the same target file(s). The default is 0, which means the builder
8317 can not be called multiple times for the same target file(s). Calling a
8318 builder multiple times for the same target simply adds additional source
8319 files to the target; it is not allowed to change the environment associated
8320 with the target, specify addition environment overrides, or associate a different
8321 builder with the target.
8324 A construction environment that can be used
8325 to fetch source code using this Builder.
8326 (Note that this environment is
8328 used for normal builds of normal target files,
8329 which use the environment that was
8330 used to call the Builder for the target file.)
8333 A function that returns a list of actions that will be executed to build
8334 the target(s) from the source(s).
8335 The returned action(s) may be
8336 an Action object, or anything that
8337 can be converted into an Action object
8338 (see the next section).
8340 The generator function
8341 takes four arguments:
8343 - a list of source nodes,
8345 - a list of target nodes,
8347 - the construction environment,
8349 - a Boolean value that specifies
8350 whether the generator is being called
8351 for generating a build signature
8352 (as opposed to actually executing the command).
8356 def g(source, target, env, for_signature):
8357 return [["gcc", "-c", "-o"] + target + source]
8359 b = Builder(generator=g)
8363 Specifies a builder to use when a source file name suffix does not match
8364 any of the suffixes of the builder. Using this argument produces a
8365 multi-stage builder.
8368 Specifies that this builder expects exactly one source file per call. Giving
8369 more than one source files without target files results in implicitely calling
8370 the builder multiple times (once for each source given). Giving multiple
8371 source files together with target files results in a UserError exception.
8379 arguments must not both be used for the same Builder.
8382 A construction environment that can be used
8383 to fetch source code using this Builder.
8384 (Note that this environment is
8386 used for normal builds of normal target files,
8387 which use the environment that was
8388 used to call the Builder for the target file.)
8391 b = Builder(action="build < $SOURCE > $TARGET")
8392 env = Environment(BUILDERS = {'MyBuild' : b})
8393 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8397 A directory from which scons
8404 a string or a directory Node,
8405 scons will change to the specified directory.
8408 is not a string or Node
8410 then scons will change to the
8411 target file's directory.
8413 Note that scons will
8415 automatically modify
8417 construction variables like
8421 when using the chdir
8422 keyword argument--that is,
8423 the expanded file names
8424 will still be relative to
8425 the top-level SConstruct directory,
8426 and consequently incorrect
8427 relative to the chdir directory.
8428 Builders created using chdir keyword argument,
8429 will need to use construction variable
8434 to use just the filename portion of the
8438 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8440 env = Environment(BUILDERS = {'MyBuild' : b})
8441 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8445 Any additional keyword arguments supplied
8446 when a Builder object is created
8447 (that is, when the Builder() function is called)
8448 will be set in the executing construction
8449 environment when the Builder object is called.
8450 The canonical example here would be
8451 to set a construction variable to
8452 the repository of a source code system.
8454 Any additional keyword arguments supplied
8458 will only be associated with the target
8459 created by that particular Builder call
8460 (and any other files built as a
8461 result of the call).
8463 These extra keyword arguments are passed to the
8464 following functions:
8465 command generator functions,
8467 and emitter functions.
8473 function will turn its
8475 keyword argument into an appropriate
8476 internal Action object.
8477 You can also explicity create Action objects
8481 which can then be passed to the
8484 This can be used to configure
8485 an Action object more flexibly,
8486 or it may simply be more efficient
8487 than letting each separate Builder object
8488 create a separate Action
8490 Builder objects need to do the same thing.
8495 returns an appropriate object for the action
8496 represented by the type of the first argument:
8499 If the first argument is already an Action object,
8500 the object is simply returned.
8503 If the first argument is a string,
8504 a command-line Action is returned.
8507 Action('$CC -c -o $TARGET $SOURCES')
8510 .\" XXX From Gary Ruben, 23 April 2002:
8511 .\" What would be useful is a discussion of how you execute command
8512 .\" shell commands ie. what is the process used to spawn the shell, pass
8513 .\" environment variables to it etc., whether there is one shell per
8514 .\" environment or one per command etc. It might help to look at the Gnu
8515 .\" make documentation to see what they think is important to discuss about
8516 .\" a build system. I'm sure you can do a better job of organising the
8517 .\" documentation than they have :-)
8521 If the first argument is a list,
8522 then a list of Action objects is returned.
8523 An Action object is created as necessary
8524 for each element in the list.
8527 the list is itself a list,
8528 the internal list is the
8529 command and arguments to be executed via
8531 This allows white space to be enclosed
8532 in an argument by defining
8533 a command in a list within a list:
8536 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8540 If the first argument is a Python function,
8541 a function Action is returned.
8542 The Python function takes three keyword arguments,
8544 (a Node object representing the target file),
8546 (a Node object representing the source file)
8549 (the construction environment
8550 used for building the target file).
8555 arguments may be lists of Node objects if there is
8556 more than one target file or source file.
8557 The actual target and source file name(s) may
8558 be retrieved from their Node objects
8559 via the built-in Python str() function:
8562 target_file_name = str(target)
8563 source_file_names = map(lambda x: str(x), source)
8566 The function should return
8570 to indicate a successful build of the target file(s).
8571 The function may raise an exception
8572 or return a non-zero exit status
8573 to indicate an unsuccessful build.
8576 def build_it(target = None, source = None, env = None):
8577 # build the target from the source
8580 a = Action(build_it)
8583 If the action argument is not one of the above,
8586 The second, optional argument
8587 is a Python function that returns
8588 a string to be printed to describe the action being executed.
8589 Like a function to build a file,
8590 this function takes three arguments:
8592 (a Node object representing the target file),
8594 (a Node object representing the source file)
8597 (a construction environment).
8602 arguments may be lists of Node objects if there is
8603 more than one target file or source file.
8607 def build_it(target, source, env):
8608 # build the target from the source
8611 def string_it(target, source, env):
8612 return "building '%s' from '%s'" % (target[0], source[0])
8614 # Use a positional argument.
8615 a = Action(build_it, string_it)
8617 # Alternatively, use a keyword argument.
8618 a = Action(build_it, strfunction=string_it)
8621 The third, also optional argument
8622 is a list of construction variables
8623 whose values will be included
8624 in the signature of the Action
8625 when deciding whether a target should
8626 be rebuilt because the action changed.
8627 This is necessary whenever you want a target to
8628 be rebuilt when a specific
8629 construction variable changes,
8630 because the underlying Python code for a function
8631 will not change when the value of the construction variable does.
8634 def build_it(target, source, env):
8635 # build the target from the 'XXX' construction variable
8636 open(target[0], 'w').write(env['XXX'])
8639 def string_it(target, source):
8640 return "building '%s' from '%s'" % (target[0], source[0])
8642 # Use positional arguments.
8643 a = Action(build_it, string_it, ['XXX'])
8645 # Alternatively, use a keyword argument.
8646 a = Action(build_it, varlist=['XXX'])
8656 which specifies that
8657 scons will execute the action
8658 after changing to the specified directory.
8659 If the chdir argument is
8660 a string or a directory Node,
8661 scons will change to the specified directory.
8662 If the chdir argument
8663 is not a string or Node
8665 then scons will change to the
8666 target file's directory.
8668 Note that scons will
8670 automatically modify
8672 construction variables like
8676 when using the chdir
8677 keyword argument--that is,
8678 the expanded file names
8679 will still be relative to
8680 the top-level SConstruct directory,
8681 and consequently incorrect
8682 relative to the chdir directory.
8683 Builders created using chdir keyword argument,
8684 will need to use construction variable
8689 to use just the filename portion of the
8693 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8697 .SS Miscellaneous Action Functions
8700 supplies a number of functions
8701 that arrange for various common
8702 file and directory manipulations
8704 These are similar in concept to "tasks" in the
8706 although the implementation is slightly different.
8707 These functions do not actually
8708 perform the specified action
8709 at the time the function is called,
8710 but instead return an Action object
8711 that can be executed at the
8713 (In Object-Oriented terminology,
8718 that return Action objects.)
8721 there are two natural ways
8724 are intended to be used.
8728 to perform the action
8729 at the time the SConscript
8733 global function to do so:
8735 Execute(Touch('file'))
8739 you can use these functions
8740 to supply Actions in a list
8744 This can allow you to
8745 perform more complicated
8746 sequences of file manipulation
8748 on platform-specific
8752 env = Environment(TMPBUILD = '/tmp/builddir')
8753 env.Command('foo.out', 'foo.in',
8754 [Mkdir('$TMPBUILD'),
8755 Copy('${SOURCE.dir}', '$TMPBUILD')
8756 "cd $TMPBUILD && make",
8757 Delete('$TMPBUILD')])
8761 .RI Chmod( dest ", " mode )
8762 Returns an Action object that
8763 changes the permissions on the specified
8765 file or directory to the specified
8770 Execute(Chmod('file', 0755))
8772 env.Command('foo.out', 'foo.in',
8773 [Copy('$TARGET', '$SOURCE'),
8774 Chmod('$TARGET', 0755)])
8778 .RI Copy( dest ", " src )
8779 Returns an Action object
8782 source file or directory to the
8784 destination file or directory.
8788 Execute(Copy('foo.output', 'foo.input'))
8790 env.Command('bar.out', 'bar.in',
8791 Copy('$TARGET', '$SOURCE'))
8795 .RI Delete( entry ", [" must_exist ])
8796 Returns an Action that
8797 deletes the specified
8799 which may be a file or a directory tree.
8800 If a directory is specified,
8801 the entire directory tree
8806 then a Python error will be thrown
8807 if the specified entry does not exist;
8810 that is, the Action will silently do nothing
8811 if the entry does not exist.
8815 Execute(Delete('/tmp/buildroot'))
8817 env.Command('foo.out', 'foo.in',
8818 [Delete('${TARGET.dir}'),
8821 Execute(Delete('file_that_must_exist', must_exist=1))
8827 that creates the specified
8833 Execute(Mkdir('/tmp/outputdir'))
8835 env.Command('foo.out', 'foo.in',
8836 [Mkdir('/tmp/builddir',
8837 Copy('$SOURCE', '/tmp/builddir')
8838 "cd /tmp/builddir && ])
8843 .RI Move( dest ", " src )
8845 that moves the specified
8847 file or directory to
8854 Execute(Move('file.destination', 'file.source'))
8856 env.Command('output_file', 'input_file',
8858 Move('$TARGET', 'file_created_by_MyBuildAction')])
8864 that updates the modification time
8870 Execute(Touch('file_to_be_touched'))
8872 env.Command('marker', 'input_file',
8877 .SS Variable Substitution
8879 Before executing a command,
8881 performs construction variable interpolation on the strings that make up
8882 the command line of builders.
8883 Variables are introduced by a
8886 Besides construction variables, scons provides the following
8887 variables for each command execution:
8890 The file name of the target being built, or the file name of the first
8891 target if multiple targets are being built.
8894 The file names of all targets being built.
8897 The file name of the source of the build command, or the file name of the
8898 first source if multiple sources are being built.
8901 The file names of the sources of the build command.
8903 (Note that the above variables are reserved
8904 and may not be set in a construction environment.)
8907 For example, given the construction variable CC='cc', targets=['foo'], and
8908 sources=['foo.c', 'bar.c']:
8911 action='$CC -c -o $TARGET $SOURCES'
8914 would produce the command line:
8917 cc -c -o foo foo.c bar.c
8920 Variable names may be surrounded by curly braces ({})
8921 to separate the name from the trailing characters.
8922 Within the curly braces, a variable name may have
8923 a Python slice subscript appended to select one
8924 or more items from a list.
8925 In the previous example, the string:
8937 Additionally, a variable name may
8938 have the following special
8939 modifiers appended within the enclosing curly braces
8940 to modify the interpolated string:
8943 The base path of the file name,
8944 including the directory path
8945 but excluding any suffix.
8948 The name of the directory in which the file exists.
8952 minus any directory portion.
8955 Just the basename of the file,
8957 and minus the directory.
8960 Just the file suffix.
8963 The absolute path name of the file.
8966 The POSIX form of the path,
8967 with directories separated by
8971 This is sometimes necessary on Win32 systems
8972 when a path references a file on other (POSIX) systems.
8975 The directory and file name to the source file linked to this file
8976 through BuildDir. If this file isn't linked, it just returns the
8977 directory and filename unchanged.
8980 The directory containing the source file linked to this file
8981 through BuildDir. If this file isn't linked, it just returns the
8982 directory part of the filename.
8985 The directory and file name to the source file linked to this file
8986 through BuildDir. If the file does not exist locally but exists in
8987 a Repository, the path in the Repository is returned.
8988 If this file isn't linked, it just returns the
8989 directory and filename unchanged.
8992 The Repository directory containing the source file linked to this file
8993 through BuildDir. If this file isn't linked, it just returns the
8994 directory part of the filename.
8997 For example, the specified target will
8998 expand as follows for the corresponding modifiers:
9001 $TARGET => sub/dir/file.x
9002 ${TARGET.base} => sub/dir/file
9003 ${TARGET.dir} => sub/dir
9004 ${TARGET.file} => file.x
9005 ${TARGET.filebase} => file
9006 ${TARGET.suffix} => .x
9007 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9009 BuildDir('sub/dir','src')
9010 $SOURCE => sub/dir/file.x
9011 ${SOURCE.srcpath} => src/file.x
9012 ${SOURCE.srcdir} => src
9014 Repository('/usr/repository')
9015 $SOURCE => sub/dir/file.x
9016 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9017 ${SOURCE.rsrcdir} => /usr/repository/src
9020 Lastly, a variable name
9021 may be a callable Python function
9023 construction variable in the environment.
9025 take four arguments:
9027 - a list of target nodes,
9029 - a list of source nodes,
9031 - the construction environment,
9033 - a Boolean value that specifies
9034 whether the function is being called
9035 for generating a build signature.
9036 SCons will insert whatever
9037 the called function returns
9038 into the expanded string:
9041 def foo(target, source, env, for_signature):
9044 # Will expand $BAR to "bar baz"
9045 env=Environment(FOO=foo, BAR="$FOO baz")
9048 You can use this feature to pass arguments to a
9049 Python function by creating a callable class
9050 that stores one or more arguments in an object,
9051 and then uses them when the
9054 Note that in this case,
9055 the entire variable expansion must
9056 be enclosed by curly braces
9057 so that the arguments will
9058 be associated with the
9059 instantiation of the class:
9063 def __init__(self, arg):
9066 def __call__(self, target, source, env, for_signature):
9069 # Will expand $BAR to "my argument bar baz"
9070 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9074 The special pseudo-variables
9078 may be used to surround parts of a command line
9081 causing a rebuild--that is,
9082 which are not included in the signature
9083 of target files built with this command.
9088 will be removed from the command line
9089 before it is added to file signatures,
9094 will be removed before the command is executed.
9095 For example, the command line:
9098 echo Last build occurred $( $TODAY $). > $TARGET
9102 would execute the command:
9105 echo Last build occurred $TODAY. > $TARGET
9109 but the command signature added to any target files would be:
9112 echo Last build occurred . > $TARGET
9115 SCons uses the following rules when converting construction variables into
9119 When the value is a string it is interpreted as a space delimited list of
9120 command line arguments.
9123 When the value is a list it is interpreted as a list of command line
9124 arguments. Each element of the list is converted to a string.
9127 Anything that is not a list or string is converted to a string and
9128 interpreted as a single command line argument.
9131 Newline characters (\\n) delimit lines. The newline parsing is done after
9132 all other parsing, so it is not possible for arguments (e.g. file names) to
9133 contain embedded newline characters. This limitation will likely go away in
9134 a future version of SCons.
9142 new file types for implicit dependencies.
9143 Scanner accepts the following arguments:
9146 A Python function that will process
9148 and return a list of strings (file names)
9149 representing the implicit
9150 dependencies found in the contents.
9151 The function takes three or four arguments:
9153 def scanner_function(node, env, path):
9155 def scanner_function(node, env, path, arg):
9159 argument is the internal
9160 SCons node representing the file.
9163 to fetch the name of the file, and
9164 .B node.get_contents()
9165 to fetch contents of the file.
9169 argument is the construction environment for the scan.
9170 Fetch values from it using the
9176 argument is a tuple (or list)
9177 of directories that can be searched
9179 This will usually be the tuple returned by the
9181 argument (see below).
9185 argument is the argument supplied
9186 when the scanner was created, if any.
9189 The name of the Scanner.
9191 to identify the Scanner internally.
9194 An optional argument that, if specified,
9195 will be passed to the scanner function
9197 and the path function
9201 An optional list that can be used to
9202 determine which scanner should be used for
9204 In the usual case of scanning for file names,
9205 this argument will be a list of suffixes
9206 for the different file types that this
9207 Scanner knows how to scan.
9208 If the argument is a string,
9209 then it will be expanded
9210 into a list by the current environment.
9213 A Python function that takes
9214 two or three arguments:
9215 a construction environment, directory Node,
9216 and optional argument supplied
9217 when the scanner was created.
9220 returns a tuple of directories
9221 that can be searched for files to be returned
9222 by this Scanner object.
9225 The class of Node that should be returned
9226 by this Scanner object.
9227 Any strings or other objects returned
9228 by the scanner function
9229 that are not of this class
9230 will be run through the
9235 A Python function that will take a string
9237 and turn it into the appropriate class of Node
9238 to be returned by this Scanner object.
9241 An optional Python function that takes two arguments,
9242 a Node (file) and a construction environment,
9243 and returns whether the
9244 Node should, in fact,
9245 be scanned for dependencies.
9246 This check can be used to eliminate unnecessary
9247 calls to the scanner function when,
9248 for example, the underlying file
9249 represented by a Node does not yet exist.
9252 An optional flag that
9253 specifies whether this scanner should be re-invoked
9254 on the dependency files returned by the scanner.
9255 When this flag is not set,
9256 the Node subsystem will
9257 only invoke the scanner on the file being scanned,
9258 and not (for example) also on the files
9259 specified by the #include lines
9260 in the file being scanned.
9262 may be a callable function,
9263 in which case it will be called with a list of
9265 should return a list of Nodes
9266 that should be scanned recursively;
9267 this can be used to select a specific subset of
9268 Nodes for additional scanning.
9273 .B SourceFileScanner
9274 object that is used by
9277 .BR SharedObject (),
9281 which scanner should be used
9282 for different file extensions.
9284 .BR SourceFileScanner.add_scanner ()
9285 method to add your own Scanner object
9289 that builds target programs or
9290 libraries from a list of
9291 source files of different types:
9294 def xyz_scan(node, env, path):
9295 contents = node.get_contents()
9296 # Scan the contents and return the included files.
9298 XYZScanner = Scanner(xyz_scan)
9300 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9302 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9305 .SH SYSTEM-SPECIFIC BEHAVIOR
9306 SCons and its configuration files are very portable,
9307 due largely to its implementation in Python.
9308 There are, however, a few portability
9309 issues waiting to trap the unwary.
9311 SCons handles the upper-case
9313 file suffix differently,
9314 depending on the capabilities of
9315 the underlying system.
9316 On a case-sensitive system
9317 such as Linux or UNIX,
9318 SCons treats a file with a
9320 suffix as a C++ source file.
9321 On a case-insensitive system
9323 SCons treats a file with a
9325 suffix as a C source file.
9327 SCons handles the upper-case
9329 file suffix differently,
9330 depending on the capabilities of
9331 the underlying system.
9332 On a case-sensitive system
9333 such as Linux or UNIX,
9334 SCons treats a file with a
9336 suffix as a Fortran source file
9337 that is to be first run through
9338 the standard C preprocessor.
9339 On a case-insensitive system
9341 SCons treats a file with a
9343 suffix as a Fortran source file that should
9345 be run through the C preprocessor.
9346 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9347 Cygwin supplies a set of tools and utilities
9348 that let users work on a
9349 Windows system using a more POSIX-like environment.
9350 The Cygwin tools, including Cygwin Python,
9352 by sharing an ability to interpret UNIX-like path names.
9353 For example, the Cygwin tools
9354 will internally translate a Cygwin path name
9355 like /cygdrive/c/mydir
9356 to an equivalent Windows pathname
9357 of C:/mydir (equivalent to C:\\mydir).
9360 that are built for native Windows execution,
9361 such as the python.org and ActiveState versions,
9362 do not have the Cygwin path name semantics.
9363 This means that using a native Windows version of Python
9364 to build compiled programs using Cygwin tools
9365 (such as gcc, bison, and flex)
9366 may yield unpredictable results.
9367 "Mixing and matching" in this way
9368 can be made to work,
9369 but it requires careful attention to the use of path names
9370 in your SConscript files.
9372 In practice, users can sidestep
9373 the issue by adopting the following rules:
9375 use the Cygwin-supplied Python interpreter
9377 when using Microsoft Visual C/C++
9378 (or some other Windows compiler)
9379 use the python.org or ActiveState version of Python
9381 .SS WIN32: scons.bat file
9383 SCons is executed via a wrapper
9386 This has (at least) two ramifications:
9388 First, Windows command-line users
9389 that want to use variable assignment
9391 may have to put double quotes
9392 around the assignments:
9395 scons "FOO=BAR" "BAZ=BLEH"
9398 Second, the Cygwin shell does not
9399 recognize this file as being the same
9402 command issued at the command-line prompt.
9403 You can work around this either by
9406 from the Cygwin command line,
9407 or by creating a wrapper shell
9413 The MinGW bin directory must be in your PATH environment variable or the
9414 PATH variable under the ENV construction variable for SCons
9415 to detect and use the MinGW tools. When running under the native Windows
9416 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9417 tools, if they are both installed, regardless of the order of the bin
9418 directories in the PATH variable. If you have both MSVC and MinGW
9419 installed and you want to use MinGW instead of MSVC,
9420 then you must explictly tell SCons to use MinGW by passing
9426 to the Environment() function, because SCons will prefer the MSVC tools
9427 over the MinGW tools.
9431 To help you get started using SCons,
9432 this section contains a brief overview of some common tasks.
9434 .SS Basic Compilation From a Single Source File
9438 env.Program(target = 'foo', source = 'foo.c')
9441 Note: Build the file by specifying
9442 the target as an argument
9443 ("scons foo" or "scons foo.exe").
9444 or by specifying a dot ("scons .").
9446 .SS Basic Compilation From Multiple Source Files
9450 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9453 .SS Setting a Compilation Flag
9456 env = Environment(CCFLAGS = '-g')
9457 env.Program(target = 'foo', source = 'foo.c')
9460 .SS Search The Local Directory For .h Files
9464 need to set CCFLAGS to specify -I options by hand.
9465 SCons will construct the right -I options from CPPPATH.
9468 env = Environment(CPPPATH = ['.'])
9469 env.Program(target = 'foo', source = 'foo.c')
9472 .SS Search Multiple Directories For .h Files
9475 env = Environment(CPPPATH = ['include1', 'include2'])
9476 env.Program(target = 'foo', source = 'foo.c')
9479 .SS Building a Static Library
9483 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9484 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9487 .SS Building a Shared Library
9491 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9492 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9495 .SS Linking a Local Library Into a Program
9498 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9499 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9500 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9503 .SS Defining Your Own Builder Object
9505 Notice that when you invoke the Builder,
9506 you can leave off the target file suffix,
9507 and SCons will add it automatically.
9510 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9512 src_suffix = '.tex')
9513 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9514 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9516 # The following creates "bar.pdf" from "bar.tex"
9517 env.PDFBuilder(target = 'bar', source = 'bar')
9520 Note also that the above initialization
9521 overwrites the default Builder objects,
9522 so the Environment created above
9523 can not be used call Builders like env.Program(),
9524 env.Object(), env.StaticLibrary(), etc.
9526 .SS Adding Your Own Builder Object to an Environment
9529 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9531 src_suffix = '.tex')
9533 env.Append(BUILDERS = {'PDFBuilder' : bld})
9534 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9535 env.Program(target = 'bar', source = 'bar.c')
9538 You also can use other Pythonic techniques to add
9539 to the BUILDERS construction variable, such as:
9543 env['BUILDERS]['PDFBuilder'] = bld
9546 .SS Defining Your Own Scanner Object
9551 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9553 def kfile_scan(node, env, path, arg):
9554 contents = node.get_contents()
9555 includes = include_re.findall(contents)
9558 kscan = Scanner(name = 'kfile',
9559 function = kfile_scan,
9562 scanners = Environment().Dictionary('SCANNERS')
9563 env = Environment(SCANNERS = scanners + [kscan])
9565 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9567 bar_in = File('bar.in')
9568 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9569 bar_in.target_scanner = kscan
9572 .SS Creating a Hierarchical Build
9574 Notice that the file names specified in a subdirectory's
9576 file are relative to that subdirectory.
9582 env.Program(target = 'foo', source = 'foo.c')
9584 SConscript('sub/SConscript')
9589 # Builds sub/foo from sub/foo.c
9590 env.Program(target = 'foo', source = 'foo.c')
9592 SConscript('dir/SConscript')
9597 # Builds sub/dir/foo from sub/dir/foo.c
9598 env.Program(target = 'foo', source = 'foo.c')
9601 .SS Sharing Variables Between SConscript Files
9603 You must explicitly Export() and Import() variables that
9604 you want to share between SConscript files.
9610 env.Program(target = 'foo', source = 'foo.c')
9613 SConscript('subdirectory/SConscript')
9615 subdirectory/SConscript:
9618 env.Program(target = 'foo', source = 'foo.c')
9621 .SS Building Multiple Variants From the Same Source
9623 Use the BuildDir() method to establish
9624 one or more separate build directories for
9625 a given source directory,
9626 then use the SConscript() method
9627 to specify the SConscript files
9628 in the build directories:
9635 BuildDir('foo', 'src')
9636 SConscript('foo/SConscript')
9640 BuildDir('bar', 'src')
9641 SConscript('bar/SConscript')
9646 env = Environment(CCFLAGS = ccflags)
9647 env.Program(target = 'src', source = 'src.c')
9650 Note the use of the Export() method
9651 to set the "ccflags" variable to a different
9652 value for each variant build.
9654 .SS Hierarchical Build of Two Libraries Linked With a Program
9659 env = Environment(LIBPATH = ['#libA', '#libB'])
9661 SConscript('libA/SConscript')
9662 SConscript('libB/SConscript')
9663 SConscript('Main/SConscript')
9668 env.Library('a', Split('a1.c a2.c a3.c'))
9673 env.Library('b', Split('b1.c b2.c b3.c'))
9678 e = env.Copy(LIBS = ['a', 'b'])
9679 e.Program('foo', Split('m1.c m2.c m3.c'))
9682 The '#' in the LIBPATH directories specify that they're relative to the
9683 top-level directory, so they don't turn into "Main/libA" when they're
9684 used in Main/SConscript.
9686 Specifying only 'a' and 'b' for the library names
9687 allows SCons to append the appropriate library
9688 prefix and suffix for the current platform
9689 (for example, 'liba.a' on POSIX systems,
9690 'a.lib' on Windows).
9692 .SS Customizing contruction variables from the command line.
9694 The following would allow the C compiler to be specified on the command
9695 line or in the file custom.py.
9698 opts = Options('custom.py')
9699 opts.Add('CC', 'The C compiler.')
9700 env = Environment(options=opts)
9701 Help(opts.GenerateHelpText(env))
9704 The user could specify the C compiler on the command line:
9710 or in the custom.py file:
9716 or get documentation on the options:
9727 .SS Using Microsoft Visual C++ precompiled headers
9729 Since windows.h includes everything and the kitchen sink, it can take quite
9730 some time to compile it over and over again for a bunch of object files, so
9731 Microsoft provides a mechanism to compile a set of headers once and then
9732 include the previously compiled headers in any object file. This
9733 technology is called precompiled headers. The general recipe is to create a
9734 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9735 then include every header you want to precompile in "StdAfx.h", and finally
9736 include "StdAfx.h" as the first header in all the source files you are
9737 compiling to object files. For example:
9741 #include <windows.h>
9742 #include <my_big_header.h>
9761 /* do some other stuff */
9767 env['PCHSTOP'] = 'StdAfx.h'
9768 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9769 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9772 For more information see the document for the PCH builder, and the PCH and
9773 PCHSTOP construction variables. To learn about the details of precompiled
9774 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9776 .SS Using Microsoft Visual C++ external debugging information
9778 Since including debugging information in programs and shared libraries can
9779 cause their size to increase significantly, Microsoft provides a mechanism
9780 for including the debugging information in an external file called a PDB
9781 file. SCons supports PDB files through the PDB construction
9787 env['PDB'] = 'MyApp.pdb'
9788 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9791 For more information see the document for the PDB construction variable.
9796 Specifies the directory that contains the SCons Python module directory
9797 (e.g. /home/aroach/scons-src-0.01/src/engine).
9800 A string of options that will be used by scons in addition to those passed
9801 on the command line.
9812 Steven Knight <knight@baldmt.com>
9814 Anthony Roach <aroach@electriceyeball.com>