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 a count of how many objects are created
514 of the various classes used internally by SCons.
515 This only works when run under Python 2.1 or later.
519 Print the dependency tree
520 after each top-level target is built. This prints out only derived files.
524 Instruct the scanner that searches for libraries
525 to print a message about each potential library
526 name it is searching for,
527 and about the actual libraries it finds.
531 Print the include tree after each top-level target is built.
532 This is generally used to find out what files are included by the sources
533 of a given derived file:
536 $ scons --debug=includes foo.o
541 Prints how much memory SCons uses
542 before and after reading the SConscript files
543 and before and after building.
547 Prints a list of the various objects
548 of the various classes used internally by SCons.
549 This only works when run under Python 2.1 or later.
553 Re-run SCons under the control of the
560 Print the raw command line used to build each target
561 before the construction environment variables are substituted.
562 Also shows which targets are being built by this command.
563 Output looks something like this:
565 $ scons --debug=presub
566 Building myprog.o with action(s):
567 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
573 Prints an internal Python stack trace
574 when encountering an otherwise unexplained error.
578 Prints various time profiling information: the time spent
579 executing each build command, the total build time, the total time spent
580 executing build commands, the total time spent executing SConstruct and
581 SConscript files, and the total time spent executing SCons itself.
585 Print the dependency tree
586 after each top-level target is built. This prints out the complete
587 dependency tree including implicit dependencies and ignored
591 .\" -e, --environment-overrides
592 .\" Variables from the execution environment override construction
593 .\" variables from the SConscript files.
596 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
599 as the initial SConscript file.
603 Print a local help message for this build, if one is defined in
604 the SConscript file(s), plus a line that describes the
606 option for command-line option help. If no local help message
607 is defined, prints the standard help message about command-line
608 options. Exits after displaying the appropriate message.
612 Print the standard help message about command-line options and
617 Ignore all errors from commands executed to rebuild files.
620 .RI -I " directory" ", --include-dir=" directory
624 imported Python modules. If several
627 are used, the directories are searched in the order specified.
631 Cache implicit dependencies. This can cause
633 to miss changes in the implicit dependencies in cases where a new implicit
634 dependency is added earlier in the implicit dependency search path
635 (e.g. CPPPATH) than a current implicit dependency with the same name.
638 --implicit-deps-changed
639 Force SCons to ignore the cached implicit dependencies. This causes the
640 implicit dependencies to be rescanned and recached. This implies
641 .BR --implicit-cache .
644 --implicit-deps-unchanged
645 Force SCons to ignore changes in the implicit dependencies.
646 This causes cached implicit dependencies to always be used.
648 .BR --implicit-cache .
651 .RI -j " N" ", --jobs=" N
652 Specifies the number of jobs (commands) to run simultaneously.
653 If there is more than one
655 option, the last one is effective.
659 .\" is specified without an argument,
661 .\" will not limit the number of
662 .\" simultaneous jobs.
666 Continue as much as possible after an error. The target that
667 failed and those that depend on it will not be remade, but other
668 targets specified on the command line will still be processed.
671 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
672 .\" No new jobs (commands) will be started if
673 .\" there are other jobs running and the system load
674 .\" average is at least
676 .\" (a floating-point number).
679 .RI --duplicate= ORDER
680 There are three ways to duplicate files in a build tree: hard links,
681 soft (symbolic) links and copies. The default behaviour of SCons is to
682 prefer hard links to soft links to copies. You can specify different
683 behaviours with this option.
693 SCons will attempt to duplicate files using
694 the mechanisms in the specified order.
699 .\" List derived files (targets, dependencies) that would be built,
700 .\" but do not build them.
701 .\" [XXX This can probably go away with the right
702 .\" combination of other options. Revisit this issue.]
706 .\" List derived files that would be built, with the actions
707 .\" (commands) that build them. Does not build the files.
708 .\" [XXX This can probably go away with the right
709 .\" combination of other options. Revisit this issue.]
713 .\" List derived files that would be built, plus where the file is
714 .\" defined (file name and line number). Does not build the files.
715 .\" [XXX This can probably go away with the right
716 .\" combination of other options. Revisit this issue.]
720 Ignored for compatibility with non-GNU versions of
724 .RI --max-drift= SECONDS
725 Set the maximum expected drift in the modification time of files to
727 This value determines how old a file must be before its content signature
728 is cached. The default value is 2 days, which means a file must have a
729 modification time of at least two days ago in order to have its content
730 signature cached. A negative value means to never cache the content
731 signature and to ignore the cached value if there already is one. A value
732 of 0 means to always cache the signature, no matter how old the file is.
735 -n, --just-print, --dry-run, --recon
736 No execute. Print the commands that would be executed to build
737 any out-of-date target files, but do not execute the commands.
740 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
744 .\" not rebuild anything due to changes in the contents of
747 .\" .RI --override " file"
748 .\" Read values to override specific build environment variables
749 .\" from the specified
753 .\" Print the data base (construction environments,
754 .\" Builder and Scanner objects) that are defined
755 .\" after reading the SConscript files.
756 .\" After printing, a normal build is performed
757 .\" as usual, as specified by other command-line options.
758 .\" This also prints version information
763 .\" To print the database without performing a build do:
771 Run SCons under the Python profiler
772 and save the results in the specified
774 The results may be analyzed using the Python
778 Do not run any commands, or print anything. Just return an exit
779 status that is zero if the specified targets are already up to
780 date, non-zero otherwise.
783 Quiets SCons status messages about
784 reading SConscript files,
786 and entering directories.
787 Commands that are executed
788 to rebuild target files are still printed.
791 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
792 .\" Clear the default construction variables. Construction
793 .\" environments that are created will be completely empty.
797 Build dependencies in a random order. This is useful when
798 building multiple trees simultaneously with caching enabled,
799 to prevent multiple builds from simultaneously trying to build
800 or retrieve the same target files.
803 -s, --silent, --quiet
804 Silent. Do not print commands that are executed to rebuild
806 Also suppresses SCons status messages.
809 -S, --no-keep-going, --stop
810 Ignored for compatibility with GNU
815 Ignored for compatibility with GNU
817 (Touching a file to make it
818 appear up-to-date is unnecessary when using
822 -u, --up, --search-up
823 Walks up the directory structure until an
828 file is found, and uses that
829 as the top of the directory tree.
830 If no targets are specified on the command line,
831 only targets at or below the
832 current directory will be built.
836 Works exactly the same way as the
838 option except for the way default targets are handled.
839 When this option is used and no targets are specified on the command line,
840 all default targets that are defined in the SConscript(s) in the current
841 directory are built, regardless of what directory the resultant targets end
848 version, copyright information,
849 list of authors, and any other relevant information.
853 -w, --print-directory
854 Print a message containing the working directory before and
855 after other processing.
858 .RI --warn= type ", --warn=no-" type
859 Enable or disable warnings.
861 specifies the type of warnings to be enabled or disabled:
864 --warn=all, --warn=no-all
865 Enables or disables all warnings.
868 --warn=dependency, --warn=no-dependency
869 Enables or disables warnings about dependencies.
870 These warnings are disabled by default.
873 --warn=deprecated, --warn=no-deprecated
874 Enables or disables warnings about use of deprecated features.
875 These warnings are enabled by default.
878 --warn=missing-sconscript, --warn=no-missing-sconscript
879 Enables or disables warnings about missing SConscript files.
880 These warnings are enabled by default.
884 Turn off -w, even if it was turned on implicitly.
887 .\" .RI --write-filenames= file
888 .\" Write all filenames considered into
892 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
893 .\" Pretend that the target
896 .\" modified. When used with the
899 .\" show you what would be rebuilt if you were to modify that file.
905 .\" --warn-undefined-variables
906 .\" Warn when an undefined variable is referenced.
909 .RI -Y " repository" ", --repository=" repository
910 Search the specified repository for any input and target
911 files not found in the local directory hierarchy. Multiple
913 options may specified, in which case the
914 repositories are searched in the order specified.
916 .SH CONFIGURATION FILE REFERENCE
917 .\" .SS Python Basics
918 .\" XXX Adding this in the future would be a help.
919 .SS Construction Environments
920 A construction environment is the basic means by which the SConscript
921 files communicate build information to
923 A new construction environment is created using the
931 By default, a new construction environment is
932 initialized with a set of builder methods
933 and construction variables that are appropriate
934 for the current platform.
935 An optional platform keyword argument may be
936 used to specify that an environment should
937 be initialized for a different platform:
940 env = Environment(platform = 'cygwin')
941 env = Environment(platform = 'os2')
942 env = Environment(platform = 'posix')
943 env = Environment(platform = 'win32')
946 Specifying a platform initializes the appropriate
947 construction variables in the environment
948 to use and generate file names with prefixes
949 and suffixes appropriate for the platform.
955 variable from the user's external environment
956 to the construction environment's
959 This is so that any executed commands
960 that use sockets to connect with other systems
961 (such as fetching source files from
962 external CVS repository specifications like
963 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
964 will work on Win32 systems.
966 The platform argument may be function or callable object,
967 in which case the Environment() method
968 will call the specified argument to update
969 the new construction environment:
972 def my_platform(env):
975 env = Environment(platform = my_platform)
978 Additionally, a specific set of tools
979 with which to initialize the environment
980 may specified as an optional keyword argument:
983 env = Environment(tools = ['msvc', 'lex'])
986 Non-built-in tools may be specified using the toolpath argument:
989 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
992 This looks for a tool specification in tools/foo.py (as well as
993 using the ordinary default tools for the platform). foo.py should
994 have two functions: generate(env, **kw) and exists(env).
998 modifies the passed in environment
999 to set up variables so that the tool
1001 it may use any keyword arguments
1002 that the user supplies (see below)
1003 to vary its initialization.
1006 function should return a true
1007 value if the tool is available.
1008 Tools in the toolpath are used before
1009 any of the built-in ones. For example, adding gcc.py to the toolpath
1010 would override the built-in gcc tool.
1012 The elements of the tools list may also
1013 be functions or callable objects,
1014 in which case the Environment() method
1015 will call the specified elements
1016 to update the new construction environment:
1020 env['XYZZY'] = 'xyzzy'
1022 env = Environment(tools = [my_tool])
1025 The individual elements of the tools list
1026 may also themselves be two-element lists of the form
1027 .RI ( toolname ", " kw_dict ).
1028 SCons searches for the
1030 specification file as described above, and
1033 which must be a dictionary, as keyword arguments to the tool's
1038 function can use the arguments to modify the tool's behavior
1039 by setting up the environment in different ways
1040 or otherwise changing its initialization.
1043 # in tools/my_tool.py:
1044 def generate(env, **kw):
1045 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1046 env['MY_TOOL'] = kw.get('arg1', '1')
1051 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1055 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1056 the environment it receives to customize the tool for different platforms.
1058 If no tool list is specified, then SCons will auto-detect the installed
1059 tools using the PATH variable in the ENV construction variable and the
1060 platform name when the Environment is constructed. Changing the PATH
1061 variable after the Environment is constructed will not cause the tools to
1064 SCons supports the following tool specifications out of the box:
1140 Additionally, there is a "tool" named
1142 which configures the
1143 environment with a default set of tools for the current platform.
1145 On posix and cygwin platforms
1146 the GNU tools (e.g. gcc) are preferred by SCons,
1147 on win32 the Microsoft tools (e.g. msvc)
1148 followed by MinGW are preferred by SCons,
1149 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1153 Build rules are specified by calling a construction
1154 environment's builder methods.
1155 The arguments to the builder methods are
1157 (a list of target files)
1160 (a list of source files).
1162 Because long lists of file names
1163 can lead to a lot of quoting,
1168 and a same-named environment method
1169 that split a single string
1170 into a list, separated on
1171 strings of white-space characters.
1172 (These are similar to the
1173 string.split() method
1174 from the standard Python library,
1175 but work even if the input isn't a string.)
1177 Like all Python arguments,
1178 the target and source arguments to a builder method
1179 can be specified either with or without
1180 the "target" and "source" keywords.
1181 When the keywords are omitted,
1182 the target is first,
1183 followed by the source.
1184 The following are equivalent examples of calling the Program builder method:
1187 env.Program('bar', ['bar.c', 'foo.c'])
1188 env.Program('bar', Split('bar.c foo.c'))
1189 env.Program('bar', env.Split('bar.c foo.c'))
1190 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1191 env.Program(target = 'bar', Split('bar.c foo.c'))
1192 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1193 env.Program('bar', source = string.split('bar.c foo.c'))
1196 When the target shares the same base name
1197 as the source and only the suffix varies,
1198 and if the builder method has a suffix defined for the target file type,
1199 then the target argument may be omitted completely,
1202 will deduce the target file name from
1203 the source file name.
1204 The following examples all build the
1210 (on Windows systems)
1211 from the bar.c source file:
1214 env.Program(target = 'bar', source = 'bar.c')
1215 env.Program('bar', source = 'bar.c')
1216 env.Program(source = 'bar.c')
1217 env.Program('bar.c')
1220 It is possible to override or add construction variables when calling a
1221 builder method by passing additional keyword arguments.
1222 These overridden or added
1223 variables will only be in effect when building the target, so they will not
1224 affect other parts of the build. For example, if you want to add additional
1225 libraries for just one program:
1228 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1231 or generate a shared library with a nonstandard suffix:
1234 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1237 Although the builder methods defined by
1240 methods of a construction environment object,
1241 they may also be called without an explicit environment:
1244 Program('hello', 'hello.c')
1245 SharedLibrary('word', 'word.cpp')
1249 the methods are called internally using a default construction
1250 environment that consists of the tools and values that
1252 has determined are appropriate for the local system.
1254 All builder methods return a list of Nodes
1255 that represent the target or targets that will be built.
1258 is an internal SCons object
1260 build targets or sources.
1262 The returned Node(s)
1263 can be passed to other builder methods as source(s)
1264 or passed to any SCons function or method
1265 where a filename would normally be accepted.
1266 For example, if it were necessary
1269 flag when compiling one specific object file:
1272 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1273 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1276 Using a Node in this way
1277 makes for a more portable build
1278 by avoiding having to specify
1279 a platform-specific object suffix
1280 when calling the Program() builder method.
1282 Note that Builder calls will automatically "flatten"
1283 the source and target file lists,
1284 so it's all right to have the bar_obj list
1285 return by the StaticObject() call
1286 in the middle of the source file list.
1287 If you need to manipulate a list of lists returned by Builders
1288 directly using Python,
1289 you can either build the list by hand:
1292 foo = Object('foo.c')
1293 bar = Object('bar.c')
1294 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1295 for object in objects:
1302 to create a list containing just the Nodes,
1303 which may be more convenient:
1306 foo = Object('foo.c')
1307 bar = Object('bar.c')
1308 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1309 for object in objects:
1313 The path name for a Node's file may be used
1314 by passing the Node to the Python-builtin
1319 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1320 print "The path to bar_obj is:", str(bar_obj_list[0])
1323 Note again that because the Builder call returns a list,
1324 we have to access the first element in the list
1325 .B (bar_obj_list[0])
1326 to get at the Node that actually represents
1329 Builder calls support a
1331 keyword argument that
1332 specifies that the Builder's action(s)
1334 after changing directory.
1338 a string or a directory Node,
1339 scons will change to the specified directory.
1342 is not a string or Node
1344 then scons will change to the
1345 target file's directory.
1348 # scons will change to the "sub" subdirectory
1349 # before executing the "cp" command.
1350 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1351 "cp dir/foo.in dir/foo.out",
1354 # Because chdir is not a string, scons will change to the
1355 # target's directory ("sub/dir") before executing the
1357 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1358 "cp foo.in foo.out",
1362 Note that scons will
1364 automatically modify
1366 construction variables like
1370 when using the chdir
1371 keyword argument--that is,
1372 the expanded file names
1373 will still be relative to
1374 the top-level SConstruct directory,
1375 and consequently incorrect
1376 relative to the chdir directory.
1377 If you use the chdir keyword argument,
1378 you will typically need to supply a different
1384 to use just the filename portion of the
1388 provides the following builder methods:
1390 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1393 Builds a C source file given a lex (.l) or yacc (.y) input file.
1394 The suffix specified by the $CFILESUFFIX construction variable
1396 is automatically added to the target
1397 if it is not already present. Example:
1401 env.CFile(target = 'foo.c', source = 'foo.l')
1403 env.CFile(target = 'bar', source = 'bar.y')
1406 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1409 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1411 The suffix specified by the $CXXFILESUFFIX construction variable
1413 is automatically added to the target
1414 if it is not already present. Example:
1418 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1420 env.CXXFile(target = 'bar', source = 'bar.yy')
1423 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1426 Builds a .dvi file from a .tex, .ltx or .latex input file.
1427 If the source file suffix is .tex,
1429 will examine the contents of the file;
1434 is found, the file is assumed to be a LaTeX file and
1435 the target is built by invoking the $LATEXCOM command line;
1436 otherwise, the $TEXCOM command line is used.
1437 If the file is a LaTeX file,
1440 builder method will also examine the contents
1443 and invoke the $BIBTEX command line
1447 and will examine the contents
1449 file and re-run the $LATEXCOM command
1450 if the log file says it is necessary.
1453 (hard-coded within TeX itself)
1454 is automatically added to the target
1455 if it is not already present. Examples:
1458 # builds from aaa.tex
1459 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1461 env.DVI(target = 'bbb', source = 'bbb.ltx')
1462 # builds from ccc.latex
1463 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1469 Builds a Java archive (.jar) file
1470 from a source tree of .class files.
1471 If the $JARCHDIR value is set, the
1473 command will change to the specified directory using the
1476 If the contents any of the source files begin with the string
1477 .BR Manifest-Version ,
1478 the file is assumed to be a manifest
1479 and is passed to the
1486 env.Jar(target = 'foo.jar', source = 'classes')
1489 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1492 Builds one or more Java class files
1493 from one or more source trees of .java files.
1494 The class files will be placed underneath
1495 the specified target directory.
1496 SCons will parse each source .java file
1498 (including inner classes)
1499 defined within that file,
1500 and from that figure out the
1501 target .class files that will be created.
1502 SCons will also search each Java file
1503 for the Java package name,
1504 which it assumes can be found on a line
1505 beginning with the string
1507 in the first column;
1508 the resulting .class files
1509 will be placed in a directory reflecting
1510 the specified package name.
1514 defining a single public
1517 containing a package name of
1519 will generate a corresponding
1520 .IR sub/dir/Foo.class
1526 env.Java(target = 'classes', source = 'src')
1527 env.Java(target = 'classes', source = ['src1', 'src2'])
1530 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1533 Builds C header and source files for
1534 implementing Java native methods.
1535 The target can be either a directory
1536 in which the header files will be written,
1537 or a header file name which
1538 will contain all of the definitions.
1539 The source can be either the names of .class files,
1540 or the objects returned from the
1544 If the construction variable
1546 is set, either in the environment
1547 or in the call to the
1549 builder method itself,
1550 then the value of the variable
1551 will be stripped from the
1552 beginning of any .class file names.
1557 # builds java_native.h
1558 classes = env.Java(target = 'classdir', source = 'src')
1559 env.JavaH(target = 'java_native.h', source = classes)
1561 # builds include/package_foo.h and include/package_bar.h
1562 env.JavaH(target = 'include',
1563 source = ['package/foo.class', 'package/bar.class'])
1565 # builds export/foo.h and export/bar.h
1566 env.JavaH(target = 'export',
1567 source = ['classes/foo.class', 'classes/bar.class'],
1568 JAVACLASSDIR = 'classes')
1571 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1578 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1581 Builds an output file from an M4 input file.
1582 This uses a default $M4FLAGS value of
1584 which considers all warnings to be fatal
1585 and stops on the first warning
1586 when using the GNU version of m4.
1590 env.M4(target = 'foo.c', source = 'foo.c.m4')
1593 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1596 Builds an output file from a moc input file. Moc input files are either
1597 header files or cxx files. This builder is only available after using the
1598 tool 'qt'. See the QTDIR variable for more information.
1602 env.Moc('foo.h') # generates moc_foo.cc
1603 env.Moc('foo.cpp') # generates foo.moc
1606 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1608 .IP env.MSVSProject()
1609 Builds Microsoft Visual Studio project files.
1610 This builds a Visual Studio project file, based on the version of
1611 Visual Studio that is configured (either the latest installed version,
1612 or the version set by
1614 in the Environment constructor).
1615 For VS 6, it will generate
1619 files, for VS 7, it will
1626 It takes several lists of filenames to be placed into the project
1627 file, currently these are limited to
1628 .B srcs, incs, localincs, resources,
1631 These are pretty self explanatory, but it
1632 should be noted that the 'srcs' list is NOT added to the $SOURCES
1633 environment variable. This is because it represents a list of files
1634 to be added to the project file, not the source used to build the
1635 project file (in this case, the 'source' is the SConscript file used
1636 to call MSVSProject).
1638 In addition to these values (which are all optional, although not
1639 specifying any of them results in an empty project file), the
1640 following values must be specified:
1642 target: The name of the target .dsp or .vcproj file. The correct
1643 suffix for the version of Visual Studio must be used, but the value
1645 env['MSVSPROJECTSUFFIX']
1647 will be defined to the correct value (see example below).
1649 variant: The name of this particular variant. These are typically
1650 things like "Debug" or "Release", but really can be anything you want.
1651 Multiple calls to MSVSProject with different variants are allowed: all
1652 variants will be added to the project file with their appropriate
1653 build targets and sources.
1655 buildtarget: A list of SCons.Node.FS objects which is returned from
1656 the command which builds the target. This is used to tell SCons what
1657 to build when the 'build' button is pressed inside of the IDE.
1662 barsrcs = ['bar.cpp'],
1663 barincs = ['bar.h'],
1664 barlocalincs = ['StdAfx.h']
1665 barresources = ['bar.rc','resource.h']
1666 barmisc = ['bar_readme.txt']
1668 dll = local.SharedLibrary(target = 'bar.dll',
1671 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1674 localincs = barlocalincs,
1675 resources = barresources,
1678 variant = 'Release')
1681 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1688 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1691 Builds a Microsoft Visual C++ precompiled header.
1692 Calling this builder method
1693 returns a list of two targets: the PCH as the first element, and the object
1694 file as the second element. Normally the object file is ignored.
1695 This builder method is only
1696 provided when Microsoft Visual C++ is being used as the compiler.
1697 The PCH builder method is generally used in
1698 conjuction with the PCH construction variable to force object files to use
1699 the precompiled header:
1702 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1705 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1708 Builds a .pdf file from a .dvi input file
1709 (or, by extension, a .tex, .ltx, or .latex input file).
1710 The suffix specified by the $PDFSUFFIX construction variable
1712 is added automatically to the target
1713 if it is not already present. Example:
1716 # builds from aaa.tex
1717 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1718 # builds bbb.pdf from bbb.dvi
1719 env.PDF(target = 'bbb', source = 'bbb.dvi')
1722 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1724 .IP env.PostScript()
1725 Builds a .ps file from a .dvi input file
1726 (or, by extension, a .tex, .ltx, or .latex input file).
1727 The suffix specified by the $PSSUFFIX construction variable
1729 is added automatically to the target
1730 if it is not already present. Example:
1733 # builds from aaa.tex
1734 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1735 # builds bbb.ps from bbb.dvi
1736 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1739 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1742 Builds an executable given one or more object files
1743 or C, C++, D, or Fortran source files.
1744 If any C, C++, D or Fortran source files are specified,
1745 then they will be automatically
1746 compiled to object files using the
1749 see that builder method's description for
1750 a list of legal source file suffixes
1751 and how they are interpreted.
1752 The target executable file prefix
1753 (specified by the $PROGPREFIX construction variable; nothing by default)
1755 (specified by the $PROGSUFFIX construction variable;
1756 by default, .exe on Windows systems, nothing on POSIX systems)
1757 are automatically added to the target if not already present.
1761 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1764 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1767 Builds a Microsoft Visual C++ resource file.
1768 This builder method is only provided
1769 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1773 for MinGW) suffix is added to the target name if no other suffix is given. The source
1774 file is scanned for implicit dependencies as though it were a C file. Example:
1777 env.RES('resource.rc')
1780 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1783 Builds stub and skeleton class files
1785 from Java .class files.
1786 The target is a directory
1787 relative to which the stub
1788 and skeleton class files will be written.
1789 The source can be the names of .class files,
1790 or the objects return from the
1794 If the construction variable
1796 is set, either in the environment
1797 or in the call to the
1799 builder method itself,
1800 then the value of the variable
1801 will be stripped from the
1802 beginning of any .class file names.
1805 classes = env.Java(target = 'classdir', source = 'src')
1806 env.RMIC(target = 'outdir1', source = classes)
1808 env.RMIC(target = 'outdir2',
1809 source = ['package/foo.class', 'package/bar.class'])
1811 env.RMIC(target = 'outdir3',
1812 source = ['classes/foo.class', 'classes/bar.class'],
1813 JAVACLASSDIR = 'classes')
1816 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1818 .IP env.RPCGenClient()
1819 Generates an RPC client stub (_clnt.c) file
1820 from a specified RPC (.x) source file.
1821 Because rpcgen only builds output files
1822 in the local directory,
1823 the command will be executed
1824 in the source file's directory by default.
1827 # Builds src/rpcif_clnt.c
1828 env.RPCGenClient('src/rpcif.x')
1831 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1833 .IP env.RPCGenHeader()
1834 Generates an RPC header (.h) file
1835 from a specified RPC (.x) source file.
1836 Because rpcgen only builds output files
1837 in the local directory,
1838 the command will be executed
1839 in the source file's directory by default.
1842 # Builds src/rpcif.h
1843 env.RPCGenHeader('src/rpcif.x')
1846 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1848 .IP env.RPCGenService()
1849 Generates an RPC server-skeleton (_svc.c) file
1850 from a specified RPC (.x) source file.
1851 Because rpcgen only builds output files
1852 in the local directory,
1853 the command will be executed
1854 in the source file's directory by default.
1857 # Builds src/rpcif_svc.c
1858 env.RPCGenClient('src/rpcif.x')
1861 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1864 Generates an RPC XDR routine (_xdr.c) file
1865 from a specified RPC (.x) source file.
1866 Because rpcgen only builds output files
1867 in the local directory,
1868 the command will be executed
1869 in the source file's directory by default.
1872 # Builds src/rpcif_xdr.c
1873 env.RPCGenClient('src/rpcif.x')
1876 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1878 .IP env.SharedLibrary()
1879 Builds a shared library
1880 (.so on a POSIX system, .dll on WIN32)
1881 given one or more object files
1882 or C, C++, D or Fortran source files.
1883 If any source files are given,
1884 then they will be automatically
1885 compiled to object files.
1886 The static library prefix and suffix (if any)
1887 are automatically added to the target.
1888 The target library file prefix
1889 (specified by the $SHLIBPREFIX construction variable;
1890 by default, lib on POSIX systems, nothing on Windows systems)
1892 (specified by the $SHLIBSUFFIX construction variable;
1893 by default, .dll on Windows systems, .so on POSIX systems)
1894 are automatically added to the target if not already present.
1898 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1901 On WIN32 systems, the
1903 builder method will always build an import (.lib) library
1904 in addition to the shared (.dll) library,
1905 adding a .lib library with the same basename
1906 if there is not already a .lib file explicitly
1907 listed in the targets.
1909 Any object files listed in the
1911 must have been built for a shared library
1916 will raise an error if there is any mismatch.
1918 On WIN32 systems, specifying "register=1" will cause the dll to be
1919 registered after it is built using REGSVR32. The command that is run
1920 ("regsvr32" by default) is determined by $REGSVR construction
1921 variable, and the flags passed are determined by $REGSVRFLAGS. By
1922 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1923 up and requiring user attention when it is run. If you change
1924 $REGSVRFLAGS, be sure to include "/s". For example,
1927 env.SharedLibrary(target = 'bar',
1928 source = ['bar.cxx', 'foo.obj'],
1933 will register "bar.dll" as a COM object when it is done linking it.
1935 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1937 .IP env.SharedObject()
1938 Builds an object file for
1939 inclusion in a shared library.
1940 Source files must have one of the same set of extensions
1941 specified above for the
1944 On some platforms building a shared object requires additional
1945 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1946 normal (static) object, but on some platforms there is no difference between a
1947 shared object and a normal (static) one. When there is a difference, SCons
1948 will only allow shared objects to be linked into a shared library, and will
1949 use a different suffix for shared objects. On platforms where there is no
1950 difference, SCons will allow both normal (static)
1951 and shared objects to be linked into a
1952 shared library, and will use the same suffix for shared and normal
1954 The target object file prefix
1955 (specified by the $SHOBJPREFIX construction variable;
1956 by default, the same as $OBJPREFIX)
1958 (specified by the $SHOBJSUFFIX construction variable)
1959 are automatically added to the target if not already present.
1963 env.SharedObject(target = 'ddd', source = 'ddd.c')
1964 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1965 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1968 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1970 .IP env.StaticLibrary()
1971 Builds a static library given one or more object files
1972 or C, C++, D or Fortran source files.
1973 If any source files are given,
1974 then they will be automatically
1975 compiled to object files.
1976 The static library prefix and suffix (if any)
1977 are automatically added to the target.
1978 The target library file prefix
1979 (specified by the $LIBPREFIX construction variable;
1980 by default, lib on POSIX systems, nothing on Windows systems)
1982 (specified by the $LIBSUFFIX construction variable;
1983 by default, .lib on Windows systems, .a on POSIX systems)
1984 are automatically added to the target if not already present.
1988 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1992 Any object files listed in the
1994 must have been built for a static library
1999 will raise an error if there is any mismatch.
2001 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2003 .IP env.StaticObject()
2004 Builds a static object file
2005 from one or more C, C++, D, or Fortran source files.
2006 Source files must have one of the following extensions:
2009 .asm assembly language file
2010 .ASM assembly language file
2022 .F WIN32: Fortran file
2023 POSIX: Fortran file + C pre-processor
2026 .fpp Fortran file + C pre-processor
2027 .FPP Fortran file + C pre-processor
2028 .s assembly language file
2029 .S WIN32: assembly language file
2030 POSIX: assembly language file + C pre-processor
2031 .spp assembly language file + C pre-processor
2032 .SPP assembly language file + C pre-processor
2035 The target object file prefix
2036 (specified by the $OBJPREFIX construction variable; nothing by default)
2038 (specified by the $OBJSUFFIX construction variable;
2039 \.obj on Windows systems, .o on POSIX systems)
2040 are automatically added to the target if not already present.
2044 env.StaticObject(target = 'aaa', source = 'aaa.c')
2045 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2046 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2049 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2052 Builds a tar archive of the specified files
2054 Unlike most builder methods,
2057 builder method may be called multiple times
2059 each additional call
2060 adds to the list of entries
2061 that will be built into the archive.
2064 env.Tar('src.tar', 'src')
2066 # Create the stuff.tar file.
2067 env.Tar('stuff', ['subdir1', 'subdir2'])
2068 # Also add "another" to the stuff.tar file.
2069 env.Tar('stuff', 'another')
2071 # Set TARFLAGS to create a gzip-filtered archive.
2072 env = Environment(TARFLAGS = '-c -z')
2073 env.Tar('foo.tar.gz', 'foo')
2075 # Also set the suffix to .tgz.
2076 env = Environment(TARFLAGS = '-c -z',
2081 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2083 .IP env.TypeLibrary()
2084 Builds a Windows type library (.tlb) file from and input IDL file
2085 (.idl). In addition, it will build the associated inteface stub and
2086 proxy source files. It names them according to the base name of the .idl file.
2091 env.TypeLibrary(source="foo.idl")
2094 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2099 Builds a header file, an implementation file and a moc file from an ui file.
2100 and returns the corresponding nodes in the above order.
2101 This builder is only available after using the tool 'qt'. Note: you can
2102 specify .ui files directly as inputs for Program, Library and SharedLibrary
2103 without using this builder. Using the builder lets you override the standard
2104 naming conventions (be careful: prefixes are always prepended to names of
2105 built files; if you don't want prefixes, you may set them to ``).
2106 See the QTDIR variable for more information.
2110 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2111 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2112 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2115 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2118 Builds a zip archive of the specified files
2120 Unlike most builder methods,
2123 builder method may be called multiple times
2125 each additional call
2126 adds to the list of entries
2127 that will be built into the archive.
2130 env.Zip('src.zip', 'src')
2132 # Create the stuff.zip file.
2133 env.Zip('stuff', ['subdir1', 'subdir2'])
2134 # Also add "another" to the stuff.tar file.
2135 env.Zip('stuff', 'another')
2140 C source files, C++ source files,
2141 Fortran source files with
2143 (POSIX systems only),
2148 and assembly language files with
2150 (POSIX systems only),
2155 for C preprocessor dependencies,
2156 so the dependencies do not need to be specified explicitly.
2158 targets of builder methods automatically depend on their sources.
2159 An explicit dependency can
2160 be specified using the
2162 method of a construction environment (see below).
2164 .SS Methods and Functions to Do Things
2165 In addition to Builder methods,
2167 provides a number of other construction environment methods
2168 and global functions to
2169 manipulate the build configuration.
2171 Usually, a construction environment method
2172 and global function with the same name both exist
2173 so that you don't have to remember whether
2174 to a specific bit of functionality
2175 must be called with or without a construction environment.
2176 In the following list,
2177 if you call something as a global function
2180 .RI Function( arguments )
2182 and if you call something through a construction
2183 environment it looks like:
2185 .RI env.Function( arguments )
2187 If you can call the functionality in both ways,
2188 then both forms are listed.
2190 Except where otherwise noted,
2192 construction environment method
2194 provide the exact same functionality.
2195 The only difference is that,
2197 calling the functionality through a construction environment will
2198 substitute construction variables into
2199 any supplied strings.
2202 env = Environment(FOO = 'foo')
2206 the first call to the global
2208 function will actually add a target named
2210 to the list of default targets,
2211 while the second call to the
2213 construction environment method
2214 will expand the value
2215 and add a target named
2217 to the list of default targets.
2218 For more on construction variable expansion,
2219 see the next section on
2220 construction variables.
2222 Construction environment methods
2223 and global functions supported by
2227 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2229 .RI Action( action ", [" strfunction ", " varlist ])
2231 .RI env.Action( action ", [" strfunction ", " varlist ])
2232 Creates an Action object for
2235 See the section "Action Objects,"
2236 below, for a complete explanation of the arguments and behavior.
2238 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2240 .RI AddPostAction( target ", " action )
2242 .RI env.AddPostAction( target ", " action )
2243 Arranges for the specified
2249 The specified action(s) may be
2250 an Action object, or anything that
2251 can be converted into an Action object
2254 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2256 .RI AddPreAction( target ", " action )
2258 .RI env.AddPreAction( target ", " action )
2259 Arranges for the specified
2262 before the specified
2265 The specified action(s) may be
2266 an Action object, or anything that
2267 can be converted into an Action object
2270 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2272 .RI Alias( alias ", [" targets ", [" action ]])
2274 .RI env.Alias( alias ", [" targets ", [" action ]])
2275 Creates one or more phony targets that
2276 expand to one or more other targets.
2281 can be specified that will be executed
2282 whenever the any of the alias targets are out-of-date.
2283 Returns the Node object representing the alias,
2284 which exists outside of any file system.
2285 This Node object, or the alias name,
2286 may be used as a dependency of any other target,
2287 including another alias.
2289 can be called multiple times for the same
2290 alias to add additional targets to the alias,
2291 or additional actions to the list for this alias.
2295 Alias('install', '/usr/bin')
2296 Alias(['install', 'install-lib'], '/usr/local/lib')
2298 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2299 env.Alias('install', ['/usr/local/man'])
2301 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2304 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2306 .RI AlwaysBuild( target ", ...)"
2308 .RI env.AlwaysBuild( target ", ...)"
2311 so that it is always assumed to be out of date,
2312 and will always be rebuilt if needed.
2315 does not add its target(s) to the default target list,
2316 so the targets will only be built
2317 if they are specified on the command line,
2318 or are a dependent of a target specified on the command line--but
2321 be built if so specified.
2322 Multiple targets can be passed in to a single call to
2325 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2327 .RI env.Append( key = val ", [...])"
2328 Appends the specified keyword arguments
2329 to the end of construction variables in the environment.
2330 If the Environment does not have
2331 the specified construction variable,
2332 it is simply added to the environment.
2333 If the values of the construction variable
2334 and the keyword argument are the same type,
2335 then the two values will be simply added together.
2336 Otherwise, the construction variable
2337 and the value of the keyword argument
2338 are both coerced to lists,
2339 and the lists are added together.
2340 (See also the Prepend method, below.)
2343 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2348 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2349 This appends new path elements to the given path in the
2350 specified external environment
2354 any particular path once (leaving the last one it encounters and
2355 ignoring the rest, to preserve path order),
2356 and to help assure this,
2357 will normalize all paths (using
2360 .BR os.path.normcase ).
2361 This can also handle the
2362 case where the given old path variable is a list instead of a
2363 string, in which case a list will be returned instead of a string.
2367 print 'before:',env['ENV']['INCLUDE']
2368 include_path = '/foo/bar:/foo'
2369 env.PrependENVPath('INCLUDE', include_path)
2370 print 'after:',env['ENV']['INCLUDE']
2374 after: /biz:/foo/bar:/foo
2377 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2379 .RI env.AppendUnique( key = val ", [...])"
2380 Appends the specified keyword arguments
2381 to the end of construction variables in the environment.
2382 If the Environment does not have
2383 the specified construction variable,
2384 it is simply added to the environment.
2385 If the construction variable being appended to is a list,
2386 then any value(s) that already exist in the
2387 construction variable will
2389 be added again to the list.
2392 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2395 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2398 A factory function that
2399 returns a Builder object
2400 to be used to fetch source files
2402 The returned Builder
2403 is intended to be passed to the
2408 env.SourceCode('.', env.BitKeeper())
2411 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2413 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2415 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2416 This specifies a build directory
2418 in which to build all derived files
2419 that would normally be built under
2421 Multiple build directories can be set up for multiple build variants, for
2424 must be underneath the SConstruct file's directory,
2427 may not be underneath the
2430 The default behavior is for
2432 to duplicate all of the files in the tree underneath
2436 and then build the derived files within the copied tree.
2437 (The duplication is performed by
2439 depending on the platform; see also the
2442 This guarantees correct builds
2443 regardless of whether intermediate source files
2444 are generated during the build,
2445 where preprocessors or other scanners search
2447 or whether individual compilers or other invoked tools
2448 are hard-coded to put derived files in the same directory as source files.
2450 This behavior of making a complete copy of the source tree
2451 may be disabled by setting
2456 to invoke Builders using the
2457 path names of source files in
2459 and the path names of derived files within
2461 This is always more efficient than
2463 and is usually safe for most builds.
2467 may cause build problems
2468 if source files are generated during the build,
2469 if any invoked tools are hard-coded to
2470 put derived files in the same directory as the source files.
2472 Note that specifying a
2474 works most naturally
2475 with a subsidiary SConscript file
2476 in the source directory.
2478 you would then call the subsidiary SConscript file
2479 not in the source directory,
2484 had made a virtual copy of the source tree
2485 regardless of the value of
2487 This is how you tell
2489 which variant of a source tree to build.
2493 BuildDir('build-variant1', 'src')
2494 SConscript('build-variant1/SConscript')
2495 BuildDir('build-variant2', 'src')
2496 SConscript('build-variant2/SConscript')
2502 function, described below,
2504 specify a build directory
2505 in conjunction with calling a subsidiary
2508 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2510 .RI Builder( action ", [" arguments ])
2512 .RI env.Builder( action ", [" arguments ])
2513 Creates a Builder object for
2516 See the section "Builder Objects,"
2517 below, for a complete explanation of the arguments and behavior.
2519 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2521 .RI CacheDir( cache_dir )
2523 .RI env.CacheDir( cache_dir )
2526 will maintain a cache of derived files in
2528 The derived files in the cache will be shared
2529 among all the builds using the same
2537 finds a derived file that needs to be rebuilt,
2538 it will first look in the cache to see if a
2539 derived file has already been built
2540 from identical input files and an identical build action
2541 (as incorporated into the MD5 build signature).
2544 will retrieve the file from the cache.
2545 If the derived file is not present in the cache,
2548 then place a copy of the built file in the cache
2549 (identified by its MD5 build signature),
2550 so that it may be retrieved by other
2551 builds that need to build the same derived file
2552 from identical inputs.
2556 may be disabled for any invocation
2565 will place a copy of
2567 derived files in the cache,
2568 even if they already existed
2569 and were not built by this invocation.
2570 This is useful to populate a cache
2573 is added to a build,
2582 "Retrieved `file' from cache,"
2585 option is being used.
2590 will print the action that
2592 have been used to build the file,
2593 without any indication that
2594 the file was actually retrieved from the cache.
2595 This is useful to generate build logs
2596 that are equivalent regardless of whether
2597 a given derived file has been built in-place
2598 or retrieved from the cache.
2600 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2602 .RI Clean( targets ", " files_or_dirs )
2604 .RI env.Clean( targets ", " files_or_dirs )
2605 This specifies a list of files or directories which should be removed
2606 whenever the targets are specified with the
2608 command line option.
2609 The specified targets may be a list
2610 or an individual target.
2614 and create new targets or add files and directories to the
2615 clean list for the specified targets.
2617 Multiple files or directories should be specified
2618 either as separate arguments to the
2620 method, or as a list.
2622 will also accept the return value of any of the construction environment
2627 Clean('foo', ['bar', 'baz'])
2628 Clean('dist', env.Program('hello', 'hello.c'))
2629 Clean(['foo', 'bar'], 'something_else_to_clean')
2632 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2634 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2636 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2637 Executes a specific action
2638 (or list of actions)
2639 to build a target file or files.
2640 This is more convenient
2641 than defining a separate Builder object
2642 for a single special-case build.
2643 Any keyword arguments specified override any
2644 same-named existing construction variables.
2646 Note that an action can be an external command,
2647 specified as a string,
2648 or a callable Python object;
2649 see "Action Objects," below.
2653 env.Command('foo.out', 'foo.in',
2654 "$FOO_BUILD < $SOURCES > $TARGET")
2656 env.Command('bar.out', 'bar.in',
2658 "$BAR_BUILD < $SOURCES > $TARGET"],
2659 ENV = {'PATH' : '/usr/local/bin/'})
2661 def rename(env, target, source):
2663 os.rename('.tmp', str(target[0]))
2665 env.Command('baz.out', 'baz.in',
2666 ["$BAZ_BUILD < $SOURCES > .tmp",
2670 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2672 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2674 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2675 Creates a Configure object for integrated
2676 functionality similar to GNU autoconf.
2677 See the section "Configure Contexts,"
2678 below, for a complete explanation of the arguments and behavior.
2680 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2682 .RI env.Copy([ key = val ", ...])"
2683 Return a separate copy of a construction environment.
2684 If there are any keyword arguments specified,
2685 they are added to the returned copy,
2686 overwriting any existing values
2691 env3 = env.Copy(CCFLAGS = '-g')
2694 Additionally, a list of tools and a toolpath may be specified, as in
2695 the Environment constructor:
2698 def MyTool(env): env['FOO'] = 'bar'
2699 env4 = env.Copy(tools = ['msvc', MyTool])
2702 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2704 .RI env.CVS( repository ", " module )
2705 A factory function that
2706 returns a Builder object
2707 to be used to fetch source files
2711 The returned Builder
2712 is intended to be passed to the
2716 The optional specified
2718 will be added to the beginning
2719 of all repository path names;
2720 this can be used, in essence,
2721 to strip initial directory names
2722 from the repository path names,
2723 so that you only have to
2724 replicate part of the repository
2725 directory hierarchy in your
2726 local build directory:
2729 # Will fetch foo/bar/src.c
2730 # from /usr/local/CVSROOT/foo/bar/src.c.
2731 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2733 # Will fetch bar/src.c
2734 # from /usr/local/CVSROOT/foo/bar/src.c.
2735 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2738 # from /usr/local/CVSROOT/foo/bar/src.c.
2739 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2742 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2744 .RI Default( targets )
2746 .RI env.Default( targets )
2747 This specifies a list of default targets,
2748 which will be built by
2750 if no explicit targets are given on the command line.
2754 and add to the list of default targets.
2756 Multiple targets should be specified as
2757 separate arguments to the
2759 method, or as a list.
2761 will also accept the Node returned by any
2762 of a construction environment's
2767 Default('foo', 'bar', 'baz')
2768 env.Default(['a', 'b', 'c'])
2769 hello = env.Program('hello', 'hello.c')
2777 will clear all default targets.
2780 will add to the (now empty) default-target list
2783 The current list of targets added using the
2785 function or method is available in the
2790 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2792 .RI DefaultEnvironment([ args ])
2793 Creates and returns a default construction environment object.
2794 This construction environment is used internally by SCons
2795 in order to execute many of the global functions in this list,
2796 and to fetch source files transparently
2797 from source code management systems.
2799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2801 .RI Depends( target ", " dependency )
2803 .RI env.Depends( target ", " dependency )
2804 Specifies an explicit dependency;
2805 the target file(s) will be rebuilt
2806 whenever the dependency file(s) has changed.
2807 This should only be necessary
2808 for cases where the dependency
2809 is not caught by a Scanner
2813 env.Depends('foo', 'other-input-file-for-foo')
2816 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2818 .RI env.Dictionary([ vars ])
2819 Returns a dictionary object
2820 containing copies of all of the
2821 construction variables in the environment.
2822 If there are any variable names specified,
2823 only the specified construction
2824 variables are returned in the dictionary.
2827 dict = env.Dictionary()
2828 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2831 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2833 .RI Dir( name ", [" directory ])
2835 .RI env.Dir( name ", [" directory ])
2836 This returns a Directory Node,
2837 an object that represents the specified directory
2840 can be a relative or absolute path.
2842 is an optional directory that will be used as the parent directory.
2845 is specified, the current script's directory is used as the parent.
2847 Directory Nodes can be used anywhere you
2848 would supply a string as a directory name
2849 to a Builder method or function.
2850 Directory Nodes have attributes and methods
2851 that are useful in many situations;
2852 see "File and Directory Nodes," below.
2854 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2856 .RI env.Dump([ key ])
2857 Returns a pretty printable representation of the environment.
2861 should be a string containing the name of the variable of interest.
2866 print env.Dump('CCCOM')
2870 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2880 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2883 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2888 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2890 .RI EnsurePythonVersion( major ", " minor )
2892 .RI env.EnsurePythonVersion( major ", " minor )
2893 Ensure that the Python version is at least
2896 print out an error message and exit SCons with a non-zero exit code if the
2897 actual Python version is not late enough.
2900 EnsurePythonVersion(2,2)
2903 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2905 .RI EnsureSConsVersion( major ", " minor )
2907 .RI env.EnsureSConsVersion( major ", " minor )
2908 Ensure that the SCons version is at least
2911 print out an error message and exit SCons with a non-zero exit code if the
2912 actual SCons version is not late enough.
2915 EnsureSConsVersion(0,9)
2918 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2920 .RI Environment([ key = value ", ...])"
2922 .RI env.Environment([ key = value ", ...])"
2923 Return a new construction environment
2924 initialized with the specified
2928 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2930 .RI Execute( action ", [" strfunction ", " varlist ])
2932 .RI env.Execute( action ", [" strfunction ", " varlist ])
2933 Executes an Action object.
2936 may be an Action object
2937 (see the section "Action Objects,"
2938 below, for a complete explanation of the arguments and behavior),
2939 or it may be a command-line string,
2941 or executable Python function,
2942 each of which will be converted
2943 into an Action object
2945 The exit value of the command
2946 or return value of the Python function
2949 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2953 .RI env.Exit([ value ])
2959 A default exit value of
2962 is used if no value is specified.
2964 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2968 .RI env.Export( vars )
2971 to export a list of variables from the current
2972 SConscript file to all other SConscript files.
2973 The exported variables are kept in a global collection,
2974 so subsequent calls to
2976 will over-write previous exports that have the same name.
2977 Multiple variable names can be passed to
2979 as separate arguments or as a list. A dictionary can be used to map
2980 variables to a different name when exported. Both local variables and
2981 global variables can be exported.
2986 # Make env available for all SConscript files to Import().
2990 # Make env and package available for all SConscript files:.
2991 Export("env", "package")
2993 # Make env and package available for all SConscript files:
2994 Export(["env", "package"])
2996 # Make env available using the name debug:.
2997 Export({"debug":env})
3003 function supports an
3005 argument that makes it easier to to export a variable or
3006 set of variables to a single SConscript file.
3007 See the description of the
3011 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3013 .RI File( name ", [" directory ])
3015 .RI env.File( name ", [" directory ])
3018 an object that represents the specified file
3021 can be a relative or absolute path.
3023 is an optional directory that will be used as the parent directory.
3025 File Nodes can be used anywhere you
3026 would supply a string as a file name
3027 to a Builder method or function.
3028 File Nodes have attributes and methods
3029 that are useful in many situations;
3030 see "File and Directory Nodes," below.
3032 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3034 .RI FindFile( file ", " dirs )
3036 .RI env.FindFile( file ", " dirs )
3039 in the path specified by
3042 may be a list of file names or a single file name. In addition to searching
3043 for files that exist in the filesytem, this function also searches for
3044 derived files that have not yet been built.
3047 foo = env.FindFile('foo', ['dir1', 'dir2'])
3050 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3052 .RI Flatten( sequence )
3054 .RI env.Flatten( sequence )
3055 Takes a sequence (that is, a Python list or tuple)
3056 that may contain nested sequences
3057 and returns a flattened list containing
3058 all of the individual elements in any sequence.
3059 This can be helpful for collecting
3060 the lists returned by calls to Builders;
3061 other Builders will automatically
3062 flatten lists specified as input,
3063 but direct Python manipulation of
3064 these lists does not:
3067 foo = Object('foo.c')
3068 bar = Object('bar.c')
3070 # Because `foo' and `bar' are lists returned by the Object() Builder,
3071 # `objects' will be a list containing nested lists:
3072 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3074 # Passing such a list to another Builder is all right because
3075 # the Builder will flatten the list automatically:
3076 Program(source = objects)
3078 # If you need to manipulate the list directly using Python, you need to
3079 # call Flatten() yourself, or otherwise handle nested lists:
3080 for object in Flatten(objects):
3084 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3086 .RI GetBuildPath( file ", [" ... ])
3088 .RI env.GetBuildPath( file ", [" ... ])
3091 path name (or names) for the specified
3099 Nodes or strings representing path names.
3101 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3105 .RI env.GetLaunchDir()
3106 Returns the absolute path name of the directory from which
3109 was initially invoked.
3110 This can be useful when using the
3115 options, which internally
3116 change to the directory in which the
3120 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3122 .RI GetOption( name )
3124 .RI env.GetOption( name )
3125 This function provides a way to query a select subset of the scons command line
3126 options from a SConscript file. See
3128 for a description of the options available.
3130 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3132 '\".RI GlobalBuilders( flag )
3136 '\"adds the names of the default builders
3137 '\"(Program, Library, etc.)
3138 '\"to the global name space
3139 '\"so they can be called without an explicit construction environment.
3140 '\"(This is the default.)
3144 '\"the names of the default builders are removed
3145 '\"from the global name space
3146 '\"so that an explicit construction environment is required
3147 '\"to call all builders.
3149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3153 .RI env.Help( text )
3154 This specifies help text to be printed if the
3156 argument is given to
3160 is called multiple times, the text is appended together in the order
3165 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3167 .RI Ignore( target ", " dependency )
3169 .RI env.Ignore( target ", " dependency )
3170 The specified dependency file(s)
3171 will be ignored when deciding if
3172 the target file(s) need to be rebuilt.
3175 env.Ignore('foo', 'foo.c')
3176 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3179 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3183 .RI env.Import( vars )
3186 to import a list of variables into the current SConscript file. This
3187 will import variables that were exported with
3193 Variables exported by
3196 Multiple variable names can be passed to
3198 as separate arguments or as a list. The variable "*" can be used
3199 to import all variables.
3204 Import("env", "variable")
3205 Import(["env", "variable"])
3209 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3211 .RI Install( dir ", " source )
3213 .RI env.Install( dir ", " source )
3214 Installs one or more files in a destination directory.
3215 The file names remain the same.
3218 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3221 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3223 .RI InstallAs( target ", " source )
3225 .RI env.InstallAs( target ", " source )
3226 Installs one or more files as specific file names,
3227 allowing changing a file name as part of the
3229 It is an error if the target and source
3230 list different numbers of files.
3233 env.InstallAs(target = '/usr/local/bin/foo',
3234 source = 'foo_debug')
3235 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3236 source = ['libFOO.a', 'libBAR.a'])
3239 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3241 .RI Literal( string )
3243 .RI env.Literal( string )
3246 will be preserved as-is
3247 and not have construction variables expanded.
3249 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3251 .RI Local( targets )
3253 .RI env.Local( targets )
3256 will have copies made in the local tree,
3257 even if an already up-to-date copy
3258 exists in a repository.
3259 Returns a list of the target Node or Nodes.
3261 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3263 .RI env.ParseConfig( command ", [" function ])
3266 to modify the environment as specified by the output of
3270 expects the output of a typical
3274 and parses the returned
3295 option gets added to both the
3302 option gets added to the
3305 Any other strings not associated with options
3306 are assumed to be the names of libraries
3309 construction variable.
3311 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3313 .RI ParseDepends( filename ", [" must_exist ])
3315 .RI env.ParseDepends( filename ", [" must_exist ])
3316 Parses the contents of the specified
3318 as a list of dependencies in the style of
3322 and explicitly establishes all of the listed dependencies.
3330 argument may be set to a non-zero
3333 throw an exception and
3334 generate an error if the file does not exist,
3335 or is otherwise inaccessible.
3338 and all of the files listed therein
3339 will be interpreted relative to
3340 the directory of the
3342 file which called the
3346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3349 A factory function that
3350 returns a Builder object
3351 to be used to fetch source files
3352 from the Perforce source code management system.
3353 The returned Builder
3354 is intended to be passed to the
3359 env.SourceCode('.', env.Perforce())
3362 Perforce uses a number of external
3363 environment variables for its operation.
3364 Consequently, this function adds the
3365 following variables from the user's external environment
3366 to the construction environment's
3379 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3381 .RI Platform( string )
3382 Returns a callable object
3383 that can be used to initialize
3384 a construction environment using the
3385 platform keyword of the Environment() method:
3388 env = Environment(platform = Platform('win32'))
3391 .RI env.Platform( string )
3392 Applies the callable object for the specified platform
3394 to the environment through which the method was called.
3397 env.Platform('posix')
3404 variable from the user's external environment
3405 to the construction environment's
3408 This is so that any executed commands
3409 that use sockets to connect with other systems
3410 (such as fetching source files from
3411 external CVS repository specifications like
3412 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3413 will work on Win32 systems.
3415 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3417 .RI Precious( target ", ...)"
3419 .RI env.Precious( target ", ...)"
3422 as precious so it is not deleted before it is rebuilt. Normally
3424 deletes a target before building it.
3425 Multiple targets can be passed in to a single call to
3428 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3430 .RI env.Prepend( key = val ", [...])"
3431 Appends the specified keyword arguments
3432 to the beginning of construction variables in the environment.
3433 If the Environment does not have
3434 the specified construction variable,
3435 it is simply added to the environment.
3436 If the values of the construction variable
3437 and the keyword argument are the same type,
3438 then the two values will be simply added together.
3439 Otherwise, the construction variable
3440 and the value of the keyword argument
3441 are both coerced to lists,
3442 and the lists are added together.
3443 (See also the Append method, above.)
3446 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3449 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3451 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3452 This appends new path elements to the given path in the
3453 specified external environment
3457 any particular path once (leaving the first one it encounters and
3458 ignoring the rest, to preserve path order),
3459 and to help assure this,
3460 will normalize all paths (using
3463 .BR os.path.normcase ).
3464 This can also handle the
3465 case where the given old path variable is a list instead of a
3466 string, in which case a list will be returned instead of a string.
3470 print 'before:',env['ENV']['INCLUDE']
3471 include_path = '/foo/bar:/foo'
3472 env.PrependENVPath('INCLUDE', include_path)
3473 print 'after:',env['ENV']['INCLUDE']
3477 after: /foo/bar:/foo:/biz
3480 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3482 .RI env.AppendUnique( key = val ", [...])"
3483 Appends the specified keyword arguments
3484 to the beginning of construction variables in the environment.
3485 If the Environment does not have
3486 the specified construction variable,
3487 it is simply added to the environment.
3488 If the construction variable being appended to is a list,
3489 then any value(s) that already exist in the
3490 construction variable will
3492 be added again to the list.
3495 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3498 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3501 A factory function that
3502 returns a Builder object
3503 to be used to fetch source files
3505 The returned Builder
3506 is intended to be passed to the
3511 env.SourceCode('.', env.RCS())
3516 will fetch source files
3517 from RCS subdirectories automatically,
3519 as demonstrated in the above example
3520 should only be necessary if
3521 you are fetching from
3524 directory as the source files,
3525 or if you need to explicitly specify RCS
3526 for a specific subdirectory.
3528 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3530 .RI env.Replace( key = val ", [...])"
3531 Replaces construction variables in the Environment
3532 with the specified keyword arguments.
3535 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3538 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3540 .RI Repository( directory )
3542 .RI env.Repository( directory )
3545 is a repository to be searched for files.
3549 and each one adds to the list of
3550 repositories that will be searched.
3554 a repository is a copy of the source tree,
3555 from the top-level directory on down,
3557 both source files and derived files
3558 that can be used to build targets in
3559 the local source tree.
3560 The canonical example would be an
3561 official source tree maintained by an integrator.
3562 If the repository contains derived files,
3563 then the derived files should have been built using
3565 so that the repository contains the necessary
3566 signature information to allow
3568 to figure out when it is appropriate to
3569 use the repository copy of a derived file,
3570 instead of building one locally.
3572 Note that if an up-to-date derived file
3573 already exists in a repository,
3577 make a copy in the local directory tree.
3578 In order to guarantee that a local copy
3584 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3589 what variable(s) to use as the return value(s) of the current SConscript
3590 file. These variables will be returned to the "calling" SConscript file
3591 as the return value(s) of
3593 Multiple variable names should be passed to
3599 Return(["foo", "bar"])
3602 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3604 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3606 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3607 Creates a Scanner object for
3610 See the section "Scanner Objects,"
3611 below, for a complete explanation of the arguments and behavior.
3613 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3616 A factory function that
3617 returns a Builder object
3618 to be used to fetch source files
3620 The returned Builder
3621 is intended to be passed to the
3626 env.SourceCode('.', env.SCCS())
3631 will fetch source files
3632 from SCCS subdirectories automatically,
3634 as demonstrated in the above example
3635 should only be necessary if
3636 you are fetching from
3639 directory as the source files,
3640 or if you need to explicitly specify SCCS
3641 for a specific subdirectory.
3643 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3645 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3647 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3649 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3651 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3655 one or more subsidiary SConscript (configuration) files.
3656 There are two ways to call the
3660 The first way you can call
3662 is to explicitly specify one or more
3664 as the first argument.
3665 A single script may be specified as a string;
3666 multiple scripts must be specified as a list
3667 (either explicitly or as created by
3671 The second way you can call
3673 is to specify a list of (sub)directory names
3680 execute a subsidiary configuration file named
3682 in each of the specified directories.
3683 You may specify a name other than
3685 by supplying an optional
3691 argument provides a list of variable names or a dictionary of
3692 named values to export to the
3694 These variables are locally exported only to the specified
3696 and do not affect the
3697 global pool of variables used by
3701 '\"If multiple dirs are provided,
3702 '\"each script gets a fresh export.
3707 function to import the variables.
3711 argument specifies that all of the target files
3712 (for example, object files and executables)
3713 that would normally be built in the subdirectory in which
3715 resides should actually
3719 is interpreted relative to the directory
3720 of the calling SConscript file.
3724 argument specifies that the
3725 source files from which
3726 the target files should be built
3730 is interpreted relative to the directory
3731 of the calling SConscript file.
3735 will link or copy (depending on the platform)
3736 all the source files into the build directory.
3737 This behavior may be disabled by
3738 setting the optional
3741 (it is set to 1 by default),
3744 will refer directly to
3745 the source files in their source directory
3746 when building target files.
3749 is usually safe, and always more efficient
3752 but it may cause build problems in certain end-cases,
3753 such as compiling from source files that
3754 are generated by the build.)
3756 Any variables returned by
3760 will be returned by the call to
3766 SConscript('subdir/SConscript')
3767 foo = SConscript('sub/SConscript', exports='env')
3768 SConscript('dir/SConscript', exports=['env', 'variable'])
3769 SConscript('src/SConscript', build_dir='build', duplicate=0)
3770 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3771 SConscript(dirs=['sub1', 'sub2'])
3772 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3777 .RI SConscriptChdir( value )
3779 .RI env.SConscriptChdir( value )
3782 changes its working directory
3783 to the directory in which each
3784 subsidiary SConscript file lives.
3785 This behavior may be disabled
3786 by specifying either:
3790 env.SConscriptChdir(0)
3795 will stay in the top-level directory
3796 while reading all SConscript files.
3797 (This may be necessary when building from repositories,
3798 when all the directories in which SConscript files may be found
3799 don't necessarily exist locally.)
3801 You may enable and disable
3802 this ability by calling
3809 SConscript('foo/SConscript') # will not chdir to foo
3810 env.SConscriptChdir(1)
3811 SConscript('bar/SConscript') # will chdir to bar
3814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3816 .RI SConsignFile([ file , dbm_module ])
3818 .RI env.SConsignFile([ file , dbm_module ])
3821 to store all file signatures
3831 is not an absolute path name,
3832 the file is placed in the same directory as the top-level
3838 argument can be used to specify
3839 which Python database module
3840 The default is to use a custom
3842 module that uses pickled
3843 Python data structures,
3844 and which works on all Python versions from 1.5.2 on.
3849 # Stores signatures in ".sconsign.dbm"
3850 # in the top-level SConstruct directory.
3853 # Stores signatures in the file "etc/scons-signatures"
3854 # relative to the top-level SConstruct directory.
3855 SConsignFile("etc/scons-signatures")
3857 # Stores signatures in the specified absolute file name.
3858 SConsignFile("/home/me/SCons/signatures")
3861 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3863 .RI env.SetDefault(key = val ", [...])"
3864 Sets construction variables to default values specified with the keyword
3865 arguments if (and only if) the variables are not already set.
3866 The following statements are equivalent:
3869 env.SetDefault(FOO = 'foo')
3871 if not env.has_key('FOO'): env['FOO'] = 'foo'
3874 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3876 .RI SetOption( name ", " value )
3878 .RI env.SetOption( name ", " value )
3879 This function provides a way to set a select subset of the scons command
3880 line options from a SConscript file. The options supported are:
3882 which corresponds to -c, --clean, and --remove;
3885 corresponds to --duplicate;
3887 which corresponds to --implicit-cache;
3889 which corresponds to --max-drift;
3891 which corresponds to -j and --jobs.
3892 See the documentation for the
3893 corresponding command line object for information about each specific
3897 SetOption('max_drift', 1)
3900 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3902 .RI SideEffect( side_effect ", " target )
3904 .RI env.SideEffect( side_effect ", " target )
3907 as a side effect of building
3913 can be a list, a file name, or a node.
3914 A side effect is a target that is created
3915 as a side effect of building other targets.
3916 For example, a Windows PDB
3917 file is created as a side effect of building the .obj
3918 files for a static library.
3919 If a target is a side effect of multiple build commands,
3921 will ensure that only one set of commands
3922 is executed at a time.
3923 Consequently, you only need to use this method
3924 for side-effect targets that are built as a result of
3925 multiple build commands.
3927 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3929 .RI SourceCode( entries ", " builder )
3931 .RI env.SourceCode( entries ", " builder )
3932 Arrange for non-existent source files to
3933 be fetched from a source code management system
3938 may be a Node, string or list of both,
3939 and may represent either individual
3940 source files or directories in which
3941 source files can be found.
3943 For any non-existent source files,
3945 will search up the directory tree
3955 will not use a builder to fetch
3956 source files for the specified
3960 builder has been specified
3961 for a directory higher up the tree.
3965 fetch files from SCCS or RCS subdirectories
3966 without explicit configuration.
3967 This takes some extra processing time
3968 to search for the necessary
3969 source code management files on disk.
3970 You can avoid these extra searches
3971 and speed up your build a little
3972 by disabling these searches as follows:
3975 env.SourceCode('.', None)
3979 Note that if the specified
3981 is one you create by hand,
3982 it must have an associated
3983 construction environment to use
3984 when fetching a source file.
3987 provides a set of canned factory
3988 functions that return appropriate
3989 Builders for various popular
3990 source code management systems.
3991 Canonical examples of invocation include:
3994 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3995 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3996 env.SourceCode('/', env.RCS())
3997 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3998 env.SourceCode('no_source.c', None)
4000 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4002 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4004 '\".RI Subversion( repository ", " module )
4005 '\"A factory function that
4006 '\"returns a Builder object
4007 '\"to be used to fetch source files
4008 '\"from the specified Subversion
4010 '\"The returned Builder
4011 '\"is intended to be passed to the
4015 '\"The optional specified
4017 '\"will be added to the beginning
4018 '\"of all repository path names;
4019 '\"this can be used, in essence,
4020 '\"to strip initial directory names
4021 '\"from the repository path names,
4022 '\"so that you only have to
4023 '\"replicate part of the repository
4024 '\"directory hierarchy in your
4025 '\"local build directory:
4028 '\"# Will fetch foo/bar/src.c
4029 '\"# from /usr/local/Subversion/foo/bar/src.c.
4030 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4032 '\"# Will fetch bar/src.c
4033 '\"# from /usr/local/Subversion/foo/bar/src.c.
4034 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4036 '\"# Will fetch src.c
4037 '\"# from /usr/local/Subversion/foo/bar/src.c.
4038 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4041 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4043 .RI SourceSignatures( type )
4045 .RI env.SourceSignatures( type )
4046 This function tells SCons what type of signature to use for source files:
4050 If the environment method is used,
4051 the specified type of source signature
4052 is only used when deciding whether targets
4053 built with that environment are up-to-date or must be rebuilt.
4054 If the global function is used,
4055 the specified type of source signature becomes the default
4056 used for all decisions
4057 about whether targets are up-to-date.
4059 "MD5" means the signature of a source file
4060 is the MD5 checksum of its contents.
4061 "timestamp" means the signature of a source file
4062 is its timestamp (modification time).
4063 There is no different between the two behaviors
4067 "MD5" signatures take longer to compute,
4068 but are more accurate than "timestamp" signatures.
4069 The default is "MD5".
4071 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4075 .RI env.Split( arg )
4076 Returns a list of file names or other objects.
4078 it will be split on strings of white-space characters
4080 making it easier to write long lists of file names.
4081 If arg is already a list,
4082 the list will be returned untouched.
4083 If arg is any other type of object,
4084 it will be returned as a list
4085 containing just the object.
4088 files = Split("f1.c f2.c f3.c")
4089 files = env.Split("f4.c f5.c f6.c")
4097 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4099 .RI TargetSignatures( type )
4101 .RI env.TargetSignatures( type )
4102 This function tells SCons what type of signatures to use
4107 If the environment method is used,
4108 the specified type of signature is only used
4109 for targets built with that environment.
4110 If the global function is used,
4111 the specified type of signature becomes the default
4112 used for all target files that
4113 don't have an explicit target signature type
4114 specified for their environments.
4116 "build" means the signature of a target file
4117 is made by concatenating all of the
4118 signatures of all its source files.
4119 "content" means the signature of a target
4120 file is an MD5 checksum of its contents.
4121 "build" signatures are usually faster to compute,
4122 but "content" signatures can prevent unnecessary rebuilds
4123 when a target file is rebuilt to the exact same contents
4124 as the previous build.
4125 The default is "build".
4127 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4129 .RI Tool( string [, toolpath ", " **kw ])
4130 Returns a callable object
4131 that can be used to initialize
4132 a construction environment using the
4133 tools keyword of the Environment() method.
4134 The object may be called with a construction
4135 environment as an argument,
4136 in which case the object will
4137 add the necessary variables
4138 to the construction environment
4139 and the name of the tool will be added to the
4141 construction variable.
4143 Additional keyword arguments are passed to the tool's
4148 env = Environment(tools = [ Tool('msvc') ])
4152 t(env) # adds 'msvc' to the TOOLS variable
4153 u = Tool('opengl', toolpath = ['tools'])
4154 u(env) # adds 'opengl' to the TOOLS variable
4157 .RI env.Tool( string [, toolpath ", " **kw ])
4158 Applies the callable object for the specified tool
4160 to the environment through which the method was called.
4162 Additional keyword arguments are passed to the tool's
4168 env.Tool('opengl', toolpath = ['build/tools'])
4171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4175 .RI env.Value( value )
4176 Returns a Node object representing the specified Python value. Value
4177 nodes can be used as dependencies of targets. If the result of
4180 changes between SCons runs, any targets depending on
4182 will be rebuilt. When using timestamp source signatures, Value nodes'
4183 timestamps are equal to the system time when the node is created.
4186 def create(target, source, env):
4187 f = open(str(target[0]), 'wb')
4188 f.write('prefix=' + source[0].get_contents())
4190 prefix = ARGUMENTS.get('prefix', '/usr/local')
4192 env['BUILDERS']['Config'] = Builder(action = create)
4193 env.Config(target = 'package-config', source = Value(prefix))
4196 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4198 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4200 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4202 Searches for the specified executable
4204 returning the full path name to the program
4206 and returning None if not.
4207 Searches the specified
4209 the value of the calling environment's PATH
4210 (env['ENV']['PATH']),
4211 or the user's current external PATH
4212 (os.environ['PATH'])
4214 On Win32 systems, searches for executable
4215 programs with any of the file extensions
4216 listed in the specified
4218 the calling environment's PATHEXT
4219 (env['ENV']['PATHEXT'])
4220 or the user's current PATHEXT
4221 (os.environ['PATHEXT'])
4229 .SS SConscript Variables
4230 In addition to the global functions and methods,
4232 supports a number of Python variables
4233 that can be used in SConscript files
4234 to affect how you want the build to be performed.
4236 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4241 arguments specified on the command line.
4242 Each element in the list is a tuple
4244 .RI ( keyword , value )
4250 elements of the tuple
4252 subscripting for element
4256 of the tuple, respectively.
4259 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4260 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4261 third_tuple = ARGLIST[2]
4262 print "third keyword, value =", third_tuple[0], third_tuple[1]
4263 for key, value in ARGLIST:
4264 # process key and value
4267 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4270 A dictionary of all the
4272 arguments specified on the command line.
4273 The dictionary is not in order,
4274 and if a given keyword has
4275 more than one value assigned to it
4276 on the command line,
4277 the last (right-most) value is
4283 if ARGUMENTS.get('debug', 0):
4284 env = Environment(CCFLAGS = '-g')
4289 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4292 A list of the targets which
4294 will actually try to build,
4295 regardless of whether they were specified on
4296 the command line or via the
4299 The elements of this list may be strings
4301 nodes, so you should run the list through the Python
4303 function to make sure any Node path names
4304 are converted to strings.
4306 Because this list may be taken from the
4307 list of targets specified using the
4310 the contents of the list may change
4311 on each successive call to
4316 for additional information.
4319 if 'foo' in BUILD_TARGETS:
4320 print "Don't forget to test the `foo' program!"
4321 if 'special/program' in BUILD_TARGETS:
4322 SConscript('special')
4327 list only contains targets expected listed
4328 on the command line or via calls to the
4333 contain all dependent targets that will be built as
4334 a result of making the sure the explicitly-specified
4335 targets are up to date.
4337 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4339 COMMAND_LINE_TARGETS
4340 A list of the targets explicitly specified on
4342 If there are no targets specified on the command line,
4344 This can be used, for example,
4345 to take specific actions only
4346 when a certain target or targets
4347 is explicitly being built:
4350 if 'foo' in COMMAND_LINE_TARGETS:
4351 print "Don't forget to test the `foo' program!"
4352 if 'special/program' in COMMAND_LINE_TARGETS:
4353 SConscript('special')
4356 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4359 A list of the target
4361 that have been specified using the
4364 The elements of the list are nodes,
4365 so you need to run them through the Python
4367 function to get at the path name for each Node.
4370 print str(DEFAULT_TARGETS[0])
4371 if 'foo' in map(str, DEFAULT_TARGETS):
4372 print "Don't forget to test the `foo' program!"
4377 list change on on each successive call to the
4382 print map(str, DEFAULT_TARGETS) # originally []
4384 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4386 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4388 print map(str, DEFAULT_TARGETS) # back to []
4391 Consequently, be sure to use
4393 only after you've made all of your
4396 or else simply be careful of the order
4397 of these statements in your SConscript files
4398 so that you don't look for a specific
4399 default target before it's actually been added to the list.
4401 .SS Construction Variables
4402 .\" XXX From Gary Ruben, 23 April 2002:
4403 .\" I think it would be good to have an example with each construction
4404 .\" variable description in the documentation.
4406 .\" CC The C compiler
4407 .\" Example: env["CC"] = "c68x"
4408 .\" Default: env["CC"] = "cc"
4410 .\" CCCOM The command line ...
4412 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4413 .\" env["CC"] = "c68x"
4414 .\" env["CFLAGS"] = "-ps -qq -mr"
4415 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4417 .\" (I dunno what this is ;-)
4418 A construction environment has an associated dictionary of
4419 .I construction variables
4420 that are used by built-in or user-supplied build rules.
4421 Construction variables must follow the same rules for
4423 the initial character must be an underscore or letter,
4424 followed by any number of underscores, letters, or digits.
4426 A number of useful construction variables are automatically defined by
4427 scons for each supported platform, and additional construction variables
4428 can be defined by the user. The following is a list of the automatically
4429 defined construction variables:
4432 The static library archiver.
4435 The command line used to generate a static library from object files.
4438 The string displayed when an object file
4439 is generated from an assembly-language source file.
4440 If this is not set, then $ARCOM (the command line) is displayed.
4443 env = Environment(ARCOMSTR = "Archiving $TARGET")
4447 General options passed to the static library archiver.
4453 The command line used to generate an object file
4454 from an assembly-language source file.
4457 The string displayed when an object file
4458 is generated from an assembly-language source file.
4459 If this is not set, then $ASCOM (the command line) is displayed.
4462 env = Environment(ASCOMSTR = "Assembling $TARGET")
4466 General options passed to the assembler.
4469 The command line used to assemble an assembly-language
4470 source file into an object file
4471 after first running the file through the C preprocessor.
4472 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4473 are included on this command line.
4476 The string displayed when an object file
4477 is generated from an assembly-language source file
4478 after first running the file through the C preprocessor.
4479 If this is not set, then $ASPPCOM (the command line) is displayed.
4482 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4486 General options when an assembling an assembly-language
4487 source file into an object file
4488 after first running the file through the C preprocessor.
4489 The default is to use the value of $ASFLAGS.
4492 The bibliography generator for the TeX formatter and typesetter and the
4493 LaTeX structured formatter and typesetter.
4496 The command line used to call the bibliography generator for the
4497 TeX formatter and typesetter and the LaTeX structured formatter and
4501 General options passed to the bibliography generator for the TeX formatter
4502 and typesetter and the LaTeX structured formatter and typesetter.
4505 The BitKeeper executable.
4508 The command line for
4509 fetching source files using BitKeeper.
4512 The string displayed when fetching
4513 a source file using BitKeeper.
4514 If this is not set, then $BITKEEPERCOM
4515 (the command line) is displayed.
4518 The command ($BITKEEPER) and subcommand
4519 for fetching source files using BitKeeper.
4521 .IP BITKEEPERGETFLAGS
4522 Options that are passed to the BitKeeper
4527 A dictionary mapping the names of the builders
4528 available through this environment
4529 to underlying Builder objects.
4531 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4532 are available by default.
4533 If you initialize this variable when an
4534 Environment is created:
4537 env = Environment(BUILDERS = {'NewBuilder' : foo})
4540 the default Builders will no longer be available.
4541 To use a new Builder object in addition to the default Builders,
4542 add your new Builder object like this:
4546 env.Append(BUILDERS = {'NewBuilder' : foo})
4553 env['BUILDERS]['NewBuilder'] = foo
4560 The command line used to compile a C source file to a (static) object file.
4561 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4562 are included on this command line.
4565 The string displayed when a C source file
4566 is compiled to a (static) object file.
4567 If this is not set, then $CCCOM (the command line) is displayed.
4570 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4574 General options that are passed to the C compiler.
4577 The suffix for C source files.
4578 This is used by the internal CFile builder
4579 when generating C files from Lex (.l) or YACC (.y) input files.
4580 The default suffix, of course, is
4583 On case-insensitive systems (like Win32),
4590 The version number of the C compiler.
4591 This may or may not be set,
4592 depending on the specific C compiler being used.
4595 A function used to produce variables like $_CPPINCFLAGS. It takes
4597 arguments: a prefix to concatenate onto each element, a list of
4598 elements, a suffix to concatenate onto each element, an environment
4599 for variable interpolation, and an optional function that will be
4600 called to transform the list before concatenation.
4603 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4607 A platform independent specification of C preprocessor definitions.
4608 The definitions will be added to command lines
4609 through the automatically-generated
4610 $_CPPDEFFLAGS construction variable (see below),
4611 which is constructed according to
4612 the type of value of $CPPDEFINES:
4615 If $CPPDEFINES is a string,
4617 $CPPDEFPREFIX and $CPPDEFSUFFIX
4618 construction variables
4619 will be added to the beginning and end.
4622 # Will add -Dxyz to POSIX compiler command lines,
4623 # and /Dxyz to Microsoft Visual C++ command lines.
4624 env = Environment(CPPDEFINES='xyz')
4628 If $CPPDEFINES is a list,
4630 $CPPDEFPREFIX and $CPPDEFSUFFIX
4631 construction variables
4632 will be appended to the beginning and end
4633 of each element in the list.
4634 If any element is a list or tuple,
4635 then the first item is the name being
4636 defined and the second item is its value:
4639 # Will add -DB=2 -DA to POSIX compiler command lines,
4640 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4641 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4645 If $CPPDEFINES is a dictionary,
4647 $CPPDEFPREFIX and $CPPDEFSUFFIX
4648 construction variables
4649 will be appended to the beginning and end
4650 of each item from the dictionary.
4651 The key of each dictionary item
4652 is a name being defined
4653 to the dictionary item's corresponding value;
4656 then the name is defined without an explicit value.
4657 Note that the resulting flags are sorted by keyword
4658 to ensure that the order of the options on the
4659 command line is consistent each time
4664 # Will add -DA -DB=2 to POSIX compiler command lines,
4665 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4666 env = Environment(CPPDEFINES={'B':2, 'A':None})
4670 An automatically-generated construction variable
4671 containing the C preprocessor command-line options
4673 The value of $_CPPDEFFLAGS is created
4674 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4675 to the beginning and end
4676 of each directory in $CPPDEFINES.
4679 The prefix used to specify preprocessor definitions
4680 on the C compiler command line.
4681 This will be appended to the beginning of each definition
4682 in the $CPPDEFINES construction variable
4683 when the $_CPPDEFFLAGS variable is automatically generated.
4686 The suffix used to specify preprocessor definitions
4687 on the C compiler command line.
4688 This will be appended to the end of each definition
4689 in the $CPPDEFINES construction variable
4690 when the $_CPPDEFFLAGS variable is automatically generated.
4693 User-specified C preprocessor options.
4694 These will be included in any command that uses the C preprocessor,
4695 including not just compilation of C and C++ source files
4696 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4697 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4698 $F77PPCOM and $SHF77PPCOM command lines
4699 used to compile a Fortran source file,
4700 and the $ASPPCOM command line
4701 used to assemble an assembly language source file,
4702 after first running each file through the C preprocessor.
4703 Note that this variable does
4707 (or similar) include search path options
4708 that scons generates automatically from $CPPPATH.
4712 for the variable that expands to those options.
4715 An automatically-generated construction variable
4716 containing the C preprocessor command-line options
4717 for specifying directories to be searched for include files.
4718 The value of $_CPPINCFLAGS is created
4719 by appending $INCPREFIX and $INCSUFFIX
4720 to the beginning and end
4721 of each directory in $CPPPATH.
4724 The list of directories that the C preprocessor will search for include
4725 directories. The C/C++ implicit dependency scanner will search these
4726 directories for include files. Don't explicitly put include directory
4727 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4728 and the directories will not be searched by the dependency scanner. Note:
4729 directory names in CPPPATH will be looked-up relative to the SConscript
4730 directory when they are used in a command. To force
4732 to look-up a directory relative to the root of the source tree use #:
4735 env = Environment(CPPPATH='#/include')
4739 The directory look-up can also be forced using the
4744 include = Dir('include')
4745 env = Environment(CPPPATH=include)
4749 The directory list will be added to command lines
4750 through the automatically-generated
4752 construction variable,
4753 which is constructed by
4754 appending the values of the
4755 $INCPREFIX and $INCSUFFIX
4756 construction variables
4757 to the beginning and end
4758 of each directory in $CPPPATH.
4759 Any command lines you define that need
4760 the CPPPATH directory list should
4761 include $_CPPINCFLAGS:
4764 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4768 The list of suffixes of files that will be scanned
4769 for C preprocessor implicit dependencies
4771 The default list is:
4774 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4775 ".h", ".H", ".hxx", ".hpp", ".hh",
4776 ".F", ".fpp", ".FPP",
4777 ".S", ".spp", ".SPP"]
4784 Options that are passed to the CVS checkout subcommand.
4787 The command line used to
4788 fetch source files from a CVS repository.
4791 The string displayed when fetching
4792 a source file from a CVS repository.
4793 If this is not set, then $CVSCOM
4794 (the command line) is displayed.
4797 General options that are passed to CVS.
4798 By default, this is set to
4800 to specify from where the files must be fetched.
4803 The path to the CVS repository.
4804 This is referenced in the default
4811 The suffix for C++ source files.
4812 This is used by the internal CXXFile builder
4813 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4814 The default suffix is
4816 SCons also treats files with the suffixes
4823 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4830 The command line used to compile a C++ source file to an object file.
4831 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4832 are included on this command line.
4835 The string displayed when a C++ source file
4836 is compiled to a (static) object file.
4837 If this is not set, then $CXXCOM (the command line) is displayed.
4840 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
4844 General options that are passed to the C++ compiler.
4847 The version number of the C++ compiler.
4848 This may or may not be set,
4849 depending on the specific C++ compiler being used.
4852 A function that converts a file name into a Dir instance relative to the
4856 The list of suffixes of files that will be scanned
4857 for imported D package files.
4858 The default list is:
4865 The TeX DVI file to PDF file converter.
4868 General options passed to the TeX DVI file to PDF file converter.
4871 The command line used to convert TeX DVI files into a PDF file.
4874 The TeX DVI file to PostScript converter.
4877 General options passed to the TeX DVI file to PostScript converter.
4880 A dictionary of environment variables
4881 to use when invoking commands. When ENV is used in a command all list
4882 values will be joined using the path separator and any other non-string
4883 values will simply be coerced to a string.
4884 Note that, by default,
4888 propagate the environment in force when you
4891 to the commands used to build target files.
4892 This is so that builds will be guaranteed
4893 repeatable regardless of the environment
4894 variables set at the time
4898 If you want to propagate your
4899 environment variables
4900 to the commands executed
4901 to build target files,
4902 you must do so explicitly:
4906 env = Environment(ENV = os.environ)
4910 Note that you can choose only to propagate
4911 certain environment variables.
4915 environment variable,
4918 uses the same utilities
4919 as the invoking shell (or other process):
4924 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4928 A function that will be called to escape shell special characters in
4929 command lines. The function should take one argument: the command line
4930 string to escape; and should return the escaped command line.
4933 The Fortran 77 compiler.
4934 You should normally set the $FORTRAN variable,
4935 which specifies the default Fortran compiler
4936 for all Fortran versions.
4937 You only need to set $F77 if you need to use a specific compiler
4938 or compiler version for Fortran 77 files.
4941 The command line used to compile a Fortran 77 source file to an object file.
4942 You only need to set $F77COM if you need to use a specific
4943 command line for Fortran 77 files.
4944 You should normally set the $FORTRANCOM variable,
4945 which specifies the default command line
4946 for all Fortran versions.
4949 The string displayed when a Fortran 77 source file
4950 is compiled to an object file.
4951 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
4954 General user-specified options that are passed to the Fortran 77 compiler.
4955 Note that this variable does
4959 (or similar) include search path options
4960 that scons generates automatically from $F77PATH.
4964 for the variable that expands to those options.
4965 You only need to set $F77FLAGS if you need to define specific
4966 user options for Fortran 77 files.
4967 You should normally set the $FORTRANFLAGS variable,
4968 which specifies the user-specified options
4969 passed to the default Fortran compiler
4970 for all Fortran versions.
4973 An automatically-generated construction variable
4974 containing the Fortran 77 compiler command-line options
4975 for specifying directories to be searched for include files.
4976 The value of $_F77INCFLAGS is created
4977 by appending $INCPREFIX and $INCSUFFIX
4978 to the beginning and end
4979 of each directory in $F77PATH.
4982 The list of directories that the Fortran 77 compiler will search for include
4983 directories. The implicit dependency scanner will search these
4984 directories for include files. Don't explicitly put include directory
4985 arguments in $F77FLAGS because the result will be non-portable
4986 and the directories will not be searched by the dependency scanner. Note:
4987 directory names in $F77PATH will be looked-up relative to the SConscript
4988 directory when they are used in a command. To force
4990 to look-up a directory relative to the root of the source tree use #:
4991 You only need to set $F77PATH if you need to define a specific
4992 include path for Fortran 77 files.
4993 You should normally set the $FORTRANPATH variable,
4994 which specifies the include path
4995 for the default Fortran compiler
4996 for all Fortran versions.
4999 env = Environment(F77PATH='#/include')
5003 The directory look-up can also be forced using the
5008 include = Dir('include')
5009 env = Environment(F77PATH=include)
5013 The directory list will be added to command lines
5014 through the automatically-generated
5016 construction variable,
5017 which is constructed by
5018 appending the values of the
5019 $INCPREFIX and $INCSUFFIX
5020 construction variables
5021 to the beginning and end
5022 of each directory in $F77PATH.
5023 Any command lines you define that need
5024 the F77PATH directory list should
5025 include $_F77INCFLAGS:
5028 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5032 The command line used to compile a Fortran 77 source file to an object file
5033 after first running the file through the C preprocessor.
5034 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5035 are included on this command line.
5036 You only need to set $F77PPCOM if you need to use a specific
5037 C-preprocessor command line for Fortran 77 files.
5038 You should normally set the $FORTRANPPCOM variable,
5039 which specifies the default C-preprocessor command line
5040 for all Fortran versions.
5043 The Fortran 90 compiler.
5044 You should normally set the $FORTRAN variable,
5045 which specifies the default Fortran compiler
5046 for all Fortran versions.
5047 You only need to set $F90 if you need to use a specific compiler
5048 or compiler version for Fortran 90 files.
5051 The command line used to compile a Fortran 90 source file to an object file.
5052 You only need to set $F90COM if you need to use a specific
5053 command line for Fortran 90 files.
5054 You should normally set the $FORTRANCOM variable,
5055 which specifies the default command line
5056 for all Fortran versions.
5059 The string displayed when a Fortran 90 source file
5060 is compiled to an object file.
5061 If this is not set, then $F90COM or $FORTRANCOM
5062 (the command line) is displayed.
5065 General user-specified options that are passed to the Fortran 90 compiler.
5066 Note that this variable does
5070 (or similar) include search path options
5071 that scons generates automatically from $F90PATH.
5075 for the variable that expands to those options.
5076 You only need to set $F90FLAGS if you need to define specific
5077 user options for Fortran 90 files.
5078 You should normally set the $FORTRANFLAGS variable,
5079 which specifies the user-specified options
5080 passed to the default Fortran compiler
5081 for all Fortran versions.
5084 An automatically-generated construction variable
5085 containing the Fortran 90 compiler command-line options
5086 for specifying directories to be searched for include files.
5087 The value of $_F90INCFLAGS is created
5088 by appending $INCPREFIX and $INCSUFFIX
5089 to the beginning and end
5090 of each directory in $F90PATH.
5093 The list of directories that the Fortran 90 compiler will search for include
5094 directories. The implicit dependency scanner will search these
5095 directories for include files. Don't explicitly put include directory
5096 arguments in $F90FLAGS because the result will be non-portable
5097 and the directories will not be searched by the dependency scanner. Note:
5098 directory names in $F90PATH will be looked-up relative to the SConscript
5099 directory when they are used in a command. To force
5101 to look-up a directory relative to the root of the source tree use #:
5102 You only need to set $F90PATH if you need to define a specific
5103 include path for Fortran 90 files.
5104 You should normally set the $FORTRANPATH variable,
5105 which specifies the include path
5106 for the default Fortran compiler
5107 for all Fortran versions.
5110 env = Environment(F90PATH='#/include')
5114 The directory look-up can also be forced using the
5119 include = Dir('include')
5120 env = Environment(F90PATH=include)
5124 The directory list will be added to command lines
5125 through the automatically-generated
5127 construction variable,
5128 which is constructed by
5129 appending the values of the
5130 $INCPREFIX and $INCSUFFIX
5131 construction variables
5132 to the beginning and end
5133 of each directory in $F90PATH.
5134 Any command lines you define that need
5135 the F90PATH directory list should
5136 include $_F90INCFLAGS:
5139 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5143 The command line used to compile a Fortran 90 source file to an object file
5144 after first running the file through the C preprocessor.
5145 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5146 are included on this command line.
5147 You only need to set $F90PPCOM if you need to use a specific
5148 C-preprocessor command line for Fortran 90 files.
5149 You should normally set the $FORTRANPPCOM variable,
5150 which specifies the default C-preprocessor command line
5151 for all Fortran versions.
5154 The Fortran 95 compiler.
5155 You should normally set the $FORTRAN variable,
5156 which specifies the default Fortran compiler
5157 for all Fortran versions.
5158 You only need to set $F95 if you need to use a specific compiler
5159 or compiler version for Fortran 95 files.
5162 The command line used to compile a Fortran 95 source file to an object file.
5163 You only need to set $F95COM if you need to use a specific
5164 command line for Fortran 95 files.
5165 You should normally set the $FORTRANCOM variable,
5166 which specifies the default command line
5167 for all Fortran versions.
5170 The string displayed when a Fortran 95 source file
5171 is compiled to an object file.
5172 If this is not set, then $F95COM or $FORTRANCOM
5173 (the command line) is displayed.
5176 General user-specified options that are passed to the Fortran 95 compiler.
5177 Note that this variable does
5181 (or similar) include search path options
5182 that scons generates automatically from $F95PATH.
5186 for the variable that expands to those options.
5187 You only need to set $F95FLAGS if you need to define specific
5188 user options for Fortran 95 files.
5189 You should normally set the $FORTRANFLAGS variable,
5190 which specifies the user-specified options
5191 passed to the default Fortran compiler
5192 for all Fortran versions.
5195 An automatically-generated construction variable
5196 containing the Fortran 95 compiler command-line options
5197 for specifying directories to be searched for include files.
5198 The value of $_F95INCFLAGS is created
5199 by appending $INCPREFIX and $INCSUFFIX
5200 to the beginning and end
5201 of each directory in $F95PATH.
5204 The list of directories that the Fortran 95 compiler will search for include
5205 directories. The implicit dependency scanner will search these
5206 directories for include files. Don't explicitly put include directory
5207 arguments in $F95FLAGS because the result will be non-portable
5208 and the directories will not be searched by the dependency scanner. Note:
5209 directory names in $F95PATH will be looked-up relative to the SConscript
5210 directory when they are used in a command. To force
5212 to look-up a directory relative to the root of the source tree use #:
5213 You only need to set $F95PATH if you need to define a specific
5214 include path for Fortran 95 files.
5215 You should normally set the $FORTRANPATH variable,
5216 which specifies the include path
5217 for the default Fortran compiler
5218 for all Fortran versions.
5221 env = Environment(F95PATH='#/include')
5225 The directory look-up can also be forced using the
5230 include = Dir('include')
5231 env = Environment(F95PATH=include)
5235 The directory list will be added to command lines
5236 through the automatically-generated
5238 construction variable,
5239 which is constructed by
5240 appending the values of the
5241 $INCPREFIX and $INCSUFFIX
5242 construction variables
5243 to the beginning and end
5244 of each directory in $F95PATH.
5245 Any command lines you define that need
5246 the F95PATH directory list should
5247 include $_F95INCFLAGS:
5250 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5254 The command line used to compile a Fortran 95 source file to an object file
5255 after first running the file through the C preprocessor.
5256 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5257 are included on this command line.
5258 You only need to set $F95PPCOM if you need to use a specific
5259 C-preprocessor command line for Fortran 95 files.
5260 You should normally set the $FORTRANPPCOM variable,
5261 which specifies the default C-preprocessor command line
5262 for all Fortran versions.
5265 The default Fortran compiler
5266 for all versions of Fortran.
5269 The command line used to compile a Fortran source file to an object file.
5270 By default, any options specified
5271 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5272 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5273 are included on this command line.
5276 The string displayed when a Fortran source file
5277 is compiled to an object file.
5278 If this is not set, then $FORTRANCOM
5279 (the command line) is displayed.
5282 General user-specified options that are passed to the Fortran compiler.
5283 Note that this variable does
5287 (or similar) include or module search path options
5288 that scons generates automatically from $FORTRANPATH.
5290 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5292 for the variables that expand those options.
5294 .IP _FORTRANINCFLAGS
5295 An automatically-generated construction variable
5296 containing the Fortran compiler command-line options
5297 for specifying directories to be searched for include
5298 files and module files.
5299 The value of $_FORTRANINCFLAGS is created
5300 by prepending/appending $INCPREFIX and $INCSUFFIX
5301 to the beginning and end
5302 of each directory in $FORTRANPATH.
5305 Directory location where the Fortran compiler should place
5306 any module files it generates. This variable is empty, by default. Some
5307 Fortran compilers will internally append this directory in the search path
5308 for module files, as well
5310 .IP FORTRANMODDIRPREFIX
5311 The prefix used to specify a module directory on the Fortran compiler command
5313 This will be appended to the beginning of the directory
5314 in the $FORTRANMODDIR construction variables
5315 when the $_FORTRANMODFLAG variables is automatically generated.
5317 .IP FORTRANMODDIRSUFFIX
5318 The suffix used to specify a module directory on the Fortran compiler command
5320 This will be appended to the beginning of the directory
5321 in the $FORTRANMODDIR construction variables
5322 when the $_FORTRANMODFLAG variables is automatically generated.
5325 An automatically-generated construction variable
5326 containing the Fortran compiler command-line option
5327 for specifying the directory location where the Fortran
5328 compiler should place any module files that happen to get
5329 generated during compilation.
5330 The value of $_FORTRANMODFLAG is created
5331 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5332 to the beginning and end of the directory in $FORTRANMODDIR.
5334 .IP FORTRANMODPREFIX
5335 The module file prefix used by the Fortran compiler. SCons assumes that
5336 the Fortran compiler follows the quasi-standard naming convention for
5338 .I <module_name>.mod.
5339 As a result, this variable is left empty, by default. For situations in
5340 which the compiler does not necessarily follow the normal convention,
5341 the user may use this variable. Its value will be appended to every
5342 module file name as scons attempts to resolve dependencies.
5344 .IP FORTRANMODSUFFIX
5345 The module file suffix used by the Fortran compiler. SCons assumes that
5346 the Fortran compiler follows the quasi-standard naming convention for
5348 .I <module_name>.mod.
5349 As a result, this variable is set to ".mod", by default. For situations
5350 in which the compiler does not necessarily follow the normal convention,
5351 the user may use this variable. Its value will be appended to every
5352 module file name as scons attempts to resolve dependencies.
5355 The list of directories that the Fortran compiler will search for
5356 include files and (for some compilers) module files. The Fortran implicit
5357 dependency scanner will search these directories for include files (but
5358 not module files since they are autogenerated and, as such, may not
5359 actually exist at the time the scan takes place). Don't explicitly put
5360 include directory arguments in FORTRANFLAGS because the result will be
5361 non-portable and the directories will not be searched by the dependency
5362 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5363 to the SConscript directory when they are used in a command. To force
5365 to look-up a directory relative to the root of the source tree use #:
5368 env = Environment(FORTRANPATH='#/include')
5372 The directory look-up can also be forced using the
5377 include = Dir('include')
5378 env = Environment(FORTRANPATH=include)
5382 The directory list will be added to command lines
5383 through the automatically-generated
5385 construction variable,
5386 which is constructed by
5387 appending the values of the
5388 $INCPREFIX and $INCSUFFIX
5389 construction variables
5390 to the beginning and end
5391 of each directory in $FORTRANPATH.
5392 Any command lines you define that need
5393 the FORTRANPATH directory list should
5394 include $_FORTRANINCFLAGS:
5397 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5401 The command line used to compile a Fortran source file to an object file
5402 after first running the file through the C preprocessor.
5403 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5404 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5405 construction variables are included on this command line.
5408 The list of suffixes of files that will be scanned
5409 for Fortran implicit dependencies
5410 (INCLUDE lines & USE statements).
5411 The default list is:
5414 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5415 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5419 A function that converts a file name into a File instance relative to the
5423 The Ghostscript program used to convert PostScript to PDF files.
5426 General options passed to the Ghostscript program
5427 when converting PostScript to PDF files.
5430 The Ghostscript command line used to convert PostScript to PDF files.
5433 The list of suffixes of files that will be scanned
5434 for IDL implicit dependencies
5435 (#include or import lines).
5436 The default list is:
5443 The prefix used to specify an include directory on the C compiler command
5445 This will be appended to the beginning of each directory
5446 in the $CPPPATH and $FORTRANPATH construction variables
5447 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5448 variables are automatically generated.
5451 The suffix used to specify an include directory on the C compiler command
5453 This will be appended to the end of each directory
5454 in the $CPPPATH and $FORTRANPATH construction variables
5455 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5456 variables are automatically generated.
5459 A function to be called to install a file into a
5460 destination file name.
5461 The default function copies the file into the destination
5462 (and sets the destination file's mode and permission bits
5463 to match the source file's).
5464 The function takes the following arguments:
5467 def install(dest, source, env):
5471 is the path name of the destination file.
5473 is the path name of the source file.
5475 is the construction environment
5476 (a dictionary of construction values)
5477 in force for this file installation.
5480 The Java archive tool.
5483 The directory to which the Java archive tool should change
5489 The command line used to call the Java archive tool.
5492 General options passed to the Java archive tool.
5493 By default this is set to
5495 to create the necessary
5500 The suffix for Java archives:
5508 The command line used to compile a directory tree containing
5509 Java source files to
5510 corresponding Java class files.
5511 Any options specified in the $JAVACFLAGS construction variable
5512 are included on this command line.
5515 General options that are passed to the Java compiler.
5518 The directory in which Java class files may be found.
5519 This is stripped from the beginning of any Java .class
5520 file names supplied to the
5525 The suffix for Java class files;
5530 The Java generator for C header and stub files.
5533 The command line used to generate C header and stub files
5535 Any options specified in the $JAVAHFLAGS construction variable
5536 are included on this command line.
5539 General options passed to the C header and stub file generator
5543 The suffix for Java files;
5548 The LaTeX structured formatter and typesetter.
5551 The command line used to call the LaTeX structured formatter and typesetter.
5554 General options passed to the LaTeX structured formatter and typesetter.
5557 The lexical analyzer generator.
5560 General options passed to the lexical analyzer generator.
5563 The command line used to call the lexical analyzer generator
5564 to generate a source file.
5567 The string displayed when generating a source file
5568 using the lexical analyzer generator.
5569 If this is not set, then $LEXCOM (the command line) is displayed.
5572 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5576 An automatically-generated construction variable
5577 containing the linker command-line options
5578 for specifying directories to be searched for library.
5579 The value of $_LIBDIRFLAGS is created
5580 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5581 to the beginning and end
5582 of each directory in $LIBPATH.
5585 The prefix used to specify a library directory on the linker command line.
5586 This will be appended to the beginning of each directory
5587 in the $LIBPATH construction variable
5588 when the $_LIBDIRFLAGS variable is automatically generated.
5591 The suffix used to specify a library directory on the linker command line.
5592 This will be appended to the end of each directory
5593 in the $LIBPATH construction variable
5594 when the $_LIBDIRFLAGS variable is automatically generated.
5597 An automatically-generated construction variable
5598 containing the linker command-line options
5599 for specifying libraries to be linked with the resulting target.
5600 The value of $_LIBFLAGS is created
5601 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5602 to the beginning and end
5603 of each directory in $LIBS.
5606 The prefix used to specify a library to link on the linker command line.
5607 This will be appended to the beginning of each library
5608 in the $LIBS construction variable
5609 when the $_LIBFLAGS variable is automatically generated.
5612 The suffix used to specify a library to link on the linker command line.
5613 This will be appended to the end of each library
5614 in the $LIBS construction variable
5615 when the $_LIBFLAGS variable is automatically generated.
5618 The list of directories that will be searched for libraries.
5619 The implicit dependency scanner will search these
5620 directories for include files. Don't explicitly put include directory
5621 arguments in $LINKFLAGS or $SHLINKFLAGS
5622 because the result will be non-portable
5623 and the directories will not be searched by the dependency scanner. Note:
5624 directory names in LIBPATH will be looked-up relative to the SConscript
5625 directory when they are used in a command. To force
5627 to look-up a directory relative to the root of the source tree use #:
5630 env = Environment(LIBPATH='#/libs')
5634 The directory look-up can also be forced using the
5640 env = Environment(LIBPATH=libs)
5644 The directory list will be added to command lines
5645 through the automatically-generated
5647 construction variable,
5648 which is constructed by
5649 appending the values of the
5650 $LIBDIRPREFIX and $LIBDIRSUFFIX
5651 construction variables
5652 to the beginning and end
5653 of each directory in $LIBPATH.
5654 Any command lines you define that need
5655 the LIBPATH directory list should
5656 include $_LIBDIRFLAGS:
5659 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5663 The prefix used for (static) library file names.
5664 A default value is set for each platform
5665 (posix, win32, os2, etc.),
5666 but the value is overridden by individual tools
5667 (ar, mslib, sgiar, sunar, tlib, etc.)
5668 to reflect the names of the libraries they create.
5671 An array of legal prefixes for library file names.
5674 A list of one or more libraries
5675 that will be linked with
5676 any executable programs
5677 created by this environment.
5680 The library list will be added to command lines
5681 through the automatically-generated
5683 construction variable,
5684 which is constructed by
5685 appending the values of the
5686 $LIBLINKPREFIX and $LIBLINKSUFFIX
5687 construction variables
5688 to the beginning and end
5689 of each directory in $LIBS.
5690 Any command lines you define that need
5691 the LIBS library list should
5695 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5699 The suffix used for (static) library file names.
5700 A default value is set for each platform
5701 (posix, win32, os2, etc.),
5702 but the value is overridden by individual tools
5703 (ar, mslib, sgiar, sunar, tlib, etc.)
5704 to reflect the names of the libraries they create.
5707 An array of legal suffixes for library file names.
5713 General user options passed to the linker.
5714 Note that this variable should
5718 (or similar) options for linking with the libraries listed in $LIBS,
5721 (or similar) library search path options
5722 that scons generates automatically from $LIBPATH.
5726 for the variable that expands to library-link options,
5730 for the variable that expands to library search path options.
5733 The command line used to link object files into an executable.
5736 The string displayed when object files
5737 are linked into an executable.
5738 If this is not set, then $LINKCOM (the command line) is displayed.
5741 env = Environment(LINKCOMSTR = "Linking $TARGET")
5745 The M4 macro preprocessor.
5748 General options passed to the M4 macro preprocessor.
5751 The command line used to pass files through the macro preprocessor.
5754 The maximum number of characters allowed on an external command line.
5756 link lines longer than this many characters
5757 are linke via a temporary file name.
5760 When the Microsoft Visual Studio tools are initialized, they set up
5761 this dictionary with the following keys:
5764 the version of MSVS being used (can be set via
5768 the available versions of MSVS installed
5771 installed directory of Visual C++
5774 installed directory of Visual Studio
5777 installed directory of the .NET framework
5779 .B FRAMEWORKVERSIONS:
5780 list of installed versions of the .NET framework, sorted latest to oldest.
5782 .B FRAMEWORKVERSION:
5783 latest installed version of the .NET framework
5786 installed location of the .NET SDK.
5789 installed location of the Platform SDK.
5791 .B PLATFORMSDK_MODULES:
5792 dictionary of installed Platform SDK modules,
5793 where the dictionary keys are keywords for the various modules, and
5794 the values are 2-tuples where the first is the release date, and the
5795 second is the version number.
5797 If a value isn't set, it wasn't available in the registry.
5799 .IP MSVS_IGNORE_IDE_PATHS
5800 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5801 instead of the settings from the IDE.
5803 For Visual Studio, SCons will (by default) automatically determine
5804 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5805 set by the IDE. You can override this behavior by setting these
5806 variables after Environment initialization, or by setting
5807 .B MSVS_IGNORE_IDE_PATHS = 1
5808 in the Environment initialization.
5809 Specifying this will not leave these unset, but will set them to a
5810 minimal set of paths needed to run the tools successfully.
5813 For VS6, the mininimal set is:
5814 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5815 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5816 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5818 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5819 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5820 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5824 Where '<VSDir>' is the installed location of Visual Studio.
5826 .IP MSVS_USE_MFC_DIRS
5827 Tells the MS Visual Studio tool(s) to use
5828 the MFC directories in its default paths
5829 for compiling and linking.
5830 Under MSVS version 6,
5832 .B MSVS_USE_MFC_DIRS
5841 external environment variable,
5847 external environment variable.
5848 Under MSVS version 7,
5850 .B MSVS_USE_MFC_DIRS
5853 .B "atlmfc\\\\include"
5854 directory to the default
5856 external environment variable,
5859 directory to the default
5861 external environment variable.
5862 The current default value is
5864 which means these directories
5865 are added to the paths by default.
5866 This default value is likely to change
5867 in a future release,
5868 so users who want the ATL and MFC
5869 values included in their paths
5870 are encouraged to enable the
5871 .B MSVS_USE_MFC_DIRS
5873 to avoid future incompatibility.
5874 This variable has no effect if the
5878 environment variables are set explictly.
5881 Sets the preferred version of MSVS to use.
5883 SCons will (by default) select the latest version of MSVS
5884 installed on your machine. So, if you have version 6 and version 7
5885 (MSVS .NET) installed, it will prefer version 7. You can override this by
5888 variable in the Environment initialization, setting it to the
5889 appropriate version ('6.0' or '7.0', for example).
5890 If the given version isn't installed, tool initialization will fail.
5893 The action used to generate Microsoft Visual Studio
5894 project and solution files.
5896 .IP MSVSPROJECTSUFFIX
5897 The suffix used for Microsoft Visual Studio project (DSP) files.
5898 The default value is
5900 when using Visual Studio version 7.x (.NET),
5903 when using earlier versions of Visual Studio.
5905 .IP MSVSSOLUTIONSUFFIX
5906 The suffix used for Microsoft Visual Studio solution (DSW) files.
5907 The default value is
5909 when using Visual Studio version 7.x (.NET),
5912 when using earlier versions of Visual Studio.
5915 The version number of the MetroWerks CodeWarrior C compiler
5919 A list of installed versions of the MetroWerks CodeWarrior C compiler
5923 When set to non-zero,
5924 suppresses creation of a corresponding Win32 static import lib by the
5926 builder when used with
5927 MinGW or Microsoft Visual Studio.
5928 This also suppresses creation
5929 of an export (.exp) file
5930 when using Microsoft Visual Studio.
5933 The prefix used for (static) object file names.
5936 The suffix used for (static) object file names.
5939 The Perforce executable.
5942 The command line used to
5943 fetch source files from Perforce.
5946 General options that are passed to Perforce.
5949 The Microsoft Visual C++ precompiled header that will be used when compiling
5950 object files. This variable is ignored by tools other than Microsoft Visual C++.
5951 When this variable is
5952 defined SCons will add options to the compiler command line to
5953 cause it to use the precompiled header, and will also set up the
5954 dependencies for the PCH file. Example:
5957 env['PCH'] = 'StdAfx.pch'
5961 This variable specifies how much of a source file is precompiled. This
5962 variable is ignored by tools other than Microsoft Visual C++, or when
5963 the PCH variable is not being used. When this variable is define it
5964 must be a string that is the name of the header that
5965 is included at the end of the precompiled portion of the source files, or
5966 the empty string if the "#pragma hrdstop" construct is being used:
5969 env['PCHSTOP'] = 'StdAfx.h'
5973 The Microsoft Visual C++ PDB file that will store debugging information for
5974 object files, shared libraries, and programs. This variable is ignored by
5975 tools other than Microsoft Visual C++.
5976 When this variable is
5977 defined SCons will add options to the compiler and linker command line to
5978 cause them to generate external debugging information, and will also set up the
5979 dependencies for the PDB file. Example:
5982 env['PDB'] = 'hello.pdb'
5986 A deprecated synonym for $DVIPDFCOM.
5989 The prefix used for PDF file names.
5992 The suffix used for PDF file names.
5995 The name of the platform used to create the Environment. If no platform is
5996 specified when the Environment is created,
5998 autodetects the platform.
6001 env = Environment(tools = [])
6002 if env['PLATFORM'] == 'cygwin':
6008 .IP PRINT_CMD_LINE_FUNC
6009 A Python function used to print the command lines as they are executed
6010 (assuming command printing is not disabled by the
6014 options or their equivalents).
6015 The function should take four arguments:
6017 the command being executed (a string),
6019 the target being built (file node, list, or string name(s)),
6021 the source(s) used (file node, list, or string name(s)), and
6023 the environment being used.
6025 The function must do the printing itself. The default implementation,
6026 used if this variable is not set or is None, is:
6028 def print_cmd_line(s, target, source, env):
6029 sys.stdout.write(s + "\n")
6032 Here's an example of a more interesting function:
6034 def print_cmd_line(s, target, source, env):
6035 sys.stdout.write("Building %s -> %s...\n" %
6036 (' and '.join([str(x) for x in source]),
6037 ' and '.join([str(x) for x in target])))
6038 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6039 env.Program('foo', 'foo.c')
6042 This just prints "Building <targetname> from <sourcename>..." instead
6043 of the actual commands.
6044 Such a function could also log the actual commands to a log file,
6048 The prefix used for executable file names.
6051 The suffix used for executable file names.
6054 The command line used to convert TeX DVI files into a PostScript file.
6057 The prefix used for PostScript file names.
6060 The prefix used for PostScript file names.
6063 The qt tool tries to take this from os.environ.
6064 It also initializes all QT_*
6065 construction variables listed below.
6066 (Note that all paths are constructed
6067 with python's os.path.join() method,
6068 but are listed here with the '/' separator
6069 for easier reading.)
6070 In addition, the construction environment
6071 variables CPPPATH, LIBPATH and LIBS may be modified
6073 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6074 are modified. Because the build-performance is affected when using this tool,
6075 you have to explicitly specify it at Environment creation:
6078 Environment(tools=['default','qt'])
6081 The qt tool supports the following operations:
6083 .B Automatic moc file generation from header files.
6084 You do not have to specify moc files explicitly, the tool does it for you.
6085 However, there are a few preconditions to do so: Your header file must have
6086 the same filebase as your implementation file and must stay in the same
6087 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6088 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6089 See also the corresponding builder method
6092 .B Automatic moc file generation from cxx files.
6093 As stated in the qt documentation, include the moc file at the end of
6094 the cxx file. Note that you have to include the file, which is generated
6095 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6096 <basename>.moc. A warning is generated after building the moc file, if you
6097 do not include the correct file. If you are using BuildDir, you may
6098 need to specify duplicate=1. You can turn off automatic moc file generation
6099 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6102 .B Automatic handling of .ui files.
6103 The implementation files generated from .ui files are handled much the same
6104 as yacc or lex files. Each .ui file given as a source of Program, Library or
6105 SharedLibrary will generate three files, the declaration file, the
6106 implementation file and a moc file. Because there are also generated headers,
6107 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6111 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6112 specify files to run moc on.
6115 The path where the qt binaries are installed.
6116 The default value is '$QTDIR/bin'.
6119 The path where the qt header files are installed.
6120 The default value is '$QTDIR/include'.
6121 Note: If you set this variable to None, the tool won't change the CPPPATH
6122 construction variable.
6125 Prints lots of debugging information while scanning for moc files.
6128 The path where the qt libraries are installed.
6129 The default value is '$QTDIR/lib'.
6130 Note: If you set this variable to None, the tool won't change the LIBPATH
6131 construction variable.
6134 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6135 this variable to None, the tool won't change the LIBS variable.
6138 Default value is '$QT_BINPATH/moc'.
6141 Default value is ''. Prefix for moc output files, when source is a cxx file.
6144 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6147 .IP QT_MOCFROMCPPFLAGS
6148 Default value is '-i'. These flags are passed to moc, when moccing a
6151 .IP QT_MOCFROMCXXCOM
6152 Command to generate a moc file from a cpp file.
6155 Command to generate a moc file from a header.
6157 .IP QT_MOCFROMHFLAGS
6158 Default value is ''. These flags are passed to moc, when moccing a header
6162 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6165 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6169 Default value is '$QT_BINPATH/uic'.
6172 Command to generate header files from .ui files.
6175 Default value is ''. These flags are passed to uic, when creating a a h
6176 file from a .ui file.
6178 .IP QT_UICDECLPREFIX
6179 Default value is ''. Prefix for uic generated header files.
6181 .IP QT_UICDECLSUFFIX
6182 Default value is '.h'. Suffix for uic generated header files.
6185 Command to generate cxx files from .ui files.
6188 Default value is ''. These flags are passed to uic, when creating a cxx
6189 file from a .ui file.
6191 .IP QT_UICIMPLPREFIX
6192 Default value is 'uic_'. Prefix for uic generated implementation files.
6194 .IP QT_UICIMPLSUFFIX
6195 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6199 Default value is '.ui'. Suffix of designer input files.
6202 The archive indexer.
6205 General options passed to the archive indexer.
6208 The resource compiler used by the RES builder.
6211 The command line used by the RES builder.
6214 The flags passed to the resource compiler by the RES builder.
6218 Note that this variable is not actually used
6219 for the command to fetch source files from RCS;
6222 construction variable, below.
6225 The RCS "checkout" executable,
6226 used to fetch source files from RCS.
6229 The command line used to
6230 fetch (checkout) source files from RCS.
6233 The string displayed when fetching
6234 a source file from RCS.
6235 If this is not set, then $RCS_COCOM
6236 (the command line) is displayed.
6239 Options that are passed to the $RCS_CO command.
6242 A function that converts a file name into a list of Dir instances by
6243 searching the repositories.
6246 The Java RMI stub compiler.
6249 The command line used to compile stub
6250 and skeleton class files
6251 from Java classes that contain RMI implementations.
6252 Any options specified in the $RMICFLAGS construction variable
6253 are included on this command line.
6256 General options passed to the Java RMI stub compiler.
6259 The RPC protocol compiler.
6261 .IP RPCGENCLIENTFLAGS
6262 Options passed to the RPC protocol compiler
6263 when generating client side stubs.
6264 These are in addition to any flags specified in the
6266 construction variable.
6269 General options passed to the RPC protocol compiler.
6271 .IP RPCGENHEADERFLAGS
6272 Options passed to the RPC protocol compiler
6273 when generating a header file.
6274 These are in addition to any flags specified in the
6276 construction variable.
6278 .IP RPCGENSERVICEFLAGS
6279 Options passed to the RPC protocol compiler
6280 when generating server side stubs.
6281 These are in addition to any flags specified in the
6283 construction variable.
6286 Options passed to the RPC protocol compiler
6287 when generating XDR routines.
6288 These are in addition to any flags specified in the
6290 construction variable.
6293 A list of paths to search for shared libraries when running programs.
6294 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6295 Ignored on platforms and toolchains that don't support it.
6296 Note that the paths added to RPATH
6297 are not transformed by
6299 in any way: if you want an absolute
6300 path, you must make it absolute yourself.
6303 A list of the available implicit dependency scanners.
6304 New file scanners may be added by
6305 appending to this list,
6306 although the more flexible approach
6307 is to associate scanners
6308 with a specific Builder.
6309 See the sections "Builder Objects"
6310 and "Scanner Objects,"
6311 below, for more information.
6314 The SCCS executable.
6317 The command line used to
6318 fetch source files from SCCS.
6321 The string displayed when fetching
6322 a source file from a CVS repository.
6323 If this is not set, then $SCCSCOM
6324 (the command line) is displayed.
6327 General options that are passed to SCCS.
6330 Options that are passed specifically to the SCCS "get" subcommand.
6331 This can be set, for example, to
6333 to check out editable files from SCCS.
6336 The C compiler used for generating shared-library objects.
6339 The command line used to compile a C source file
6340 to a shared-library object file.
6341 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6342 are included on this command line.
6345 The string displayed when a C source file
6346 is compiled to a shared object file.
6347 If this is not set, then $SHCCCOM (the command line) is displayed.
6350 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6354 Options that are passed to the C compiler
6355 to generate shared-library objects.
6358 The C++ compiler used for generating shared-library objects.
6361 The command line used to compile a C++ source file
6362 to a shared-library object file.
6363 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6364 are included on this command line.
6367 The string displayed when a C++ source file
6368 is compiled to a shared object file.
6369 If this is not set, then $SHCXXCOM (the command line) is displayed.
6372 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6376 Options that are passed to the C++ compiler
6377 to generate shared-library objects.
6380 A string naming the shell program that will be passed to the
6385 construction variable for more information.
6388 The Fortran 77 compiler used for generating shared-library objects.
6389 You should normally set the $SHFORTRANC variable,
6390 which specifies the default Fortran compiler
6391 for all Fortran versions.
6392 You only need to set $SHF77 if you need to use a specific compiler
6393 or compiler version for Fortran 77 files.
6396 The command line used to compile a Fortran 77 source file
6397 to a shared-library object file.
6398 You only need to set $SHF77COM if you need to use a specific
6399 command line for Fortran 77 files.
6400 You should normally set the $SHFORTRANCOM variable,
6401 which specifies the default command line
6402 for all Fortran versions.
6405 The string displayed when a Fortran 77 source file
6406 is compiled to a shared-library object file.
6407 If this is not set, then $SHF77COM or $SHFORTRANCOM
6408 (the command line) is displayed.
6411 Options that are passed to the Fortran 77 compiler
6412 to generated shared-library objects.
6413 You only need to set $SHF77FLAGS if you need to define specific
6414 user options for Fortran 77 files.
6415 You should normally set the $SHFORTRANFLAGS variable,
6416 which specifies the user-specified options
6417 passed to the default Fortran compiler
6418 for all Fortran versions.
6421 The command line used to compile a Fortran 77 source file to a
6422 shared-library object file
6423 after first running the file through the C preprocessor.
6424 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6425 are included on this command line.
6426 You only need to set $SHF77PPCOM if you need to use a specific
6427 C-preprocessor command line for Fortran 77 files.
6428 You should normally set the $SHFORTRANPPCOM variable,
6429 which specifies the default C-preprocessor command line
6430 for all Fortran versions.
6433 The Fortran 90 compiler used for generating shared-library objects.
6434 You should normally set the $SHFORTRANC variable,
6435 which specifies the default Fortran compiler
6436 for all Fortran versions.
6437 You only need to set $SHF90 if you need to use a specific compiler
6438 or compiler version for Fortran 90 files.
6441 The command line used to compile a Fortran 90 source file
6442 to a shared-library object file.
6443 You only need to set $SHF90COM if you need to use a specific
6444 command line for Fortran 90 files.
6445 You should normally set the $SHFORTRANCOM variable,
6446 which specifies the default command line
6447 for all Fortran versions.
6450 The string displayed when a Fortran 90 source file
6451 is compiled to a shared-library object file.
6452 If this is not set, then $SHF90COM or $SHFORTRANCOM
6453 (the command line) is displayed.
6456 Options that are passed to the Fortran 90 compiler
6457 to generated shared-library objects.
6458 You only need to set $SHF90FLAGS if you need to define specific
6459 user options for Fortran 90 files.
6460 You should normally set the $SHFORTRANFLAGS variable,
6461 which specifies the user-specified options
6462 passed to the default Fortran compiler
6463 for all Fortran versions.
6466 The command line used to compile a Fortran 90 source file to a
6467 shared-library object file
6468 after first running the file through the C preprocessor.
6469 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6470 are included on this command line.
6471 You only need to set $SHF90PPCOM if you need to use a specific
6472 C-preprocessor command line for Fortran 90 files.
6473 You should normally set the $SHFORTRANPPCOM variable,
6474 which specifies the default C-preprocessor command line
6475 for all Fortran versions.
6478 The Fortran 95 compiler used for generating shared-library objects.
6479 You should normally set the $SHFORTRANC variable,
6480 which specifies the default Fortran compiler
6481 for all Fortran versions.
6482 You only need to set $SHF95 if you need to use a specific compiler
6483 or compiler version for Fortran 95 files.
6486 The command line used to compile a Fortran 95 source file
6487 to a shared-library object file.
6488 You only need to set $SHF95COM if you need to use a specific
6489 command line for Fortran 95 files.
6490 You should normally set the $SHFORTRANCOM variable,
6491 which specifies the default command line
6492 for all Fortran versions.
6495 The string displayed when a Fortran 95 source file
6496 is compiled to a shared-library object file.
6497 If this is not set, then $SHF95COM or $SHFORTRANCOM
6498 (the command line) is displayed.
6501 Options that are passed to the Fortran 95 compiler
6502 to generated shared-library objects.
6503 You only need to set $SHF95FLAGS if you need to define specific
6504 user options for Fortran 95 files.
6505 You should normally set the $SHFORTRANFLAGS variable,
6506 which specifies the user-specified options
6507 passed to the default Fortran compiler
6508 for all Fortran versions.
6511 The command line used to compile a Fortran 95 source file to a
6512 shared-library object file
6513 after first running the file through the C preprocessor.
6514 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6515 are included on this command line.
6516 You only need to set $SHF95PPCOM if you need to use a specific
6517 C-preprocessor command line for Fortran 95 files.
6518 You should normally set the $SHFORTRANPPCOM variable,
6519 which specifies the default C-preprocessor command line
6520 for all Fortran versions.
6523 The default Fortran compiler used for generating shared-library objects.
6526 The command line used to compile a Fortran source file
6527 to a shared-library object file.
6530 The string displayed when a Fortran source file
6531 is compiled to a shared-library object file.
6532 If this is not set, then $SHFORTRANCOM
6533 (the command line) is displayed.
6536 Options that are passed to the Fortran compiler
6537 to generate shared-library objects.
6540 The command line used to compile a Fortran source file to a
6541 shared-library object file
6542 after first running the file through the C preprocessor.
6543 Any options specified
6544 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6545 are included on this command line.
6548 The prefix used for shared library file names.
6551 The suffix used for shared library file names.
6554 The linker for programs that use shared libraries.
6557 The command line used to link programs using shared libaries.
6560 The string displayed when programs using shared libraries are linked.
6561 If this is not set, then $SHLINKCOM (the command line) is displayed.
6564 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6568 General user options passed to the linker for programs using shared libraries.
6569 Note that this variable should
6573 (or similar) options for linking with the libraries listed in $LIBS,
6576 (or similar) include search path options
6577 that scons generates automatically from $LIBPATH.
6581 for the variable that expands to library-link options,
6585 for the variable that expands to library search path options.
6588 The prefix used for shared object file names.
6591 The suffix used for shared object file names.
6594 A reserved variable name
6595 that may not be set or used in a construction environment.
6596 (See "Variable Substitution," below.)
6599 A reserved variable name
6600 that may not be set or used in a construction environment.
6601 (See "Variable Substitution," below.)
6604 A command interpreter function that will be called to execute command line
6605 strings. The function must expect the following arguments:
6608 def spawn(shell, escape, cmd, args, env):
6612 is a string naming the shell program to use.
6614 is a function that can be called to escape shell special characters in
6617 is the path to the command to be executed.
6619 is the arguments to the command.
6621 is a dictionary of the environment variables
6622 in which the command should be executed.
6625 '\"The Subversion executable (usually named
6629 '\"The command line used to
6630 '\"fetch source files from a Subversion repository.
6633 '\"General options that are passed to Subversion.
6636 The scripting language wrapper and interface generator.
6639 The suffix that will be used for intermediate C
6640 source files generated by
6641 the scripting language wrapper and interface generator.
6642 The default value is
6643 .BR _wrap$CFILESUFFIX .
6644 By default, this value is used whenever the
6648 specified as part of the
6650 construction variable.
6653 The command line used to call
6654 the scripting language wrapper and interface generator.
6656 .IP SWIGCXXFILESUFFIX
6657 The suffix that will be used for intermediate C++
6658 source files generated by
6659 the scripting language wrapper and interface generator.
6660 The default value is
6661 .BR _wrap$CFILESUFFIX .
6662 By default, this value is used whenever the
6664 option is specified as part of the
6666 construction variable.
6669 General options passed to
6670 the scripting language wrapper and interface generator.
6671 This is where you should set
6675 or whatever other options you want to specify to SWIG.
6678 option in this variable,
6681 generate a C++ intermediate source file
6682 with the extension that is specified as the
6690 The command line used to call the tar archiver.
6693 General options passed to the tar archiver.
6696 A reserved variable name
6697 that may not be set or used in a construction environment.
6698 (See "Variable Substitution," below.)
6701 A reserved variable name
6702 that may not be set or used in a construction environment.
6703 (See "Variable Substitution," below.)
6706 The suffix used for tar file names.
6709 The TeX formatter and typesetter.
6712 The command line used to call the TeX formatter and typesetter.
6715 General options passed to the TeX formatter and typesetter.
6718 A list of the names of the Tool specifications
6719 that are part of this construction environment.
6721 .IP WIN32_INSERT_DEF
6722 When this is set to true,
6723 a library build of a WIN32 shared library (.dll file)
6724 will also build a corresponding .def file at the same time,
6725 if a .def file is not already listed as a build target.
6726 The default is 0 (do not build a .def file).
6729 The prefix used for WIN32 .def file names.
6732 The suffix used for WIN32 .def file names.
6735 The parser generator.
6738 The command line used to call the parser generator
6739 to generate a source file.
6742 The string displayed when generating a source file
6743 using the parser generator.
6744 If this is not set, then $YACCCOM (the command line) is displayed.
6747 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
6751 General options passed to the parser generator.
6752 If $YACCFLAGS contains a \-d option,
6753 SCons assumes that the call will also create a .h file
6754 (if the yacc source file ends in a .y suffix)
6756 (if the yacc source file ends in a .yy suffix)
6759 The zip compression and file packaging utility.
6762 The command line used to call the zip utility,
6763 or the internal Python function used to create a
6772 module used by the internal Python function
6773 to control whether the zip archive
6774 is compressed or not.
6775 The default value is
6776 .BR zipfile.ZIP_DEFLATED ,
6777 which creates a compressed zip archive.
6778 This value has no effect when using Python 1.5.2
6781 module is otherwise unavailable.
6784 General options passed to the zip utility.
6787 Construction variables can be retrieved and set using the
6789 method of the construction environment:
6792 dict = env.Dictionary()
6796 or using the [] operator:
6802 Construction variables can also be passed to the construction environment
6806 env = Environment(CC="cc")
6809 or when copying a construction environment using the
6814 env2 = env.Copy(CC="cl.exe")
6817 .SS Configure Contexts
6821 .I configure contexts,
6822 an integrated mechanism similar to the
6823 various AC_CHECK macros in GNU autoconf
6824 for testing for the existence of C header
6825 files, libraries, etc.
6826 In contrast to autoconf,
6828 does not maintain an explicit cache of the tested values,
6829 but uses its normal dependency tracking to keep the checked values
6830 up to date. However, users may override this behaviour with the
6832 command line option.
6834 The following methods can be used to perform checks:
6837 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
6839 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
6840 This creates a configure context, which can be used to perform checks.
6842 specifies the environment for building the tests.
6843 This environment may be modified when performing checks.
6845 is a dictionary containing custom tests.
6846 See also the section about custom tests below.
6847 By default, no custom tests are added to the configure context.
6849 specifies a directory where the test cases are built.
6850 Note that this directory is not used for building
6852 The default value is the directory
6855 specifies a file which collects the output from commands
6856 that are executed to check for the existence of header files, libraries, etc.
6857 The default is the file #/config.log.
6858 If you are using the
6861 you may want to specify a subdirectory under your build directory.
6863 specifies a C header file where the results of tests
6864 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6865 The default is to not write a
6868 You can specify the same
6870 file in multiple calls to Configure,
6873 will concatenate all results in the specified file.
6875 uses its normal dependency checking
6876 to decide if it's necessary to rebuild
6880 This means that the file is not necessarily re-built each
6882 but is only rebuilt if its contents will have changed
6883 and some target that depends on the
6885 file is being built.
6890 instance has the following associated methods:
6893 .RI Configure.Finish( self )
6894 This method should be called after configuration is done.
6895 It returns the environment as modified
6896 by the configuration checks performed.
6897 After this method is called, no further checks can be performed
6898 with this configuration context.
6899 However, you can create a new
6901 context to perform additional checks.
6902 Only one context should be active at a time.
6904 The following Checks are predefined.
6905 (This list will likely grow larger as time
6906 goes by and developers contribute new useful tests.)
6909 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6912 is usable in the specified language.
6915 in which case the last item in the list
6916 is the header file to be checked,
6917 and the previous list items are
6920 lines should precede the
6921 header line being checked for.
6922 The optional argument
6925 a two character string, where the first character denotes the opening
6926 quote and the second character denotes the closing quote.
6927 By default, both characters are " (double quote).
6928 The optional argument
6934 and selects the compiler to be used for the check.
6935 Returns 1 on success and 0 on failure.
6938 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6939 This is a wrapper around
6940 .B Configure.CheckHeader
6943 is usable in the C language.
6946 in which case the last item in the list
6947 is the header file to be checked,
6948 and the previous list items are
6951 lines should precede the
6952 header line being checked for.
6953 The optional argument
6956 a two character string, where the first character denotes the opening
6957 quote and the second character denotes the closing quote (both default
6959 Returns 1 on success and 0 on failure.
6962 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6963 This is a wrapper around
6964 .B Configure.CheckHeader
6967 is usable in the C++ language.
6970 in which case the last item in the list
6971 is the header file to be checked,
6972 and the previous list items are
6975 lines should precede the
6976 header line being checked for.
6977 The optional argument
6980 a two character string, where the first character denotes the opening
6981 quote and the second character denotes the closing quote (both default
6983 Returns 1 on success and 0 on failure.
6986 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
6987 Checks if the specified
6988 C or C++ function is available.
6990 is the name of the function to check for.
6993 argument is a string
6997 that will be compiled
6998 to check if the function exists;
7004 char function_name();
7012 and selects the compiler to be used for the check;
7016 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
7023 is 1 and the library provides the specified
7025 appends the library to the LIBS construction environment variable.
7027 may also be None (the default),
7030 is checked with the current LIBS variable,
7031 or a list of library names,
7032 in which case each library in the list
7039 you can link against the specified
7047 and selects the compiler to be used for the check;
7049 The default value for
7052 It is assumed, that the C-language is used.
7053 This method returns 1 on success and 0 on error.
7056 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7059 .RI Configure.CheckLib
7060 call, this call provides a more sophisticated way to check against libraries.
7063 specifies the library or a list of libraries to check.
7065 specifies a header to check for.
7068 in which case the last item in the list
7069 is the header file to be checked,
7070 and the previous list items are
7073 lines should precede the
7074 header line being checked for.
7076 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7078 can be any valid expression (with a trailing ';'). The default is 'main();'.
7080 specifies whether to add the library to the environment (only if the check
7081 succeeds). This method returns 1 on success and 0 on error.
7084 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7085 Checks for the existence of a type defined by
7088 specifies the typedef name to check for.
7090 is a string containing one or more
7092 lines that will be inserted into the program
7093 that will be run to test for the existence of the type.
7100 and selects the compiler to be used for the check;
7104 Example of a typical Configure usage:
7108 conf = Configure( env )
7109 if not conf.CheckCHeader( 'math.h' ):
7110 print 'We really need math.h!'
7112 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7113 # do stuff for qt - usage, e.g.
7114 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7119 You can define your own custom checks.
7120 in addition to the predefined checks.
7121 These are passed in a dictionary to the Configure function.
7122 This dictionary maps the names of the checks
7123 to user defined Python callables
7124 (either Python functions or class instances implementing the
7127 The first argument of the call is always a
7129 instance followed by the arguments,
7130 which must be supplied by the user of the check.
7131 These CheckContext instances define the following methods:
7134 .RI CheckContext.Message( self ", " text )
7136 Usually called before the check is started.
7138 will be displayed to the user, e.g. 'Checking for library X...'
7141 .RI CheckContext.Result( self, ", " res )
7143 Usually called after the check is done.
7145 can be either an integer or a string. In the former case, 'ok' (res != 0)
7146 or 'failed' (res == 0) is displayed to the user, in the latter case the
7147 given string is displayed.
7150 .RI CheckContext.TryCompile( self ", " text ", " extension )
7151 Checks if a file with the specified
7153 (e.g. '.c') containing
7155 can be compiled using the environment's
7157 builder. Returns 1 on success and 0 on failure.
7160 .RI CheckContext.TryLink( self ", " text ", " extension )
7161 Checks, if a file with the specified
7163 (e.g. '.c') containing
7165 can be compiled using the environment's
7167 builder. Returns 1 on success and 0 on failure.
7170 .RI CheckContext.TryRun( self ", " text ", " extension )
7171 Checks, if a file with the specified
7173 (e.g. '.c') containing
7175 can be compiled using the environment's
7177 builder. On success, the program is run. If the program
7178 executes successfully
7179 (that is, its return status is 0),
7184 is the standard output of the
7186 If the program fails execution
7187 (its return status is non-zero),
7188 then (0, '') is returned.
7191 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7192 Checks if the specified
7194 with an optional source file (contents
7201 may be anything which can be converted to a
7208 is the content of the target file.
7214 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7215 Low level implementation for testing specific builds;
7216 the methods above are based on this method.
7217 Given the Builder instance
7221 of a source file with optional
7223 this method returns 1 on success and 0 on failure. In addition,
7225 is set to the build target node, if the build was successful.
7228 Example for implementing and using custom tests:
7231 def CheckQt(context, qtdir):
7232 context.Message( 'Checking for qt ...' )
7233 lastLIBS = context.env['LIBS']
7234 lastLIBPATH = context.env['LIBPATH']
7235 lastCPPPATH= context.env['CPPPATH']
7236 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7237 ret = context.TryLink("""
7239 int main(int argc, char **argv) {
7240 QApplication qapp(argc, argv);
7245 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7246 context.Result( ret )
7250 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7251 if not conf.CheckQt('/usr/lib/qt'):
7252 print 'We really need qt!'
7257 .SS Construction Variable Options
7259 Often when building software, various options need to be specified at build
7260 time that are not known when the SConstruct/SConscript files are
7261 written. For example, libraries needed for the build may be in non-standard
7262 locations, or site-specific compiler options may need to be passed to the
7265 provides a mechanism for overridding construction variables from the
7266 command line or a text-based SConscript file through an Options
7267 object. To create an Options object, call the Options() function:
7270 .RI Options([ files "], [" args ])
7271 This creates an Options object that will read construction variables from
7272 the file or list of filenames specified in
7274 If no files are specified,
7279 then no files will be read.
7280 The optional argument
7283 values that will override anything read from the specified files;
7284 it is primarily intended to be passed the
7286 dictionary that holds variables
7287 specified on the command line.
7291 opts = Options('custom.py')
7292 opts = Options('overrides.py', ARGUMENTS)
7293 opts = Options(None, {FOO:'expansion', BAR:7})
7296 Options objects have the following methods:
7299 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7300 This adds a customizable construction variable to the Options object.
7302 is the name of the variable.
7304 is the help text for the variable.
7306 is the default value of the variable;
7307 if the default value is
7309 and there is no explicit value specified,
7310 the construction variable will
7312 be added to the construction environment.
7314 is called to validate the value of the variable, and should take three
7315 arguments: key, value, and environment
7317 is called to convert the value before putting it in the environment, and
7318 should take a single argument: value. Example:
7321 opts.Add('CC', 'The C compiler')
7325 .RI AddOptions( list )
7326 A wrapper script that adds
7327 multiple customizable construction variables
7328 to an Options object.
7330 is a list of tuple or list objects
7331 that contain the arguments
7332 for an individual call to the
7339 ('CC', 'The C compiler'),
7340 ('VALIDATE', 'An option for testing validation',
7341 'notset', validator, None),
7346 .RI Update( env ", [" args ])
7347 This updates a construction environment
7349 with the customized construction variables. Normally this method is not
7350 called directly, but is called indirectly by passing the Options object to
7351 the Environment() function:
7354 env = Environment(options=opts)
7358 .RI Save( filename ", " env )
7359 This saves the currently set options into a script file named
7361 that can be used on the next invocation to automatically load the current
7362 settings. This method combined with the Options method can be used to
7363 support caching of options between runs.
7367 opts = Options(['options.cache', 'custom.py'])
7370 opts.Save('options.cache', env)
7374 .RI GenerateHelpText( env ", [" sort ])
7375 This generates help text documenting the customizable construction
7376 variables suitable to passing in to the Help() function.
7378 is the construction environment that will be used to get the actual values
7379 of customizable variables. Calling with
7383 will cause the output to be sorted
7384 by the specified argument.
7388 should take two arguments
7391 (like the standard Python
7396 Help(opts.GenerateHelpText(env))
7397 Help(opts.GenerateHelpText(env, sort=cmp))
7400 The text based SConscript file is executed as a Python script, and the
7401 global variables are queried for customizable construction
7408 To make it more convenient to work with customizable Options,
7410 provides a number of functions
7411 that make it easy to set up
7412 various types of Options:
7415 .RI BoolOption( key ", " help ", " default )
7416 Return a tuple of arguments
7417 to set up a Boolean option.
7421 have a default value of
7423 and display the specified
7426 The option will interpret the values
7448 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7449 Return a tuple of arguments
7451 whose value may be one
7452 of a specified list of legal enumerated values.
7456 have a default value of
7458 and display the specified
7461 The option will only support those
7467 argument is a dictionary
7468 that can be used to convert
7469 input values into specific legal values
7478 then the values are case-sensitive.
7483 then values will be matched
7489 then values will be matched
7491 and all input values will be
7492 converted to lower case.
7495 .RI ListOption( key ", " help ", " default ", " names )
7496 Return a tuple of arguments
7498 whose value may be one or more
7499 of a specified list of legal enumerated values.
7503 have a default value of
7505 and display the specified
7508 The option will only support the values
7511 or the values in the
7514 More than one value may be specified,
7515 with all values separated by commas.
7516 The default may be a string of
7517 comma-separated default values,
7518 or a list of the default values.
7521 .RI PackageOption( key ", " help ", " default )
7522 Return a tuple of arguments
7524 whose value is a path name
7525 of a package that may be
7526 enabled, disabled or
7527 given an explicit path name.
7531 have a default value of
7533 and display the specified
7536 The option will support the values
7543 in which case the specified
7546 or the option may be set to an
7548 (typically the path name to a package
7549 that is being enabled).
7550 The option will also support the values
7556 to disable use of the specified option.
7559 .RI PathOption( key ", " help ", " default ", [" validator ])
7560 Return a tuple of arguments
7562 whose value is expected to be a path name.
7566 have a default value of
7568 and display the specified
7574 that will be called to
7575 verify that the specified path
7578 following ready-made validators:
7579 .BR PathOption.PathExists
7581 which verifies that the specified path exists;
7582 .BR PathOption.PathIsFile ,
7583 which verifies that the specified path is an existing file;
7584 .BR PathOption.PathIsDir ,
7585 which verifies that the specified path is an existing directory;
7587 .BR PathOption.PathIsDirCreate ,
7588 which verifies that the specified path is a directory,
7589 and will create the specified directory if the path exist.
7590 You may supply your own
7593 which must take three arguments
7595 the name of the options variable to be set;
7597 the specified value being checked;
7600 the construction environment)
7601 and should raise an exception
7602 if the specified value is not acceptable.
7605 These functions make it
7606 convenient to create a number
7607 of options with consistent behavior
7608 in a single call to the
7614 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7615 EnumOption('debug', 'debug output and symbols', 'no'
7616 allowed_values=('yes', 'no', 'full'),
7617 map={}, ignorecase=0), # case sensitive
7618 ListOption('shared',
7619 'libraries to build as shared libraries',
7621 names = list_of_libs),
7622 PackageOption('x11',
7623 'use X11 installed here (yes = search some places)',
7625 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7626 PathOption('foopath', 'where the foo library is installed', foopath,
7627 PathOption.PathIsDir),
7632 .SS File and Directory Nodes
7642 Nodes, respectively.
7643 python objects, respectively.
7644 Those objects have several user-visible attributes
7645 and methods that are often useful:
7651 This path is relative to the top-level directory
7655 The build path is the same as the source path if
7660 The absolute build path of the given file or directory.
7670 object representing the
7679 # Get the current build dir's path, relative to top.
7681 # Current dir's absolute path
7683 # Next line is always '.', because it is the top dir's path relative to itself.
7685 File('foo.c').srcnode().path # source path of the given source file.
7687 # Builders also return File objects:
7688 foo = env.Program('foo.c')
7689 print "foo will be built in %s"%foo.path
7695 can be extended to build different types of targets
7696 by adding new Builder objects
7697 to a construction environment.
7699 you should only need to add a new Builder object
7700 when you want to build a new type of file or other external target.
7701 If you just want to invoke a different compiler or other tool
7702 to build a Program, Object, Library, or any other
7703 type of output file for which
7705 already has an existing Builder,
7706 it is generally much easier to
7707 use those existing Builders
7708 in a construction environment
7709 that sets the appropriate construction variables
7712 Builder objects are created
7718 function accepts the following arguments:
7721 The command line string used to build the target from the source.
7724 a list of strings representing the command
7725 to be executed and its arguments
7726 (suitable for enclosing white space in an argument),
7728 mapping source file name suffixes to
7729 any combination of command line strings
7730 (if the builder should accept multiple source file extensions),
7733 (see the next section);
7734 or a list of any of the above.
7737 takes three arguments:
7739 - a list of source nodes,
7741 - a list of target nodes,
7743 - the construction environment.
7746 The prefix that will be prepended to the target file name.
7747 This may be specified as a:
7757 - a function or other callable that takes
7758 two arguments (a construction environment and a list of sources)
7759 and returns a prefix,
7764 - specifies a mapping from a specific source suffix (of the first
7765 source specified) to a corresponding target prefix. Both the source
7766 suffix and target prefix specifications may use environment variable
7767 substitution, and the target prefix (the 'value' entries in the
7768 dictionary) may also be a callable object. The default target prefix
7769 may be indicated by a dictionary entry with a key value of None.
7774 b = Builder("build_it < $SOURCE > $TARGET"
7777 def gen_prefix(env, sources):
7778 return "file-" + env['PLATFORM'] + '-'
7779 b = Builder("build_it < $SOURCE > $TARGET",
7780 prefix = gen_prefix)
7782 b = Builder("build_it < $SOURCE > $TARGET",
7783 suffix = { None: "file-",
7784 "$SRC_SFX_A": gen_prefix })
7788 The suffix that will be appended to the target file name.
7789 This may be specified in the same manner as the prefix above.
7790 If the suffix is a string, then
7792 will append a '.' to the beginning of the suffix if it's not already
7793 there. The string returned by callable object (or obtained from the
7794 dictionary) is untouched and must append its own '.' to the beginning
7798 b = Builder("build_it < $SOURCE > $TARGET"
7801 def gen_suffix(env, sources):
7802 return "." + env['PLATFORM'] + "-file"
7803 b = Builder("build_it < $SOURCE > $TARGET",
7804 suffix = gen_suffix)
7806 b = Builder("build_it < $SOURCE > $TARGET",
7807 suffix = { None: ".sfx1",
7808 "$SRC_SFX_A": gen_suffix })
7812 The expected source file name suffix. This may be a string or a list
7816 A Scanner object that
7817 will be invoked to find
7818 implicit dependencies for this target file.
7819 This keyword argument should be used
7820 for Scanner objects that find
7821 implicit dependencies
7822 based only on the target file
7823 and the construction environment,
7826 (See the section "Scanner Objects," below,
7827 for information about creating Scanner objects.)
7830 A Scanner object that
7832 find implicit dependences in
7834 used to build this target file.
7835 This is where you would
7836 specify a scanner to
7839 lines in source files.
7840 (See the section "Scanner Objects," below,
7841 for information about creating Scanner objects.)
7844 A factory function that the Builder will use
7845 to turn any targets specified as strings into SCons Nodes.
7847 SCons assumes that all targets are files.
7848 Other useful target_factory
7851 for when a Builder creates a directory target,
7854 for when a Builder can create either a file
7855 or directory target.
7860 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7862 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7863 env.MakeDirectory('new_directory', [])
7867 A factory function that the Builder will use
7868 to turn any sources specified as strings into SCons Nodes.
7870 SCons assumes that all source are files.
7871 Other useful source_factory
7874 for when a Builder uses a directory as a source,
7877 for when a Builder can use files
7878 or directories (or both) as sources.
7883 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7885 env.Append(BUILDERS = {'Collect':CollectBuilder})
7886 env.Collect('archive', ['directory_name', 'file_name'])
7890 A function or list of functions to manipulate the target and source
7891 lists before dependencies are established
7892 and the target(s) are actually built.
7894 can also be a string containing a construction variable to expand
7895 to an emitter function or list of functions,
7896 or a dictionary mapping source file suffixes
7897 to emitter functions.
7898 (Only the suffix of the first source file
7899 is used to select the actual emitter function
7900 from an emitter dictionary.)
7903 takes three arguments:
7905 - a list of source nodes,
7907 - a list of target nodes,
7909 - the construction environment.
7910 An emitter must return a tuple containing two lists,
7911 the list of targets to be built by this builder,
7912 and the list of sources for this builder.
7917 def e(target, source, env):
7918 return (target + ['foo.foo'], source + ['foo.src'])
7920 # Simple association of an emitter function with a Builder.
7921 b = Builder("my_build < $TARGET > $SOURCE",
7924 def e2(target, source, env):
7925 return (target + ['bar.foo'], source + ['bar.src'])
7927 # Simple association of a list of emitter functions with a Builder.
7928 b = Builder("my_build < $TARGET > $SOURCE",
7931 # Calling an emitter function through a construction variable.
7932 env = Environment(MY_EMITTER = e)
7933 b = Builder("my_build < $TARGET > $SOURCE",
7934 emitter = '$MY_EMITTER')
7936 # Calling a list of emitter functions through a construction variable.
7937 env = Environment(EMITTER_LIST = [e, e2])
7938 b = Builder("my_build < $TARGET > $SOURCE",
7939 emitter = '$EMITTER_LIST')
7941 # Associating multiple emitters with different file
7942 # suffixes using a dictionary.
7943 def e_suf1(target, source, env):
7944 return (target + ['another_target_file'], source)
7945 def e_suf2(target, source, env):
7946 return (target, source + ['another_source_file'])
7947 b = Builder("my_build < $TARGET > $SOURCE",
7948 emitter = {'.suf1' : e_suf1,
7956 arguments must not both be used for the same Builder.
7959 Specifies whether this builder is allowed to be called multiple times for
7960 the same target file(s). The default is 0, which means the builder
7961 can not be called multiple times for the same target file(s). Calling a
7962 builder multiple times for the same target simply adds additional source
7963 files to the target; it is not allowed to change the environment associated
7964 with the target, specify addition environment overrides, or associate a different
7965 builder with the target.
7968 A construction environment that can be used
7969 to fetch source code using this Builder.
7970 (Note that this environment is
7972 used for normal builds of normal target files,
7973 which use the environment that was
7974 used to call the Builder for the target file.)
7977 A function that returns a list of actions that will be executed to build
7978 the target(s) from the source(s).
7979 The returned action(s) may be
7980 an Action object, or anything that
7981 can be converted into an Action object
7982 (see the next section).
7984 The generator function
7985 takes four arguments:
7987 - a list of source nodes,
7989 - a list of target nodes,
7991 - the construction environment,
7993 - a Boolean value that specifies
7994 whether the generator is being called
7995 for generating a build signature
7996 (as opposed to actually executing the command).
8000 def g(source, target, env, for_signature):
8001 return [["gcc", "-c", "-o"] + target + source]
8003 b = Builder(generator=g)
8007 Specifies a builder to use when a source file name suffix does not match
8008 any of the suffixes of the builder. Using this argument produces a
8009 multi-stage builder.
8012 Specifies that this builder expects exactly one source file per call. Giving
8013 more than one source files without target files results in implicitely calling
8014 the builder multiple times (once for each source given). Giving multiple
8015 source files together with target files results in a UserError exception.
8023 arguments must not both be used for the same Builder.
8026 A construction environment that can be used
8027 to fetch source code using this Builder.
8028 (Note that this environment is
8030 used for normal builds of normal target files,
8031 which use the environment that was
8032 used to call the Builder for the target file.)
8035 b = Builder(action="build < $SOURCE > $TARGET")
8036 env = Environment(BUILDERS = {'MyBuild' : b})
8037 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8041 A directory from which scons
8048 a string or a directory Node,
8049 scons will change to the specified directory.
8052 is not a string or Node
8054 then scons will change to the
8055 target file's directory.
8057 Note that scons will
8059 automatically modify
8061 construction variables like
8065 when using the chdir
8066 keyword argument--that is,
8067 the expanded file names
8068 will still be relative to
8069 the top-level SConstruct directory,
8070 and consequently incorrect
8071 relative to the chdir directory.
8072 Builders created using chdir keyword argument,
8073 will need to use construction variable
8078 to use just the filename portion of the
8082 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8084 env = Environment(BUILDERS = {'MyBuild' : b})
8085 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8089 Any additional keyword arguments supplied
8090 when a Builder object is created
8091 (that is, when the Builder() function is called)
8092 will be set in the executing construction
8093 environment when the Builder object is called.
8094 The canonical example here would be
8095 to set a construction variable to
8096 the repository of a source code system.
8098 Any additional keyword arguments supplied
8102 will only be associated with the target
8103 created by that particular Builder call
8104 (and any other files built as a
8105 result of the call).
8107 These extra keyword arguments are passed to the
8108 following functions:
8109 command generator functions,
8111 and emitter functions.
8117 function will turn its
8119 keyword argument into an appropriate
8120 internal Action object.
8121 You can also explicity create Action objects
8125 which can then be passed to the
8128 This can be used to configure
8129 an Action object more flexibly,
8130 or it may simply be more efficient
8131 than letting each separate Builder object
8132 create a separate Action
8134 Builder objects need to do the same thing.
8139 returns an appropriate object for the action
8140 represented by the type of the first argument:
8143 If the first argument is already an Action object,
8144 the object is simply returned.
8147 If the first argument is a string,
8148 a command-line Action is returned.
8151 Action('$CC -c -o $TARGET $SOURCES')
8154 .\" XXX From Gary Ruben, 23 April 2002:
8155 .\" What would be useful is a discussion of how you execute command
8156 .\" shell commands ie. what is the process used to spawn the shell, pass
8157 .\" environment variables to it etc., whether there is one shell per
8158 .\" environment or one per command etc. It might help to look at the Gnu
8159 .\" make documentation to see what they think is important to discuss about
8160 .\" a build system. I'm sure you can do a better job of organising the
8161 .\" documentation than they have :-)
8165 If the first argument is a list,
8166 then a list of Action objects is returned.
8167 An Action object is created as necessary
8168 for each element in the list.
8171 the list is itself a list,
8172 the internal list is the
8173 command and arguments to be executed via
8175 This allows white space to be enclosed
8176 in an argument by defining
8177 a command in a list within a list:
8180 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8184 If the first argument is a Python function,
8185 a function Action is returned.
8186 The Python function takes three keyword arguments,
8188 (a Node object representing the target file),
8190 (a Node object representing the source file)
8193 (the construction environment
8194 used for building the target file).
8199 arguments may be lists of Node objects if there is
8200 more than one target file or source file.
8201 The actual target and source file name(s) may
8202 be retrieved from their Node objects
8203 via the built-in Python str() function:
8206 target_file_name = str(target)
8207 source_file_names = map(lambda x: str(x), source)
8210 The function should return
8214 to indicate a successful build of the target file(s).
8215 The function may raise an exception
8216 or return a non-zero exit status
8217 to indicate an unsuccessful build.
8220 def build_it(target = None, source = None, env = None):
8221 # build the target from the source
8224 a = Action(build_it)
8227 If the action argument is not one of the above,
8230 The second, optional argument
8231 is a Python function that returns
8232 a string to be printed to describe the action being executed.
8233 Like a function to build a file,
8234 this function takes three arguments:
8236 (a Node object representing the target file),
8238 (a Node object representing the source file)
8241 (a construction environment).
8246 arguments may be lists of Node objects if there is
8247 more than one target file or source file.
8251 def build_it(target, source, env):
8252 # build the target from the source
8255 def string_it(target, source, env):
8256 return "building '%s' from '%s'" % (target[0], source[0])
8258 # Use a positional argument.
8259 a = Action(build_it, string_it)
8261 # Alternatively, use a keyword argument.
8262 a = Action(build_it, strfunction=string_it)
8265 The third, also optional argument
8266 is a list of construction variables
8267 whose values will be included
8268 in the signature of the Action
8269 when deciding whether a target should
8270 be rebuilt because the action changed.
8271 This is necessary whenever you want a target to
8272 be rebuilt when a specific
8273 construction variable changes,
8274 because the underlying Python code for a function
8275 will not change when the value of the construction variable does.
8278 def build_it(target, source, env):
8279 # build the target from the 'XXX' construction variable
8280 open(target[0], 'w').write(env['XXX'])
8283 def string_it(target, source):
8284 return "building '%s' from '%s'" % (target[0], source[0])
8286 # Use positional arguments.
8287 a = Action(build_it, string_it, ['XXX'])
8289 # Alternatively, use a keyword argument.
8290 a = Action(build_it, varlist=['XXX'])
8300 which specifies that
8301 scons will execute the action
8302 after changing to the specified directory.
8303 If the chdir argument is
8304 a string or a directory Node,
8305 scons will change to the specified directory.
8306 If the chdir argument
8307 is not a string or Node
8309 then scons will change to the
8310 target file's directory.
8312 Note that scons will
8314 automatically modify
8316 construction variables like
8320 when using the chdir
8321 keyword argument--that is,
8322 the expanded file names
8323 will still be relative to
8324 the top-level SConstruct directory,
8325 and consequently incorrect
8326 relative to the chdir directory.
8327 Builders created using chdir keyword argument,
8328 will need to use construction variable
8333 to use just the filename portion of the
8337 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8341 .SS Miscellaneous Action Functions
8344 supplies a number of functions
8345 that arrange for various common
8346 file and directory manipulations
8348 These are similar in concept to "tasks" in the
8350 although the implementation is slightly different.
8351 These functions do not actually
8352 perform the specified action
8353 at the time the function is called,
8354 but instead return an Action object
8355 that can be executed at the
8357 (In Object-Oriented terminology,
8362 that return Action objects.)
8365 there are two natural ways
8368 are intended to be used.
8372 to perform the action
8373 at the time the SConscript
8377 global function to do so:
8379 Execute(Touch('file'))
8383 you can use these functions
8384 to supply Actions in a list
8388 This can allow you to
8389 perform more complicated
8390 sequences of file manipulation
8392 on platform-specific
8396 env = Environment(TMPBUILD = '/tmp/builddir')
8397 env.Command('foo.out', 'foo.in',
8398 [Mkdir('$TMPBUILD'),
8399 Copy('${SOURCE.dir}', '$TMPBUILD')
8400 "cd $TMPBUILD && make",
8401 Delete('$TMPBUILD')])
8405 .RI Chmod( dest ", " mode )
8406 Returns an Action object that
8407 changes the permissions on the specified
8409 file or directory to the specified
8414 Execute(Chmod('file', 0755))
8416 env.Command('foo.out', 'foo.in',
8417 [Copy('$TARGET', '$SOURCE'),
8418 Chmod('$TARGET', 0755)])
8422 .RI Copy( dest ", " src )
8423 Returns an Action object
8426 source file or directory to the
8428 destination file or directory.
8432 Execute(Copy('foo.output', 'foo.input'))
8434 env.Command('bar.out', 'bar.in',
8435 Copy('$TARGET', '$SOURCE'))
8439 .RI Delete( entry ", [" must_exist ])
8440 Returns an Action that
8441 deletes the specified
8443 which may be a file or a directory tree.
8444 If a directory is specified,
8445 the entire directory tree
8450 then a Python error will be thrown
8451 if the specified entry does not exist;
8454 that is, the Action will silently do nothing
8455 if the entry does not exist.
8459 Execute(Delete('/tmp/buildroot'))
8461 env.Command('foo.out', 'foo.in',
8462 [Delete('${TARGET.dir}'),
8465 Execute(Delete('file_that_must_exist', must_exist=1))
8471 that creates the specified
8477 Execute(Mkdir('/tmp/outputdir'))
8479 env.Command('foo.out', 'foo.in',
8480 [Mkdir('/tmp/builddir',
8481 Copy('$SOURCE', '/tmp/builddir')
8482 "cd /tmp/builddir && ])
8487 .RI Move( dest ", " src )
8489 that moves the specified
8491 file or directory to
8498 Execute(Move('file.destination', 'file.source'))
8500 env.Command('output_file', 'input_file',
8502 Move('$TARGET', 'file_created_by_MyBuildAction')])
8508 that updates the modification time
8514 Execute(Touch('file_to_be_touched'))
8516 env.Command('marker', 'input_file',
8521 .SS Variable Substitution
8523 Before executing a command,
8525 performs construction variable interpolation on the strings that make up
8526 the command line of builders.
8527 Variables are introduced by a
8530 Besides construction variables, scons provides the following
8531 variables for each command execution:
8534 The file name of the target being built, or the file name of the first
8535 target if multiple targets are being built.
8538 The file names of all targets being built.
8541 The file name of the source of the build command, or the file name of the
8542 first source if multiple sources are being built.
8545 The file names of the sources of the build command.
8547 (Note that the above variables are reserved
8548 and may not be set in a construction environment.)
8551 For example, given the construction variable CC='cc', targets=['foo'], and
8552 sources=['foo.c', 'bar.c']:
8555 action='$CC -c -o $TARGET $SOURCES'
8558 would produce the command line:
8561 cc -c -o foo foo.c bar.c
8564 Variable names may be surrounded by curly braces ({})
8565 to separate the name from the trailing characters.
8566 Within the curly braces, a variable name may have
8567 a Python slice subscript appended to select one
8568 or more items from a list.
8569 In the previous example, the string:
8581 Additionally, a variable name may
8582 have the following special
8583 modifiers appended within the enclosing curly braces
8584 to modify the interpolated string:
8587 The base path of the file name,
8588 including the directory path
8589 but excluding any suffix.
8592 The name of the directory in which the file exists.
8596 minus any directory portion.
8599 Just the basename of the file,
8601 and minus the directory.
8604 Just the file suffix.
8607 The absolute path name of the file.
8610 The POSIX form of the path,
8611 with directories separated by
8615 This is sometimes necessary on Win32 systems
8616 when a path references a file on other (POSIX) systems.
8619 The directory and file name to the source file linked to this file
8620 through BuildDir. If this file isn't linked, it just returns the
8621 directory and filename unchanged.
8624 The directory containing the source file linked to this file
8625 through BuildDir. If this file isn't linked, it just returns the
8626 directory part of the filename.
8629 The directory and file name to the source file linked to this file
8630 through BuildDir. If the file does not exist locally but exists in
8631 a Repository, the path in the Repository is returned.
8632 If this file isn't linked, it just returns the
8633 directory and filename unchanged.
8636 The Repository directory containing the source file linked to this file
8637 through BuildDir. If this file isn't linked, it just returns the
8638 directory part of the filename.
8641 For example, the specified target will
8642 expand as follows for the corresponding modifiers:
8645 $TARGET => sub/dir/file.x
8646 ${TARGET.base} => sub/dir/file
8647 ${TARGET.dir} => sub/dir
8648 ${TARGET.file} => file.x
8649 ${TARGET.filebase} => file
8650 ${TARGET.suffix} => .x
8651 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8653 BuildDir('sub/dir','src')
8654 $SOURCE => sub/dir/file.x
8655 ${SOURCE.srcpath} => src/file.x
8656 ${SOURCE.srcdir} => src
8658 Repository('/usr/repository')
8659 $SOURCE => sub/dir/file.x
8660 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8661 ${SOURCE.rsrcdir} => /usr/repository/src
8664 Lastly, a variable name
8665 may be a callable Python function
8667 construction variable in the environment.
8669 take four arguments:
8671 - a list of target nodes,
8673 - a list of source nodes,
8675 - the construction environment,
8677 - a Boolean value that specifies
8678 whether the function is being called
8679 for generating a build signature.
8680 SCons will insert whatever
8681 the called function returns
8682 into the expanded string:
8685 def foo(target, source, env, for_signature):
8688 # Will expand $BAR to "bar baz"
8689 env=Environment(FOO=foo, BAR="$FOO baz")
8692 You can use this feature to pass arguments to a
8693 Python function by creating a callable class
8694 that stores one or more arguments in an object,
8695 and then uses them when the
8698 Note that in this case,
8699 the entire variable expansion must
8700 be enclosed by curly braces
8701 so that the arguments will
8702 be associated with the
8703 instantiation of the class:
8707 def __init__(self, arg):
8710 def __call__(self, target, source, env, for_signature):
8713 # Will expand $BAR to "my argument bar baz"
8714 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8718 The special pseudo-variables
8722 may be used to surround parts of a command line
8725 causing a rebuild--that is,
8726 which are not included in the signature
8727 of target files built with this command.
8732 will be removed from the command line
8733 before it is added to file signatures,
8738 will be removed before the command is executed.
8739 For example, the command line:
8742 echo Last build occurred $( $TODAY $). > $TARGET
8746 would execute the command:
8749 echo Last build occurred $TODAY. > $TARGET
8753 but the command signature added to any target files would be:
8756 echo Last build occurred . > $TARGET
8759 SCons uses the following rules when converting construction variables into
8763 When the value is a string it is interpreted as a space delimited list of
8764 command line arguments.
8767 When the value is a list it is interpreted as a list of command line
8768 arguments. Each element of the list is converted to a string.
8771 Anything that is not a list or string is converted to a string and
8772 interpreted as a single command line argument.
8775 Newline characters (\\n) delimit lines. The newline parsing is done after
8776 all other parsing, so it is not possible for arguments (e.g. file names) to
8777 contain embedded newline characters. This limitation will likely go away in
8778 a future version of SCons.
8786 new file types for implicit dependencies.
8787 Scanner accepts the following arguments:
8790 A Python function that will process
8792 and return a list of strings (file names)
8793 representing the implicit
8794 dependencies found in the contents.
8795 The function takes three or four arguments:
8797 def scanner_function(node, env, path):
8799 def scanner_function(node, env, path, arg):
8803 argument is the internal
8804 SCons node representing the file.
8807 to fetch the name of the file, and
8808 .B node.get_contents()
8809 to fetch contents of the file.
8813 argument is the construction environment for the scan.
8814 Fetch values from it using the
8820 argument is a tuple (or list)
8821 of directories that can be searched
8823 This will usually be the tuple returned by the
8825 argument (see below).
8829 argument is the argument supplied
8830 when the scanner was created, if any.
8833 The name of the Scanner.
8835 to identify the Scanner internally.
8838 An optional argument that, if specified,
8839 will be passed to the scanner function
8841 and the path function
8845 An optional list that can be used to
8846 determine which scanner should be used for
8848 In the usual case of scanning for file names,
8849 this argument will be a list of suffixes
8850 for the different file types that this
8851 Scanner knows how to scan.
8852 If the argument is a string,
8853 then it will be expanded
8854 into a list by the current environment.
8857 A Python function that takes
8858 two or three arguments:
8859 a construction environment, directory Node,
8860 and optional argument supplied
8861 when the scanner was created.
8864 returns a tuple of directories
8865 that can be searched for files to be returned
8866 by this Scanner object.
8869 The class of Node that should be returned
8870 by this Scanner object.
8871 Any strings or other objects returned
8872 by the scanner function
8873 that are not of this class
8874 will be run through the
8879 A Python function that will take a string
8881 and turn it into the appropriate class of Node
8882 to be returned by this Scanner object.
8885 An optional Python function that takes two arguments,
8886 a Node (file) and a construction environment,
8887 and returns whether the
8888 Node should, in fact,
8889 be scanned for dependencies.
8890 This check can be used to eliminate unnecessary
8891 calls to the scanner function when,
8892 for example, the underlying file
8893 represented by a Node does not yet exist.
8896 An optional flag that
8897 specifies whether this scanner should be re-invoked
8898 on the dependency files returned by the scanner.
8899 When this flag is not set,
8900 the Node subsystem will
8901 only invoke the scanner on the file being scanned,
8902 and not (for example) also on the files
8903 specified by the #include lines
8904 in the file being scanned.
8906 .SH SYSTEM-SPECIFIC BEHAVIOR
8907 SCons and its configuration files are very portable,
8908 due largely to its implementation in Python.
8909 There are, however, a few portability
8910 issues waiting to trap the unwary.
8912 SCons handles the upper-case
8914 file suffix differently,
8915 depending on the capabilities of
8916 the underlying system.
8917 On a case-sensitive system
8918 such as Linux or UNIX,
8919 SCons treats a file with a
8921 suffix as a C++ source file.
8922 On a case-insensitive system
8924 SCons treats a file with a
8926 suffix as a C source file.
8928 SCons handles the upper-case
8930 file suffix differently,
8931 depending on the capabilities of
8932 the underlying system.
8933 On a case-sensitive system
8934 such as Linux or UNIX,
8935 SCons treats a file with a
8937 suffix as a Fortran source file
8938 that is to be first run through
8939 the standard C preprocessor.
8940 On a case-insensitive system
8942 SCons treats a file with a
8944 suffix as a Fortran source file that should
8946 be run through the C preprocessor.
8947 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
8948 Cygwin supplies a set of tools and utilities
8949 that let users work on a
8950 Windows system using a more POSIX-like environment.
8951 The Cygwin tools, including Cygwin Python,
8953 by sharing an ability to interpret UNIX-like path names.
8954 For example, the Cygwin tools
8955 will internally translate a Cygwin path name
8956 like /cygdrive/c/mydir
8957 to an equivalent Windows pathname
8958 of C:/mydir (equivalent to C:\\mydir).
8961 that are built for native Windows execution,
8962 such as the python.org and ActiveState versions,
8963 do not have the Cygwin path name semantics.
8964 This means that using a native Windows version of Python
8965 to build compiled programs using Cygwin tools
8966 (such as gcc, bison, and flex)
8967 may yield unpredictable results.
8968 "Mixing and matching" in this way
8969 can be made to work,
8970 but it requires careful attention to the use of path names
8971 in your SConscript files.
8973 In practice, users can sidestep
8974 the issue by adopting the following rules:
8976 use the Cygwin-supplied Python interpreter
8978 when using Microsoft Visual C/C++
8979 (or some other Windows compiler)
8980 use the python.org or ActiveState version of Python
8982 .SS WIN32: scons.bat file
8984 SCons is executed via a wrapper
8987 This has (at least) two ramifications:
8989 First, Windows command-line users
8990 that want to use variable assignment
8992 may have to put double quotes
8993 around the assignments:
8996 scons "FOO=BAR" "BAZ=BLEH"
8999 Second, the Cygwin shell does not
9000 recognize this file as being the same
9003 command issued at the command-line prompt.
9004 You can work around this either by
9007 from the Cygwin command line,
9008 or by creating a wrapper shell
9014 The MinGW bin directory must be in your PATH environment variable or the
9015 PATH variable under the ENV construction variable for SCons
9016 to detect and use the MinGW tools. When running under the native Windows
9017 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9018 tools, if they are both installed, regardless of the order of the bin
9019 directories in the PATH variable. If you have both MSVC and MinGW
9020 installed and you want to use MinGW instead of MSVC,
9021 then you must explictly tell SCons to use MinGW by passing
9027 to the Environment() function, because SCons will prefer the MSVC tools
9028 over the MinGW tools.
9032 To help you get started using SCons,
9033 this section contains a brief overview of some common tasks.
9035 .SS Basic Compilation From a Single Source File
9039 env.Program(target = 'foo', source = 'foo.c')
9042 Note: Build the file by specifying
9043 the target as an argument
9044 ("scons foo" or "scons foo.exe").
9045 or by specifying a dot ("scons .").
9047 .SS Basic Compilation From Multiple Source Files
9051 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9054 .SS Setting a Compilation Flag
9057 env = Environment(CCFLAGS = '-g')
9058 env.Program(target = 'foo', source = 'foo.c')
9061 .SS Search The Local Directory For .h Files
9065 need to set CCFLAGS to specify -I options by hand.
9066 SCons will construct the right -I options from CPPPATH.
9069 env = Environment(CPPPATH = ['.'])
9070 env.Program(target = 'foo', source = 'foo.c')
9073 .SS Search Multiple Directories For .h Files
9076 env = Environment(CPPPATH = ['include1', 'include2'])
9077 env.Program(target = 'foo', source = 'foo.c')
9080 .SS Building a Static Library
9084 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9085 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9088 .SS Building a Shared Library
9092 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9093 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9096 .SS Linking a Local Library Into a Program
9099 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9100 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9101 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9104 .SS Defining Your Own Builder Object
9106 Notice that when you invoke the Builder,
9107 you can leave off the target file suffix,
9108 and SCons will add it automatically.
9111 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9113 src_suffix = '.tex')
9114 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9115 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9117 # The following creates "bar.pdf" from "bar.tex"
9118 env.PDFBuilder(target = 'bar', source = 'bar')
9121 Note also that the above initialization
9122 overwrites the default Builder objects,
9123 so the Environment created above
9124 can not be used call Builders like env.Program(),
9125 env.Object(), env.StaticLibrary(), etc.
9127 .SS Adding Your Own Builder Object to an Environment
9130 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9132 src_suffix = '.tex')
9134 env.Append(BUILDERS = {'PDFBuilder' : bld})
9135 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9136 env.Program(target = 'bar', source = 'bar.c')
9139 You also can use other Pythonic techniques to add
9140 to the BUILDERS construction variable, such as:
9144 env['BUILDERS]['PDFBuilder'] = bld
9147 .SS Defining Your Own Scanner Object
9152 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9154 def kfile_scan(node, env, path, arg):
9155 contents = node.get_contents()
9156 includes = include_re.findall(contents)
9159 kscan = Scanner(name = 'kfile',
9160 function = kfile_scan,
9163 scanners = Environment().Dictionary('SCANNERS')
9164 env = Environment(SCANNERS = scanners + [kscan])
9166 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9168 bar_in = File('bar.in')
9169 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9170 bar_in.target_scanner = kscan
9173 .SS Creating a Hierarchical Build
9175 Notice that the file names specified in a subdirectory's
9177 file are relative to that subdirectory.
9183 env.Program(target = 'foo', source = 'foo.c')
9185 SConscript('sub/SConscript')
9190 # Builds sub/foo from sub/foo.c
9191 env.Program(target = 'foo', source = 'foo.c')
9193 SConscript('dir/SConscript')
9198 # Builds sub/dir/foo from sub/dir/foo.c
9199 env.Program(target = 'foo', source = 'foo.c')
9202 .SS Sharing Variables Between SConscript Files
9204 You must explicitly Export() and Import() variables that
9205 you want to share between SConscript files.
9211 env.Program(target = 'foo', source = 'foo.c')
9214 SConscript('subdirectory/SConscript')
9216 subdirectory/SConscript:
9219 env.Program(target = 'foo', source = 'foo.c')
9222 .SS Building Multiple Variants From the Same Source
9224 Use the BuildDir() method to establish
9225 one or more separate build directories for
9226 a given source directory,
9227 then use the SConscript() method
9228 to specify the SConscript files
9229 in the build directories:
9236 BuildDir('foo', 'src')
9237 SConscript('foo/SConscript')
9241 BuildDir('bar', 'src')
9242 SConscript('bar/SConscript')
9247 env = Environment(CCFLAGS = ccflags)
9248 env.Program(target = 'src', source = 'src.c')
9251 Note the use of the Export() method
9252 to set the "ccflags" variable to a different
9253 value for each variant build.
9255 .SS Hierarchical Build of Two Libraries Linked With a Program
9260 env = Environment(LIBPATH = ['#libA', '#libB'])
9262 SConscript('libA/SConscript')
9263 SConscript('libB/SConscript')
9264 SConscript('Main/SConscript')
9269 env.Library('a', Split('a1.c a2.c a3.c'))
9274 env.Library('b', Split('b1.c b2.c b3.c'))
9279 e = env.Copy(LIBS = ['a', 'b'])
9280 e.Program('foo', Split('m1.c m2.c m3.c'))
9283 The '#' in the LIBPATH directories specify that they're relative to the
9284 top-level directory, so they don't turn into "Main/libA" when they're
9285 used in Main/SConscript.
9287 Specifying only 'a' and 'b' for the library names
9288 allows SCons to append the appropriate library
9289 prefix and suffix for the current platform
9290 (for example, 'liba.a' on POSIX systems,
9291 'a.lib' on Windows).
9293 .SS Customizing contruction variables from the command line.
9295 The following would allow the C compiler to be specified on the command
9296 line or in the file custom.py.
9299 opts = Options('custom.py')
9300 opts.Add('CC', 'The C compiler.')
9301 env = Environment(options=opts)
9302 Help(opts.GenerateHelpText(env))
9305 The user could specify the C compiler on the command line:
9311 or in the custom.py file:
9317 or get documentation on the options:
9328 .SS Using Microsoft Visual C++ precompiled headers
9330 Since windows.h includes everything and the kitchen sink, it can take quite
9331 some time to compile it over and over again for a bunch of object files, so
9332 Microsoft provides a mechanism to compile a set of headers once and then
9333 include the previously compiled headers in any object file. This
9334 technology is called precompiled headers. The general recipe is to create a
9335 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9336 then include every header you want to precompile in "StdAfx.h", and finally
9337 include "StdAfx.h" as the first header in all the source files you are
9338 compiling to object files. For example:
9342 #include <windows.h>
9343 #include <my_big_header.h>
9362 /* do some other stuff */
9368 env['PCHSTOP'] = 'StdAfx.h'
9369 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9370 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9373 For more information see the document for the PCH builder, and the PCH and
9374 PCHSTOP construction variables. To learn about the details of precompiled
9375 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9377 .SS Using Microsoft Visual C++ external debugging information
9379 Since including debugging information in programs and shared libraries can
9380 cause their size to increase significantly, Microsoft provides a mechanism
9381 for including the debugging information in an external file called a PDB
9382 file. SCons supports PDB files through the PDB construction
9388 env['PDB'] = 'MyApp.pdb'
9389 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9392 For more information see the document for the PDB construction variable.
9397 Specifies the directory that contains the SCons Python module directory
9398 (e.g. /home/aroach/scons-src-0.01/src/engine).
9401 A string of options that will be used by scons in addition to those passed
9402 on the command line.
9413 Steven Knight <knight@baldmt.com>
9415 Anthony Roach <aroach@electriceyeball.com>