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 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2004 .IP env.StaticLibrary()
2005 Builds a static library given one or more object files
2006 or C, C++, D or Fortran source files.
2007 If any source files are given,
2008 then they will be automatically
2009 compiled to object files.
2010 The static library prefix and suffix (if any)
2011 are automatically added to the target.
2012 The target library file prefix
2013 (specified by the $LIBPREFIX construction variable;
2014 by default, lib on POSIX systems, nothing on Windows systems)
2016 (specified by the $LIBSUFFIX construction variable;
2017 by default, .lib on Windows systems, .a on POSIX systems)
2018 are automatically added to the target if not already present.
2022 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2026 Any object files listed in the
2028 must have been built for a static library
2033 will raise an error if there is any mismatch.
2035 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2037 .IP env.StaticObject()
2038 Builds a static object file
2039 from one or more C, C++, D, or Fortran source files.
2040 Source files must have one of the following extensions:
2043 .asm assembly language file
2044 .ASM assembly language file
2056 .F WIN32: Fortran file
2057 POSIX: Fortran file + C pre-processor
2060 .fpp Fortran file + C pre-processor
2061 .FPP Fortran file + C pre-processor
2062 .s assembly language file
2063 .S WIN32: assembly language file
2064 POSIX: assembly language file + C pre-processor
2065 .spp assembly language file + C pre-processor
2066 .SPP assembly language file + C pre-processor
2069 The target object file prefix
2070 (specified by the $OBJPREFIX construction variable; nothing by default)
2072 (specified by the $OBJSUFFIX construction variable;
2073 \.obj on Windows systems, .o on POSIX systems)
2074 are automatically added to the target if not already present.
2078 env.StaticObject(target = 'aaa', source = 'aaa.c')
2079 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2080 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2083 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2086 Builds a tar archive of the specified files
2088 Unlike most builder methods,
2091 builder method may be called multiple times
2093 each additional call
2094 adds to the list of entries
2095 that will be built into the archive.
2098 env.Tar('src.tar', 'src')
2100 # Create the stuff.tar file.
2101 env.Tar('stuff', ['subdir1', 'subdir2'])
2102 # Also add "another" to the stuff.tar file.
2103 env.Tar('stuff', 'another')
2105 # Set TARFLAGS to create a gzip-filtered archive.
2106 env = Environment(TARFLAGS = '-c -z')
2107 env.Tar('foo.tar.gz', 'foo')
2109 # Also set the suffix to .tgz.
2110 env = Environment(TARFLAGS = '-c -z',
2115 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2117 .IP env.TypeLibrary()
2118 Builds a Windows type library (.tlb) file from and input IDL file
2119 (.idl). In addition, it will build the associated inteface stub and
2120 proxy source files. It names them according to the base name of the .idl file.
2125 env.TypeLibrary(source="foo.idl")
2128 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2130 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2133 Builds a header file, an implementation file and a moc file from an ui file.
2134 and returns the corresponding nodes in the above order.
2135 This builder is only available after using the tool 'qt'. Note: you can
2136 specify .ui files directly as inputs for Program, Library and SharedLibrary
2137 without using this builder. Using the builder lets you override the standard
2138 naming conventions (be careful: prefixes are always prepended to names of
2139 built files; if you don't want prefixes, you may set them to ``).
2140 See the QTDIR variable for more information.
2144 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2145 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2146 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2152 Builds a zip archive of the specified files
2154 Unlike most builder methods,
2157 builder method may be called multiple times
2159 each additional call
2160 adds to the list of entries
2161 that will be built into the archive.
2164 env.Zip('src.zip', 'src')
2166 # Create the stuff.zip file.
2167 env.Zip('stuff', ['subdir1', 'subdir2'])
2168 # Also add "another" to the stuff.tar file.
2169 env.Zip('stuff', 'another')
2174 C source files, C++ source files,
2175 Fortran source files with
2177 (POSIX systems only),
2182 and assembly language files with
2184 (POSIX systems only),
2189 for C preprocessor dependencies,
2190 so the dependencies do not need to be specified explicitly.
2192 targets of builder methods automatically depend on their sources.
2193 An explicit dependency can
2194 be specified using the
2196 method of a construction environment (see below).
2198 .SS Methods and Functions to Do Things
2199 In addition to Builder methods,
2201 provides a number of other construction environment methods
2202 and global functions to
2203 manipulate the build configuration.
2205 Usually, a construction environment method
2206 and global function with the same name both exist
2207 so that you don't have to remember whether
2208 to a specific bit of functionality
2209 must be called with or without a construction environment.
2210 In the following list,
2211 if you call something as a global function
2214 .RI Function( arguments )
2216 and if you call something through a construction
2217 environment it looks like:
2219 .RI env.Function( arguments )
2221 If you can call the functionality in both ways,
2222 then both forms are listed.
2224 Global functions may be called from custom Python modules that you
2225 import into an SConscript file by adding the following
2226 to the Python module:
2229 from SCons.Script import *
2232 Except where otherwise noted,
2234 construction environment method
2236 provide the exact same functionality.
2237 The only difference is that,
2239 calling the functionality through a construction environment will
2240 substitute construction variables into
2241 any supplied strings.
2244 env = Environment(FOO = 'foo')
2248 the first call to the global
2250 function will actually add a target named
2252 to the list of default targets,
2253 while the second call to the
2255 construction environment method
2256 will expand the value
2257 and add a target named
2259 to the list of default targets.
2260 For more on construction variable expansion,
2261 see the next section on
2262 construction variables.
2264 Construction environment methods
2265 and global functions supported by
2269 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2271 .RI Action( action ", [" strfunction ", " varlist ])
2273 .RI env.Action( action ", [" strfunction ", " varlist ])
2274 Creates an Action object for
2277 See the section "Action Objects,"
2278 below, for a complete explanation of the arguments and behavior.
2280 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2282 .RI AddPostAction( target ", " action )
2284 .RI env.AddPostAction( target ", " action )
2285 Arranges for the specified
2291 The specified action(s) may be
2292 an Action object, or anything that
2293 can be converted into an Action object
2296 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2298 .RI AddPreAction( target ", " action )
2300 .RI env.AddPreAction( target ", " action )
2301 Arranges for the specified
2304 before the specified
2307 The specified action(s) may be
2308 an Action object, or anything that
2309 can be converted into an Action object
2312 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2314 .RI Alias( alias ", [" targets ", [" action ]])
2316 .RI env.Alias( alias ", [" targets ", [" action ]])
2317 Creates one or more phony targets that
2318 expand to one or more other targets.
2323 can be specified that will be executed
2324 whenever the any of the alias targets are out-of-date.
2325 Returns the Node object representing the alias,
2326 which exists outside of any file system.
2327 This Node object, or the alias name,
2328 may be used as a dependency of any other target,
2329 including another alias.
2331 can be called multiple times for the same
2332 alias to add additional targets to the alias,
2333 or additional actions to the list for this alias.
2337 Alias('install', '/usr/bin')
2338 Alias(['install', 'install-lib'], '/usr/local/lib')
2340 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2341 env.Alias('install', ['/usr/local/man'])
2343 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2348 .RI AlwaysBuild( target ", ...)"
2350 .RI env.AlwaysBuild( target ", ...)"
2353 so that it is always assumed to be out of date,
2354 and will always be rebuilt if needed.
2357 does not add its target(s) to the default target list,
2358 so the targets will only be built
2359 if they are specified on the command line,
2360 or are a dependent of a target specified on the command line--but
2363 be built if so specified.
2364 Multiple targets can be passed in to a single call to
2367 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2369 .RI env.Append( key = val ", [...])"
2370 Appends the specified keyword arguments
2371 to the end of construction variables in the environment.
2372 If the Environment does not have
2373 the specified construction variable,
2374 it is simply added to the environment.
2375 If the values of the construction variable
2376 and the keyword argument are the same type,
2377 then the two values will be simply added together.
2378 Otherwise, the construction variable
2379 and the value of the keyword argument
2380 are both coerced to lists,
2381 and the lists are added together.
2382 (See also the Prepend method, below.)
2385 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2388 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2390 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2391 This appends new path elements to the given path in the
2392 specified external environment
2396 any particular path once (leaving the last one it encounters and
2397 ignoring the rest, to preserve path order),
2398 and to help assure this,
2399 will normalize all paths (using
2402 .BR os.path.normcase ).
2403 This can also handle the
2404 case where the given old path variable is a list instead of a
2405 string, in which case a list will be returned instead of a string.
2409 print 'before:',env['ENV']['INCLUDE']
2410 include_path = '/foo/bar:/foo'
2411 env.PrependENVPath('INCLUDE', include_path)
2412 print 'after:',env['ENV']['INCLUDE']
2416 after: /biz:/foo/bar:/foo
2419 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2421 .RI env.AppendUnique( key = val ", [...])"
2422 Appends the specified keyword arguments
2423 to the end of construction variables in the environment.
2424 If the Environment does not have
2425 the specified construction variable,
2426 it is simply added to the environment.
2427 If the construction variable being appended to is a list,
2428 then any value(s) that already exist in the
2429 construction variable will
2431 be added again to the list.
2434 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2437 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2440 A factory function that
2441 returns a Builder object
2442 to be used to fetch source files
2444 The returned Builder
2445 is intended to be passed to the
2450 env.SourceCode('.', env.BitKeeper())
2453 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2455 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2457 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2458 This specifies a build directory
2460 in which to build all derived files
2461 that would normally be built under
2463 Multiple build directories can be set up for multiple build variants, for
2466 must be underneath the SConstruct file's directory,
2469 may not be underneath the
2472 The default behavior is for
2474 to duplicate all of the files in the tree underneath
2478 and then build the derived files within the copied tree.
2479 (The duplication is performed by
2481 depending on the platform; see also the
2484 This guarantees correct builds
2485 regardless of whether intermediate source files
2486 are generated during the build,
2487 where preprocessors or other scanners search
2489 or whether individual compilers or other invoked tools
2490 are hard-coded to put derived files in the same directory as source files.
2492 This behavior of making a complete copy of the source tree
2493 may be disabled by setting
2498 to invoke Builders using the
2499 path names of source files in
2501 and the path names of derived files within
2503 This is always more efficient than
2505 and is usually safe for most builds.
2509 may cause build problems
2510 if source files are generated during the build,
2511 if any invoked tools are hard-coded to
2512 put derived files in the same directory as the source files.
2514 Note that specifying a
2516 works most naturally
2517 with a subsidiary SConscript file
2518 in the source directory.
2520 you would then call the subsidiary SConscript file
2521 not in the source directory,
2526 had made a virtual copy of the source tree
2527 regardless of the value of
2529 This is how you tell
2531 which variant of a source tree to build.
2535 BuildDir('build-variant1', 'src')
2536 SConscript('build-variant1/SConscript')
2537 BuildDir('build-variant2', 'src')
2538 SConscript('build-variant2/SConscript')
2544 function, described below,
2546 specify a build directory
2547 in conjunction with calling a subsidiary
2550 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2552 .RI Builder( action ", [" arguments ])
2554 .RI env.Builder( action ", [" arguments ])
2555 Creates a Builder object for
2558 See the section "Builder Objects,"
2559 below, for a complete explanation of the arguments and behavior.
2561 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2563 .RI CacheDir( cache_dir )
2565 .RI env.CacheDir( cache_dir )
2568 will maintain a cache of derived files in
2570 The derived files in the cache will be shared
2571 among all the builds using the same
2579 finds a derived file that needs to be rebuilt,
2580 it will first look in the cache to see if a
2581 derived file has already been built
2582 from identical input files and an identical build action
2583 (as incorporated into the MD5 build signature).
2586 will retrieve the file from the cache.
2587 If the derived file is not present in the cache,
2590 then place a copy of the built file in the cache
2591 (identified by its MD5 build signature),
2592 so that it may be retrieved by other
2593 builds that need to build the same derived file
2594 from identical inputs.
2598 may be disabled for any invocation
2607 will place a copy of
2609 derived files in the cache,
2610 even if they already existed
2611 and were not built by this invocation.
2612 This is useful to populate a cache
2615 is added to a build,
2624 "Retrieved `file' from cache,"
2627 option is being used.
2632 will print the action that
2634 have been used to build the file,
2635 without any indication that
2636 the file was actually retrieved from the cache.
2637 This is useful to generate build logs
2638 that are equivalent regardless of whether
2639 a given derived file has been built in-place
2640 or retrieved from the cache.
2642 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2644 .RI Clean( targets ", " files_or_dirs )
2646 .RI env.Clean( targets ", " files_or_dirs )
2647 This specifies a list of files or directories which should be removed
2648 whenever the targets are specified with the
2650 command line option.
2651 The specified targets may be a list
2652 or an individual target.
2656 and create new targets or add files and directories to the
2657 clean list for the specified targets.
2659 Multiple files or directories should be specified
2660 either as separate arguments to the
2662 method, or as a list.
2664 will also accept the return value of any of the construction environment
2669 Clean('foo', ['bar', 'baz'])
2670 Clean('dist', env.Program('hello', 'hello.c'))
2671 Clean(['foo', 'bar'], 'something_else_to_clean')
2674 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2676 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2678 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2679 Executes a specific action
2680 (or list of actions)
2681 to build a target file or files.
2682 This is more convenient
2683 than defining a separate Builder object
2684 for a single special-case build.
2685 Any keyword arguments specified override any
2686 same-named existing construction variables.
2688 Note that an action can be an external command,
2689 specified as a string,
2690 or a callable Python object;
2691 see "Action Objects," below.
2695 env.Command('foo.out', 'foo.in',
2696 "$FOO_BUILD < $SOURCES > $TARGET")
2698 env.Command('bar.out', 'bar.in',
2700 "$BAR_BUILD < $SOURCES > $TARGET"],
2701 ENV = {'PATH' : '/usr/local/bin/'})
2703 def rename(env, target, source):
2705 os.rename('.tmp', str(target[0]))
2707 env.Command('baz.out', 'baz.in',
2708 ["$BAZ_BUILD < $SOURCES > .tmp",
2712 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2714 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2716 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2717 Creates a Configure object for integrated
2718 functionality similar to GNU autoconf.
2719 See the section "Configure Contexts,"
2720 below, for a complete explanation of the arguments and behavior.
2722 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2724 .RI env.Copy([ key = val ", ...])"
2725 Return a separate copy of a construction environment.
2726 If there are any keyword arguments specified,
2727 they are added to the returned copy,
2728 overwriting any existing values
2733 env3 = env.Copy(CCFLAGS = '-g')
2736 Additionally, a list of tools and a toolpath may be specified, as in
2737 the Environment constructor:
2740 def MyTool(env): env['FOO'] = 'bar'
2741 env4 = env.Copy(tools = ['msvc', MyTool])
2744 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2746 .RI env.CVS( repository ", " module )
2747 A factory function that
2748 returns a Builder object
2749 to be used to fetch source files
2753 The returned Builder
2754 is intended to be passed to the
2758 The optional specified
2760 will be added to the beginning
2761 of all repository path names;
2762 this can be used, in essence,
2763 to strip initial directory names
2764 from the repository path names,
2765 so that you only have to
2766 replicate part of the repository
2767 directory hierarchy in your
2768 local build directory:
2771 # Will fetch foo/bar/src.c
2772 # from /usr/local/CVSROOT/foo/bar/src.c.
2773 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2775 # Will fetch bar/src.c
2776 # from /usr/local/CVSROOT/foo/bar/src.c.
2777 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2780 # from /usr/local/CVSROOT/foo/bar/src.c.
2781 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2786 .RI Default( targets )
2788 .RI env.Default( targets )
2789 This specifies a list of default targets,
2790 which will be built by
2792 if no explicit targets are given on the command line.
2796 and add to the list of default targets.
2798 Multiple targets should be specified as
2799 separate arguments to the
2801 method, or as a list.
2803 will also accept the Node returned by any
2804 of a construction environment's
2809 Default('foo', 'bar', 'baz')
2810 env.Default(['a', 'b', 'c'])
2811 hello = env.Program('hello', 'hello.c')
2819 will clear all default targets.
2822 will add to the (now empty) default-target list
2825 The current list of targets added using the
2827 function or method is available in the
2832 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2834 .RI DefaultEnvironment([ args ])
2835 Creates and returns a default construction environment object.
2836 This construction environment is used internally by SCons
2837 in order to execute many of the global functions in this list,
2838 and to fetch source files transparently
2839 from source code management systems.
2841 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2843 .RI Depends( target ", " dependency )
2845 .RI env.Depends( target ", " dependency )
2846 Specifies an explicit dependency;
2847 the target file(s) will be rebuilt
2848 whenever the dependency file(s) has changed.
2849 This should only be necessary
2850 for cases where the dependency
2851 is not caught by a Scanner
2855 env.Depends('foo', 'other-input-file-for-foo')
2858 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2860 .RI env.Dictionary([ vars ])
2861 Returns a dictionary object
2862 containing copies of all of the
2863 construction variables in the environment.
2864 If there are any variable names specified,
2865 only the specified construction
2866 variables are returned in the dictionary.
2869 dict = env.Dictionary()
2870 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2873 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2875 .RI Dir( name ", [" directory ])
2877 .RI env.Dir( name ", [" directory ])
2878 This returns a Directory Node,
2879 an object that represents the specified directory
2882 can be a relative or absolute path.
2884 is an optional directory that will be used as the parent directory.
2887 is specified, the current script's directory is used as the parent.
2889 Directory Nodes can be used anywhere you
2890 would supply a string as a directory name
2891 to a Builder method or function.
2892 Directory Nodes have attributes and methods
2893 that are useful in many situations;
2894 see "File and Directory Nodes," below.
2896 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2898 .RI env.Dump([ key ])
2899 Returns a pretty printable representation of the environment.
2903 should be a string containing the name of the variable of interest.
2908 print env.Dump('CCCOM')
2912 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2922 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2925 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2930 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2932 .RI EnsurePythonVersion( major ", " minor )
2934 .RI env.EnsurePythonVersion( major ", " minor )
2935 Ensure that the Python version is at least
2938 print out an error message and exit SCons with a non-zero exit code if the
2939 actual Python version is not late enough.
2942 EnsurePythonVersion(2,2)
2945 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2947 .RI EnsureSConsVersion( major ", " minor )
2949 .RI env.EnsureSConsVersion( major ", " minor )
2950 Ensure that the SCons version is at least
2953 print out an error message and exit SCons with a non-zero exit code if the
2954 actual SCons version is not late enough.
2957 EnsureSConsVersion(0,9)
2960 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2962 .RI Environment([ key = value ", ...])"
2964 .RI env.Environment([ key = value ", ...])"
2965 Return a new construction environment
2966 initialized with the specified
2970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2972 .RI Execute( action ", [" strfunction ", " varlist ])
2974 .RI env.Execute( action ", [" strfunction ", " varlist ])
2975 Executes an Action object.
2978 may be an Action object
2979 (see the section "Action Objects,"
2980 below, for a complete explanation of the arguments and behavior),
2981 or it may be a command-line string,
2983 or executable Python function,
2984 each of which will be converted
2985 into an Action object
2987 The exit value of the command
2988 or return value of the Python function
2991 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2995 .RI env.Exit([ value ])
3001 A default exit value of
3004 is used if no value is specified.
3006 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3010 .RI env.Export( vars )
3013 to export a list of variables from the current
3014 SConscript file to all other SConscript files.
3015 The exported variables are kept in a global collection,
3016 so subsequent calls to
3018 will over-write previous exports that have the same name.
3019 Multiple variable names can be passed to
3021 as separate arguments or as a list. A dictionary can be used to map
3022 variables to a different name when exported. Both local variables and
3023 global variables can be exported.
3028 # Make env available for all SConscript files to Import().
3032 # Make env and package available for all SConscript files:.
3033 Export("env", "package")
3035 # Make env and package available for all SConscript files:
3036 Export(["env", "package"])
3038 # Make env available using the name debug:.
3039 Export({"debug":env})
3045 function supports an
3047 argument that makes it easier to to export a variable or
3048 set of variables to a single SConscript file.
3049 See the description of the
3053 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3055 .RI File( name ", [" directory ])
3057 .RI env.File( name ", [" directory ])
3060 an object that represents the specified file
3063 can be a relative or absolute path.
3065 is an optional directory that will be used as the parent directory.
3067 File Nodes can be used anywhere you
3068 would supply a string as a file name
3069 to a Builder method or function.
3070 File Nodes have attributes and methods
3071 that are useful in many situations;
3072 see "File and Directory Nodes," below.
3074 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3076 .RI FindFile( file ", " dirs )
3078 .RI env.FindFile( file ", " dirs )
3081 in the path specified by
3084 may be a list of file names or a single file name. In addition to searching
3085 for files that exist in the filesytem, this function also searches for
3086 derived files that have not yet been built.
3089 foo = env.FindFile('foo', ['dir1', 'dir2'])
3092 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3094 .RI Flatten( sequence )
3096 .RI env.Flatten( sequence )
3097 Takes a sequence (that is, a Python list or tuple)
3098 that may contain nested sequences
3099 and returns a flattened list containing
3100 all of the individual elements in any sequence.
3101 This can be helpful for collecting
3102 the lists returned by calls to Builders;
3103 other Builders will automatically
3104 flatten lists specified as input,
3105 but direct Python manipulation of
3106 these lists does not:
3109 foo = Object('foo.c')
3110 bar = Object('bar.c')
3112 # Because `foo' and `bar' are lists returned by the Object() Builder,
3113 # `objects' will be a list containing nested lists:
3114 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3116 # Passing such a list to another Builder is all right because
3117 # the Builder will flatten the list automatically:
3118 Program(source = objects)
3120 # If you need to manipulate the list directly using Python, you need to
3121 # call Flatten() yourself, or otherwise handle nested lists:
3122 for object in Flatten(objects):
3126 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3128 .RI GetBuildPath( file ", [" ... ])
3130 .RI env.GetBuildPath( file ", [" ... ])
3133 path name (or names) for the specified
3141 Nodes or strings representing path names.
3143 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3147 .RI env.GetLaunchDir()
3148 Returns the absolute path name of the directory from which
3151 was initially invoked.
3152 This can be useful when using the
3157 options, which internally
3158 change to the directory in which the
3162 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3164 .RI GetOption( name )
3166 .RI env.GetOption( name )
3167 This function provides a way to query a select subset of the scons command line
3168 options from a SConscript file. See
3170 for a description of the options available.
3172 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3174 '\".RI GlobalBuilders( flag )
3178 '\"adds the names of the default builders
3179 '\"(Program, Library, etc.)
3180 '\"to the global name space
3181 '\"so they can be called without an explicit construction environment.
3182 '\"(This is the default.)
3186 '\"the names of the default builders are removed
3187 '\"from the global name space
3188 '\"so that an explicit construction environment is required
3189 '\"to call all builders.
3191 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3195 .RI env.Help( text )
3196 This specifies help text to be printed if the
3198 argument is given to
3202 is called multiple times, the text is appended together in the order
3207 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3209 .RI Ignore( target ", " dependency )
3211 .RI env.Ignore( target ", " dependency )
3212 The specified dependency file(s)
3213 will be ignored when deciding if
3214 the target file(s) need to be rebuilt.
3217 env.Ignore('foo', 'foo.c')
3218 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3221 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3225 .RI env.Import( vars )
3228 to import a list of variables into the current SConscript file. This
3229 will import variables that were exported with
3235 Variables exported by
3238 Multiple variable names can be passed to
3240 as separate arguments or as a list. The variable "*" can be used
3241 to import all variables.
3246 Import("env", "variable")
3247 Import(["env", "variable"])
3251 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3253 .RI Install( dir ", " source )
3255 .RI env.Install( dir ", " source )
3256 Installs one or more files in a destination directory.
3257 The file names remain the same.
3260 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3263 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3265 .RI InstallAs( target ", " source )
3267 .RI env.InstallAs( target ", " source )
3268 Installs one or more files as specific file names,
3269 allowing changing a file name as part of the
3271 It is an error if the target and source
3272 list different numbers of files.
3275 env.InstallAs(target = '/usr/local/bin/foo',
3276 source = 'foo_debug')
3277 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3278 source = ['libFOO.a', 'libBAR.a'])
3281 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3283 .RI Literal( string )
3285 .RI env.Literal( string )
3288 will be preserved as-is
3289 and not have construction variables expanded.
3291 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3293 .RI Local( targets )
3295 .RI env.Local( targets )
3298 will have copies made in the local tree,
3299 even if an already up-to-date copy
3300 exists in a repository.
3301 Returns a list of the target Node or Nodes.
3303 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3305 .RI env.ParseConfig( command ", [" function ", " unique ])
3308 to modify the environment as specified by the output of
3312 expects the output of a typical
3316 and adds the options
3317 to the appropriate construction variables.
3319 duplicate values are not
3320 added to any construction variables;
3343 construction variables,
3347 option gets added to both the
3354 option gets added to the
3357 Any other strings not associated with options
3358 are assumed to be the names of libraries
3361 construction variable.
3363 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3365 .RI ParseDepends( filename ", [" must_exist ])
3367 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3368 Parses the contents of the specified
3370 as a list of dependencies in the style of
3374 and explicitly establishes all of the listed dependencies.
3383 argument may be set to a non-zero
3386 throw an exception and
3387 generate an error if the file does not exist,
3388 or is otherwise inaccessible.
3392 argument may be set to a non-zero
3395 thrown an exception and
3397 if the file contains dependency
3398 information for more than one target.
3399 This can provide a small sanity check
3400 for files intended to be generated
3401 by, for example, the
3404 which should typically only
3405 write dependency information for
3406 one output file into a corresponding
3412 and all of the files listed therein
3413 will be interpreted relative to
3414 the directory of the
3416 file which calls the
3420 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3423 A factory function that
3424 returns a Builder object
3425 to be used to fetch source files
3426 from the Perforce source code management system.
3427 The returned Builder
3428 is intended to be passed to the
3433 env.SourceCode('.', env.Perforce())
3436 Perforce uses a number of external
3437 environment variables for its operation.
3438 Consequently, this function adds the
3439 following variables from the user's external environment
3440 to the construction environment's
3453 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3455 .RI Platform( string )
3456 Returns a callable object
3457 that can be used to initialize
3458 a construction environment using the
3459 platform keyword of the Environment() method:
3462 env = Environment(platform = Platform('win32'))
3465 .RI env.Platform( string )
3466 Applies the callable object for the specified platform
3468 to the environment through which the method was called.
3471 env.Platform('posix')
3478 variable from the user's external environment
3479 to the construction environment's
3482 This is so that any executed commands
3483 that use sockets to connect with other systems
3484 (such as fetching source files from
3485 external CVS repository specifications like
3486 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3487 will work on Win32 systems.
3489 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3491 .RI Precious( target ", ...)"
3493 .RI env.Precious( target ", ...)"
3496 as precious so it is not deleted before it is rebuilt. Normally
3498 deletes a target before building it.
3499 Multiple targets can be passed in to a single call to
3502 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3504 .RI env.Prepend( key = val ", [...])"
3505 Appends the specified keyword arguments
3506 to the beginning of construction variables in the environment.
3507 If the Environment does not have
3508 the specified construction variable,
3509 it is simply added to the environment.
3510 If the values of the construction variable
3511 and the keyword argument are the same type,
3512 then the two values will be simply added together.
3513 Otherwise, the construction variable
3514 and the value of the keyword argument
3515 are both coerced to lists,
3516 and the lists are added together.
3517 (See also the Append method, above.)
3520 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3523 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3525 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3526 This appends new path elements to the given path in the
3527 specified external environment
3531 any particular path once (leaving the first one it encounters and
3532 ignoring the rest, to preserve path order),
3533 and to help assure this,
3534 will normalize all paths (using
3537 .BR os.path.normcase ).
3538 This can also handle the
3539 case where the given old path variable is a list instead of a
3540 string, in which case a list will be returned instead of a string.
3544 print 'before:',env['ENV']['INCLUDE']
3545 include_path = '/foo/bar:/foo'
3546 env.PrependENVPath('INCLUDE', include_path)
3547 print 'after:',env['ENV']['INCLUDE']
3551 after: /foo/bar:/foo:/biz
3554 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3556 .RI env.AppendUnique( key = val ", [...])"
3557 Appends the specified keyword arguments
3558 to the beginning of construction variables in the environment.
3559 If the Environment does not have
3560 the specified construction variable,
3561 it is simply added to the environment.
3562 If the construction variable being appended to is a list,
3563 then any value(s) that already exist in the
3564 construction variable will
3566 be added again to the list.
3569 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3572 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3575 A factory function that
3576 returns a Builder object
3577 to be used to fetch source files
3579 The returned Builder
3580 is intended to be passed to the
3585 env.SourceCode('.', env.RCS())
3590 will fetch source files
3591 from RCS subdirectories automatically,
3593 as demonstrated in the above example
3594 should only be necessary if
3595 you are fetching from
3598 directory as the source files,
3599 or if you need to explicitly specify RCS
3600 for a specific subdirectory.
3602 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3604 .RI env.Replace( key = val ", [...])"
3605 Replaces construction variables in the Environment
3606 with the specified keyword arguments.
3609 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3614 .RI Repository( directory )
3616 .RI env.Repository( directory )
3619 is a repository to be searched for files.
3623 and each one adds to the list of
3624 repositories that will be searched.
3628 a repository is a copy of the source tree,
3629 from the top-level directory on down,
3631 both source files and derived files
3632 that can be used to build targets in
3633 the local source tree.
3634 The canonical example would be an
3635 official source tree maintained by an integrator.
3636 If the repository contains derived files,
3637 then the derived files should have been built using
3639 so that the repository contains the necessary
3640 signature information to allow
3642 to figure out when it is appropriate to
3643 use the repository copy of a derived file,
3644 instead of building one locally.
3646 Note that if an up-to-date derived file
3647 already exists in a repository,
3651 make a copy in the local directory tree.
3652 In order to guarantee that a local copy
3658 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3663 what variable(s) to use as the return value(s) of the current SConscript
3664 file. These variables will be returned to the "calling" SConscript file
3665 as the return value(s) of
3667 Multiple variable names should be passed to
3673 Return(["foo", "bar"])
3676 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3678 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3680 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3681 Creates a Scanner object for
3684 See the section "Scanner Objects,"
3685 below, for a complete explanation of the arguments and behavior.
3687 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3690 A factory function that
3691 returns a Builder object
3692 to be used to fetch source files
3694 The returned Builder
3695 is intended to be passed to the
3700 env.SourceCode('.', env.SCCS())
3705 will fetch source files
3706 from SCCS subdirectories automatically,
3708 as demonstrated in the above example
3709 should only be necessary if
3710 you are fetching from
3713 directory as the source files,
3714 or if you need to explicitly specify SCCS
3715 for a specific subdirectory.
3717 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3719 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3721 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3723 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3725 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3729 one or more subsidiary SConscript (configuration) files.
3730 There are two ways to call the
3734 The first way you can call
3736 is to explicitly specify one or more
3738 as the first argument.
3739 A single script may be specified as a string;
3740 multiple scripts must be specified as a list
3741 (either explicitly or as created by
3745 The second way you can call
3747 is to specify a list of (sub)directory names
3754 execute a subsidiary configuration file named
3756 in each of the specified directories.
3757 You may specify a name other than
3759 by supplying an optional
3765 argument provides a list of variable names or a dictionary of
3766 named values to export to the
3768 These variables are locally exported only to the specified
3770 and do not affect the
3771 global pool of variables used by
3775 '\"If multiple dirs are provided,
3776 '\"each script gets a fresh export.
3781 function to import the variables.
3785 argument specifies that all of the target files
3786 (for example, object files and executables)
3787 that would normally be built in the subdirectory in which
3789 resides should actually
3793 is interpreted relative to the directory
3794 of the calling SConscript file.
3798 argument specifies that the
3799 source files from which
3800 the target files should be built
3804 is interpreted relative to the directory
3805 of the calling SConscript file.
3809 will link or copy (depending on the platform)
3810 all the source files into the build directory.
3811 This behavior may be disabled by
3812 setting the optional
3815 (it is set to 1 by default),
3818 will refer directly to
3819 the source files in their source directory
3820 when building target files.
3823 is usually safe, and always more efficient
3826 but it may cause build problems in certain end-cases,
3827 such as compiling from source files that
3828 are generated by the build.)
3830 Any variables returned by
3834 will be returned by the call to
3840 SConscript('subdir/SConscript')
3841 foo = SConscript('sub/SConscript', exports='env')
3842 SConscript('dir/SConscript', exports=['env', 'variable'])
3843 SConscript('src/SConscript', build_dir='build', duplicate=0)
3844 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3845 SConscript(dirs=['sub1', 'sub2'])
3846 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3849 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3851 .RI SConscriptChdir( value )
3853 .RI env.SConscriptChdir( value )
3856 changes its working directory
3857 to the directory in which each
3858 subsidiary SConscript file lives.
3859 This behavior may be disabled
3860 by specifying either:
3864 env.SConscriptChdir(0)
3869 will stay in the top-level directory
3870 while reading all SConscript files.
3871 (This may be necessary when building from repositories,
3872 when all the directories in which SConscript files may be found
3873 don't necessarily exist locally.)
3875 You may enable and disable
3876 this ability by calling
3883 SConscript('foo/SConscript') # will not chdir to foo
3884 env.SConscriptChdir(1)
3885 SConscript('bar/SConscript') # will chdir to bar
3888 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3890 .RI SConsignFile([ file , dbm_module ])
3892 .RI env.SConsignFile([ file , dbm_module ])
3895 to store all file signatures
3905 is not an absolute path name,
3906 the file is placed in the same directory as the top-level
3912 argument can be used to specify
3913 which Python database module
3914 The default is to use a custom
3916 module that uses pickled
3917 Python data structures,
3918 and which works on all Python versions from 1.5.2 on.
3923 # Stores signatures in ".sconsign.dbm"
3924 # in the top-level SConstruct directory.
3927 # Stores signatures in the file "etc/scons-signatures"
3928 # relative to the top-level SConstruct directory.
3929 SConsignFile("etc/scons-signatures")
3931 # Stores signatures in the specified absolute file name.
3932 SConsignFile("/home/me/SCons/signatures")
3935 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3937 .RI env.SetDefault(key = val ", [...])"
3938 Sets construction variables to default values specified with the keyword
3939 arguments if (and only if) the variables are not already set.
3940 The following statements are equivalent:
3943 env.SetDefault(FOO = 'foo')
3945 if not env.has_key('FOO'): env['FOO'] = 'foo'
3948 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3950 .RI SetOption( name ", " value )
3952 .RI env.SetOption( name ", " value )
3953 This function provides a way to set a select subset of the scons command
3954 line options from a SConscript file. The options supported are:
3956 which corresponds to -c, --clean, and --remove;
3959 corresponds to --duplicate;
3961 which corresponds to --implicit-cache;
3963 which corresponds to --max-drift;
3965 which corresponds to -j and --jobs.
3966 See the documentation for the
3967 corresponding command line object for information about each specific
3971 SetOption('max_drift', 1)
3974 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3976 .RI SideEffect( side_effect ", " target )
3978 .RI env.SideEffect( side_effect ", " target )
3981 as a side effect of building
3987 can be a list, a file name, or a node.
3988 A side effect is a target that is created
3989 as a side effect of building other targets.
3990 For example, a Windows PDB
3991 file is created as a side effect of building the .obj
3992 files for a static library.
3993 If a target is a side effect of multiple build commands,
3995 will ensure that only one set of commands
3996 is executed at a time.
3997 Consequently, you only need to use this method
3998 for side-effect targets that are built as a result of
3999 multiple build commands.
4001 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4003 .RI SourceCode( entries ", " builder )
4005 .RI env.SourceCode( entries ", " builder )
4006 Arrange for non-existent source files to
4007 be fetched from a source code management system
4012 may be a Node, string or list of both,
4013 and may represent either individual
4014 source files or directories in which
4015 source files can be found.
4017 For any non-existent source files,
4019 will search up the directory tree
4029 will not use a builder to fetch
4030 source files for the specified
4034 builder has been specified
4035 for a directory higher up the tree.
4039 fetch files from SCCS or RCS subdirectories
4040 without explicit configuration.
4041 This takes some extra processing time
4042 to search for the necessary
4043 source code management files on disk.
4044 You can avoid these extra searches
4045 and speed up your build a little
4046 by disabling these searches as follows:
4049 env.SourceCode('.', None)
4053 Note that if the specified
4055 is one you create by hand,
4056 it must have an associated
4057 construction environment to use
4058 when fetching a source file.
4061 provides a set of canned factory
4062 functions that return appropriate
4063 Builders for various popular
4064 source code management systems.
4065 Canonical examples of invocation include:
4068 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4069 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4070 env.SourceCode('/', env.RCS())
4071 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4072 env.SourceCode('no_source.c', None)
4074 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4076 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4078 '\".RI Subversion( repository ", " module )
4079 '\"A factory function that
4080 '\"returns a Builder object
4081 '\"to be used to fetch source files
4082 '\"from the specified Subversion
4084 '\"The returned Builder
4085 '\"is intended to be passed to the
4089 '\"The optional specified
4091 '\"will be added to the beginning
4092 '\"of all repository path names;
4093 '\"this can be used, in essence,
4094 '\"to strip initial directory names
4095 '\"from the repository path names,
4096 '\"so that you only have to
4097 '\"replicate part of the repository
4098 '\"directory hierarchy in your
4099 '\"local build directory:
4102 '\"# Will fetch foo/bar/src.c
4103 '\"# from /usr/local/Subversion/foo/bar/src.c.
4104 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4106 '\"# Will fetch bar/src.c
4107 '\"# from /usr/local/Subversion/foo/bar/src.c.
4108 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4110 '\"# Will fetch src.c
4111 '\"# from /usr/local/Subversion/foo/bar/src.c.
4112 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4115 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4117 .RI SourceSignatures( type )
4119 .RI env.SourceSignatures( type )
4120 This function tells SCons what type of signature to use for source files:
4124 If the environment method is used,
4125 the specified type of source signature
4126 is only used when deciding whether targets
4127 built with that environment are up-to-date or must be rebuilt.
4128 If the global function is used,
4129 the specified type of source signature becomes the default
4130 used for all decisions
4131 about whether targets are up-to-date.
4133 "MD5" means the signature of a source file
4134 is the MD5 checksum of its contents.
4135 "timestamp" means the signature of a source file
4136 is its timestamp (modification time).
4137 There is no different between the two behaviors
4141 "MD5" signatures take longer to compute,
4142 but are more accurate than "timestamp" signatures.
4143 The default is "MD5".
4145 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4149 .RI env.Split( arg )
4150 Returns a list of file names or other objects.
4152 it will be split on strings of white-space characters
4154 making it easier to write long lists of file names.
4155 If arg is already a list,
4156 the list will be returned untouched.
4157 If arg is any other type of object,
4158 it will be returned as a list
4159 containing just the object.
4162 files = Split("f1.c f2.c f3.c")
4163 files = env.Split("f4.c f5.c f6.c")
4171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4173 .RI TargetSignatures( type )
4175 .RI env.TargetSignatures( type )
4176 This function tells SCons what type of signatures to use
4181 If the environment method is used,
4182 the specified type of signature is only used
4183 for targets built with that environment.
4184 If the global function is used,
4185 the specified type of signature becomes the default
4186 used for all target files that
4187 don't have an explicit target signature type
4188 specified for their environments.
4190 "build" means the signature of a target file
4191 is made by concatenating all of the
4192 signatures of all its source files.
4193 "content" means the signature of a target
4194 file is an MD5 checksum of its contents.
4195 "build" signatures are usually faster to compute,
4196 but "content" signatures can prevent unnecessary rebuilds
4197 when a target file is rebuilt to the exact same contents
4198 as the previous build.
4199 The default is "build".
4201 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4203 .RI Tool( string [, toolpath ", " **kw ])
4204 Returns a callable object
4205 that can be used to initialize
4206 a construction environment using the
4207 tools keyword of the Environment() method.
4208 The object may be called with a construction
4209 environment as an argument,
4210 in which case the object will
4211 add the necessary variables
4212 to the construction environment
4213 and the name of the tool will be added to the
4215 construction variable.
4217 Additional keyword arguments are passed to the tool's
4222 env = Environment(tools = [ Tool('msvc') ])
4226 t(env) # adds 'msvc' to the TOOLS variable
4227 u = Tool('opengl', toolpath = ['tools'])
4228 u(env) # adds 'opengl' to the TOOLS variable
4231 .RI env.Tool( string [, toolpath ", " **kw ])
4232 Applies the callable object for the specified tool
4234 to the environment through which the method was called.
4236 Additional keyword arguments are passed to the tool's
4242 env.Tool('opengl', toolpath = ['build/tools'])
4245 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4249 .RI env.Value( value )
4250 Returns a Node object representing the specified Python value. Value
4251 nodes can be used as dependencies of targets. If the result of
4254 changes between SCons runs, any targets depending on
4256 will be rebuilt. When using timestamp source signatures, Value nodes'
4257 timestamps are equal to the system time when the node is created.
4260 def create(target, source, env):
4261 f = open(str(target[0]), 'wb')
4262 f.write('prefix=' + source[0].get_contents())
4264 prefix = ARGUMENTS.get('prefix', '/usr/local')
4266 env['BUILDERS']['Config'] = Builder(action = create)
4267 env.Config(target = 'package-config', source = Value(prefix))
4270 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4272 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4274 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4276 Searches for the specified executable
4278 returning the full path name to the program
4280 and returning None if not.
4281 Searches the specified
4283 the value of the calling environment's PATH
4284 (env['ENV']['PATH']),
4285 or the user's current external PATH
4286 (os.environ['PATH'])
4288 On Win32 systems, searches for executable
4289 programs with any of the file extensions
4290 listed in the specified
4292 the calling environment's PATHEXT
4293 (env['ENV']['PATHEXT'])
4294 or the user's current PATHEXT
4295 (os.environ['PATHEXT'])
4303 .SS SConscript Variables
4304 In addition to the global functions and methods,
4306 supports a number of Python variables
4307 that can be used in SConscript files
4308 to affect how you want the build to be performed.
4309 These variables may be accessed from custom Python modules that you
4310 import into an SConscript file by adding the following
4311 to the Python module:
4314 from SCons.Script import *
4317 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4322 arguments specified on the command line.
4323 Each element in the list is a tuple
4325 .RI ( keyword , value )
4331 elements of the tuple
4333 subscripting for element
4337 of the tuple, respectively.
4340 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4341 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4342 third_tuple = ARGLIST[2]
4343 print "third keyword, value =", third_tuple[0], third_tuple[1]
4344 for key, value in ARGLIST:
4345 # process key and value
4348 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4351 A dictionary of all the
4353 arguments specified on the command line.
4354 The dictionary is not in order,
4355 and if a given keyword has
4356 more than one value assigned to it
4357 on the command line,
4358 the last (right-most) value is
4364 if ARGUMENTS.get('debug', 0):
4365 env = Environment(CCFLAGS = '-g')
4370 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4373 A list of the targets which
4375 will actually try to build,
4376 regardless of whether they were specified on
4377 the command line or via the
4380 The elements of this list may be strings
4382 nodes, so you should run the list through the Python
4384 function to make sure any Node path names
4385 are converted to strings.
4387 Because this list may be taken from the
4388 list of targets specified using the
4391 the contents of the list may change
4392 on each successive call to
4397 for additional information.
4400 if 'foo' in BUILD_TARGETS:
4401 print "Don't forget to test the `foo' program!"
4402 if 'special/program' in BUILD_TARGETS:
4403 SConscript('special')
4408 list only contains targets expected listed
4409 on the command line or via calls to the
4414 contain all dependent targets that will be built as
4415 a result of making the sure the explicitly-specified
4416 targets are up to date.
4418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4420 COMMAND_LINE_TARGETS
4421 A list of the targets explicitly specified on
4423 If there are no targets specified on the command line,
4425 This can be used, for example,
4426 to take specific actions only
4427 when a certain target or targets
4428 is explicitly being built:
4431 if 'foo' in COMMAND_LINE_TARGETS:
4432 print "Don't forget to test the `foo' program!"
4433 if 'special/program' in COMMAND_LINE_TARGETS:
4434 SConscript('special')
4437 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4440 A list of the target
4442 that have been specified using the
4445 The elements of the list are nodes,
4446 so you need to run them through the Python
4448 function to get at the path name for each Node.
4451 print str(DEFAULT_TARGETS[0])
4452 if 'foo' in map(str, DEFAULT_TARGETS):
4453 print "Don't forget to test the `foo' program!"
4458 list change on on each successive call to the
4463 print map(str, DEFAULT_TARGETS) # originally []
4465 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4467 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4469 print map(str, DEFAULT_TARGETS) # back to []
4472 Consequently, be sure to use
4474 only after you've made all of your
4477 or else simply be careful of the order
4478 of these statements in your SConscript files
4479 so that you don't look for a specific
4480 default target before it's actually been added to the list.
4482 .SS Construction Variables
4483 .\" XXX From Gary Ruben, 23 April 2002:
4484 .\" I think it would be good to have an example with each construction
4485 .\" variable description in the documentation.
4487 .\" CC The C compiler
4488 .\" Example: env["CC"] = "c68x"
4489 .\" Default: env["CC"] = "cc"
4491 .\" CCCOM The command line ...
4493 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4494 .\" env["CC"] = "c68x"
4495 .\" env["CFLAGS"] = "-ps -qq -mr"
4496 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4498 .\" (I dunno what this is ;-)
4499 A construction environment has an associated dictionary of
4500 .I construction variables
4501 that are used by built-in or user-supplied build rules.
4502 Construction variables must follow the same rules for
4504 the initial character must be an underscore or letter,
4505 followed by any number of underscores, letters, or digits.
4507 A number of useful construction variables are automatically defined by
4508 scons for each supported platform, and additional construction variables
4509 can be defined by the user. The following is a list of the automatically
4510 defined construction variables:
4513 The static library archiver.
4516 The command line used to generate a static library from object files.
4519 The string displayed when an object file
4520 is generated from an assembly-language source file.
4521 If this is not set, then $ARCOM (the command line) is displayed.
4524 env = Environment(ARCOMSTR = "Archiving $TARGET")
4528 General options passed to the static library archiver.
4534 The command line used to generate an object file
4535 from an assembly-language source file.
4538 The string displayed when an object file
4539 is generated from an assembly-language source file.
4540 If this is not set, then $ASCOM (the command line) is displayed.
4543 env = Environment(ASCOMSTR = "Assembling $TARGET")
4547 General options passed to the assembler.
4550 The command line used to assemble an assembly-language
4551 source file into an object file
4552 after first running the file through the C preprocessor.
4553 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4554 are included on this command line.
4557 The string displayed when an object file
4558 is generated from an assembly-language source file
4559 after first running the file through the C preprocessor.
4560 If this is not set, then $ASPPCOM (the command line) is displayed.
4563 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4567 General options when an assembling an assembly-language
4568 source file into an object file
4569 after first running the file through the C preprocessor.
4570 The default is to use the value of $ASFLAGS.
4573 The bibliography generator for the TeX formatter and typesetter and the
4574 LaTeX structured formatter and typesetter.
4577 The command line used to call the bibliography generator for the
4578 TeX formatter and typesetter and the LaTeX structured formatter and
4582 The string displayed when generating a bibliography
4584 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4587 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4592 General options passed to the bibliography generator for the TeX formatter
4593 and typesetter and the LaTeX structured formatter and typesetter.
4596 The BitKeeper executable.
4599 The command line for
4600 fetching source files using BitKeeper.
4603 The string displayed when fetching
4604 a source file using BitKeeper.
4605 If this is not set, then $BITKEEPERCOM
4606 (the command line) is displayed.
4609 The command ($BITKEEPER) and subcommand
4610 for fetching source files using BitKeeper.
4612 .IP BITKEEPERGETFLAGS
4613 Options that are passed to the BitKeeper
4618 A dictionary mapping the names of the builders
4619 available through this environment
4620 to underlying Builder objects.
4622 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4623 are available by default.
4624 If you initialize this variable when an
4625 Environment is created:
4628 env = Environment(BUILDERS = {'NewBuilder' : foo})
4631 the default Builders will no longer be available.
4632 To use a new Builder object in addition to the default Builders,
4633 add your new Builder object like this:
4637 env.Append(BUILDERS = {'NewBuilder' : foo})
4644 env['BUILDERS]['NewBuilder'] = foo
4651 The command line used to compile a C source file to a (static) object file.
4652 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4653 are included on this command line.
4656 The string displayed when a C source file
4657 is compiled to a (static) object file.
4658 If this is not set, then $CCCOM (the command line) is displayed.
4661 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4665 General options that are passed to the C compiler.
4668 The suffix for C source files.
4669 This is used by the internal CFile builder
4670 when generating C files from Lex (.l) or YACC (.y) input files.
4671 The default suffix, of course, is
4674 On case-insensitive systems (like Win32),
4681 The version number of the C compiler.
4682 This may or may not be set,
4683 depending on the specific C compiler being used.
4686 A function used to produce variables like $_CPPINCFLAGS. It takes
4688 arguments: a prefix to concatenate onto each element, a list of
4689 elements, a suffix to concatenate onto each element, an environment
4690 for variable interpolation, and an optional function that will be
4691 called to transform the list before concatenation.
4694 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4698 A platform independent specification of C preprocessor definitions.
4699 The definitions will be added to command lines
4700 through the automatically-generated
4701 $_CPPDEFFLAGS construction variable (see below),
4702 which is constructed according to
4703 the type of value of $CPPDEFINES:
4706 If $CPPDEFINES is a string,
4708 $CPPDEFPREFIX and $CPPDEFSUFFIX
4709 construction variables
4710 will be added to the beginning and end.
4713 # Will add -Dxyz to POSIX compiler command lines,
4714 # and /Dxyz to Microsoft Visual C++ command lines.
4715 env = Environment(CPPDEFINES='xyz')
4719 If $CPPDEFINES is a list,
4721 $CPPDEFPREFIX and $CPPDEFSUFFIX
4722 construction variables
4723 will be appended to the beginning and end
4724 of each element in the list.
4725 If any element is a list or tuple,
4726 then the first item is the name being
4727 defined and the second item is its value:
4730 # Will add -DB=2 -DA to POSIX compiler command lines,
4731 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4732 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4736 If $CPPDEFINES is a dictionary,
4738 $CPPDEFPREFIX and $CPPDEFSUFFIX
4739 construction variables
4740 will be appended to the beginning and end
4741 of each item from the dictionary.
4742 The key of each dictionary item
4743 is a name being defined
4744 to the dictionary item's corresponding value;
4747 then the name is defined without an explicit value.
4748 Note that the resulting flags are sorted by keyword
4749 to ensure that the order of the options on the
4750 command line is consistent each time
4755 # Will add -DA -DB=2 to POSIX compiler command lines,
4756 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4757 env = Environment(CPPDEFINES={'B':2, 'A':None})
4761 An automatically-generated construction variable
4762 containing the C preprocessor command-line options
4764 The value of $_CPPDEFFLAGS is created
4765 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4766 to the beginning and end
4767 of each directory in $CPPDEFINES.
4770 The prefix used to specify preprocessor definitions
4771 on the C compiler command line.
4772 This will be appended to the beginning of each definition
4773 in the $CPPDEFINES construction variable
4774 when the $_CPPDEFFLAGS variable is automatically generated.
4777 The suffix used to specify preprocessor definitions
4778 on the C compiler command line.
4779 This will be appended to the end of each definition
4780 in the $CPPDEFINES construction variable
4781 when the $_CPPDEFFLAGS variable is automatically generated.
4784 User-specified C preprocessor options.
4785 These will be included in any command that uses the C preprocessor,
4786 including not just compilation of C and C++ source files
4787 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4788 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4789 $F77PPCOM and $SHF77PPCOM command lines
4790 used to compile a Fortran source file,
4791 and the $ASPPCOM command line
4792 used to assemble an assembly language source file,
4793 after first running each file through the C preprocessor.
4794 Note that this variable does
4798 (or similar) include search path options
4799 that scons generates automatically from $CPPPATH.
4803 for the variable that expands to those options.
4806 An automatically-generated construction variable
4807 containing the C preprocessor command-line options
4808 for specifying directories to be searched for include files.
4809 The value of $_CPPINCFLAGS is created
4810 by appending $INCPREFIX and $INCSUFFIX
4811 to the beginning and end
4812 of each directory in $CPPPATH.
4815 The list of directories that the C preprocessor will search for include
4816 directories. The C/C++ implicit dependency scanner will search these
4817 directories for include files. Don't explicitly put include directory
4818 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4819 and the directories will not be searched by the dependency scanner. Note:
4820 directory names in CPPPATH will be looked-up relative to the SConscript
4821 directory when they are used in a command. To force
4823 to look-up a directory relative to the root of the source tree use #:
4826 env = Environment(CPPPATH='#/include')
4830 The directory look-up can also be forced using the
4835 include = Dir('include')
4836 env = Environment(CPPPATH=include)
4840 The directory list will be added to command lines
4841 through the automatically-generated
4843 construction variable,
4844 which is constructed by
4845 appending the values of the
4846 $INCPREFIX and $INCSUFFIX
4847 construction variables
4848 to the beginning and end
4849 of each directory in $CPPPATH.
4850 Any command lines you define that need
4851 the CPPPATH directory list should
4852 include $_CPPINCFLAGS:
4855 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4859 The list of suffixes of files that will be scanned
4860 for C preprocessor implicit dependencies
4862 The default list is:
4865 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4866 ".h", ".H", ".hxx", ".hpp", ".hh",
4867 ".F", ".fpp", ".FPP",
4868 ".S", ".spp", ".SPP"]
4875 Options that are passed to the CVS checkout subcommand.
4878 The command line used to
4879 fetch source files from a CVS repository.
4882 The string displayed when fetching
4883 a source file from a CVS repository.
4884 If this is not set, then $CVSCOM
4885 (the command line) is displayed.
4888 General options that are passed to CVS.
4889 By default, this is set to
4891 to specify from where the files must be fetched.
4894 The path to the CVS repository.
4895 This is referenced in the default
4902 The suffix for C++ source files.
4903 This is used by the internal CXXFile builder
4904 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4905 The default suffix is
4907 SCons also treats files with the suffixes
4914 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4921 The command line used to compile a C++ source file to an object file.
4922 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4923 are included on this command line.
4926 The string displayed when a C++ source file
4927 is compiled to a (static) object file.
4928 If this is not set, then $CXXCOM (the command line) is displayed.
4931 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
4935 General options that are passed to the C++ compiler.
4938 The version number of the C++ compiler.
4939 This may or may not be set,
4940 depending on the specific C++ compiler being used.
4943 A function that converts a file name into a Dir instance relative to the
4947 The list of suffixes of files that will be scanned
4948 for imported D package files.
4949 The default list is:
4956 The TeX DVI file to PDF file converter.
4959 General options passed to the TeX DVI file to PDF file converter.
4962 The command line used to convert TeX DVI files into a PDF file.
4965 The string displayed when a TeX DVI file
4966 is converted into a PDF file.
4967 If this is not set, then $DVIPDFCOM (the command line) is displayed.
4970 The TeX DVI file to PostScript converter.
4973 General options passed to the TeX DVI file to PostScript converter.
4976 A dictionary of environment variables
4977 to use when invoking commands. When ENV is used in a command all list
4978 values will be joined using the path separator and any other non-string
4979 values will simply be coerced to a string.
4980 Note that, by default,
4984 propagate the environment in force when you
4987 to the commands used to build target files.
4988 This is so that builds will be guaranteed
4989 repeatable regardless of the environment
4990 variables set at the time
4994 If you want to propagate your
4995 environment variables
4996 to the commands executed
4997 to build target files,
4998 you must do so explicitly:
5002 env = Environment(ENV = os.environ)
5006 Note that you can choose only to propagate
5007 certain environment variables.
5011 environment variable,
5014 uses the same utilities
5015 as the invoking shell (or other process):
5020 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5024 A function that will be called to escape shell special characters in
5025 command lines. The function should take one argument: the command line
5026 string to escape; and should return the escaped command line.
5029 The Fortran 77 compiler.
5030 You should normally set the $FORTRAN variable,
5031 which specifies the default Fortran compiler
5032 for all Fortran versions.
5033 You only need to set $F77 if you need to use a specific compiler
5034 or compiler version for Fortran 77 files.
5037 The command line used to compile a Fortran 77 source file to an object file.
5038 You only need to set $F77COM if you need to use a specific
5039 command line for Fortran 77 files.
5040 You should normally set the $FORTRANCOM variable,
5041 which specifies the default command line
5042 for all Fortran versions.
5045 The string displayed when a Fortran 77 source file
5046 is compiled to an object file.
5047 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5050 General user-specified options that are passed to the Fortran 77 compiler.
5051 Note that this variable does
5055 (or similar) include search path options
5056 that scons generates automatically from $F77PATH.
5060 for the variable that expands to those options.
5061 You only need to set $F77FLAGS if you need to define specific
5062 user options for Fortran 77 files.
5063 You should normally set the $FORTRANFLAGS variable,
5064 which specifies the user-specified options
5065 passed to the default Fortran compiler
5066 for all Fortran versions.
5069 An automatically-generated construction variable
5070 containing the Fortran 77 compiler command-line options
5071 for specifying directories to be searched for include files.
5072 The value of $_F77INCFLAGS is created
5073 by appending $INCPREFIX and $INCSUFFIX
5074 to the beginning and end
5075 of each directory in $F77PATH.
5078 The list of directories that the Fortran 77 compiler will search for include
5079 directories. The implicit dependency scanner will search these
5080 directories for include files. Don't explicitly put include directory
5081 arguments in $F77FLAGS because the result will be non-portable
5082 and the directories will not be searched by the dependency scanner. Note:
5083 directory names in $F77PATH will be looked-up relative to the SConscript
5084 directory when they are used in a command. To force
5086 to look-up a directory relative to the root of the source tree use #:
5087 You only need to set $F77PATH if you need to define a specific
5088 include path for Fortran 77 files.
5089 You should normally set the $FORTRANPATH variable,
5090 which specifies the include path
5091 for the default Fortran compiler
5092 for all Fortran versions.
5095 env = Environment(F77PATH='#/include')
5099 The directory look-up can also be forced using the
5104 include = Dir('include')
5105 env = Environment(F77PATH=include)
5109 The directory list will be added to command lines
5110 through the automatically-generated
5112 construction variable,
5113 which is constructed by
5114 appending the values of the
5115 $INCPREFIX and $INCSUFFIX
5116 construction variables
5117 to the beginning and end
5118 of each directory in $F77PATH.
5119 Any command lines you define that need
5120 the F77PATH directory list should
5121 include $_F77INCFLAGS:
5124 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5128 The command line used to compile a Fortran 77 source file to an object file
5129 after first running the file through the C preprocessor.
5130 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5131 are included on this command line.
5132 You only need to set $F77PPCOM if you need to use a specific
5133 C-preprocessor command line for Fortran 77 files.
5134 You should normally set the $FORTRANPPCOM variable,
5135 which specifies the default C-preprocessor command line
5136 for all Fortran versions.
5139 The Fortran 90 compiler.
5140 You should normally set the $FORTRAN variable,
5141 which specifies the default Fortran compiler
5142 for all Fortran versions.
5143 You only need to set $F90 if you need to use a specific compiler
5144 or compiler version for Fortran 90 files.
5147 The command line used to compile a Fortran 90 source file to an object file.
5148 You only need to set $F90COM if you need to use a specific
5149 command line for Fortran 90 files.
5150 You should normally set the $FORTRANCOM variable,
5151 which specifies the default command line
5152 for all Fortran versions.
5155 The string displayed when a Fortran 90 source file
5156 is compiled to an object file.
5157 If this is not set, then $F90COM or $FORTRANCOM
5158 (the command line) is displayed.
5161 General user-specified options that are passed to the Fortran 90 compiler.
5162 Note that this variable does
5166 (or similar) include search path options
5167 that scons generates automatically from $F90PATH.
5171 for the variable that expands to those options.
5172 You only need to set $F90FLAGS if you need to define specific
5173 user options for Fortran 90 files.
5174 You should normally set the $FORTRANFLAGS variable,
5175 which specifies the user-specified options
5176 passed to the default Fortran compiler
5177 for all Fortran versions.
5180 An automatically-generated construction variable
5181 containing the Fortran 90 compiler command-line options
5182 for specifying directories to be searched for include files.
5183 The value of $_F90INCFLAGS is created
5184 by appending $INCPREFIX and $INCSUFFIX
5185 to the beginning and end
5186 of each directory in $F90PATH.
5189 The list of directories that the Fortran 90 compiler will search for include
5190 directories. The implicit dependency scanner will search these
5191 directories for include files. Don't explicitly put include directory
5192 arguments in $F90FLAGS because the result will be non-portable
5193 and the directories will not be searched by the dependency scanner. Note:
5194 directory names in $F90PATH will be looked-up relative to the SConscript
5195 directory when they are used in a command. To force
5197 to look-up a directory relative to the root of the source tree use #:
5198 You only need to set $F90PATH if you need to define a specific
5199 include path for Fortran 90 files.
5200 You should normally set the $FORTRANPATH variable,
5201 which specifies the include path
5202 for the default Fortran compiler
5203 for all Fortran versions.
5206 env = Environment(F90PATH='#/include')
5210 The directory look-up can also be forced using the
5215 include = Dir('include')
5216 env = Environment(F90PATH=include)
5220 The directory list will be added to command lines
5221 through the automatically-generated
5223 construction variable,
5224 which is constructed by
5225 appending the values of the
5226 $INCPREFIX and $INCSUFFIX
5227 construction variables
5228 to the beginning and end
5229 of each directory in $F90PATH.
5230 Any command lines you define that need
5231 the F90PATH directory list should
5232 include $_F90INCFLAGS:
5235 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5239 The command line used to compile a Fortran 90 source file to an object file
5240 after first running the file through the C preprocessor.
5241 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5242 are included on this command line.
5243 You only need to set $F90PPCOM if you need to use a specific
5244 C-preprocessor command line for Fortran 90 files.
5245 You should normally set the $FORTRANPPCOM variable,
5246 which specifies the default C-preprocessor command line
5247 for all Fortran versions.
5250 The Fortran 95 compiler.
5251 You should normally set the $FORTRAN variable,
5252 which specifies the default Fortran compiler
5253 for all Fortran versions.
5254 You only need to set $F95 if you need to use a specific compiler
5255 or compiler version for Fortran 95 files.
5258 The command line used to compile a Fortran 95 source file to an object file.
5259 You only need to set $F95COM if you need to use a specific
5260 command line for Fortran 95 files.
5261 You should normally set the $FORTRANCOM variable,
5262 which specifies the default command line
5263 for all Fortran versions.
5266 The string displayed when a Fortran 95 source file
5267 is compiled to an object file.
5268 If this is not set, then $F95COM or $FORTRANCOM
5269 (the command line) is displayed.
5272 General user-specified options that are passed to the Fortran 95 compiler.
5273 Note that this variable does
5277 (or similar) include search path options
5278 that scons generates automatically from $F95PATH.
5282 for the variable that expands to those options.
5283 You only need to set $F95FLAGS if you need to define specific
5284 user options for Fortran 95 files.
5285 You should normally set the $FORTRANFLAGS variable,
5286 which specifies the user-specified options
5287 passed to the default Fortran compiler
5288 for all Fortran versions.
5291 An automatically-generated construction variable
5292 containing the Fortran 95 compiler command-line options
5293 for specifying directories to be searched for include files.
5294 The value of $_F95INCFLAGS is created
5295 by appending $INCPREFIX and $INCSUFFIX
5296 to the beginning and end
5297 of each directory in $F95PATH.
5300 The list of directories that the Fortran 95 compiler will search for include
5301 directories. The implicit dependency scanner will search these
5302 directories for include files. Don't explicitly put include directory
5303 arguments in $F95FLAGS because the result will be non-portable
5304 and the directories will not be searched by the dependency scanner. Note:
5305 directory names in $F95PATH will be looked-up relative to the SConscript
5306 directory when they are used in a command. To force
5308 to look-up a directory relative to the root of the source tree use #:
5309 You only need to set $F95PATH if you need to define a specific
5310 include path for Fortran 95 files.
5311 You should normally set the $FORTRANPATH variable,
5312 which specifies the include path
5313 for the default Fortran compiler
5314 for all Fortran versions.
5317 env = Environment(F95PATH='#/include')
5321 The directory look-up can also be forced using the
5326 include = Dir('include')
5327 env = Environment(F95PATH=include)
5331 The directory list will be added to command lines
5332 through the automatically-generated
5334 construction variable,
5335 which is constructed by
5336 appending the values of the
5337 $INCPREFIX and $INCSUFFIX
5338 construction variables
5339 to the beginning and end
5340 of each directory in $F95PATH.
5341 Any command lines you define that need
5342 the F95PATH directory list should
5343 include $_F95INCFLAGS:
5346 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5350 The command line used to compile a Fortran 95 source file to an object file
5351 after first running the file through the C preprocessor.
5352 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5353 are included on this command line.
5354 You only need to set $F95PPCOM if you need to use a specific
5355 C-preprocessor command line for Fortran 95 files.
5356 You should normally set the $FORTRANPPCOM variable,
5357 which specifies the default C-preprocessor command line
5358 for all Fortran versions.
5361 The default Fortran compiler
5362 for all versions of Fortran.
5365 The command line used to compile a Fortran source file to an object file.
5366 By default, any options specified
5367 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5368 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5369 are included on this command line.
5372 The string displayed when a Fortran source file
5373 is compiled to an object file.
5374 If this is not set, then $FORTRANCOM
5375 (the command line) is displayed.
5378 General user-specified options that are passed to the Fortran compiler.
5379 Note that this variable does
5383 (or similar) include or module search path options
5384 that scons generates automatically from $FORTRANPATH.
5386 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5388 for the variables that expand those options.
5390 .IP _FORTRANINCFLAGS
5391 An automatically-generated construction variable
5392 containing the Fortran compiler command-line options
5393 for specifying directories to be searched for include
5394 files and module files.
5395 The value of $_FORTRANINCFLAGS is created
5396 by prepending/appending $INCPREFIX and $INCSUFFIX
5397 to the beginning and end
5398 of each directory in $FORTRANPATH.
5401 Directory location where the Fortran compiler should place
5402 any module files it generates. This variable is empty, by default. Some
5403 Fortran compilers will internally append this directory in the search path
5404 for module files, as well
5406 .IP FORTRANMODDIRPREFIX
5407 The prefix used to specify a module directory on the Fortran compiler command
5409 This will be appended to the beginning of the directory
5410 in the $FORTRANMODDIR construction variables
5411 when the $_FORTRANMODFLAG variables is automatically generated.
5413 .IP FORTRANMODDIRSUFFIX
5414 The suffix used to specify a module directory on the Fortran compiler command
5416 This will be appended to the beginning of the directory
5417 in the $FORTRANMODDIR construction variables
5418 when the $_FORTRANMODFLAG variables is automatically generated.
5421 An automatically-generated construction variable
5422 containing the Fortran compiler command-line option
5423 for specifying the directory location where the Fortran
5424 compiler should place any module files that happen to get
5425 generated during compilation.
5426 The value of $_FORTRANMODFLAG is created
5427 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5428 to the beginning and end of the directory in $FORTRANMODDIR.
5430 .IP FORTRANMODPREFIX
5431 The module file prefix used by the Fortran compiler. SCons assumes that
5432 the Fortran compiler follows the quasi-standard naming convention for
5434 .I <module_name>.mod.
5435 As a result, this variable is left empty, by default. For situations in
5436 which the compiler does not necessarily follow the normal convention,
5437 the user may use this variable. Its value will be appended to every
5438 module file name as scons attempts to resolve dependencies.
5440 .IP FORTRANMODSUFFIX
5441 The module file suffix used by the Fortran compiler. SCons assumes that
5442 the Fortran compiler follows the quasi-standard naming convention for
5444 .I <module_name>.mod.
5445 As a result, this variable is set to ".mod", by default. For situations
5446 in which the compiler does not necessarily follow the normal convention,
5447 the user may use this variable. Its value will be appended to every
5448 module file name as scons attempts to resolve dependencies.
5451 The list of directories that the Fortran compiler will search for
5452 include files and (for some compilers) module files. The Fortran implicit
5453 dependency scanner will search these directories for include files (but
5454 not module files since they are autogenerated and, as such, may not
5455 actually exist at the time the scan takes place). Don't explicitly put
5456 include directory arguments in FORTRANFLAGS because the result will be
5457 non-portable and the directories will not be searched by the dependency
5458 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5459 to the SConscript directory when they are used in a command. To force
5461 to look-up a directory relative to the root of the source tree use #:
5464 env = Environment(FORTRANPATH='#/include')
5468 The directory look-up can also be forced using the
5473 include = Dir('include')
5474 env = Environment(FORTRANPATH=include)
5478 The directory list will be added to command lines
5479 through the automatically-generated
5481 construction variable,
5482 which is constructed by
5483 appending the values of the
5484 $INCPREFIX and $INCSUFFIX
5485 construction variables
5486 to the beginning and end
5487 of each directory in $FORTRANPATH.
5488 Any command lines you define that need
5489 the FORTRANPATH directory list should
5490 include $_FORTRANINCFLAGS:
5493 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5497 The command line used to compile a Fortran source file to an object file
5498 after first running the file through the C preprocessor.
5499 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5500 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5501 construction variables are included on this command line.
5504 The list of suffixes of files that will be scanned
5505 for Fortran implicit dependencies
5506 (INCLUDE lines & USE statements).
5507 The default list is:
5510 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5511 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5515 A function that converts a file name into a File instance relative to the
5520 frameworks options to be addad at
5521 the end of a command
5522 line building a loadable module.
5525 The Ghostscript program used to convert PostScript to PDF files.
5528 General options passed to the Ghostscript program
5529 when converting PostScript to PDF files.
5532 The Ghostscript command line used to convert PostScript to PDF files.
5535 The string displayed when
5536 Ghostscript is used to convert
5537 a PostScript file to a PDF file.
5538 If this is not set, then $GSCOM (the command line) is displayed.
5541 The list of suffixes of files that will be scanned
5542 for IDL implicit dependencies
5543 (#include or import lines).
5544 The default list is:
5551 The prefix used to specify an include directory on the C compiler command
5553 This will be appended to the beginning of each directory
5554 in the $CPPPATH and $FORTRANPATH construction variables
5555 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5556 variables are automatically generated.
5559 The suffix used to specify an include directory on the C compiler command
5561 This will be appended to the end of each directory
5562 in the $CPPPATH and $FORTRANPATH construction variables
5563 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5564 variables are automatically generated.
5567 A function to be called to install a file into a
5568 destination file name.
5569 The default function copies the file into the destination
5570 (and sets the destination file's mode and permission bits
5571 to match the source file's).
5572 The function takes the following arguments:
5575 def install(dest, source, env):
5579 is the path name of the destination file.
5581 is the path name of the source file.
5583 is the construction environment
5584 (a dictionary of construction values)
5585 in force for this file installation.
5587 .IP INTEL_C_COMPILER_VERSION
5588 Set by the "intelc" Tool
5589 to the major version number of the Intel C compiler
5593 The Java archive tool.
5596 The directory to which the Java archive tool should change
5602 The command line used to call the Java archive tool.
5605 The string displayed when the Java archive tool
5607 If this is not set, then $JARCOM (the command line) is displayed.
5610 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5614 General options passed to the Java archive tool.
5615 By default this is set to
5617 to create the necessary
5622 The suffix for Java archives:
5630 The command line used to compile a directory tree containing
5631 Java source files to
5632 corresponding Java class files.
5633 Any options specified in the $JAVACFLAGS construction variable
5634 are included on this command line.
5637 The string displayed when compiling
5638 a directory tree of Java source files to
5639 corresponding Java class files.
5640 If this is not set, then $JAVACCOM (the command line) is displayed.
5643 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5647 General options that are passed to the Java compiler.
5650 The directory in which Java class files may be found.
5651 This is stripped from the beginning of any Java .class
5652 file names supplied to the
5657 The suffix for Java class files;
5662 The Java generator for C header and stub files.
5665 The command line used to generate C header and stub files
5667 Any options specified in the $JAVAHFLAGS construction variable
5668 are included on this command line.
5671 The string displayed when C header and stub files
5672 are generated from Java classes.
5673 If this is not set, then $JAVAHCOM (the command line) is displayed.
5676 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5680 General options passed to the C header and stub file generator
5684 The suffix for Java files;
5689 The LaTeX structured formatter and typesetter.
5692 The command line used to call the LaTeX structured formatter and typesetter.
5695 The string displayed when calling
5696 the LaTeX structured formatter and typesetter.
5697 If this is not set, then $LATEXCOM (the command line) is displayed.
5700 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5704 General options passed to the LaTeX structured formatter and typesetter.
5707 The linker for building loadable modules.
5708 By default, this is the same as $SHLINK.
5711 The command line for building loadable modules.
5712 On Mac OS X, this uses the $LDMODULE,
5713 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
5714 On other systems, this is the same as $SHLINK.
5717 The string displayed when building loadable modules.
5718 If this is not set, then $LDMODULECOM (the command line) is displayed.
5721 General user options passed to the linker for building loadable modules.
5724 The prefix used for loadable module file names.
5725 On Mac OS X, this is null;
5726 on other systems, this is
5727 the same $SHLIBPREFIX.
5730 The suffix used for loadable module file names.
5731 On Mac OS X, this is null;
5732 on other systems, this is
5733 the same $SHLIBSUFFIX.
5736 The lexical analyzer generator.
5739 General options passed to the lexical analyzer generator.
5742 The command line used to call the lexical analyzer generator
5743 to generate a source file.
5746 The string displayed when generating a source file
5747 using the lexical analyzer generator.
5748 If this is not set, then $LEXCOM (the command line) is displayed.
5751 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5755 An automatically-generated construction variable
5756 containing the linker command-line options
5757 for specifying directories to be searched for library.
5758 The value of $_LIBDIRFLAGS is created
5759 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5760 to the beginning and end
5761 of each directory in $LIBPATH.
5764 The prefix used to specify a library directory on the linker command line.
5765 This will be appended to the beginning of each directory
5766 in the $LIBPATH construction variable
5767 when the $_LIBDIRFLAGS variable is automatically generated.
5770 The suffix used to specify a library directory on the linker command line.
5771 This will be appended to the end of each directory
5772 in the $LIBPATH construction variable
5773 when the $_LIBDIRFLAGS variable is automatically generated.
5776 An automatically-generated construction variable
5777 containing the linker command-line options
5778 for specifying libraries to be linked with the resulting target.
5779 The value of $_LIBFLAGS is created
5780 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5781 to the beginning and end
5782 of each directory in $LIBS.
5785 The prefix used to specify a library to link on the linker command line.
5786 This will be appended to the beginning of each library
5787 in the $LIBS construction variable
5788 when the $_LIBFLAGS variable is automatically generated.
5791 The suffix used to specify a library to link on the linker command line.
5792 This will be appended to the end of each library
5793 in the $LIBS construction variable
5794 when the $_LIBFLAGS variable is automatically generated.
5797 The list of directories that will be searched for libraries.
5798 The implicit dependency scanner will search these
5799 directories for include files. Don't explicitly put include directory
5800 arguments in $LINKFLAGS or $SHLINKFLAGS
5801 because the result will be non-portable
5802 and the directories will not be searched by the dependency scanner. Note:
5803 directory names in LIBPATH will be looked-up relative to the SConscript
5804 directory when they are used in a command. To force
5806 to look-up a directory relative to the root of the source tree use #:
5809 env = Environment(LIBPATH='#/libs')
5813 The directory look-up can also be forced using the
5819 env = Environment(LIBPATH=libs)
5823 The directory list will be added to command lines
5824 through the automatically-generated
5826 construction variable,
5827 which is constructed by
5828 appending the values of the
5829 $LIBDIRPREFIX and $LIBDIRSUFFIX
5830 construction variables
5831 to the beginning and end
5832 of each directory in $LIBPATH.
5833 Any command lines you define that need
5834 the LIBPATH directory list should
5835 include $_LIBDIRFLAGS:
5838 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5842 The prefix used for (static) library file names.
5843 A default value is set for each platform
5844 (posix, win32, os2, etc.),
5845 but the value is overridden by individual tools
5846 (ar, mslib, sgiar, sunar, tlib, etc.)
5847 to reflect the names of the libraries they create.
5850 An array of legal prefixes for library file names.
5853 A list of one or more libraries
5854 that will be linked with
5855 any executable programs
5856 created by this environment.
5859 The library list will be added to command lines
5860 through the automatically-generated
5862 construction variable,
5863 which is constructed by
5864 appending the values of the
5865 $LIBLINKPREFIX and $LIBLINKSUFFIX
5866 construction variables
5867 to the beginning and end
5868 of each directory in $LIBS.
5869 Any command lines you define that need
5870 the LIBS library list should
5874 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5878 The suffix used for (static) library file names.
5879 A default value is set for each platform
5880 (posix, win32, os2, etc.),
5881 but the value is overridden by individual tools
5882 (ar, mslib, sgiar, sunar, tlib, etc.)
5883 to reflect the names of the libraries they create.
5886 An array of legal suffixes for library file names.
5892 General user options passed to the linker.
5893 Note that this variable should
5897 (or similar) options for linking with the libraries listed in $LIBS,
5900 (or similar) library search path options
5901 that scons generates automatically from $LIBPATH.
5905 for the variable that expands to library-link options,
5909 for the variable that expands to library search path options.
5912 The command line used to link object files into an executable.
5915 The string displayed when object files
5916 are linked into an executable.
5917 If this is not set, then $LINKCOM (the command line) is displayed.
5920 env = Environment(LINKCOMSTR = "Linking $TARGET")
5924 The M4 macro preprocessor.
5927 General options passed to the M4 macro preprocessor.
5930 The command line used to pass files through the M4 macro preprocessor.
5933 The string displayed when
5934 a file is passed through the M4 macro preprocessor.
5935 If this is not set, then $M4COM (the command line) is displayed.
5938 The maximum number of characters allowed on an external command line.
5940 link lines longer than this many characters
5941 are linke via a temporary file name.
5944 When the Microsoft Visual Studio tools are initialized, they set up
5945 this dictionary with the following keys:
5948 the version of MSVS being used (can be set via
5952 the available versions of MSVS installed
5955 installed directory of Visual C++
5958 installed directory of Visual Studio
5961 installed directory of the .NET framework
5963 .B FRAMEWORKVERSIONS:
5964 list of installed versions of the .NET framework, sorted latest to oldest.
5966 .B FRAMEWORKVERSION:
5967 latest installed version of the .NET framework
5970 installed location of the .NET SDK.
5973 installed location of the Platform SDK.
5975 .B PLATFORMSDK_MODULES:
5976 dictionary of installed Platform SDK modules,
5977 where the dictionary keys are keywords for the various modules, and
5978 the values are 2-tuples where the first is the release date, and the
5979 second is the version number.
5981 If a value isn't set, it wasn't available in the registry.
5983 .IP MSVS_IGNORE_IDE_PATHS
5984 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5985 instead of the settings from the IDE.
5987 For Visual Studio, SCons will (by default) automatically determine
5988 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5989 set by the IDE. You can override this behavior by setting these
5990 variables after Environment initialization, or by setting
5991 .B MSVS_IGNORE_IDE_PATHS = 1
5992 in the Environment initialization.
5993 Specifying this will not leave these unset, but will set them to a
5994 minimal set of paths needed to run the tools successfully.
5997 For VS6, the mininimal set is:
5998 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5999 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6000 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6002 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6003 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6004 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6008 Where '<VSDir>' is the installed location of Visual Studio.
6010 .IP MSVS_USE_MFC_DIRS
6011 Tells the MS Visual Studio tool(s) to use
6012 the MFC directories in its default paths
6013 for compiling and linking.
6014 Under MSVS version 6,
6016 .B MSVS_USE_MFC_DIRS
6025 external environment variable,
6031 external environment variable.
6032 Under MSVS version 7,
6034 .B MSVS_USE_MFC_DIRS
6037 .B "atlmfc\\\\include"
6038 directory to the default
6040 external environment variable,
6043 directory to the default
6045 external environment variable.
6046 The current default value is
6048 which means these directories
6049 are added to the paths by default.
6050 This default value is likely to change
6051 in a future release,
6052 so users who want the ATL and MFC
6053 values included in their paths
6054 are encouraged to enable the
6055 .B MSVS_USE_MFC_DIRS
6057 to avoid future incompatibility.
6058 This variable has no effect if the
6062 environment variables are set explictly.
6065 Sets the preferred version of MSVS to use.
6067 SCons will (by default) select the latest version of MSVS
6068 installed on your machine. So, if you have version 6 and version 7
6069 (MSVS .NET) installed, it will prefer version 7. You can override this by
6072 variable in the Environment initialization, setting it to the
6073 appropriate version ('6.0' or '7.0', for example).
6074 If the given version isn't installed, tool initialization will fail.
6077 The action used to generate Microsoft Visual Studio
6078 project and solution files.
6080 .IP MSVSPROJECTSUFFIX
6081 The suffix used for Microsoft Visual Studio project (DSP) files.
6082 The default value is
6084 when using Visual Studio version 7.x (.NET),
6087 when using earlier versions of Visual Studio.
6089 .IP MSVSSOLUTIONSUFFIX
6090 The suffix used for Microsoft Visual Studio solution (DSW) files.
6091 The default value is
6093 when using Visual Studio version 7.x (.NET),
6096 when using earlier versions of Visual Studio.
6099 The version number of the MetroWerks CodeWarrior C compiler
6103 A list of installed versions of the MetroWerks CodeWarrior C compiler
6107 When set to non-zero,
6108 suppresses creation of a corresponding Win32 static import lib by the
6110 builder when used with
6111 MinGW or Microsoft Visual Studio.
6112 This also suppresses creation
6113 of an export (.exp) file
6114 when using Microsoft Visual Studio.
6117 The prefix used for (static) object file names.
6120 The suffix used for (static) object file names.
6123 The Perforce executable.
6126 The command line used to
6127 fetch source files from Perforce.
6130 The string displayed when
6131 fetching a source file from Perforce.
6132 If this is not set, then $P4COM (the command line) is displayed.
6135 General options that are passed to Perforce.
6138 The Microsoft Visual C++ precompiled header that will be used when compiling
6139 object files. This variable is ignored by tools other than Microsoft Visual C++.
6140 When this variable is
6141 defined SCons will add options to the compiler command line to
6142 cause it to use the precompiled header, and will also set up the
6143 dependencies for the PCH file. Example:
6146 env['PCH'] = 'StdAfx.pch'
6150 The command line used by the
6152 builder to generated a precompiled header.
6155 The string displayed when generating a precompiled header.
6156 If this is not set, then $PCHCOM (the command line) is displayed.
6159 This variable specifies how much of a source file is precompiled. This
6160 variable is ignored by tools other than Microsoft Visual C++, or when
6161 the PCH variable is not being used. When this variable is define it
6162 must be a string that is the name of the header that
6163 is included at the end of the precompiled portion of the source files, or
6164 the empty string if the "#pragma hrdstop" construct is being used:
6167 env['PCHSTOP'] = 'StdAfx.h'
6171 The Microsoft Visual C++ PDB file that will store debugging information for
6172 object files, shared libraries, and programs. This variable is ignored by
6173 tools other than Microsoft Visual C++.
6174 When this variable is
6175 defined SCons will add options to the compiler and linker command line to
6176 cause them to generate external debugging information, and will also set up the
6177 dependencies for the PDB file. Example:
6180 env['PDB'] = 'hello.pdb'
6184 A deprecated synonym for $DVIPDFCOM.
6187 The prefix used for PDF file names.
6190 The suffix used for PDF file names.
6193 The name of the platform used to create the Environment. If no platform is
6194 specified when the Environment is created,
6196 autodetects the platform.
6199 env = Environment(tools = [])
6200 if env['PLATFORM'] == 'cygwin':
6206 .IP PRINT_CMD_LINE_FUNC
6207 A Python function used to print the command lines as they are executed
6208 (assuming command printing is not disabled by the
6212 options or their equivalents).
6213 The function should take four arguments:
6215 the command being executed (a string),
6217 the target being built (file node, list, or string name(s)),
6219 the source(s) used (file node, list, or string name(s)), and
6221 the environment being used.
6223 The function must do the printing itself. The default implementation,
6224 used if this variable is not set or is None, is:
6226 def print_cmd_line(s, target, source, env):
6227 sys.stdout.write(s + "\n")
6230 Here's an example of a more interesting function:
6232 def print_cmd_line(s, target, source, env):
6233 sys.stdout.write("Building %s -> %s...\n" %
6234 (' and '.join([str(x) for x in source]),
6235 ' and '.join([str(x) for x in target])))
6236 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6237 env.Program('foo', 'foo.c')
6240 This just prints "Building <targetname> from <sourcename>..." instead
6241 of the actual commands.
6242 Such a function could also log the actual commands to a log file,
6246 The prefix used for executable file names.
6249 The suffix used for executable file names.
6252 The command line used to convert TeX DVI files into a PostScript file.
6255 The string displayed when a TeX DVI file
6256 is converted into a PostScript file.
6257 If this is not set, then $PSCOM (the command line) is displayed.
6260 The prefix used for PostScript file names.
6263 The prefix used for PostScript file names.
6266 The qt tool tries to take this from os.environ.
6267 It also initializes all QT_*
6268 construction variables listed below.
6269 (Note that all paths are constructed
6270 with python's os.path.join() method,
6271 but are listed here with the '/' separator
6272 for easier reading.)
6273 In addition, the construction environment
6274 variables CPPPATH, LIBPATH and LIBS may be modified
6276 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6277 are modified. Because the build-performance is affected when using this tool,
6278 you have to explicitly specify it at Environment creation:
6281 Environment(tools=['default','qt'])
6284 The qt tool supports the following operations:
6286 .B Automatic moc file generation from header files.
6287 You do not have to specify moc files explicitly, the tool does it for you.
6288 However, there are a few preconditions to do so: Your header file must have
6289 the same filebase as your implementation file and must stay in the same
6290 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6291 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6292 See also the corresponding builder method
6295 .B Automatic moc file generation from cxx files.
6296 As stated in the qt documentation, include the moc file at the end of
6297 the cxx file. Note that you have to include the file, which is generated
6298 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6299 <basename>.moc. A warning is generated after building the moc file, if you
6300 do not include the correct file. If you are using BuildDir, you may
6301 need to specify duplicate=1. You can turn off automatic moc file generation
6302 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6305 .B Automatic handling of .ui files.
6306 The implementation files generated from .ui files are handled much the same
6307 as yacc or lex files. Each .ui file given as a source of Program, Library or
6308 SharedLibrary will generate three files, the declaration file, the
6309 implementation file and a moc file. Because there are also generated headers,
6310 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6314 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6315 specify files to run moc on.
6318 The path where the qt binaries are installed.
6319 The default value is '$QTDIR/bin'.
6322 The path where the qt header files are installed.
6323 The default value is '$QTDIR/include'.
6324 Note: If you set this variable to None, the tool won't change the CPPPATH
6325 construction variable.
6328 Prints lots of debugging information while scanning for moc files.
6331 The path where the qt libraries are installed.
6332 The default value is '$QTDIR/lib'.
6333 Note: If you set this variable to None, the tool won't change the LIBPATH
6334 construction variable.
6337 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6338 this variable to None, the tool won't change the LIBS variable.
6341 Default value is '$QT_BINPATH/moc'.
6344 Default value is ''. Prefix for moc output files, when source is a cxx file.
6347 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6350 .IP QT_MOCFROMCPPFLAGS
6351 Default value is '-i'. These flags are passed to moc, when moccing a
6354 .IP QT_MOCFROMCXXCOM
6355 Command to generate a moc file from a cpp file.
6357 .IP QT_MOCFROMCXXCOMSTR
6358 The string displayed when generating a moc file from a cpp file.
6359 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6362 Command to generate a moc file from a header.
6364 .IP QT_MOCFROMHCOMSTR
6365 The string displayed when generating a moc file from a cpp file.
6366 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6368 .IP QT_MOCFROMHFLAGS
6369 Default value is ''. These flags are passed to moc, when moccing a header
6373 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6376 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6380 Default value is '$QT_BINPATH/uic'.
6383 Command to generate header files from .ui files.
6386 The string displayed when generating header files from .ui files.
6387 If this is not set, then $QT_UICCOM (the command line) is displayed.
6390 Default value is ''. These flags are passed to uic, when creating a a h
6391 file from a .ui file.
6393 .IP QT_UICDECLPREFIX
6394 Default value is ''. Prefix for uic generated header files.
6396 .IP QT_UICDECLSUFFIX
6397 Default value is '.h'. Suffix for uic generated header files.
6400 Default value is ''. These flags are passed to uic, when creating a cxx
6401 file from a .ui file.
6403 .IP QT_UICIMPLPREFIX
6404 Default value is 'uic_'. Prefix for uic generated implementation files.
6406 .IP QT_UICIMPLSUFFIX
6407 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6411 Default value is '.ui'. Suffix of designer input files.
6414 The archive indexer.
6417 General options passed to the archive indexer.
6420 The resource compiler used by the RES builder.
6423 The command line used by the RES builder.
6426 The string displayed when invoking the resource compiler.
6427 If this is not set, then $RCCOM (the command line) is displayed.
6430 The flags passed to the resource compiler by the RES builder.
6434 Note that this variable is not actually used
6435 for the command to fetch source files from RCS;
6438 construction variable, below.
6441 The RCS "checkout" executable,
6442 used to fetch source files from RCS.
6445 The command line used to
6446 fetch (checkout) source files from RCS.
6449 The string displayed when fetching
6450 a source file from RCS.
6451 If this is not set, then $RCS_COCOM
6452 (the command line) is displayed.
6455 Options that are passed to the $RCS_CO command.
6458 The program used to register DLLs on Windows systems.
6461 The command line used to register a newly-built DLL file
6463 Invoked when the "register=1"
6464 keyword argument is passed to the
6469 The string displayed when registering a newly-built DLL file.
6470 If this is not set, then $REGSVRCOM (the command line) is displayed.
6473 A function that converts a file name into a list of Dir instances by
6474 searching the repositories.
6477 The Java RMI stub compiler.
6480 The command line used to compile stub
6481 and skeleton class files
6482 from Java classes that contain RMI implementations.
6483 Any options specified in the $RMICFLAGS construction variable
6484 are included on this command line.
6487 The string displayed when compiling
6488 stub and skeleton class files
6489 from Java classes that contain RMI implementations.
6490 If this is not set, then $RMICCOM (the command line) is displayed.
6493 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6497 General options passed to the Java RMI stub compiler.
6500 The RPC protocol compiler.
6502 .IP RPCGENCLIENTFLAGS
6503 Options passed to the RPC protocol compiler
6504 when generating client side stubs.
6505 These are in addition to any flags specified in the
6507 construction variable.
6510 General options passed to the RPC protocol compiler.
6512 .IP RPCGENHEADERFLAGS
6513 Options passed to the RPC protocol compiler
6514 when generating a header file.
6515 These are in addition to any flags specified in the
6517 construction variable.
6519 .IP RPCGENSERVICEFLAGS
6520 Options passed to the RPC protocol compiler
6521 when generating server side stubs.
6522 These are in addition to any flags specified in the
6524 construction variable.
6527 Options passed to the RPC protocol compiler
6528 when generating XDR routines.
6529 These are in addition to any flags specified in the
6531 construction variable.
6534 A list of paths to search for shared libraries when running programs.
6535 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6536 Ignored on platforms and toolchains that don't support it.
6537 Note that the paths added to RPATH
6538 are not transformed by
6540 in any way: if you want an absolute
6541 path, you must make it absolute yourself.
6544 A list of the available implicit dependency scanners.
6545 New file scanners may be added by
6546 appending to this list,
6547 although the more flexible approach
6548 is to associate scanners
6549 with a specific Builder.
6550 See the sections "Builder Objects"
6551 and "Scanner Objects,"
6552 below, for more information.
6555 The SCCS executable.
6558 The command line used to
6559 fetch source files from SCCS.
6562 The string displayed when fetching
6563 a source file from a CVS repository.
6564 If this is not set, then $SCCSCOM
6565 (the command line) is displayed.
6568 General options that are passed to SCCS.
6571 Options that are passed specifically to the SCCS "get" subcommand.
6572 This can be set, for example, to
6574 to check out editable files from SCCS.
6577 The C compiler used for generating shared-library objects.
6580 The command line used to compile a C source file
6581 to a shared-library object file.
6582 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6583 are included on this command line.
6586 The string displayed when a C source file
6587 is compiled to a shared object file.
6588 If this is not set, then $SHCCCOM (the command line) is displayed.
6591 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6595 Options that are passed to the C compiler
6596 to generate shared-library objects.
6599 The C++ compiler used for generating shared-library objects.
6602 The command line used to compile a C++ source file
6603 to a shared-library object file.
6604 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6605 are included on this command line.
6608 The string displayed when a C++ source file
6609 is compiled to a shared object file.
6610 If this is not set, then $SHCXXCOM (the command line) is displayed.
6613 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6617 Options that are passed to the C++ compiler
6618 to generate shared-library objects.
6621 A string naming the shell program that will be passed to the
6626 construction variable for more information.
6629 The Fortran 77 compiler used for generating shared-library objects.
6630 You should normally set the $SHFORTRANC variable,
6631 which specifies the default Fortran compiler
6632 for all Fortran versions.
6633 You only need to set $SHF77 if you need to use a specific compiler
6634 or compiler version for Fortran 77 files.
6637 The command line used to compile a Fortran 77 source file
6638 to a shared-library object file.
6639 You only need to set $SHF77COM if you need to use a specific
6640 command line for Fortran 77 files.
6641 You should normally set the $SHFORTRANCOM variable,
6642 which specifies the default command line
6643 for all Fortran versions.
6646 The string displayed when a Fortran 77 source file
6647 is compiled to a shared-library object file.
6648 If this is not set, then $SHF77COM or $SHFORTRANCOM
6649 (the command line) is displayed.
6652 Options that are passed to the Fortran 77 compiler
6653 to generated shared-library objects.
6654 You only need to set $SHF77FLAGS if you need to define specific
6655 user options for Fortran 77 files.
6656 You should normally set the $SHFORTRANFLAGS variable,
6657 which specifies the user-specified options
6658 passed to the default Fortran compiler
6659 for all Fortran versions.
6662 The command line used to compile a Fortran 77 source file to a
6663 shared-library object file
6664 after first running the file through the C preprocessor.
6665 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6666 are included on this command line.
6667 You only need to set $SHF77PPCOM if you need to use a specific
6668 C-preprocessor command line for Fortran 77 files.
6669 You should normally set the $SHFORTRANPPCOM variable,
6670 which specifies the default C-preprocessor command line
6671 for all Fortran versions.
6674 The Fortran 90 compiler used for generating shared-library objects.
6675 You should normally set the $SHFORTRANC variable,
6676 which specifies the default Fortran compiler
6677 for all Fortran versions.
6678 You only need to set $SHF90 if you need to use a specific compiler
6679 or compiler version for Fortran 90 files.
6682 The command line used to compile a Fortran 90 source file
6683 to a shared-library object file.
6684 You only need to set $SHF90COM if you need to use a specific
6685 command line for Fortran 90 files.
6686 You should normally set the $SHFORTRANCOM variable,
6687 which specifies the default command line
6688 for all Fortran versions.
6691 The string displayed when a Fortran 90 source file
6692 is compiled to a shared-library object file.
6693 If this is not set, then $SHF90COM or $SHFORTRANCOM
6694 (the command line) is displayed.
6697 Options that are passed to the Fortran 90 compiler
6698 to generated shared-library objects.
6699 You only need to set $SHF90FLAGS if you need to define specific
6700 user options for Fortran 90 files.
6701 You should normally set the $SHFORTRANFLAGS variable,
6702 which specifies the user-specified options
6703 passed to the default Fortran compiler
6704 for all Fortran versions.
6707 The command line used to compile a Fortran 90 source file to a
6708 shared-library object file
6709 after first running the file through the C preprocessor.
6710 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6711 are included on this command line.
6712 You only need to set $SHF90PPCOM if you need to use a specific
6713 C-preprocessor command line for Fortran 90 files.
6714 You should normally set the $SHFORTRANPPCOM variable,
6715 which specifies the default C-preprocessor command line
6716 for all Fortran versions.
6719 The Fortran 95 compiler used for generating shared-library objects.
6720 You should normally set the $SHFORTRANC variable,
6721 which specifies the default Fortran compiler
6722 for all Fortran versions.
6723 You only need to set $SHF95 if you need to use a specific compiler
6724 or compiler version for Fortran 95 files.
6727 The command line used to compile a Fortran 95 source file
6728 to a shared-library object file.
6729 You only need to set $SHF95COM if you need to use a specific
6730 command line for Fortran 95 files.
6731 You should normally set the $SHFORTRANCOM variable,
6732 which specifies the default command line
6733 for all Fortran versions.
6736 The string displayed when a Fortran 95 source file
6737 is compiled to a shared-library object file.
6738 If this is not set, then $SHF95COM or $SHFORTRANCOM
6739 (the command line) is displayed.
6742 Options that are passed to the Fortran 95 compiler
6743 to generated shared-library objects.
6744 You only need to set $SHF95FLAGS if you need to define specific
6745 user options for Fortran 95 files.
6746 You should normally set the $SHFORTRANFLAGS variable,
6747 which specifies the user-specified options
6748 passed to the default Fortran compiler
6749 for all Fortran versions.
6752 The command line used to compile a Fortran 95 source file to a
6753 shared-library object file
6754 after first running the file through the C preprocessor.
6755 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6756 are included on this command line.
6757 You only need to set $SHF95PPCOM if you need to use a specific
6758 C-preprocessor command line for Fortran 95 files.
6759 You should normally set the $SHFORTRANPPCOM variable,
6760 which specifies the default C-preprocessor command line
6761 for all Fortran versions.
6764 The default Fortran compiler used for generating shared-library objects.
6767 The command line used to compile a Fortran source file
6768 to a shared-library object file.
6771 The string displayed when a Fortran source file
6772 is compiled to a shared-library object file.
6773 If this is not set, then $SHFORTRANCOM
6774 (the command line) is displayed.
6777 Options that are passed to the Fortran compiler
6778 to generate shared-library objects.
6781 The command line used to compile a Fortran source file to a
6782 shared-library object file
6783 after first running the file through the C preprocessor.
6784 Any options specified
6785 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6786 are included on this command line.
6789 The prefix used for shared library file names.
6792 The suffix used for shared library file names.
6795 The linker for programs that use shared libraries.
6798 The command line used to link programs using shared libaries.
6801 The string displayed when programs using shared libraries are linked.
6802 If this is not set, then $SHLINKCOM (the command line) is displayed.
6805 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6809 General user options passed to the linker for programs using shared libraries.
6810 Note that this variable should
6814 (or similar) options for linking with the libraries listed in $LIBS,
6817 (or similar) include search path options
6818 that scons generates automatically from $LIBPATH.
6822 for the variable that expands to library-link options,
6826 for the variable that expands to library search path options.
6829 The prefix used for shared object file names.
6832 The suffix used for shared object file names.
6835 A reserved variable name
6836 that may not be set or used in a construction environment.
6837 (See "Variable Substitution," below.)
6840 A reserved variable name
6841 that may not be set or used in a construction environment.
6842 (See "Variable Substitution," below.)
6845 A command interpreter function that will be called to execute command line
6846 strings. The function must expect the following arguments:
6849 def spawn(shell, escape, cmd, args, env):
6853 is a string naming the shell program to use.
6855 is a function that can be called to escape shell special characters in
6858 is the path to the command to be executed.
6860 is the arguments to the command.
6862 is a dictionary of the environment variables
6863 in which the command should be executed.
6866 '\"The Subversion executable (usually named
6870 '\"The command line used to
6871 '\"fetch source files from a Subversion repository.
6874 '\"General options that are passed to Subversion.
6877 The scripting language wrapper and interface generator.
6880 The suffix that will be used for intermediate C
6881 source files generated by
6882 the scripting language wrapper and interface generator.
6883 The default value is
6884 .BR _wrap$CFILESUFFIX .
6885 By default, this value is used whenever the
6889 specified as part of the
6891 construction variable.
6894 The command line used to call
6895 the scripting language wrapper and interface generator.
6898 The string displayed when calling
6899 the scripting language wrapper and interface generator.
6900 If this is not set, then $SWIGCOM (the command line) is displayed.
6902 .IP SWIGCXXFILESUFFIX
6903 The suffix that will be used for intermediate C++
6904 source files generated by
6905 the scripting language wrapper and interface generator.
6906 The default value is
6907 .BR _wrap$CFILESUFFIX .
6908 By default, this value is used whenever the
6910 option is specified as part of the
6912 construction variable.
6915 General options passed to
6916 the scripting language wrapper and interface generator.
6917 This is where you should set
6921 or whatever other options you want to specify to SWIG.
6924 option in this variable,
6927 generate a C++ intermediate source file
6928 with the extension that is specified as the
6936 The command line used to call the tar archiver.
6939 The string displayed when archiving files
6940 using the tar archiver.
6941 If this is not set, then $TARCOM (the command line) is displayed.
6944 env = Environment(TARCOMSTR = "Archiving $TARGET")
6948 General options passed to the tar archiver.
6951 A reserved variable name
6952 that may not be set or used in a construction environment.
6953 (See "Variable Substitution," below.)
6956 A reserved variable name
6957 that may not be set or used in a construction environment.
6958 (See "Variable Substitution," below.)
6961 The suffix used for tar file names.
6964 The TeX formatter and typesetter.
6967 The command line used to call the TeX formatter and typesetter.
6970 The string displayed when calling
6971 the TeX formatter and typesetter.
6972 If this is not set, then $TEXCOM (the command line) is displayed.
6975 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
6979 General options passed to the TeX formatter and typesetter.
6982 A list of the names of the Tool specifications
6983 that are part of this construction environment.
6985 .IP WIN32_INSERT_DEF
6986 When this is set to true,
6987 a library build of a WIN32 shared library (.dll file)
6988 will also build a corresponding .def file at the same time,
6989 if a .def file is not already listed as a build target.
6990 The default is 0 (do not build a .def file).
6993 The prefix used for WIN32 .def file names.
6996 The suffix used for WIN32 .def file names.
6999 The parser generator.
7002 The command line used to call the parser generator
7003 to generate a source file.
7006 The string displayed when generating a source file
7007 using the parser generator.
7008 If this is not set, then $YACCCOM (the command line) is displayed.
7011 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7015 General options passed to the parser generator.
7016 If $YACCFLAGS contains a \-d option,
7017 SCons assumes that the call will also create a .h file
7018 (if the yacc source file ends in a .y suffix)
7020 (if the yacc source file ends in a .yy suffix)
7023 The zip compression and file packaging utility.
7026 The command line used to call the zip utility,
7027 or the internal Python function used to create a
7031 The string displayed when archiving files
7032 using the zip utility.
7033 If this is not set, then $ZIPCOM
7034 (the command line or internal Python function) is displayed.
7037 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7046 module used by the internal Python function
7047 to control whether the zip archive
7048 is compressed or not.
7049 The default value is
7050 .BR zipfile.ZIP_DEFLATED ,
7051 which creates a compressed zip archive.
7052 This value has no effect when using Python 1.5.2
7055 module is otherwise unavailable.
7058 General options passed to the zip utility.
7061 Construction variables can be retrieved and set using the
7063 method of the construction environment:
7066 dict = env.Dictionary()
7070 or using the [] operator:
7076 Construction variables can also be passed to the construction environment
7080 env = Environment(CC="cc")
7083 or when copying a construction environment using the
7088 env2 = env.Copy(CC="cl.exe")
7091 .SS Configure Contexts
7095 .I configure contexts,
7096 an integrated mechanism similar to the
7097 various AC_CHECK macros in GNU autoconf
7098 for testing for the existence of C header
7099 files, libraries, etc.
7100 In contrast to autoconf,
7102 does not maintain an explicit cache of the tested values,
7103 but uses its normal dependency tracking to keep the checked values
7104 up to date. However, users may override this behaviour with the
7106 command line option.
7108 The following methods can be used to perform checks:
7111 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7113 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7114 This creates a configure context, which can be used to perform checks.
7116 specifies the environment for building the tests.
7117 This environment may be modified when performing checks.
7119 is a dictionary containing custom tests.
7120 See also the section about custom tests below.
7121 By default, no custom tests are added to the configure context.
7123 specifies a directory where the test cases are built.
7124 Note that this directory is not used for building
7126 The default value is the directory
7129 specifies a file which collects the output from commands
7130 that are executed to check for the existence of header files, libraries, etc.
7131 The default is the file #/config.log.
7132 If you are using the
7135 you may want to specify a subdirectory under your build directory.
7137 specifies a C header file where the results of tests
7138 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7139 The default is to not write a
7142 You can specify the same
7144 file in multiple calls to Configure,
7147 will concatenate all results in the specified file.
7149 uses its normal dependency checking
7150 to decide if it's necessary to rebuild
7154 This means that the file is not necessarily re-built each
7156 but is only rebuilt if its contents will have changed
7157 and some target that depends on the
7159 file is being built.
7164 instance has the following associated methods:
7167 .RI Configure.Finish( self )
7168 This method should be called after configuration is done.
7169 It returns the environment as modified
7170 by the configuration checks performed.
7171 After this method is called, no further checks can be performed
7172 with this configuration context.
7173 However, you can create a new
7175 context to perform additional checks.
7176 Only one context should be active at a time.
7178 The following Checks are predefined.
7179 (This list will likely grow larger as time
7180 goes by and developers contribute new useful tests.)
7183 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7186 is usable in the specified language.
7189 in which case the last item in the list
7190 is the header file to be checked,
7191 and the previous list items are
7194 lines should precede the
7195 header line being checked for.
7196 The optional argument
7199 a two character string, where the first character denotes the opening
7200 quote and the second character denotes the closing quote.
7201 By default, both characters are " (double quote).
7202 The optional argument
7208 and selects the compiler to be used for the check.
7209 Returns 1 on success and 0 on failure.
7212 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7213 This is a wrapper around
7214 .B Configure.CheckHeader
7217 is usable in the C language.
7220 in which case the last item in the list
7221 is the header file to be checked,
7222 and the previous list items are
7225 lines should precede the
7226 header line being checked for.
7227 The optional argument
7230 a two character string, where the first character denotes the opening
7231 quote and the second character denotes the closing quote (both default
7233 Returns 1 on success and 0 on failure.
7236 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7237 This is a wrapper around
7238 .B Configure.CheckHeader
7241 is usable in the C++ language.
7244 in which case the last item in the list
7245 is the header file to be checked,
7246 and the previous list items are
7249 lines should precede the
7250 header line being checked for.
7251 The optional argument
7254 a two character string, where the first character denotes the opening
7255 quote and the second character denotes the closing quote (both default
7257 Returns 1 on success and 0 on failure.
7260 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7261 Checks if the specified
7262 C or C++ function is available.
7264 is the name of the function to check for.
7267 argument is a string
7271 that will be compiled
7272 to check if the function exists;
7278 char function_name();
7286 and selects the compiler to be used for the check;
7290 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
7297 is 1 and the library provides the specified
7299 appends the library to the LIBS construction environment variable.
7301 may also be None (the default),
7304 is checked with the current LIBS variable,
7305 or a list of library names,
7306 in which case each library in the list
7313 you can link against the specified
7321 and selects the compiler to be used for the check;
7323 The default value for
7326 It is assumed, that the C-language is used.
7327 This method returns 1 on success and 0 on error.
7330 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7333 .RI Configure.CheckLib
7334 call, this call provides a more sophisticated way to check against libraries.
7337 specifies the library or a list of libraries to check.
7339 specifies a header to check for.
7342 in which case the last item in the list
7343 is the header file to be checked,
7344 and the previous list items are
7347 lines should precede the
7348 header line being checked for.
7350 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7352 can be any valid expression (with a trailing ';'). The default is 'main();'.
7354 specifies whether to add the library to the environment (only if the check
7355 succeeds). This method returns 1 on success and 0 on error.
7358 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7359 Checks for the existence of a type defined by
7362 specifies the typedef name to check for.
7364 is a string containing one or more
7366 lines that will be inserted into the program
7367 that will be run to test for the existence of the type.
7374 and selects the compiler to be used for the check;
7378 Example of a typical Configure usage:
7382 conf = Configure( env )
7383 if not conf.CheckCHeader( 'math.h' ):
7384 print 'We really need math.h!'
7386 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7387 # do stuff for qt - usage, e.g.
7388 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7393 You can define your own custom checks.
7394 in addition to the predefined checks.
7395 These are passed in a dictionary to the Configure function.
7396 This dictionary maps the names of the checks
7397 to user defined Python callables
7398 (either Python functions or class instances implementing the
7401 The first argument of the call is always a
7403 instance followed by the arguments,
7404 which must be supplied by the user of the check.
7405 These CheckContext instances define the following methods:
7408 .RI CheckContext.Message( self ", " text )
7410 Usually called before the check is started.
7412 will be displayed to the user, e.g. 'Checking for library X...'
7415 .RI CheckContext.Result( self, ", " res )
7417 Usually called after the check is done.
7419 can be either an integer or a string. In the former case, 'ok' (res != 0)
7420 or 'failed' (res == 0) is displayed to the user, in the latter case the
7421 given string is displayed.
7424 .RI CheckContext.TryCompile( self ", " text ", " extension )
7425 Checks if a file with the specified
7427 (e.g. '.c') containing
7429 can be compiled using the environment's
7431 builder. Returns 1 on success and 0 on failure.
7434 .RI CheckContext.TryLink( self ", " text ", " extension )
7435 Checks, if a file with the specified
7437 (e.g. '.c') containing
7439 can be compiled using the environment's
7441 builder. Returns 1 on success and 0 on failure.
7444 .RI CheckContext.TryRun( self ", " text ", " extension )
7445 Checks, if a file with the specified
7447 (e.g. '.c') containing
7449 can be compiled using the environment's
7451 builder. On success, the program is run. If the program
7452 executes successfully
7453 (that is, its return status is 0),
7458 is the standard output of the
7460 If the program fails execution
7461 (its return status is non-zero),
7462 then (0, '') is returned.
7465 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7466 Checks if the specified
7468 with an optional source file (contents
7475 may be anything which can be converted to a
7482 is the content of the target file.
7488 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7489 Low level implementation for testing specific builds;
7490 the methods above are based on this method.
7491 Given the Builder instance
7495 of a source file with optional
7497 this method returns 1 on success and 0 on failure. In addition,
7499 is set to the build target node, if the build was successful.
7502 Example for implementing and using custom tests:
7505 def CheckQt(context, qtdir):
7506 context.Message( 'Checking for qt ...' )
7507 lastLIBS = context.env['LIBS']
7508 lastLIBPATH = context.env['LIBPATH']
7509 lastCPPPATH= context.env['CPPPATH']
7510 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7511 ret = context.TryLink("""
7513 int main(int argc, char **argv) {
7514 QApplication qapp(argc, argv);
7519 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7520 context.Result( ret )
7524 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7525 if not conf.CheckQt('/usr/lib/qt'):
7526 print 'We really need qt!'
7531 .SS Construction Variable Options
7533 Often when building software, various options need to be specified at build
7534 time that are not known when the SConstruct/SConscript files are
7535 written. For example, libraries needed for the build may be in non-standard
7536 locations, or site-specific compiler options may need to be passed to the
7539 provides a mechanism for overridding construction variables from the
7540 command line or a text-based SConscript file through an Options
7541 object. To create an Options object, call the Options() function:
7544 .RI Options([ files "], [" args ])
7545 This creates an Options object that will read construction variables from
7546 the file or list of filenames specified in
7548 If no files are specified,
7553 then no files will be read.
7554 The optional argument
7557 values that will override anything read from the specified files;
7558 it is primarily intended to be passed the
7560 dictionary that holds variables
7561 specified on the command line.
7565 opts = Options('custom.py')
7566 opts = Options('overrides.py', ARGUMENTS)
7567 opts = Options(None, {FOO:'expansion', BAR:7})
7570 Options objects have the following methods:
7573 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7574 This adds a customizable construction variable to the Options object.
7576 is the name of the variable.
7578 is the help text for the variable.
7580 is the default value of the variable;
7581 if the default value is
7583 and there is no explicit value specified,
7584 the construction variable will
7586 be added to the construction environment.
7588 is called to validate the value of the variable, and should take three
7589 arguments: key, value, and environment
7591 is called to convert the value before putting it in the environment, and
7592 should take a single argument: value. Example:
7595 opts.Add('CC', 'The C compiler')
7599 .RI AddOptions( list )
7600 A wrapper script that adds
7601 multiple customizable construction variables
7602 to an Options object.
7604 is a list of tuple or list objects
7605 that contain the arguments
7606 for an individual call to the
7613 ('CC', 'The C compiler'),
7614 ('VALIDATE', 'An option for testing validation',
7615 'notset', validator, None),
7620 .RI Update( env ", [" args ])
7621 This updates a construction environment
7623 with the customized construction variables. Normally this method is not
7624 called directly, but is called indirectly by passing the Options object to
7625 the Environment() function:
7628 env = Environment(options=opts)
7632 .RI Save( filename ", " env )
7633 This saves the currently set options into a script file named
7635 that can be used on the next invocation to automatically load the current
7636 settings. This method combined with the Options method can be used to
7637 support caching of options between runs.
7641 opts = Options(['options.cache', 'custom.py'])
7644 opts.Save('options.cache', env)
7648 .RI GenerateHelpText( env ", [" sort ])
7649 This generates help text documenting the customizable construction
7650 variables suitable to passing in to the Help() function.
7652 is the construction environment that will be used to get the actual values
7653 of customizable variables. Calling with
7657 will cause the output to be sorted
7658 by the specified argument.
7662 should take two arguments
7665 (like the standard Python
7670 Help(opts.GenerateHelpText(env))
7671 Help(opts.GenerateHelpText(env, sort=cmp))
7674 The text based SConscript file is executed as a Python script, and the
7675 global variables are queried for customizable construction
7682 To make it more convenient to work with customizable Options,
7684 provides a number of functions
7685 that make it easy to set up
7686 various types of Options:
7689 .RI BoolOption( key ", " help ", " default )
7690 Return a tuple of arguments
7691 to set up a Boolean option.
7695 have a default value of
7697 and display the specified
7700 The option will interpret the values
7722 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7723 Return a tuple of arguments
7725 whose value may be one
7726 of a specified list of legal enumerated values.
7730 have a default value of
7732 and display the specified
7735 The option will only support those
7741 argument is a dictionary
7742 that can be used to convert
7743 input values into specific legal values
7752 then the values are case-sensitive.
7757 then values will be matched
7763 then values will be matched
7765 and all input values will be
7766 converted to lower case.
7769 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
7770 Return a tuple of arguments
7772 whose value may be one or more
7773 of a specified list of legal enumerated values.
7777 have a default value of
7779 and display the specified
7782 The option will only support the values
7785 or the values in the
7788 More than one value may be specified,
7789 with all values separated by commas.
7790 The default may be a string of
7791 comma-separated default values,
7792 or a list of the default values.
7795 argument is a dictionary
7796 that can be used to convert
7797 input values into specific legal values
7803 .RI PackageOption( key ", " help ", " default )
7804 Return a tuple of arguments
7806 whose value is a path name
7807 of a package that may be
7808 enabled, disabled or
7809 given an explicit path name.
7813 have a default value of
7815 and display the specified
7818 The option will support the values
7825 in which case the specified
7828 or the option may be set to an
7830 (typically the path name to a package
7831 that is being enabled).
7832 The option will also support the values
7838 to disable use of the specified option.
7841 .RI PathOption( key ", " help ", " default ", [" validator ])
7842 Return a tuple of arguments
7844 whose value is expected to be a path name.
7848 have a default value of
7850 and display the specified
7856 that will be called to
7857 verify that the specified path
7860 following ready-made validators:
7861 .BR PathOption.PathExists
7863 which verifies that the specified path exists;
7864 .BR PathOption.PathIsFile ,
7865 which verifies that the specified path is an existing file;
7866 .BR PathOption.PathIsDir ,
7867 which verifies that the specified path is an existing directory;
7869 .BR PathOption.PathIsDirCreate ,
7870 which verifies that the specified path is a directory,
7871 and will create the specified directory if the path exist.
7872 You may supply your own
7875 which must take three arguments
7877 the name of the options variable to be set;
7879 the specified value being checked;
7882 the construction environment)
7883 and should raise an exception
7884 if the specified value is not acceptable.
7887 These functions make it
7888 convenient to create a number
7889 of options with consistent behavior
7890 in a single call to the
7896 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7897 EnumOption('debug', 'debug output and symbols', 'no'
7898 allowed_values=('yes', 'no', 'full'),
7899 map={}, ignorecase=0), # case sensitive
7900 ListOption('shared',
7901 'libraries to build as shared libraries',
7903 names = list_of_libs),
7904 PackageOption('x11',
7905 'use X11 installed here (yes = search some places)',
7907 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7908 PathOption('foopath', 'where the foo library is installed', foopath,
7909 PathOption.PathIsDir),
7914 .SS File and Directory Nodes
7924 Nodes, respectively.
7925 python objects, respectively.
7926 Those objects have several user-visible attributes
7927 and methods that are often useful:
7933 This path is relative to the top-level directory
7937 The build path is the same as the source path if
7942 The absolute build path of the given file or directory.
7952 object representing the
7961 # Get the current build dir's path, relative to top.
7963 # Current dir's absolute path
7965 # Next line is always '.', because it is the top dir's path relative to itself.
7967 File('foo.c').srcnode().path # source path of the given source file.
7969 # Builders also return File objects:
7970 foo = env.Program('foo.c')
7971 print "foo will be built in %s"%foo.path
7977 can be extended to build different types of targets
7978 by adding new Builder objects
7979 to a construction environment.
7981 you should only need to add a new Builder object
7982 when you want to build a new type of file or other external target.
7983 If you just want to invoke a different compiler or other tool
7984 to build a Program, Object, Library, or any other
7985 type of output file for which
7987 already has an existing Builder,
7988 it is generally much easier to
7989 use those existing Builders
7990 in a construction environment
7991 that sets the appropriate construction variables
7994 Builder objects are created
8000 function accepts the following arguments:
8003 The command line string used to build the target from the source.
8006 a list of strings representing the command
8007 to be executed and its arguments
8008 (suitable for enclosing white space in an argument),
8010 mapping source file name suffixes to
8011 any combination of command line strings
8012 (if the builder should accept multiple source file extensions),
8015 (see the next section);
8016 or a list of any of the above.
8019 takes three arguments:
8021 - a list of source nodes,
8023 - a list of target nodes,
8025 - the construction environment.
8028 The prefix that will be prepended to the target file name.
8029 This may be specified as a:
8039 - a function or other callable that takes
8040 two arguments (a construction environment and a list of sources)
8041 and returns a prefix,
8046 - specifies a mapping from a specific source suffix (of the first
8047 source specified) to a corresponding target prefix. Both the source
8048 suffix and target prefix specifications may use environment variable
8049 substitution, and the target prefix (the 'value' entries in the
8050 dictionary) may also be a callable object. The default target prefix
8051 may be indicated by a dictionary entry with a key value of None.
8056 b = Builder("build_it < $SOURCE > $TARGET"
8059 def gen_prefix(env, sources):
8060 return "file-" + env['PLATFORM'] + '-'
8061 b = Builder("build_it < $SOURCE > $TARGET",
8062 prefix = gen_prefix)
8064 b = Builder("build_it < $SOURCE > $TARGET",
8065 suffix = { None: "file-",
8066 "$SRC_SFX_A": gen_prefix })
8070 The suffix that will be appended to the target file name.
8071 This may be specified in the same manner as the prefix above.
8072 If the suffix is a string, then
8074 will append a '.' to the beginning of the suffix if it's not already
8075 there. The string returned by callable object (or obtained from the
8076 dictionary) is untouched and must append its own '.' to the beginning
8080 b = Builder("build_it < $SOURCE > $TARGET"
8083 def gen_suffix(env, sources):
8084 return "." + env['PLATFORM'] + "-file"
8085 b = Builder("build_it < $SOURCE > $TARGET",
8086 suffix = gen_suffix)
8088 b = Builder("build_it < $SOURCE > $TARGET",
8089 suffix = { None: ".sfx1",
8090 "$SRC_SFX_A": gen_suffix })
8094 The expected source file name suffix. This may be a string or a list
8098 A Scanner object that
8099 will be invoked to find
8100 implicit dependencies for this target file.
8101 This keyword argument should be used
8102 for Scanner objects that find
8103 implicit dependencies
8104 based only on the target file
8105 and the construction environment,
8108 (See the section "Scanner Objects," below,
8109 for information about creating Scanner objects.)
8112 A Scanner object that
8114 find implicit dependences in
8116 used to build this target file.
8117 This is where you would
8118 specify a scanner to
8121 lines in source files.
8122 (See the section "Scanner Objects," below,
8123 for information about creating Scanner objects.)
8126 A factory function that the Builder will use
8127 to turn any targets specified as strings into SCons Nodes.
8129 SCons assumes that all targets are files.
8130 Other useful target_factory
8133 for when a Builder creates a directory target,
8136 for when a Builder can create either a file
8137 or directory target.
8142 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8144 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8145 env.MakeDirectory('new_directory', [])
8149 A factory function that the Builder will use
8150 to turn any sources specified as strings into SCons Nodes.
8152 SCons assumes that all source are files.
8153 Other useful source_factory
8156 for when a Builder uses a directory as a source,
8159 for when a Builder can use files
8160 or directories (or both) as sources.
8165 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8167 env.Append(BUILDERS = {'Collect':CollectBuilder})
8168 env.Collect('archive', ['directory_name', 'file_name'])
8172 A function or list of functions to manipulate the target and source
8173 lists before dependencies are established
8174 and the target(s) are actually built.
8176 can also be a string containing a construction variable to expand
8177 to an emitter function or list of functions,
8178 or a dictionary mapping source file suffixes
8179 to emitter functions.
8180 (Only the suffix of the first source file
8181 is used to select the actual emitter function
8182 from an emitter dictionary.)
8185 takes three arguments:
8187 - a list of source nodes,
8189 - a list of target nodes,
8191 - the construction environment.
8192 An emitter must return a tuple containing two lists,
8193 the list of targets to be built by this builder,
8194 and the list of sources for this builder.
8199 def e(target, source, env):
8200 return (target + ['foo.foo'], source + ['foo.src'])
8202 # Simple association of an emitter function with a Builder.
8203 b = Builder("my_build < $TARGET > $SOURCE",
8206 def e2(target, source, env):
8207 return (target + ['bar.foo'], source + ['bar.src'])
8209 # Simple association of a list of emitter functions with a Builder.
8210 b = Builder("my_build < $TARGET > $SOURCE",
8213 # Calling an emitter function through a construction variable.
8214 env = Environment(MY_EMITTER = e)
8215 b = Builder("my_build < $TARGET > $SOURCE",
8216 emitter = '$MY_EMITTER')
8218 # Calling a list of emitter functions through a construction variable.
8219 env = Environment(EMITTER_LIST = [e, e2])
8220 b = Builder("my_build < $TARGET > $SOURCE",
8221 emitter = '$EMITTER_LIST')
8223 # Associating multiple emitters with different file
8224 # suffixes using a dictionary.
8225 def e_suf1(target, source, env):
8226 return (target + ['another_target_file'], source)
8227 def e_suf2(target, source, env):
8228 return (target, source + ['another_source_file'])
8229 b = Builder("my_build < $TARGET > $SOURCE",
8230 emitter = {'.suf1' : e_suf1,
8238 arguments must not both be used for the same Builder.
8241 Specifies whether this builder is allowed to be called multiple times for
8242 the same target file(s). The default is 0, which means the builder
8243 can not be called multiple times for the same target file(s). Calling a
8244 builder multiple times for the same target simply adds additional source
8245 files to the target; it is not allowed to change the environment associated
8246 with the target, specify addition environment overrides, or associate a different
8247 builder with the target.
8250 A construction environment that can be used
8251 to fetch source code using this Builder.
8252 (Note that this environment is
8254 used for normal builds of normal target files,
8255 which use the environment that was
8256 used to call the Builder for the target file.)
8259 A function that returns a list of actions that will be executed to build
8260 the target(s) from the source(s).
8261 The returned action(s) may be
8262 an Action object, or anything that
8263 can be converted into an Action object
8264 (see the next section).
8266 The generator function
8267 takes four arguments:
8269 - a list of source nodes,
8271 - a list of target nodes,
8273 - the construction environment,
8275 - a Boolean value that specifies
8276 whether the generator is being called
8277 for generating a build signature
8278 (as opposed to actually executing the command).
8282 def g(source, target, env, for_signature):
8283 return [["gcc", "-c", "-o"] + target + source]
8285 b = Builder(generator=g)
8289 Specifies a builder to use when a source file name suffix does not match
8290 any of the suffixes of the builder. Using this argument produces a
8291 multi-stage builder.
8294 Specifies that this builder expects exactly one source file per call. Giving
8295 more than one source files without target files results in implicitely calling
8296 the builder multiple times (once for each source given). Giving multiple
8297 source files together with target files results in a UserError exception.
8305 arguments must not both be used for the same Builder.
8308 A construction environment that can be used
8309 to fetch source code using this Builder.
8310 (Note that this environment is
8312 used for normal builds of normal target files,
8313 which use the environment that was
8314 used to call the Builder for the target file.)
8317 b = Builder(action="build < $SOURCE > $TARGET")
8318 env = Environment(BUILDERS = {'MyBuild' : b})
8319 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8323 A directory from which scons
8330 a string or a directory Node,
8331 scons will change to the specified directory.
8334 is not a string or Node
8336 then scons will change to the
8337 target file's directory.
8339 Note that scons will
8341 automatically modify
8343 construction variables like
8347 when using the chdir
8348 keyword argument--that is,
8349 the expanded file names
8350 will still be relative to
8351 the top-level SConstruct directory,
8352 and consequently incorrect
8353 relative to the chdir directory.
8354 Builders created using chdir keyword argument,
8355 will need to use construction variable
8360 to use just the filename portion of the
8364 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8366 env = Environment(BUILDERS = {'MyBuild' : b})
8367 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8371 Any additional keyword arguments supplied
8372 when a Builder object is created
8373 (that is, when the Builder() function is called)
8374 will be set in the executing construction
8375 environment when the Builder object is called.
8376 The canonical example here would be
8377 to set a construction variable to
8378 the repository of a source code system.
8380 Any additional keyword arguments supplied
8384 will only be associated with the target
8385 created by that particular Builder call
8386 (and any other files built as a
8387 result of the call).
8389 These extra keyword arguments are passed to the
8390 following functions:
8391 command generator functions,
8393 and emitter functions.
8399 function will turn its
8401 keyword argument into an appropriate
8402 internal Action object.
8403 You can also explicity create Action objects
8407 which can then be passed to the
8410 This can be used to configure
8411 an Action object more flexibly,
8412 or it may simply be more efficient
8413 than letting each separate Builder object
8414 create a separate Action
8416 Builder objects need to do the same thing.
8421 returns an appropriate object for the action
8422 represented by the type of the first argument:
8425 If the first argument is already an Action object,
8426 the object is simply returned.
8429 If the first argument is a string,
8430 a command-line Action is returned.
8433 Action('$CC -c -o $TARGET $SOURCES')
8436 .\" XXX From Gary Ruben, 23 April 2002:
8437 .\" What would be useful is a discussion of how you execute command
8438 .\" shell commands ie. what is the process used to spawn the shell, pass
8439 .\" environment variables to it etc., whether there is one shell per
8440 .\" environment or one per command etc. It might help to look at the Gnu
8441 .\" make documentation to see what they think is important to discuss about
8442 .\" a build system. I'm sure you can do a better job of organising the
8443 .\" documentation than they have :-)
8447 If the first argument is a list,
8448 then a list of Action objects is returned.
8449 An Action object is created as necessary
8450 for each element in the list.
8453 the list is itself a list,
8454 the internal list is the
8455 command and arguments to be executed via
8457 This allows white space to be enclosed
8458 in an argument by defining
8459 a command in a list within a list:
8462 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8466 If the first argument is a Python function,
8467 a function Action is returned.
8468 The Python function takes three keyword arguments,
8470 (a Node object representing the target file),
8472 (a Node object representing the source file)
8475 (the construction environment
8476 used for building the target file).
8481 arguments may be lists of Node objects if there is
8482 more than one target file or source file.
8483 The actual target and source file name(s) may
8484 be retrieved from their Node objects
8485 via the built-in Python str() function:
8488 target_file_name = str(target)
8489 source_file_names = map(lambda x: str(x), source)
8492 The function should return
8496 to indicate a successful build of the target file(s).
8497 The function may raise an exception
8498 or return a non-zero exit status
8499 to indicate an unsuccessful build.
8502 def build_it(target = None, source = None, env = None):
8503 # build the target from the source
8506 a = Action(build_it)
8509 If the action argument is not one of the above,
8512 The second, optional argument
8513 is a Python function that returns
8514 a string to be printed to describe the action being executed.
8515 Like a function to build a file,
8516 this function takes three arguments:
8518 (a Node object representing the target file),
8520 (a Node object representing the source file)
8523 (a construction environment).
8528 arguments may be lists of Node objects if there is
8529 more than one target file or source file.
8533 def build_it(target, source, env):
8534 # build the target from the source
8537 def string_it(target, source, env):
8538 return "building '%s' from '%s'" % (target[0], source[0])
8540 # Use a positional argument.
8541 a = Action(build_it, string_it)
8543 # Alternatively, use a keyword argument.
8544 a = Action(build_it, strfunction=string_it)
8547 The third, also optional argument
8548 is a list of construction variables
8549 whose values will be included
8550 in the signature of the Action
8551 when deciding whether a target should
8552 be rebuilt because the action changed.
8553 This is necessary whenever you want a target to
8554 be rebuilt when a specific
8555 construction variable changes,
8556 because the underlying Python code for a function
8557 will not change when the value of the construction variable does.
8560 def build_it(target, source, env):
8561 # build the target from the 'XXX' construction variable
8562 open(target[0], 'w').write(env['XXX'])
8565 def string_it(target, source):
8566 return "building '%s' from '%s'" % (target[0], source[0])
8568 # Use positional arguments.
8569 a = Action(build_it, string_it, ['XXX'])
8571 # Alternatively, use a keyword argument.
8572 a = Action(build_it, varlist=['XXX'])
8582 which specifies that
8583 scons will execute the action
8584 after changing to the specified directory.
8585 If the chdir argument is
8586 a string or a directory Node,
8587 scons will change to the specified directory.
8588 If the chdir argument
8589 is not a string or Node
8591 then scons will change to the
8592 target file's directory.
8594 Note that scons will
8596 automatically modify
8598 construction variables like
8602 when using the chdir
8603 keyword argument--that is,
8604 the expanded file names
8605 will still be relative to
8606 the top-level SConstruct directory,
8607 and consequently incorrect
8608 relative to the chdir directory.
8609 Builders created using chdir keyword argument,
8610 will need to use construction variable
8615 to use just the filename portion of the
8619 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8623 .SS Miscellaneous Action Functions
8626 supplies a number of functions
8627 that arrange for various common
8628 file and directory manipulations
8630 These are similar in concept to "tasks" in the
8632 although the implementation is slightly different.
8633 These functions do not actually
8634 perform the specified action
8635 at the time the function is called,
8636 but instead return an Action object
8637 that can be executed at the
8639 (In Object-Oriented terminology,
8644 that return Action objects.)
8647 there are two natural ways
8650 are intended to be used.
8654 to perform the action
8655 at the time the SConscript
8659 global function to do so:
8661 Execute(Touch('file'))
8665 you can use these functions
8666 to supply Actions in a list
8670 This can allow you to
8671 perform more complicated
8672 sequences of file manipulation
8674 on platform-specific
8678 env = Environment(TMPBUILD = '/tmp/builddir')
8679 env.Command('foo.out', 'foo.in',
8680 [Mkdir('$TMPBUILD'),
8681 Copy('${SOURCE.dir}', '$TMPBUILD')
8682 "cd $TMPBUILD && make",
8683 Delete('$TMPBUILD')])
8687 .RI Chmod( dest ", " mode )
8688 Returns an Action object that
8689 changes the permissions on the specified
8691 file or directory to the specified
8696 Execute(Chmod('file', 0755))
8698 env.Command('foo.out', 'foo.in',
8699 [Copy('$TARGET', '$SOURCE'),
8700 Chmod('$TARGET', 0755)])
8704 .RI Copy( dest ", " src )
8705 Returns an Action object
8708 source file or directory to the
8710 destination file or directory.
8714 Execute(Copy('foo.output', 'foo.input'))
8716 env.Command('bar.out', 'bar.in',
8717 Copy('$TARGET', '$SOURCE'))
8721 .RI Delete( entry ", [" must_exist ])
8722 Returns an Action that
8723 deletes the specified
8725 which may be a file or a directory tree.
8726 If a directory is specified,
8727 the entire directory tree
8732 then a Python error will be thrown
8733 if the specified entry does not exist;
8736 that is, the Action will silently do nothing
8737 if the entry does not exist.
8741 Execute(Delete('/tmp/buildroot'))
8743 env.Command('foo.out', 'foo.in',
8744 [Delete('${TARGET.dir}'),
8747 Execute(Delete('file_that_must_exist', must_exist=1))
8753 that creates the specified
8759 Execute(Mkdir('/tmp/outputdir'))
8761 env.Command('foo.out', 'foo.in',
8762 [Mkdir('/tmp/builddir',
8763 Copy('$SOURCE', '/tmp/builddir')
8764 "cd /tmp/builddir && ])
8769 .RI Move( dest ", " src )
8771 that moves the specified
8773 file or directory to
8780 Execute(Move('file.destination', 'file.source'))
8782 env.Command('output_file', 'input_file',
8784 Move('$TARGET', 'file_created_by_MyBuildAction')])
8790 that updates the modification time
8796 Execute(Touch('file_to_be_touched'))
8798 env.Command('marker', 'input_file',
8803 .SS Variable Substitution
8805 Before executing a command,
8807 performs construction variable interpolation on the strings that make up
8808 the command line of builders.
8809 Variables are introduced by a
8812 Besides construction variables, scons provides the following
8813 variables for each command execution:
8816 The file name of the target being built, or the file name of the first
8817 target if multiple targets are being built.
8820 The file names of all targets being built.
8823 The file name of the source of the build command, or the file name of the
8824 first source if multiple sources are being built.
8827 The file names of the sources of the build command.
8829 (Note that the above variables are reserved
8830 and may not be set in a construction environment.)
8833 For example, given the construction variable CC='cc', targets=['foo'], and
8834 sources=['foo.c', 'bar.c']:
8837 action='$CC -c -o $TARGET $SOURCES'
8840 would produce the command line:
8843 cc -c -o foo foo.c bar.c
8846 Variable names may be surrounded by curly braces ({})
8847 to separate the name from the trailing characters.
8848 Within the curly braces, a variable name may have
8849 a Python slice subscript appended to select one
8850 or more items from a list.
8851 In the previous example, the string:
8863 Additionally, a variable name may
8864 have the following special
8865 modifiers appended within the enclosing curly braces
8866 to modify the interpolated string:
8869 The base path of the file name,
8870 including the directory path
8871 but excluding any suffix.
8874 The name of the directory in which the file exists.
8878 minus any directory portion.
8881 Just the basename of the file,
8883 and minus the directory.
8886 Just the file suffix.
8889 The absolute path name of the file.
8892 The POSIX form of the path,
8893 with directories separated by
8897 This is sometimes necessary on Win32 systems
8898 when a path references a file on other (POSIX) systems.
8901 The directory and file name to the source file linked to this file
8902 through BuildDir. If this file isn't linked, it just returns the
8903 directory and filename unchanged.
8906 The directory containing the source file linked to this file
8907 through BuildDir. If this file isn't linked, it just returns the
8908 directory part of the filename.
8911 The directory and file name to the source file linked to this file
8912 through BuildDir. If the file does not exist locally but exists in
8913 a Repository, the path in the Repository is returned.
8914 If this file isn't linked, it just returns the
8915 directory and filename unchanged.
8918 The Repository directory containing the source file linked to this file
8919 through BuildDir. If this file isn't linked, it just returns the
8920 directory part of the filename.
8923 For example, the specified target will
8924 expand as follows for the corresponding modifiers:
8927 $TARGET => sub/dir/file.x
8928 ${TARGET.base} => sub/dir/file
8929 ${TARGET.dir} => sub/dir
8930 ${TARGET.file} => file.x
8931 ${TARGET.filebase} => file
8932 ${TARGET.suffix} => .x
8933 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8935 BuildDir('sub/dir','src')
8936 $SOURCE => sub/dir/file.x
8937 ${SOURCE.srcpath} => src/file.x
8938 ${SOURCE.srcdir} => src
8940 Repository('/usr/repository')
8941 $SOURCE => sub/dir/file.x
8942 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8943 ${SOURCE.rsrcdir} => /usr/repository/src
8946 Lastly, a variable name
8947 may be a callable Python function
8949 construction variable in the environment.
8951 take four arguments:
8953 - a list of target nodes,
8955 - a list of source nodes,
8957 - the construction environment,
8959 - a Boolean value that specifies
8960 whether the function is being called
8961 for generating a build signature.
8962 SCons will insert whatever
8963 the called function returns
8964 into the expanded string:
8967 def foo(target, source, env, for_signature):
8970 # Will expand $BAR to "bar baz"
8971 env=Environment(FOO=foo, BAR="$FOO baz")
8974 You can use this feature to pass arguments to a
8975 Python function by creating a callable class
8976 that stores one or more arguments in an object,
8977 and then uses them when the
8980 Note that in this case,
8981 the entire variable expansion must
8982 be enclosed by curly braces
8983 so that the arguments will
8984 be associated with the
8985 instantiation of the class:
8989 def __init__(self, arg):
8992 def __call__(self, target, source, env, for_signature):
8995 # Will expand $BAR to "my argument bar baz"
8996 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9000 The special pseudo-variables
9004 may be used to surround parts of a command line
9007 causing a rebuild--that is,
9008 which are not included in the signature
9009 of target files built with this command.
9014 will be removed from the command line
9015 before it is added to file signatures,
9020 will be removed before the command is executed.
9021 For example, the command line:
9024 echo Last build occurred $( $TODAY $). > $TARGET
9028 would execute the command:
9031 echo Last build occurred $TODAY. > $TARGET
9035 but the command signature added to any target files would be:
9038 echo Last build occurred . > $TARGET
9041 SCons uses the following rules when converting construction variables into
9045 When the value is a string it is interpreted as a space delimited list of
9046 command line arguments.
9049 When the value is a list it is interpreted as a list of command line
9050 arguments. Each element of the list is converted to a string.
9053 Anything that is not a list or string is converted to a string and
9054 interpreted as a single command line argument.
9057 Newline characters (\\n) delimit lines. The newline parsing is done after
9058 all other parsing, so it is not possible for arguments (e.g. file names) to
9059 contain embedded newline characters. This limitation will likely go away in
9060 a future version of SCons.
9068 new file types for implicit dependencies.
9069 Scanner accepts the following arguments:
9072 A Python function that will process
9074 and return a list of strings (file names)
9075 representing the implicit
9076 dependencies found in the contents.
9077 The function takes three or four arguments:
9079 def scanner_function(node, env, path):
9081 def scanner_function(node, env, path, arg):
9085 argument is the internal
9086 SCons node representing the file.
9089 to fetch the name of the file, and
9090 .B node.get_contents()
9091 to fetch contents of the file.
9095 argument is the construction environment for the scan.
9096 Fetch values from it using the
9102 argument is a tuple (or list)
9103 of directories that can be searched
9105 This will usually be the tuple returned by the
9107 argument (see below).
9111 argument is the argument supplied
9112 when the scanner was created, if any.
9115 The name of the Scanner.
9117 to identify the Scanner internally.
9120 An optional argument that, if specified,
9121 will be passed to the scanner function
9123 and the path function
9127 An optional list that can be used to
9128 determine which scanner should be used for
9130 In the usual case of scanning for file names,
9131 this argument will be a list of suffixes
9132 for the different file types that this
9133 Scanner knows how to scan.
9134 If the argument is a string,
9135 then it will be expanded
9136 into a list by the current environment.
9139 A Python function that takes
9140 two or three arguments:
9141 a construction environment, directory Node,
9142 and optional argument supplied
9143 when the scanner was created.
9146 returns a tuple of directories
9147 that can be searched for files to be returned
9148 by this Scanner object.
9151 The class of Node that should be returned
9152 by this Scanner object.
9153 Any strings or other objects returned
9154 by the scanner function
9155 that are not of this class
9156 will be run through the
9161 A Python function that will take a string
9163 and turn it into the appropriate class of Node
9164 to be returned by this Scanner object.
9167 An optional Python function that takes two arguments,
9168 a Node (file) and a construction environment,
9169 and returns whether the
9170 Node should, in fact,
9171 be scanned for dependencies.
9172 This check can be used to eliminate unnecessary
9173 calls to the scanner function when,
9174 for example, the underlying file
9175 represented by a Node does not yet exist.
9178 An optional flag that
9179 specifies whether this scanner should be re-invoked
9180 on the dependency files returned by the scanner.
9181 When this flag is not set,
9182 the Node subsystem will
9183 only invoke the scanner on the file being scanned,
9184 and not (for example) also on the files
9185 specified by the #include lines
9186 in the file being scanned.
9188 .SH SYSTEM-SPECIFIC BEHAVIOR
9189 SCons and its configuration files are very portable,
9190 due largely to its implementation in Python.
9191 There are, however, a few portability
9192 issues waiting to trap the unwary.
9194 SCons handles the upper-case
9196 file suffix differently,
9197 depending on the capabilities of
9198 the underlying system.
9199 On a case-sensitive system
9200 such as Linux or UNIX,
9201 SCons treats a file with a
9203 suffix as a C++ source file.
9204 On a case-insensitive system
9206 SCons treats a file with a
9208 suffix as a C source file.
9210 SCons handles the upper-case
9212 file suffix differently,
9213 depending on the capabilities of
9214 the underlying system.
9215 On a case-sensitive system
9216 such as Linux or UNIX,
9217 SCons treats a file with a
9219 suffix as a Fortran source file
9220 that is to be first run through
9221 the standard C preprocessor.
9222 On a case-insensitive system
9224 SCons treats a file with a
9226 suffix as a Fortran source file that should
9228 be run through the C preprocessor.
9229 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9230 Cygwin supplies a set of tools and utilities
9231 that let users work on a
9232 Windows system using a more POSIX-like environment.
9233 The Cygwin tools, including Cygwin Python,
9235 by sharing an ability to interpret UNIX-like path names.
9236 For example, the Cygwin tools
9237 will internally translate a Cygwin path name
9238 like /cygdrive/c/mydir
9239 to an equivalent Windows pathname
9240 of C:/mydir (equivalent to C:\\mydir).
9243 that are built for native Windows execution,
9244 such as the python.org and ActiveState versions,
9245 do not have the Cygwin path name semantics.
9246 This means that using a native Windows version of Python
9247 to build compiled programs using Cygwin tools
9248 (such as gcc, bison, and flex)
9249 may yield unpredictable results.
9250 "Mixing and matching" in this way
9251 can be made to work,
9252 but it requires careful attention to the use of path names
9253 in your SConscript files.
9255 In practice, users can sidestep
9256 the issue by adopting the following rules:
9258 use the Cygwin-supplied Python interpreter
9260 when using Microsoft Visual C/C++
9261 (or some other Windows compiler)
9262 use the python.org or ActiveState version of Python
9264 .SS WIN32: scons.bat file
9266 SCons is executed via a wrapper
9269 This has (at least) two ramifications:
9271 First, Windows command-line users
9272 that want to use variable assignment
9274 may have to put double quotes
9275 around the assignments:
9278 scons "FOO=BAR" "BAZ=BLEH"
9281 Second, the Cygwin shell does not
9282 recognize this file as being the same
9285 command issued at the command-line prompt.
9286 You can work around this either by
9289 from the Cygwin command line,
9290 or by creating a wrapper shell
9296 The MinGW bin directory must be in your PATH environment variable or the
9297 PATH variable under the ENV construction variable for SCons
9298 to detect and use the MinGW tools. When running under the native Windows
9299 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9300 tools, if they are both installed, regardless of the order of the bin
9301 directories in the PATH variable. If you have both MSVC and MinGW
9302 installed and you want to use MinGW instead of MSVC,
9303 then you must explictly tell SCons to use MinGW by passing
9309 to the Environment() function, because SCons will prefer the MSVC tools
9310 over the MinGW tools.
9314 To help you get started using SCons,
9315 this section contains a brief overview of some common tasks.
9317 .SS Basic Compilation From a Single Source File
9321 env.Program(target = 'foo', source = 'foo.c')
9324 Note: Build the file by specifying
9325 the target as an argument
9326 ("scons foo" or "scons foo.exe").
9327 or by specifying a dot ("scons .").
9329 .SS Basic Compilation From Multiple Source Files
9333 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9336 .SS Setting a Compilation Flag
9339 env = Environment(CCFLAGS = '-g')
9340 env.Program(target = 'foo', source = 'foo.c')
9343 .SS Search The Local Directory For .h Files
9347 need to set CCFLAGS to specify -I options by hand.
9348 SCons will construct the right -I options from CPPPATH.
9351 env = Environment(CPPPATH = ['.'])
9352 env.Program(target = 'foo', source = 'foo.c')
9355 .SS Search Multiple Directories For .h Files
9358 env = Environment(CPPPATH = ['include1', 'include2'])
9359 env.Program(target = 'foo', source = 'foo.c')
9362 .SS Building a Static Library
9366 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9367 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9370 .SS Building a Shared Library
9374 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9375 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9378 .SS Linking a Local Library Into a Program
9381 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9382 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9383 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9386 .SS Defining Your Own Builder Object
9388 Notice that when you invoke the Builder,
9389 you can leave off the target file suffix,
9390 and SCons will add it automatically.
9393 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9395 src_suffix = '.tex')
9396 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9397 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9399 # The following creates "bar.pdf" from "bar.tex"
9400 env.PDFBuilder(target = 'bar', source = 'bar')
9403 Note also that the above initialization
9404 overwrites the default Builder objects,
9405 so the Environment created above
9406 can not be used call Builders like env.Program(),
9407 env.Object(), env.StaticLibrary(), etc.
9409 .SS Adding Your Own Builder Object to an Environment
9412 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9414 src_suffix = '.tex')
9416 env.Append(BUILDERS = {'PDFBuilder' : bld})
9417 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9418 env.Program(target = 'bar', source = 'bar.c')
9421 You also can use other Pythonic techniques to add
9422 to the BUILDERS construction variable, such as:
9426 env['BUILDERS]['PDFBuilder'] = bld
9429 .SS Defining Your Own Scanner Object
9434 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9436 def kfile_scan(node, env, path, arg):
9437 contents = node.get_contents()
9438 includes = include_re.findall(contents)
9441 kscan = Scanner(name = 'kfile',
9442 function = kfile_scan,
9445 scanners = Environment().Dictionary('SCANNERS')
9446 env = Environment(SCANNERS = scanners + [kscan])
9448 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9450 bar_in = File('bar.in')
9451 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9452 bar_in.target_scanner = kscan
9455 .SS Creating a Hierarchical Build
9457 Notice that the file names specified in a subdirectory's
9459 file are relative to that subdirectory.
9465 env.Program(target = 'foo', source = 'foo.c')
9467 SConscript('sub/SConscript')
9472 # Builds sub/foo from sub/foo.c
9473 env.Program(target = 'foo', source = 'foo.c')
9475 SConscript('dir/SConscript')
9480 # Builds sub/dir/foo from sub/dir/foo.c
9481 env.Program(target = 'foo', source = 'foo.c')
9484 .SS Sharing Variables Between SConscript Files
9486 You must explicitly Export() and Import() variables that
9487 you want to share between SConscript files.
9493 env.Program(target = 'foo', source = 'foo.c')
9496 SConscript('subdirectory/SConscript')
9498 subdirectory/SConscript:
9501 env.Program(target = 'foo', source = 'foo.c')
9504 .SS Building Multiple Variants From the Same Source
9506 Use the BuildDir() method to establish
9507 one or more separate build directories for
9508 a given source directory,
9509 then use the SConscript() method
9510 to specify the SConscript files
9511 in the build directories:
9518 BuildDir('foo', 'src')
9519 SConscript('foo/SConscript')
9523 BuildDir('bar', 'src')
9524 SConscript('bar/SConscript')
9529 env = Environment(CCFLAGS = ccflags)
9530 env.Program(target = 'src', source = 'src.c')
9533 Note the use of the Export() method
9534 to set the "ccflags" variable to a different
9535 value for each variant build.
9537 .SS Hierarchical Build of Two Libraries Linked With a Program
9542 env = Environment(LIBPATH = ['#libA', '#libB'])
9544 SConscript('libA/SConscript')
9545 SConscript('libB/SConscript')
9546 SConscript('Main/SConscript')
9551 env.Library('a', Split('a1.c a2.c a3.c'))
9556 env.Library('b', Split('b1.c b2.c b3.c'))
9561 e = env.Copy(LIBS = ['a', 'b'])
9562 e.Program('foo', Split('m1.c m2.c m3.c'))
9565 The '#' in the LIBPATH directories specify that they're relative to the
9566 top-level directory, so they don't turn into "Main/libA" when they're
9567 used in Main/SConscript.
9569 Specifying only 'a' and 'b' for the library names
9570 allows SCons to append the appropriate library
9571 prefix and suffix for the current platform
9572 (for example, 'liba.a' on POSIX systems,
9573 'a.lib' on Windows).
9575 .SS Customizing contruction variables from the command line.
9577 The following would allow the C compiler to be specified on the command
9578 line or in the file custom.py.
9581 opts = Options('custom.py')
9582 opts.Add('CC', 'The C compiler.')
9583 env = Environment(options=opts)
9584 Help(opts.GenerateHelpText(env))
9587 The user could specify the C compiler on the command line:
9593 or in the custom.py file:
9599 or get documentation on the options:
9610 .SS Using Microsoft Visual C++ precompiled headers
9612 Since windows.h includes everything and the kitchen sink, it can take quite
9613 some time to compile it over and over again for a bunch of object files, so
9614 Microsoft provides a mechanism to compile a set of headers once and then
9615 include the previously compiled headers in any object file. This
9616 technology is called precompiled headers. The general recipe is to create a
9617 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9618 then include every header you want to precompile in "StdAfx.h", and finally
9619 include "StdAfx.h" as the first header in all the source files you are
9620 compiling to object files. For example:
9624 #include <windows.h>
9625 #include <my_big_header.h>
9644 /* do some other stuff */
9650 env['PCHSTOP'] = 'StdAfx.h'
9651 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9652 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9655 For more information see the document for the PCH builder, and the PCH and
9656 PCHSTOP construction variables. To learn about the details of precompiled
9657 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9659 .SS Using Microsoft Visual C++ external debugging information
9661 Since including debugging information in programs and shared libraries can
9662 cause their size to increase significantly, Microsoft provides a mechanism
9663 for including the debugging information in an external file called a PDB
9664 file. SCons supports PDB files through the PDB construction
9670 env['PDB'] = 'MyApp.pdb'
9671 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9674 For more information see the document for the PDB construction variable.
9679 Specifies the directory that contains the SCons Python module directory
9680 (e.g. /home/aroach/scons-src-0.01/src/engine).
9683 A string of options that will be used by scons in addition to those passed
9684 on the command line.
9695 Steven Knight <knight@baldmt.com>
9697 Anthony Roach <aroach@electriceyeball.com>