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:
1137 Additionally, there is a "tool" named
1139 which configures the
1140 environment with a default set of tools for the current platform.
1142 On posix and cygwin platforms
1143 the GNU tools (e.g. gcc) are preferred by SCons,
1144 on win32 the Microsoft tools (e.g. msvc)
1145 followed by MinGW are preferred by SCons,
1146 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1150 Build rules are specified by calling a construction
1151 environment's builder methods.
1152 The arguments to the builder methods are
1154 (a list of target files)
1157 (a list of source files).
1159 Because long lists of file names
1160 can lead to a lot of quoting,
1165 and a same-named environment method
1166 that split a single string
1167 into a list, separated on
1168 strings of white-space characters.
1169 (These are similar to the
1170 string.split() method
1171 from the standard Python library,
1172 but work even if the input isn't a string.)
1174 Like all Python arguments,
1175 the target and source arguments to a builder method
1176 can be specified either with or without
1177 the "target" and "source" keywords.
1178 When the keywords are omitted,
1179 the target is first,
1180 followed by the source.
1181 The following are equivalent examples of calling the Program builder method:
1184 env.Program('bar', ['bar.c', 'foo.c'])
1185 env.Program('bar', Split('bar.c foo.c'))
1186 env.Program('bar', env.Split('bar.c foo.c'))
1187 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1188 env.Program(target = 'bar', Split('bar.c foo.c'))
1189 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1190 env.Program('bar', source = string.split('bar.c foo.c'))
1193 When the target shares the same base name
1194 as the source and only the suffix varies,
1195 and if the builder method has a suffix defined for the target file type,
1196 then the target argument may be omitted completely,
1199 will deduce the target file name from
1200 the source file name.
1201 The following examples all build the
1207 (on Windows systems)
1208 from the bar.c source file:
1211 env.Program(target = 'bar', source = 'bar.c')
1212 env.Program('bar', source = 'bar.c')
1213 env.Program(source = 'bar.c')
1214 env.Program('bar.c')
1217 It is possible to override or add construction variables when calling a
1218 builder method by passing additional keyword arguments.
1219 These overridden or added
1220 variables will only be in effect when building the target, so they will not
1221 affect other parts of the build. For example, if you want to add additional
1222 libraries for just one program:
1225 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1228 or generate a shared library with a nonstandard suffix:
1231 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1234 Although the builder methods defined by
1237 methods of a construction environment object,
1238 they may also be called without an explicit environment:
1241 Program('hello', 'hello.c')
1242 SharedLibrary('word', 'word.cpp')
1246 the methods are called internally using a default construction
1247 environment that consists of the tools and values that
1249 has determined are appropriate for the local system.
1251 All builder methods return a list of Nodes
1252 that represent the target or targets that will be built.
1255 is an internal SCons object
1257 build targets or sources.
1259 The returned Node(s)
1260 can be passed to other builder methods as source(s)
1261 or passed to any SCons function or method
1262 where a filename would normally be accepted.
1263 For example, if it were necessary
1266 flag when compiling one specific object file:
1269 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1270 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1273 Using a Node in this way
1274 makes for a more portable build
1275 by avoiding having to specify
1276 a platform-specific object suffix
1277 when calling the Program() builder method.
1279 Note that Builder calls will automatically "flatten"
1280 the source and target file lists,
1281 so it's all right to have the bar_obj list
1282 return by the StaticObject() call
1283 in the middle of the source file list.
1284 If you need to manipulate a list of lists returned by Builders
1285 directly using Python,
1286 you can either build the list by hand:
1289 foo = Object('foo.c')
1290 bar = Object('bar.c')
1291 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1292 for object in objects:
1299 to create a list containing just the Nodes,
1300 which may be more convenient:
1303 foo = Object('foo.c')
1304 bar = Object('bar.c')
1305 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1306 for object in objects:
1310 The path name for a Node's file may be used
1311 by passing the Node to the Python-builtin
1316 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1317 print "The path to bar_obj is:", str(bar_obj_list[0])
1320 Note again that because the Builder call returns a list,
1321 we have to access the first element in the list
1322 .B (bar_obj_list[0])
1323 to get at the Node that actually represents
1326 Builder calls support a
1328 keyword argument that
1329 specifies that the Builder's action(s)
1331 after changing directory.
1335 a string or a directory Node,
1336 scons will change to the specified directory.
1339 is not a string or Node
1341 then scons will change to the
1342 target file's directory.
1345 # scons will change to the "sub" subdirectory
1346 # before executing the "cp" command.
1347 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1348 "cp dir/foo.in dir/foo.out",
1351 # Because chdir is not a string, scons will change to the
1352 # target's directory ("sub/dir") before executing the
1354 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1355 "cp foo.in foo.out",
1359 Note that scons will
1361 automatically modify
1363 construction variables like
1367 when using the chdir
1368 keyword argument--that is,
1369 the expanded file names
1370 will still be relative to
1371 the top-level SConstruct directory,
1372 and consequently incorrect
1373 relative to the chdir directory.
1374 If you use the chdir keyword argument,
1375 you will typically need to supply a different
1381 to use just the filename portion of the
1385 provides the following builder methods:
1387 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1390 Builds a C source file given a lex (.l) or yacc (.y) input file.
1391 The suffix specified by the $CFILESUFFIX construction variable
1393 is automatically added to the target
1394 if it is not already present. Example:
1398 env.CFile(target = 'foo.c', source = 'foo.l')
1400 env.CFile(target = 'bar', source = 'bar.y')
1403 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1406 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1408 The suffix specified by the $CXXFILESUFFIX construction variable
1410 is automatically added to the target
1411 if it is not already present. Example:
1415 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1417 env.CXXFile(target = 'bar', source = 'bar.yy')
1420 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1423 Builds a .dvi file from a .tex, .ltx or .latex input file.
1424 If the source file suffix is .tex,
1426 will examine the contents of the file;
1431 is found, the file is assumed to be a LaTeX file and
1432 the target is built by invoking the $LATEXCOM command line;
1433 otherwise, the $TEXCOM command line is used.
1434 If the file is a LaTeX file,
1437 builder method will also examine the contents
1440 and invoke the $BIBTEX command line
1444 and will examine the contents
1446 file and re-run the $LATEXCOM command
1447 if the log file says it is necessary.
1450 (hard-coded within TeX itself)
1451 is automatically added to the target
1452 if it is not already present. Examples:
1455 # builds from aaa.tex
1456 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1458 env.DVI(target = 'bbb', source = 'bbb.ltx')
1459 # builds from ccc.latex
1460 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1463 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1466 Builds a Java archive (.jar) file
1467 from a source tree of .class files.
1468 If the $JARCHDIR value is set, the
1470 command will change to the specified directory using the
1473 If the contents any of the source files begin with the string
1474 .BR Manifest-Version ,
1475 the file is assumed to be a manifest
1476 and is passed to the
1483 env.Jar(target = 'foo.jar', source = 'classes')
1486 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1489 Builds one or more Java class files
1490 from one or more source trees of .java files.
1491 The class files will be placed underneath
1492 the specified target directory.
1493 SCons will parse each source .java file
1495 (including inner classes)
1496 defined within that file,
1497 and from that figure out the
1498 target .class files that will be created.
1499 SCons will also search each Java file
1500 for the Java package name,
1501 which it assumes can be found on a line
1502 beginning with the string
1504 in the first column;
1505 the resulting .class files
1506 will be placed in a directory reflecting
1507 the specified package name.
1511 defining a single public
1514 containing a package name of
1516 will generate a corresponding
1517 .IR sub/dir/Foo.class
1523 env.Java(target = 'classes', source = 'src')
1524 env.Java(target = 'classes', source = ['src1', 'src2'])
1527 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1530 Builds C header and source files for
1531 implementing Java native methods.
1532 The target can be either a directory
1533 in which the header files will be written,
1534 or a header file name which
1535 will contain all of the definitions.
1536 The source can be either the names of .class files,
1537 or the objects returned from the
1541 If the construction variable
1543 is set, either in the environment
1544 or in the call to the
1546 builder method itself,
1547 then the value of the variable
1548 will be stripped from the
1549 beginning of any .class file names.
1554 # builds java_native.h
1555 classes = env.Java(target = 'classdir', source = 'src')
1556 env.JavaH(target = 'java_native.h', source = classes)
1558 # builds include/package_foo.h and include/package_bar.h
1559 env.JavaH(target = 'include',
1560 source = ['package/foo.class', 'package/bar.class'])
1562 # builds export/foo.h and export/bar.h
1563 env.JavaH(target = 'export',
1564 source = ['classes/foo.class', 'classes/bar.class'],
1565 JAVACLASSDIR = 'classes')
1568 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1575 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1578 Builds an output file from an M4 input file.
1579 This uses a default $M4FLAGS value of
1581 which considers all warnings to be fatal
1582 and stops on the first warning
1583 when using the GNU version of m4.
1587 env.M4(target = 'foo.c', source = 'foo.c.m4')
1590 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1593 Builds an output file from a moc input file. Moc input files are either
1594 header files or cxx files. This builder is only available after using the
1595 tool 'qt'. See the QTDIR variable for more information.
1599 env.Moc('foo.h') # generates moc_foo.cc
1600 env.Moc('foo.cpp') # generates foo.moc
1603 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1605 .IP env.MSVSProject()
1606 Builds Microsoft Visual Studio project files.
1607 This builds a Visual Studio project file, based on the version of
1608 Visual Studio that is configured (either the latest installed version,
1609 or the version set by
1611 in the Environment constructor).
1612 For VS 6, it will generate
1616 files, for VS 7, it will
1623 It takes several lists of filenames to be placed into the project
1624 file, currently these are limited to
1625 .B srcs, incs, localincs, resources,
1628 These are pretty self explanatory, but it
1629 should be noted that the 'srcs' list is NOT added to the $SOURCES
1630 environment variable. This is because it represents a list of files
1631 to be added to the project file, not the source used to build the
1632 project file (in this case, the 'source' is the SConscript file used
1633 to call MSVSProject).
1635 In addition to these values (which are all optional, although not
1636 specifying any of them results in an empty project file), the
1637 following values must be specified:
1639 target: The name of the target .dsp or .vcproj file. The correct
1640 suffix for the version of Visual Studio must be used, but the value
1642 env['MSVSPROJECTSUFFIX']
1644 will be defined to the correct value (see example below).
1646 variant: The name of this particular variant. These are typically
1647 things like "Debug" or "Release", but really can be anything you want.
1648 Multiple calls to MSVSProject with different variants are allowed: all
1649 variants will be added to the project file with their appropriate
1650 build targets and sources.
1652 buildtarget: A list of SCons.Node.FS objects which is returned from
1653 the command which builds the target. This is used to tell SCons what
1654 to build when the 'build' button is pressed inside of the IDE.
1659 barsrcs = ['bar.cpp'],
1660 barincs = ['bar.h'],
1661 barlocalincs = ['StdAfx.h']
1662 barresources = ['bar.rc','resource.h']
1663 barmisc = ['bar_readme.txt']
1665 dll = local.SharedLibrary(target = 'bar.dll',
1668 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1671 localincs = barlocalincs,
1672 resources = barresources,
1675 variant = 'Release')
1678 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1685 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1688 Builds a Microsoft Visual C++ precompiled header.
1689 Calling this builder method
1690 returns a list of two targets: the PCH as the first element, and the object
1691 file as the second element. Normally the object file is ignored.
1692 This builder method is only
1693 provided when Microsoft Visual C++ is being used as the compiler.
1694 The PCH builder method is generally used in
1695 conjuction with the PCH construction variable to force object files to use
1696 the precompiled header:
1699 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1702 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1705 Builds a .pdf file from a .dvi input file
1706 (or, by extension, a .tex, .ltx, or .latex input file).
1707 The suffix specified by the $PDFSUFFIX construction variable
1709 is added automatically to the target
1710 if it is not already present. Example:
1713 # builds from aaa.tex
1714 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1715 # builds bbb.pdf from bbb.dvi
1716 env.PDF(target = 'bbb', source = 'bbb.dvi')
1719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1721 .IP env.PostScript()
1722 Builds a .ps file from a .dvi input file
1723 (or, by extension, a .tex, .ltx, or .latex input file).
1724 The suffix specified by the $PSSUFFIX construction variable
1726 is added automatically to the target
1727 if it is not already present. Example:
1730 # builds from aaa.tex
1731 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1732 # builds bbb.ps from bbb.dvi
1733 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1736 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1739 Builds an executable given one or more object files
1740 or C, C++, D, or Fortran source files.
1741 If any C, C++, D or Fortran source files are specified,
1742 then they will be automatically
1743 compiled to object files using the
1746 see that builder method's description for
1747 a list of legal source file suffixes
1748 and how they are interpreted.
1749 The target executable file prefix
1750 (specified by the $PROGPREFIX construction variable; nothing by default)
1752 (specified by the $PROGSUFFIX construction variable;
1753 by default, .exe on Windows systems, nothing on POSIX systems)
1754 are automatically added to the target if not already present.
1758 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1761 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1764 Builds a Microsoft Visual C++ resource file.
1765 This builder method is only provided
1766 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1770 for MinGW) suffix is added to the target name if no other suffix is given. The source
1771 file is scanned for implicit dependencies as though it were a C file. Example:
1774 env.RES('resource.rc')
1777 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1780 Builds stub and skeleton class files
1782 from Java .class files.
1783 The target is a directory
1784 relative to which the stub
1785 and skeleton class files will be written.
1786 The source can be the names of .class files,
1787 or the objects return from the
1791 If the construction variable
1793 is set, either in the environment
1794 or in the call to the
1796 builder method itself,
1797 then the value of the variable
1798 will be stripped from the
1799 beginning of any .class file names.
1802 classes = env.Java(target = 'classdir', source = 'src')
1803 env.RMIC(target = 'outdir1', source = classes)
1805 env.RMIC(target = 'outdir2',
1806 source = ['package/foo.class', 'package/bar.class'])
1808 env.RMIC(target = 'outdir3',
1809 source = ['classes/foo.class', 'classes/bar.class'],
1810 JAVACLASSDIR = 'classes')
1813 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1815 .IP env.RPCGenClient()
1816 Generates an RPC client stub (_clnt.c) file
1817 from a specified RPC (.x) source file.
1818 Because rpcgen only builds output files
1819 in the local directory,
1820 the command will be executed
1821 in the source file's directory by default.
1824 # Builds src/rpcif_clnt.c
1825 env.RPCGenClient('src/rpcif.x')
1828 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1830 .IP env.RPCGenHeader()
1831 Generates an RPC header (.h) file
1832 from a specified RPC (.x) source file.
1833 Because rpcgen only builds output files
1834 in the local directory,
1835 the command will be executed
1836 in the source file's directory by default.
1839 # Builds src/rpcif.h
1840 env.RPCGenHeader('src/rpcif.x')
1843 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1845 .IP env.RPCGenService()
1846 Generates an RPC server-skeleton (_svc.c) file
1847 from a specified RPC (.x) source file.
1848 Because rpcgen only builds output files
1849 in the local directory,
1850 the command will be executed
1851 in the source file's directory by default.
1854 # Builds src/rpcif_svc.c
1855 env.RPCGenClient('src/rpcif.x')
1858 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1861 Generates an RPC XDR routine (_xdr.c) file
1862 from a specified RPC (.x) source file.
1863 Because rpcgen only builds output files
1864 in the local directory,
1865 the command will be executed
1866 in the source file's directory by default.
1869 # Builds src/rpcif_xdr.c
1870 env.RPCGenClient('src/rpcif.x')
1873 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1875 .IP env.SharedLibrary()
1876 Builds a shared library
1877 (.so on a POSIX system, .dll on WIN32)
1878 given one or more object files
1879 or C, C++, D or Fortran source files.
1880 If any source files are given,
1881 then they will be automatically
1882 compiled to object files.
1883 The static library prefix and suffix (if any)
1884 are automatically added to the target.
1885 The target library file prefix
1886 (specified by the $SHLIBPREFIX construction variable;
1887 by default, lib on POSIX systems, nothing on Windows systems)
1889 (specified by the $SHLIBSUFFIX construction variable;
1890 by default, .dll on Windows systems, .so on POSIX systems)
1891 are automatically added to the target if not already present.
1895 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1898 On WIN32 systems, the
1900 builder method will always build an import (.lib) library
1901 in addition to the shared (.dll) library,
1902 adding a .lib library with the same basename
1903 if there is not already a .lib file explicitly
1904 listed in the targets.
1906 Any object files listed in the
1908 must have been built for a shared library
1913 will raise an error if there is any mismatch.
1915 On WIN32 systems, specifying "register=1" will cause the dll to be
1916 registered after it is built using REGSVR32. The command that is run
1917 ("regsvr32" by default) is determined by $REGSVR construction
1918 variable, and the flags passed are determined by $REGSVRFLAGS. By
1919 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1920 up and requiring user attention when it is run. If you change
1921 $REGSVRFLAGS, be sure to include "/s". For example,
1924 env.SharedLibrary(target = 'bar',
1925 source = ['bar.cxx', 'foo.obj'],
1930 will register "bar.dll" as a COM object when it is done linking it.
1932 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1934 .IP env.SharedObject()
1935 Builds an object file for
1936 inclusion in a shared library.
1937 Source files must have one of the same set of extensions
1938 specified above for the
1941 On some platforms building a shared object requires additional
1942 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1943 normal (static) object, but on some platforms there is no difference between a
1944 shared object and a normal (static) one. When there is a difference, SCons
1945 will only allow shared objects to be linked into a shared library, and will
1946 use a different suffix for shared objects. On platforms where there is no
1947 difference, SCons will allow both normal (static)
1948 and shared objects to be linked into a
1949 shared library, and will use the same suffix for shared and normal
1951 The target object file prefix
1952 (specified by the $SHOBJPREFIX construction variable;
1953 by default, the same as $OBJPREFIX)
1955 (specified by the $SHOBJSUFFIX construction variable)
1956 are automatically added to the target if not already present.
1960 env.SharedObject(target = 'ddd', source = 'ddd.c')
1961 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1962 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1965 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1967 .IP env.StaticLibrary()
1968 Builds a static library given one or more object files
1969 or C, C++, D or Fortran source files.
1970 If any source files are given,
1971 then they will be automatically
1972 compiled to object files.
1973 The static library prefix and suffix (if any)
1974 are automatically added to the target.
1975 The target library file prefix
1976 (specified by the $LIBPREFIX construction variable;
1977 by default, lib on POSIX systems, nothing on Windows systems)
1979 (specified by the $LIBSUFFIX construction variable;
1980 by default, .lib on Windows systems, .a on POSIX systems)
1981 are automatically added to the target if not already present.
1985 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1989 Any object files listed in the
1991 must have been built for a static library
1996 will raise an error if there is any mismatch.
1998 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2000 .IP env.StaticObject()
2001 Builds a static object file
2002 from one or more C, C++, D, or Fortran source files.
2003 Source files must have one of the following extensions:
2006 .asm assembly language file
2007 .ASM assembly language file
2019 .F WIN32: Fortran file
2020 POSIX: Fortran file + C pre-processor
2023 .fpp Fortran file + C pre-processor
2024 .FPP Fortran file + C pre-processor
2025 .s assembly language file
2026 .S WIN32: assembly language file
2027 POSIX: assembly language file + C pre-processor
2028 .spp assembly language file + C pre-processor
2029 .SPP assembly language file + C pre-processor
2032 The target object file prefix
2033 (specified by the $OBJPREFIX construction variable; nothing by default)
2035 (specified by the $OBJSUFFIX construction variable;
2036 \.obj on Windows systems, .o on POSIX systems)
2037 are automatically added to the target if not already present.
2041 env.StaticObject(target = 'aaa', source = 'aaa.c')
2042 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2043 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2046 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2049 Builds a tar archive of the specified files
2051 Unlike most builder methods,
2054 builder method may be called multiple times
2056 each additional call
2057 adds to the list of entries
2058 that will be built into the archive.
2061 env.Tar('src.tar', 'src')
2063 # Create the stuff.tar file.
2064 env.Tar('stuff', ['subdir1', 'subdir2'])
2065 # Also add "another" to the stuff.tar file.
2066 env.Tar('stuff', 'another')
2068 # Set TARFLAGS to create a gzip-filtered archive.
2069 env = Environment(TARFLAGS = '-c -z')
2070 env.Tar('foo.tar.gz', 'foo')
2072 # Also set the suffix to .tgz.
2073 env = Environment(TARFLAGS = '-c -z',
2078 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2080 .IP env.TypeLibrary()
2081 Builds a Windows type library (.tlb) file from and input IDL file
2082 (.idl). In addition, it will build the associated inteface stub and
2083 proxy source files. It names them according to the base name of the .idl file.
2088 env.TypeLibrary(source="foo.idl")
2091 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2093 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2096 Builds a header file, an implementation file and a moc file from an ui file.
2097 and returns the corresponding nodes in the above order.
2098 This builder is only available after using the tool 'qt'. Note: you can
2099 specify .ui files directly as inputs for Program, Library and SharedLibrary
2100 without using this builder. Using the builder lets you override the standard
2101 naming conventions (be careful: prefixes are always prepended to names of
2102 built files; if you don't want prefixes, you may set them to ``).
2103 See the QTDIR variable for more information.
2107 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2108 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2109 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2112 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2115 Builds a zip archive of the specified files
2117 Unlike most builder methods,
2120 builder method may be called multiple times
2122 each additional call
2123 adds to the list of entries
2124 that will be built into the archive.
2127 env.Zip('src.zip', 'src')
2129 # Create the stuff.zip file.
2130 env.Zip('stuff', ['subdir1', 'subdir2'])
2131 # Also add "another" to the stuff.tar file.
2132 env.Zip('stuff', 'another')
2137 C source files, C++ source files,
2138 Fortran source files with
2140 (POSIX systems only),
2145 and assembly language files with
2147 (POSIX systems only),
2152 for C preprocessor dependencies,
2153 so the dependencies do not need to be specified explicitly.
2155 targets of builder methods automatically depend on their sources.
2156 An explicit dependency can
2157 be specified using the
2159 method of a construction environment (see below).
2161 .SS Methods and Functions to Do Things
2162 In addition to Builder methods,
2164 provides a number of other construction environment methods
2165 and global functions to
2166 manipulate the build configuration.
2168 Usually, a construction environment method
2169 and global function with the same name both exist
2170 so that you don't have to remember whether
2171 to a specific bit of functionality
2172 must be called with or without a construction environment.
2173 In the following list,
2174 if you call something as a global function
2177 .RI Function( arguments )
2179 and if you call something through a construction
2180 environment it looks like:
2182 .RI env.Function( arguments )
2184 If you can call the functionality in both ways,
2185 then both forms are listed.
2187 Except where otherwise noted,
2189 construction environment method
2191 provide the exact same functionality.
2192 The only difference is that,
2194 calling the functionality through a construction environment will
2195 substitute construction variables into
2196 any supplied strings.
2199 env = Environment(FOO = 'foo')
2203 the first call to the global
2205 function will actually add a target named
2207 to the list of default targets,
2208 while the second call to the
2210 construction environment method
2211 will expand the value
2212 and add a target named
2214 to the list of default targets.
2215 For more on construction variable expansion,
2216 see the next section on
2217 construction variables.
2219 Construction environment methods
2220 and global functions supported by
2224 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2226 .RI Action( action ", [" strfunction ", " varlist ])
2228 .RI env.Action( action ", [" strfunction ", " varlist ])
2229 Creates an Action object for
2232 See the section "Action Objects,"
2233 below, for a complete explanation of the arguments and behavior.
2235 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2237 .RI AddPostAction( target ", " action )
2239 .RI env.AddPostAction( target ", " action )
2240 Arranges for the specified
2246 The specified action(s) may be
2247 an Action object, or anything that
2248 can be converted into an Action object
2251 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2253 .RI AddPreAction( target ", " action )
2255 .RI env.AddPreAction( target ", " action )
2256 Arranges for the specified
2259 before the specified
2262 The specified action(s) may be
2263 an Action object, or anything that
2264 can be converted into an Action object
2267 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2269 .RI Alias( alias ", [" targets ", [" action ]])
2271 .RI env.Alias( alias ", [" targets ", [" action ]])
2272 Creates one or more phony targets that
2273 expand to one or more other targets.
2278 can be specified that will be executed
2279 whenever the any of the alias targets are out-of-date.
2280 Returns the Node object representing the alias,
2281 which exists outside of any file system.
2282 This Node object, or the alias name,
2283 may be used as a dependency of any other target,
2284 including another alias.
2286 can be called multiple times for the same
2287 alias to add additional targets to the alias,
2288 or additional actions to the list for this alias.
2292 Alias('install', '/usr/bin')
2293 Alias(['install', 'install-lib'], '/usr/local/lib')
2295 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2296 env.Alias('install', ['/usr/local/man'])
2298 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2301 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2303 .RI AlwaysBuild( target ", ...)"
2305 .RI env.AlwaysBuild( target ", ...)"
2308 so that it is always assumed to be out of date,
2309 and will always be rebuilt if needed.
2312 does not add its target(s) to the default target list,
2313 so the targets will only be built
2314 if they are specified on the command line,
2315 or are a dependent of a target specified on the command line--but
2318 be built if so specified.
2319 Multiple targets can be passed in to a single call to
2322 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2324 .RI env.Append( key = val ", [...])"
2325 Appends the specified keyword arguments
2326 to the end of construction variables in the environment.
2327 If the Environment does not have
2328 the specified construction variable,
2329 it is simply added to the environment.
2330 If the values of the construction variable
2331 and the keyword argument are the same type,
2332 then the two values will be simply added together.
2333 Otherwise, the construction variable
2334 and the value of the keyword argument
2335 are both coerced to lists,
2336 and the lists are added together.
2337 (See also the Prepend method, below.)
2340 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2343 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2345 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2346 This appends new path elements to the given path in the
2347 specified external environment
2351 any particular path once (leaving the last one it encounters and
2352 ignoring the rest, to preserve path order),
2353 and to help assure this,
2354 will normalize all paths (using
2357 .BR os.path.normcase ).
2358 This can also handle the
2359 case where the given old path variable is a list instead of a
2360 string, in which case a list will be returned instead of a string.
2364 print 'before:',env['ENV']['INCLUDE']
2365 include_path = '/foo/bar:/foo'
2366 env.PrependENVPath('INCLUDE', include_path)
2367 print 'after:',env['ENV']['INCLUDE']
2371 after: /biz:/foo/bar:/foo
2374 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2376 .RI env.AppendUnique( key = val ", [...])"
2377 Appends the specified keyword arguments
2378 to the end of construction variables in the environment.
2379 If the Environment does not have
2380 the specified construction variable,
2381 it is simply added to the environment.
2382 If the construction variable being appended to is a list,
2383 then any value(s) that already exist in the
2384 construction variable will
2386 be added again to the list.
2389 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2392 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2395 A factory function that
2396 returns a Builder object
2397 to be used to fetch source files
2399 The returned Builder
2400 is intended to be passed to the
2405 env.SourceCode('.', env.BitKeeper())
2408 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2410 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2412 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2413 This specifies a build directory
2415 in which to build all derived files
2416 that would normally be built under
2418 Multiple build directories can be set up for multiple build variants, for
2421 must be underneath the SConstruct file's directory,
2424 may not be underneath the
2427 The default behavior is for
2429 to duplicate all of the files in the tree underneath
2433 and then build the derived files within the copied tree.
2434 (The duplication is performed by
2436 depending on the platform; see also the
2439 This guarantees correct builds
2440 regardless of whether intermediate source files
2441 are generated during the build,
2442 where preprocessors or other scanners search
2444 or whether individual compilers or other invoked tools
2445 are hard-coded to put derived files in the same directory as source files.
2447 This behavior of making a complete copy of the source tree
2448 may be disabled by setting
2453 to invoke Builders using the
2454 path names of source files in
2456 and the path names of derived files within
2458 This is always more efficient than
2460 and is usually safe for most builds.
2464 may cause build problems
2465 if source files are generated during the build,
2466 if any invoked tools are hard-coded to
2467 put derived files in the same directory as the source files.
2469 Note that specifying a
2471 works most naturally
2472 with a subsidiary SConscript file
2473 in the source directory.
2475 you would then call the subsidiary SConscript file
2476 not in the source directory,
2481 had made a virtual copy of the source tree
2482 regardless of the value of
2484 This is how you tell
2486 which variant of a source tree to build.
2490 BuildDir('build-variant1', 'src')
2491 SConscript('build-variant1/SConscript')
2492 BuildDir('build-variant2', 'src')
2493 SConscript('build-variant2/SConscript')
2499 function, described below,
2501 specify a build directory
2502 in conjunction with calling a subsidiary
2505 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2507 .RI Builder( action ", [" arguments ])
2509 .RI env.Builder( action ", [" arguments ])
2510 Creates a Builder object for
2513 See the section "Builder Objects,"
2514 below, for a complete explanation of the arguments and behavior.
2516 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2518 .RI CacheDir( cache_dir )
2520 .RI env.CacheDir( cache_dir )
2523 will maintain a cache of derived files in
2525 The derived files in the cache will be shared
2526 among all the builds using the same
2534 finds a derived file that needs to be rebuilt,
2535 it will first look in the cache to see if a
2536 derived file has already been built
2537 from identical input files and an identical build action
2538 (as incorporated into the MD5 build signature).
2541 will retrieve the file from the cache.
2542 If the derived file is not present in the cache,
2545 then place a copy of the built file in the cache
2546 (identified by its MD5 build signature),
2547 so that it may be retrieved by other
2548 builds that need to build the same derived file
2549 from identical inputs.
2553 may be disabled for any invocation
2562 will place a copy of
2564 derived files in the cache,
2565 even if they already existed
2566 and were not built by this invocation.
2567 This is useful to populate a cache
2570 is added to a build,
2579 "Retrieved `file' from cache,"
2582 option is being used.
2587 will print the action that
2589 have been used to build the file,
2590 without any indication that
2591 the file was actually retrieved from the cache.
2592 This is useful to generate build logs
2593 that are equivalent regardless of whether
2594 a given derived file has been built in-place
2595 or retrieved from the cache.
2597 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2599 .RI Clean( targets ", " files_or_dirs )
2601 .RI env.Clean( targets ", " files_or_dirs )
2602 This specifies a list of files or directories which should be removed
2603 whenever the targets are specified with the
2605 command line option.
2606 The specified targets may be a list
2607 or an individual target.
2611 and create new targets or add files and directories to the
2612 clean list for the specified targets.
2614 Multiple files or directories should be specified
2615 either as separate arguments to the
2617 method, or as a list.
2619 will also accept the return value of any of the construction environment
2624 Clean('foo', ['bar', 'baz'])
2625 Clean('dist', env.Program('hello', 'hello.c'))
2626 Clean(['foo', 'bar'], 'something_else_to_clean')
2629 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2631 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2633 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2634 Executes a specific action
2635 (or list of actions)
2636 to build a target file or files.
2637 This is more convenient
2638 than defining a separate Builder object
2639 for a single special-case build.
2640 Any keyword arguments specified override any
2641 same-named existing construction variables.
2643 Note that an action can be an external command,
2644 specified as a string,
2645 or a callable Python object;
2646 see "Action Objects," below.
2650 env.Command('foo.out', 'foo.in',
2651 "$FOO_BUILD < $SOURCES > $TARGET")
2653 env.Command('bar.out', 'bar.in',
2655 "$BAR_BUILD < $SOURCES > $TARGET"],
2656 ENV = {'PATH' : '/usr/local/bin/'})
2658 def rename(env, target, source):
2660 os.rename('.tmp', str(target[0]))
2662 env.Command('baz.out', 'baz.in',
2663 ["$BAZ_BUILD < $SOURCES > .tmp",
2667 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2669 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2671 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2672 Creates a Configure object for integrated
2673 functionality similar to GNU autoconf.
2674 See the section "Configure Contexts,"
2675 below, for a complete explanation of the arguments and behavior.
2677 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2679 .RI env.Copy([ key = val ", ...])"
2680 Return a separate copy of a construction environment.
2681 If there are any keyword arguments specified,
2682 they are added to the returned copy,
2683 overwriting any existing values
2688 env3 = env.Copy(CCFLAGS = '-g')
2691 Additionally, a list of tools and a toolpath may be specified, as in
2692 the Environment constructor:
2695 def MyTool(env): env['FOO'] = 'bar'
2696 env4 = env.Copy(tools = ['msvc', MyTool])
2699 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2701 .RI env.CVS( repository ", " module )
2702 A factory function that
2703 returns a Builder object
2704 to be used to fetch source files
2708 The returned Builder
2709 is intended to be passed to the
2713 The optional specified
2715 will be added to the beginning
2716 of all repository path names;
2717 this can be used, in essence,
2718 to strip initial directory names
2719 from the repository path names,
2720 so that you only have to
2721 replicate part of the repository
2722 directory hierarchy in your
2723 local build directory:
2726 # Will fetch foo/bar/src.c
2727 # from /usr/local/CVSROOT/foo/bar/src.c.
2728 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2730 # Will fetch bar/src.c
2731 # from /usr/local/CVSROOT/foo/bar/src.c.
2732 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2735 # from /usr/local/CVSROOT/foo/bar/src.c.
2736 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2739 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2741 .RI Default( targets )
2743 .RI env.Default( targets )
2744 This specifies a list of default targets,
2745 which will be built by
2747 if no explicit targets are given on the command line.
2751 and add to the list of default targets.
2753 Multiple targets should be specified as
2754 separate arguments to the
2756 method, or as a list.
2758 will also accept the Node returned by any
2759 of a construction environment's
2764 Default('foo', 'bar', 'baz')
2765 env.Default(['a', 'b', 'c'])
2766 hello = env.Program('hello', 'hello.c')
2774 will clear all default targets.
2777 will add to the (now empty) default-target list
2780 The current list of targets added using the
2782 function or method is available in the
2787 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2789 .RI DefaultEnvironment([ args ])
2790 Creates and returns a default construction environment object.
2791 This construction environment is used internally by SCons
2792 in order to execute many of the global functions in this list,
2793 and to fetch source files transparently
2794 from source code management systems.
2796 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2798 .RI Depends( target ", " dependency )
2800 .RI env.Depends( target ", " dependency )
2801 Specifies an explicit dependency;
2802 the target file(s) will be rebuilt
2803 whenever the dependency file(s) has changed.
2804 This should only be necessary
2805 for cases where the dependency
2806 is not caught by a Scanner
2810 env.Depends('foo', 'other-input-file-for-foo')
2813 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2815 .RI env.Dictionary([ vars ])
2816 Returns a dictionary object
2817 containing copies of all of the
2818 construction variables in the environment.
2819 If there are any variable names specified,
2820 only the specified construction
2821 variables are returned in the dictionary.
2824 dict = env.Dictionary()
2825 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2828 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2830 .RI Dir( name ", [" directory ])
2832 .RI env.Dir( name ", [" directory ])
2833 This returns a Directory Node,
2834 an object that represents the specified directory
2837 can be a relative or absolute path.
2839 is an optional directory that will be used as the parent directory.
2842 is specified, the current script's directory is used as the parent.
2844 Directory Nodes can be used anywhere you
2845 would supply a string as a directory name
2846 to a Builder method or function.
2847 Directory Nodes have attributes and methods
2848 that are useful in many situations;
2849 see "File and Directory Nodes," below.
2851 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2853 .RI env.Dump([ key ])
2854 Returns a pretty printable representation of the environment.
2858 should be a string containing the name of the variable of interest.
2863 print env.Dump('CCCOM')
2867 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2877 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2880 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2885 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2887 .RI EnsurePythonVersion( major ", " minor )
2889 .RI env.EnsurePythonVersion( major ", " minor )
2890 Ensure that the Python version is at least
2893 print out an error message and exit SCons with a non-zero exit code if the
2894 actual Python version is not late enough.
2897 EnsurePythonVersion(2,2)
2900 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2902 .RI EnsureSConsVersion( major ", " minor )
2904 .RI env.EnsureSConsVersion( major ", " minor )
2905 Ensure that the SCons version is at least
2908 print out an error message and exit SCons with a non-zero exit code if the
2909 actual SCons version is not late enough.
2912 EnsureSConsVersion(0,9)
2915 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2917 .RI Environment([ key = value ", ...])"
2919 .RI env.Environment([ key = value ", ...])"
2920 Return a new construction environment
2921 initialized with the specified
2925 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2927 .RI Execute( action ", [" strfunction ", " varlist ])
2929 .RI env.Execute( action ", [" strfunction ", " varlist ])
2930 Executes an Action object.
2933 may be an Action object
2934 (see the section "Action Objects,"
2935 below, for a complete explanation of the arguments and behavior),
2936 or it may be a command-line string,
2938 or executable Python function,
2939 each of which will be converted
2940 into an Action object
2942 The exit value of the command
2943 or return value of the Python function
2946 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2950 .RI env.Exit([ value ])
2956 A default exit value of
2959 is used if no value is specified.
2961 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2965 .RI env.Export( vars )
2968 to export a list of variables from the current
2969 SConscript file to all other SConscript files.
2970 The exported variables are kept in a global collection,
2971 so subsequent calls to
2973 will over-write previous exports that have the same name.
2974 Multiple variable names can be passed to
2976 as separate arguments or as a list. A dictionary can be used to map
2977 variables to a different name when exported. Both local variables and
2978 global variables can be exported.
2983 # Make env available for all SConscript files to Import().
2987 # Make env and package available for all SConscript files:.
2988 Export("env", "package")
2990 # Make env and package available for all SConscript files:
2991 Export(["env", "package"])
2993 # Make env available using the name debug:.
2994 Export({"debug":env})
3000 function supports an
3002 argument that makes it easier to to export a variable or
3003 set of variables to a single SConscript file.
3004 See the description of the
3008 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3010 .RI File( name ", [" directory ])
3012 .RI env.File( name ", [" directory ])
3015 an object that represents the specified file
3018 can be a relative or absolute path.
3020 is an optional directory that will be used as the parent directory.
3022 File Nodes can be used anywhere you
3023 would supply a string as a file name
3024 to a Builder method or function.
3025 File Nodes have attributes and methods
3026 that are useful in many situations;
3027 see "File and Directory Nodes," below.
3029 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3031 .RI FindFile( file ", " dirs )
3033 .RI env.FindFile( file ", " dirs )
3036 in the path specified by
3039 may be a list of file names or a single file name. In addition to searching
3040 for files that exist in the filesytem, this function also searches for
3041 derived files that have not yet been built.
3044 foo = env.FindFile('foo', ['dir1', 'dir2'])
3047 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3049 .RI Flatten( sequence )
3051 .RI env.Flatten( sequence )
3052 Takes a sequence (that is, a Python list or tuple)
3053 that may contain nested sequences
3054 and returns a flattened list containing
3055 all of the individual elements in any sequence.
3056 This can be helpful for collecting
3057 the lists returned by calls to Builders;
3058 other Builders will automatically
3059 flatten lists specified as input,
3060 but direct Python manipulation of
3061 these lists does not:
3064 foo = Object('foo.c')
3065 bar = Object('bar.c')
3067 # Because `foo' and `bar' are lists returned by the Object() Builder,
3068 # `objects' will be a list containing nested lists:
3069 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3071 # Passing such a list to another Builder is all right because
3072 # the Builder will flatten the list automatically:
3073 Program(source = objects)
3075 # If you need to manipulate the list directly using Python, you need to
3076 # call Flatten() yourself, or otherwise handle nested lists:
3077 for object in Flatten(objects):
3081 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3083 .RI GetBuildPath( file ", [" ... ])
3085 .RI env.GetBuildPath( file ", [" ... ])
3088 path name (or names) for the specified
3096 Nodes or strings representing path names.
3098 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3102 .RI env.GetLaunchDir()
3103 Returns the absolute path name of the directory from which
3106 was initially invoked.
3107 This can be useful when using the
3112 options, which internally
3113 change to the directory in which the
3117 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3119 .RI GetOption( name )
3121 .RI env.GetOption( name )
3122 This function provides a way to query a select subset of the scons command line
3123 options from a SConscript file. See
3125 for a description of the options available.
3127 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3129 '\".RI GlobalBuilders( flag )
3133 '\"adds the names of the default builders
3134 '\"(Program, Library, etc.)
3135 '\"to the global name space
3136 '\"so they can be called without an explicit construction environment.
3137 '\"(This is the default.)
3141 '\"the names of the default builders are removed
3142 '\"from the global name space
3143 '\"so that an explicit construction environment is required
3144 '\"to call all builders.
3146 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3150 .RI env.Help( text )
3151 This specifies help text to be printed if the
3153 argument is given to
3157 is called multiple times, the text is appended together in the order
3162 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3164 .RI Ignore( target ", " dependency )
3166 .RI env.Ignore( target ", " dependency )
3167 The specified dependency file(s)
3168 will be ignored when deciding if
3169 the target file(s) need to be rebuilt.
3172 env.Ignore('foo', 'foo.c')
3173 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3176 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3180 .RI env.Import( vars )
3183 to import a list of variables into the current SConscript file. This
3184 will import variables that were exported with
3190 Variables exported by
3193 Multiple variable names can be passed to
3195 as separate arguments or as a list. The variable "*" can be used
3196 to import all variables.
3201 Import("env", "variable")
3202 Import(["env", "variable"])
3206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3208 .RI Install( dir ", " source )
3210 .RI env.Install( dir ", " source )
3211 Installs one or more files in a destination directory.
3212 The file names remain the same.
3215 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3218 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3220 .RI InstallAs( target ", " source )
3222 .RI env.InstallAs( target ", " source )
3223 Installs one or more files as specific file names,
3224 allowing changing a file name as part of the
3226 It is an error if the target and source
3227 list different numbers of files.
3230 env.InstallAs(target = '/usr/local/bin/foo',
3231 source = 'foo_debug')
3232 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3233 source = ['libFOO.a', 'libBAR.a'])
3236 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3238 .RI Literal( string )
3240 .RI env.Literal( string )
3243 will be preserved as-is
3244 and not have construction variables expanded.
3246 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3248 .RI Local( targets )
3250 .RI env.Local( targets )
3253 will have copies made in the local tree,
3254 even if an already up-to-date copy
3255 exists in a repository.
3256 Returns a list of the target Node or Nodes.
3258 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3260 .RI env.ParseConfig( command ", [" function ])
3263 to modify the environment as specified by the output of
3267 expects the output of a typical
3271 and parses the returned
3292 option gets added to both the
3299 option gets added to the
3302 Any other strings not associated with options
3303 are assumed to be the names of libraries
3306 construction variable.
3308 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3310 .RI ParseDepends( filename ", [" must_exist ])
3312 .RI env.ParseDepends( filename ", [" must_exist ])
3313 Parses the contents of the specified
3315 as a list of dependencies in the style of
3319 and explicitly establishes all of the listed dependencies.
3327 argument may be set to a non-zero
3330 throw an exception and
3331 generate an error if the file does not exist,
3332 or is otherwise inaccessible.
3335 and all of the files listed therein
3336 will be interpreted relative to
3337 the directory of the
3339 file which called the
3343 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3346 A factory function that
3347 returns a Builder object
3348 to be used to fetch source files
3349 from the Perforce source code management system.
3350 The returned Builder
3351 is intended to be passed to the
3356 env.SourceCode('.', env.Perforce())
3359 Perforce uses a number of external
3360 environment variables for its operation.
3361 Consequently, this function adds the
3362 following variables from the user's external environment
3363 to the construction environment's
3376 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3378 .RI Platform( string )
3379 Returns a callable object
3380 that can be used to initialize
3381 a construction environment using the
3382 platform keyword of the Environment() method:
3385 env = Environment(platform = Platform('win32'))
3388 .RI env.Platform( string )
3389 Applies the callable object for the specified platform
3391 to the environment through which the method was called.
3394 env.Platform('posix')
3401 variable from the user's external environment
3402 to the construction environment's
3405 This is so that any executed commands
3406 that use sockets to connect with other systems
3407 (such as fetching source files from
3408 external CVS repository specifications like
3409 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3410 will work on Win32 systems.
3412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3414 .RI Precious( target ", ...)"
3416 .RI env.Precious( target ", ...)"
3419 as precious so it is not deleted before it is rebuilt. Normally
3421 deletes a target before building it.
3422 Multiple targets can be passed in to a single call to
3425 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3427 .RI env.Prepend( key = val ", [...])"
3428 Appends the specified keyword arguments
3429 to the beginning of construction variables in the environment.
3430 If the Environment does not have
3431 the specified construction variable,
3432 it is simply added to the environment.
3433 If the values of the construction variable
3434 and the keyword argument are the same type,
3435 then the two values will be simply added together.
3436 Otherwise, the construction variable
3437 and the value of the keyword argument
3438 are both coerced to lists,
3439 and the lists are added together.
3440 (See also the Append method, above.)
3443 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3446 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3448 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3449 This appends new path elements to the given path in the
3450 specified external environment
3454 any particular path once (leaving the first one it encounters and
3455 ignoring the rest, to preserve path order),
3456 and to help assure this,
3457 will normalize all paths (using
3460 .BR os.path.normcase ).
3461 This can also handle the
3462 case where the given old path variable is a list instead of a
3463 string, in which case a list will be returned instead of a string.
3467 print 'before:',env['ENV']['INCLUDE']
3468 include_path = '/foo/bar:/foo'
3469 env.PrependENVPath('INCLUDE', include_path)
3470 print 'after:',env['ENV']['INCLUDE']
3474 after: /foo/bar:/foo:/biz
3477 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3479 .RI env.AppendUnique( key = val ", [...])"
3480 Appends the specified keyword arguments
3481 to the beginning of construction variables in the environment.
3482 If the Environment does not have
3483 the specified construction variable,
3484 it is simply added to the environment.
3485 If the construction variable being appended to is a list,
3486 then any value(s) that already exist in the
3487 construction variable will
3489 be added again to the list.
3492 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3495 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3498 A factory function that
3499 returns a Builder object
3500 to be used to fetch source files
3502 The returned Builder
3503 is intended to be passed to the
3508 env.SourceCode('.', env.RCS())
3513 will fetch source files
3514 from RCS subdirectories automatically,
3516 as demonstrated in the above example
3517 should only be necessary if
3518 you are fetching from
3521 directory as the source files,
3522 or if you need to explicitly specify RCS
3523 for a specific subdirectory.
3525 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3527 .RI env.Replace( key = val ", [...])"
3528 Replaces construction variables in the Environment
3529 with the specified keyword arguments.
3532 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3535 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3537 .RI Repository( directory )
3539 .RI env.Repository( directory )
3542 is a repository to be searched for files.
3546 and each one adds to the list of
3547 repositories that will be searched.
3551 a repository is a copy of the source tree,
3552 from the top-level directory on down,
3554 both source files and derived files
3555 that can be used to build targets in
3556 the local source tree.
3557 The canonical example would be an
3558 official source tree maintained by an integrator.
3559 If the repository contains derived files,
3560 then the derived files should have been built using
3562 so that the repository contains the necessary
3563 signature information to allow
3565 to figure out when it is appropriate to
3566 use the repository copy of a derived file,
3567 instead of building one locally.
3569 Note that if an up-to-date derived file
3570 already exists in a repository,
3574 make a copy in the local directory tree.
3575 In order to guarantee that a local copy
3581 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3586 what variable(s) to use as the return value(s) of the current SConscript
3587 file. These variables will be returned to the "calling" SConscript file
3588 as the return value(s) of
3590 Multiple variable names should be passed to
3596 Return(["foo", "bar"])
3599 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3601 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3603 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3604 Creates a Scanner object for
3607 See the section "Scanner Objects,"
3608 below, for a complete explanation of the arguments and behavior.
3610 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3613 A factory function that
3614 returns a Builder object
3615 to be used to fetch source files
3617 The returned Builder
3618 is intended to be passed to the
3623 env.SourceCode('.', env.SCCS())
3628 will fetch source files
3629 from SCCS subdirectories automatically,
3631 as demonstrated in the above example
3632 should only be necessary if
3633 you are fetching from
3636 directory as the source files,
3637 or if you need to explicitly specify SCCS
3638 for a specific subdirectory.
3640 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3642 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3644 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3646 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3648 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3652 one or more subsidiary SConscript (configuration) files.
3653 There are two ways to call the
3657 The first way you can call
3659 is to explicitly specify one or more
3661 as the first argument.
3662 A single script may be specified as a string;
3663 multiple scripts must be specified as a list
3664 (either explicitly or as created by
3668 The second way you can call
3670 is to specify a list of (sub)directory names
3677 execute a subsidiary configuration file named
3679 in each of the specified directories.
3680 You may specify a name other than
3682 by supplying an optional
3688 argument provides a list of variable names or a dictionary of
3689 named values to export to the
3691 These variables are locally exported only to the specified
3693 and do not affect the
3694 global pool of variables used by
3698 '\"If multiple dirs are provided,
3699 '\"each script gets a fresh export.
3704 function to import the variables.
3708 argument specifies that all of the target files
3709 (for example, object files and executables)
3710 that would normally be built in the subdirectory in which
3712 resides should actually
3716 is interpreted relative to the directory
3717 of the calling SConscript file.
3721 argument specifies that the
3722 source files from which
3723 the target files should be built
3727 is interpreted relative to the directory
3728 of the calling SConscript file.
3732 will link or copy (depending on the platform)
3733 all the source files into the build directory.
3734 This behavior may be disabled by
3735 setting the optional
3738 (it is set to 1 by default),
3741 will refer directly to
3742 the source files in their source directory
3743 when building target files.
3746 is usually safe, and always more efficient
3749 but it may cause build problems in certain end-cases,
3750 such as compiling from source files that
3751 are generated by the build.)
3753 Any variables returned by
3757 will be returned by the call to
3763 SConscript('subdir/SConscript')
3764 foo = SConscript('sub/SConscript', exports='env')
3765 SConscript('dir/SConscript', exports=['env', 'variable'])
3766 SConscript('src/SConscript', build_dir='build', duplicate=0)
3767 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3768 SConscript(dirs=['sub1', 'sub2'])
3769 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3772 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3774 .RI SConscriptChdir( value )
3776 .RI env.SConscriptChdir( value )
3779 changes its working directory
3780 to the directory in which each
3781 subsidiary SConscript file lives.
3782 This behavior may be disabled
3783 by specifying either:
3787 env.SConscriptChdir(0)
3792 will stay in the top-level directory
3793 while reading all SConscript files.
3794 (This may be necessary when building from repositories,
3795 when all the directories in which SConscript files may be found
3796 don't necessarily exist locally.)
3798 You may enable and disable
3799 this ability by calling
3806 SConscript('foo/SConscript') # will not chdir to foo
3807 env.SConscriptChdir(1)
3808 SConscript('bar/SConscript') # will chdir to bar
3811 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3813 .RI SConsignFile([ file , dbm_module ])
3815 .RI env.SConsignFile([ file , dbm_module ])
3818 to store all file signatures
3828 is not an absolute path name,
3829 the file is placed in the same directory as the top-level
3835 argument can be used to specify
3836 which Python database module
3837 The default is to use a custom
3839 module that uses pickled
3840 Python data structures,
3841 and which works on all Python versions from 1.5.2 on.
3846 # Stores signatures in ".sconsign.dbm"
3847 # in the top-level SConstruct directory.
3850 # Stores signatures in the file "etc/scons-signatures"
3851 # relative to the top-level SConstruct directory.
3852 SConsignFile("etc/scons-signatures")
3854 # Stores signatures in the specified absolute file name.
3855 SConsignFile("/home/me/SCons/signatures")
3858 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3860 .RI env.SetDefault(key = val ", [...])"
3861 Sets construction variables to default values specified with the keyword
3862 arguments if (and only if) the variables are not already set.
3863 The following statements are equivalent:
3866 env.SetDefault(FOO = 'foo')
3868 if not env.has_key('FOO'): env['FOO'] = 'foo'
3871 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3873 .RI SetOption( name ", " value )
3875 .RI env.SetOption( name ", " value )
3876 This function provides a way to set a select subset of the scons command
3877 line options from a SConscript file. The options supported are:
3879 which corresponds to -c, --clean, and --remove;
3882 corresponds to --duplicate;
3884 which corresponds to --implicit-cache;
3886 which corresponds to --max-drift;
3888 which corresponds to -j and --jobs.
3889 See the documentation for the
3890 corresponding command line object for information about each specific
3894 SetOption('max_drift', 1)
3897 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3899 .RI SideEffect( side_effect ", " target )
3901 .RI env.SideEffect( side_effect ", " target )
3904 as a side effect of building
3910 can be a list, a file name, or a node.
3911 A side effect is a target that is created
3912 as a side effect of building other targets.
3913 For example, a Windows PDB
3914 file is created as a side effect of building the .obj
3915 files for a static library.
3916 If a target is a side effect of multiple build commands,
3918 will ensure that only one set of commands
3919 is executed at a time.
3920 Consequently, you only need to use this method
3921 for side-effect targets that are built as a result of
3922 multiple build commands.
3924 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3926 .RI SourceCode( entries ", " builder )
3928 .RI env.SourceCode( entries ", " builder )
3929 Arrange for non-existent source files to
3930 be fetched from a source code management system
3935 may be a Node, string or list of both,
3936 and may represent either individual
3937 source files or directories in which
3938 source files can be found.
3940 For any non-existent source files,
3942 will search up the directory tree
3952 will not use a builder to fetch
3953 source files for the specified
3957 builder has been specified
3958 for a directory higher up the tree.
3962 fetch files from SCCS or RCS subdirectories
3963 without explicit configuration.
3964 This takes some extra processing time
3965 to search for the necessary
3966 source code management files on disk.
3967 You can avoid these extra searches
3968 and speed up your build a little
3969 by disabling these searches as follows:
3972 env.SourceCode('.', None)
3976 Note that if the specified
3978 is one you create by hand,
3979 it must have an associated
3980 construction environment to use
3981 when fetching a source file.
3984 provides a set of canned factory
3985 functions that return appropriate
3986 Builders for various popular
3987 source code management systems.
3988 Canonical examples of invocation include:
3991 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3992 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3993 env.SourceCode('/', env.RCS())
3994 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3995 env.SourceCode('no_source.c', None)
3997 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3999 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4001 '\".RI Subversion( repository ", " module )
4002 '\"A factory function that
4003 '\"returns a Builder object
4004 '\"to be used to fetch source files
4005 '\"from the specified Subversion
4007 '\"The returned Builder
4008 '\"is intended to be passed to the
4012 '\"The optional specified
4014 '\"will be added to the beginning
4015 '\"of all repository path names;
4016 '\"this can be used, in essence,
4017 '\"to strip initial directory names
4018 '\"from the repository path names,
4019 '\"so that you only have to
4020 '\"replicate part of the repository
4021 '\"directory hierarchy in your
4022 '\"local build directory:
4025 '\"# Will fetch foo/bar/src.c
4026 '\"# from /usr/local/Subversion/foo/bar/src.c.
4027 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4029 '\"# Will fetch bar/src.c
4030 '\"# from /usr/local/Subversion/foo/bar/src.c.
4031 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4033 '\"# Will fetch src.c
4034 '\"# from /usr/local/Subversion/foo/bar/src.c.
4035 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4038 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4040 .RI SourceSignatures( type )
4042 .RI env.SourceSignatures( type )
4043 This function tells SCons what type of signature to use for source files:
4047 If the environment method is used,
4048 the specified type of source signature
4049 is only used when deciding whether targets
4050 built with that environment are up-to-date or must be rebuilt.
4051 If the global function is used,
4052 the specified type of source signature becomes the default
4053 used for all decisions
4054 about whether targets are up-to-date.
4056 "MD5" means the signature of a source file
4057 is the MD5 checksum of its contents.
4058 "timestamp" means the signature of a source file
4059 is its timestamp (modification time).
4060 There is no different between the two behaviors
4064 "MD5" signatures take longer to compute,
4065 but are more accurate than "timestamp" signatures.
4066 The default is "MD5".
4068 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4072 .RI env.Split( arg )
4073 Returns a list of file names or other objects.
4075 it will be split on strings of white-space characters
4077 making it easier to write long lists of file names.
4078 If arg is already a list,
4079 the list will be returned untouched.
4080 If arg is any other type of object,
4081 it will be returned as a list
4082 containing just the object.
4085 files = Split("f1.c f2.c f3.c")
4086 files = env.Split("f4.c f5.c f6.c")
4094 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4096 .RI TargetSignatures( type )
4098 .RI env.TargetSignatures( type )
4099 This function tells SCons what type of signatures to use
4104 If the environment method is used,
4105 the specified type of signature is only used
4106 for targets built with that environment.
4107 If the global function is used,
4108 the specified type of signature becomes the default
4109 used for all target files that
4110 don't have an explicit target signature type
4111 specified for their environments.
4113 "build" means the signature of a target file
4114 is made by concatenating all of the
4115 signatures of all its source files.
4116 "content" means the signature of a target
4117 file is an MD5 checksum of its contents.
4118 "build" signatures are usually faster to compute,
4119 but "content" signatures can prevent unnecessary rebuilds
4120 when a target file is rebuilt to the exact same contents
4121 as the previous build.
4122 The default is "build".
4124 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4126 .RI Tool( string [, toolpath ", " **kw ])
4127 Returns a callable object
4128 that can be used to initialize
4129 a construction environment using the
4130 tools keyword of the Environment() method.
4131 The object may be called with a construction
4132 environment as an argument,
4133 in which case the object will
4134 add the necessary variables
4135 to the construction environment
4136 and the name of the tool will be added to the
4138 construction variable.
4140 Additional keyword arguments are passed to the tool's
4145 env = Environment(tools = [ Tool('msvc') ])
4149 t(env) # adds 'msvc' to the TOOLS variable
4150 u = Tool('opengl', toolpath = ['tools'])
4151 u(env) # adds 'opengl' to the TOOLS variable
4154 .RI env.Tool( string [, toolpath ", " **kw ])
4155 Applies the callable object for the specified tool
4157 to the environment through which the method was called.
4159 Additional keyword arguments are passed to the tool's
4165 env.Tool('opengl', toolpath = ['build/tools'])
4168 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4172 .RI env.Value( value )
4173 Returns a Node object representing the specified Python value. Value
4174 nodes can be used as dependencies of targets. If the result of
4177 changes between SCons runs, any targets depending on
4179 will be rebuilt. When using timestamp source signatures, Value nodes'
4180 timestamps are equal to the system time when the node is created.
4183 def create(target, source, env):
4184 f = open(str(target[0]), 'wb')
4185 f.write('prefix=' + source[0].get_contents())
4187 prefix = ARGUMENTS.get('prefix', '/usr/local')
4189 env['BUILDERS']['Config'] = Builder(action = create)
4190 env.Config(target = 'package-config', source = Value(prefix))
4193 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4195 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4197 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4199 Searches for the specified executable
4201 returning the full path name to the program
4203 and returning None if not.
4204 Searches the specified
4206 the value of the calling environment's PATH
4207 (env['ENV']['PATH']),
4208 or the user's current external PATH
4209 (os.environ['PATH'])
4211 On Win32 systems, searches for executable
4212 programs with any of the file extensions
4213 listed in the specified
4215 the calling environment's PATHEXT
4216 (env['ENV']['PATHEXT'])
4217 or the user's current PATHEXT
4218 (os.environ['PATHEXT'])
4226 .SS SConscript Variables
4227 In addition to the global functions and methods,
4229 supports a number of Python variables
4230 that can be used in SConscript files
4231 to affect how you want the build to be performed.
4233 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4238 arguments specified on the command line.
4239 Each element in the list is a tuple
4241 .RI ( keyword , value )
4247 elements of the tuple
4249 subscripting for element
4253 of the tuple, respectively.
4256 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4257 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4258 third_tuple = ARGLIST[2]
4259 print "third keyword, value =", third_tuple[0], third_tuple[1]
4260 for key, value in ARGLIST:
4261 # process key and value
4264 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4267 A dictionary of all the
4269 arguments specified on the command line.
4270 The dictionary is not in order,
4271 and if a given keyword has
4272 more than one value assigned to it
4273 on the command line,
4274 the last (right-most) value is
4280 if ARGUMENTS.get('debug', 0):
4281 env = Environment(CCFLAGS = '-g')
4286 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4289 A list of the targets which
4291 will actually try to build,
4292 regardless of whether they were specified on
4293 the command line or via the
4296 The elements of this list may be strings
4298 nodes, so you should run the list through the Python
4300 function to make sure any Node path names
4301 are converted to strings.
4303 Because this list may be taken from the
4304 list of targets specified using the
4307 the contents of the list may change
4308 on each successive call to
4313 for additional information.
4316 if 'foo' in BUILD_TARGETS:
4317 print "Don't forget to test the `foo' program!"
4318 if 'special/program' in BUILD_TARGETS:
4319 SConscript('special')
4324 list only contains targets expected listed
4325 on the command line or via calls to the
4330 contain all dependent targets that will be built as
4331 a result of making the sure the explicitly-specified
4332 targets are up to date.
4334 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4336 COMMAND_LINE_TARGETS
4337 A list of the targets explicitly specified on
4339 If there are no targets specified on the command line,
4341 This can be used, for example,
4342 to take specific actions only
4343 when a certain target or targets
4344 is explicitly being built:
4347 if 'foo' in COMMAND_LINE_TARGETS:
4348 print "Don't forget to test the `foo' program!"
4349 if 'special/program' in COMMAND_LINE_TARGETS:
4350 SConscript('special')
4353 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4356 A list of the target
4358 that have been specified using the
4361 The elements of the list are nodes,
4362 so you need to run them through the Python
4364 function to get at the path name for each Node.
4367 print str(DEFAULT_TARGETS[0])
4368 if 'foo' in map(str, DEFAULT_TARGETS):
4369 print "Don't forget to test the `foo' program!"
4374 list change on on each successive call to the
4379 print map(str, DEFAULT_TARGETS) # originally []
4381 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4383 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4385 print map(str, DEFAULT_TARGETS) # back to []
4388 Consequently, be sure to use
4390 only after you've made all of your
4393 or else simply be careful of the order
4394 of these statements in your SConscript files
4395 so that you don't look for a specific
4396 default target before it's actually been added to the list.
4398 .SS Construction Variables
4399 .\" XXX From Gary Ruben, 23 April 2002:
4400 .\" I think it would be good to have an example with each construction
4401 .\" variable description in the documentation.
4403 .\" CC The C compiler
4404 .\" Example: env["CC"] = "c68x"
4405 .\" Default: env["CC"] = "cc"
4407 .\" CCCOM The command line ...
4409 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4410 .\" env["CC"] = "c68x"
4411 .\" env["CFLAGS"] = "-ps -qq -mr"
4412 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4414 .\" (I dunno what this is ;-)
4415 A construction environment has an associated dictionary of
4416 .I construction variables
4417 that are used by built-in or user-supplied build rules.
4418 Construction variables must follow the same rules for
4420 the initial character must be an underscore or letter,
4421 followed by any number of underscores, letters, or digits.
4423 A number of useful construction variables are automatically defined by
4424 scons for each supported platform, and additional construction variables
4425 can be defined by the user. The following is a list of the automatically
4426 defined construction variables:
4429 The static library archiver.
4432 The command line used to generate a static library from object files.
4435 General options passed to the static library archiver.
4441 The command line used to generate an object file
4442 from an assembly-language source file.
4445 General options passed to the assembler.
4448 The command line used to assemble an assembly-language
4449 source file into an object file
4450 after first running the file through the C preprocessor.
4451 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4452 are included on this command line.
4455 The bibliography generator for the TeX formatter and typesetter and the
4456 LaTeX structured formatter and typesetter.
4459 The command line used to call the bibliography generator for the
4460 TeX formatter and typesetter and the LaTeX structured formatter and
4464 General options passed to the bibliography generator for the TeX formatter
4465 and typesetter and the LaTeX structured formatter and typesetter.
4468 The BitKeeper executable.
4471 The command line for
4472 fetching source files using BitKEeper.
4475 The command ($BITKEEPER) and subcommand
4476 for fetching source files using BitKeeper.
4478 .IP BITKEEPERGETFLAGS
4479 Options that are passed to the BitKeeper
4484 A dictionary mapping the names of the builders
4485 available through this environment
4486 to underlying Builder objects.
4488 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4489 are available by default.
4490 If you initialize this variable when an
4491 Environment is created:
4494 env = Environment(BUILDERS = {'NewBuilder' : foo})
4497 the default Builders will no longer be available.
4498 To use a new Builder object in addition to the default Builders,
4499 add your new Builder object like this:
4503 env.Append(BUILDERS = {'NewBuilder' : foo})
4510 env['BUILDERS]['NewBuilder'] = foo
4517 The command line used to compile a C source file to a (static) object file.
4518 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4519 are included on this command line.
4522 General options that are passed to the C compiler.
4525 The suffix for C source files.
4526 This is used by the internal CFile builder
4527 when generating C files from Lex (.l) or YACC (.y) input files.
4528 The default suffix, of course, is
4531 On case-insensitive systems (like Win32),
4538 The version number of the C compiler.
4539 This may or may not be set,
4540 depending on the specific C compiler being used.
4543 A function used to produce variables like $_CPPINCFLAGS. It takes
4545 arguments: a prefix to concatenate onto each element, a list of
4546 elements, a suffix to concatenate onto each element, an environment
4547 for variable interpolation, and an optional function that will be
4548 called to transform the list before concatenation.
4551 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4555 A platform independent specification of C preprocessor definitions.
4556 The definitions will be added to command lines
4557 through the automatically-generated
4558 $_CPPDEFFLAGS construction variable (see below),
4559 which is constructed according to
4560 the type of value of $CPPDEFINES:
4563 If $CPPDEFINES is a string,
4565 $CPPDEFPREFIX and $CPPDEFSUFFIX
4566 construction variables
4567 will be added to the beginning and end.
4570 # Will add -Dxyz to POSIX compiler command lines,
4571 # and /Dxyz to Microsoft Visual C++ command lines.
4572 env = Environment(CPPDEFINES='xyz')
4576 If $CPPDEFINES is a list,
4578 $CPPDEFPREFIX and $CPPDEFSUFFIX
4579 construction variables
4580 will be appended to the beginning and end
4581 of each element in the list.
4582 If any element is a list or tuple,
4583 then the first item is the name being
4584 defined and the second item is its value:
4587 # Will add -DB=2 -DA to POSIX compiler command lines,
4588 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4589 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4593 If $CPPDEFINES is a dictionary,
4595 $CPPDEFPREFIX and $CPPDEFSUFFIX
4596 construction variables
4597 will be appended to the beginning and end
4598 of each item from the dictionary.
4599 The key of each dictionary item
4600 is a name being defined
4601 to the dictionary item's corresponding value;
4604 then the name is defined without an explicit value.
4605 Note that the resulting flags are sorted by keyword
4606 to ensure that the order of the options on the
4607 command line is consistent each time
4612 # Will add -DA -DB=2 to POSIX compiler command lines,
4613 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4614 env = Environment(CPPDEFINES={'B':2, 'A':None})
4618 An automatically-generated construction variable
4619 containing the C preprocessor command-line options
4621 The value of $_CPPDEFFLAGS is created
4622 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4623 to the beginning and end
4624 of each directory in $CPPDEFINES.
4627 The prefix used to specify preprocessor definitions
4628 on the C compiler command line.
4629 This will be appended to the beginning of each definition
4630 in the $CPPDEFINES construction variable
4631 when the $_CPPDEFFLAGS variable is automatically generated.
4634 The suffix used to specify preprocessor definitions
4635 on the C compiler command line.
4636 This will be appended to the end of each definition
4637 in the $CPPDEFINES construction variable
4638 when the $_CPPDEFFLAGS variable is automatically generated.
4641 User-specified C preprocessor options.
4642 These will be included in any command that uses the C preprocessor,
4643 including not just compilation of C and C++ source files
4644 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4645 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4646 $F77PPCOM and $SHF77PPCOM command lines
4647 used to compile a Fortran source file,
4648 and the $ASPPCOM command line
4649 used to assemble an assembly language source file,
4650 after first running each file through the C preprocessor.
4651 Note that this variable does
4655 (or similar) include search path options
4656 that scons generates automatically from $CPPPATH.
4660 for the variable that expands to those options.
4663 An automatically-generated construction variable
4664 containing the C preprocessor command-line options
4665 for specifying directories to be searched for include files.
4666 The value of $_CPPINCFLAGS is created
4667 by appending $INCPREFIX and $INCSUFFIX
4668 to the beginning and end
4669 of each directory in $CPPPATH.
4672 The list of directories that the C preprocessor will search for include
4673 directories. The C/C++ implicit dependency scanner will search these
4674 directories for include files. Don't explicitly put include directory
4675 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4676 and the directories will not be searched by the dependency scanner. Note:
4677 directory names in CPPPATH will be looked-up relative to the SConscript
4678 directory when they are used in a command. To force
4680 to look-up a directory relative to the root of the source tree use #:
4683 env = Environment(CPPPATH='#/include')
4687 The directory look-up can also be forced using the
4692 include = Dir('include')
4693 env = Environment(CPPPATH=include)
4697 The directory list will be added to command lines
4698 through the automatically-generated
4700 construction variable,
4701 which is constructed by
4702 appending the values of the
4703 $INCPREFIX and $INCSUFFIX
4704 construction variables
4705 to the beginning and end
4706 of each directory in $CPPPATH.
4707 Any command lines you define that need
4708 the CPPPATH directory list should
4709 include $_CPPINCFLAGS:
4712 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4716 The list of suffixes of files that will be scanned
4717 for C preprocessor implicit dependencies
4719 The default list is:
4722 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4723 ".h", ".H", ".hxx", ".hpp", ".hh",
4724 ".F", ".fpp", ".FPP",
4725 ".S", ".spp", ".SPP"]
4732 Options that are passed to the CVS checkout subcommand.
4735 The command line used to
4736 fetch source files from a CVS repository.
4739 General options that are passed to CVS.
4740 By default, this is set to
4742 to specify from where the files must be fetched.
4745 The path to the CVS repository.
4746 This is referenced in the default
4753 The suffix for C++ source files.
4754 This is used by the internal CXXFile builder
4755 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4756 The default suffix is
4758 SCons also treats files with the suffixes
4765 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4772 The command line used to compile a C++ source file to an object file.
4773 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4774 are included on this command line.
4777 General options that are passed to the C++ compiler.
4780 The version number of the C++ compiler.
4781 This may or may not be set,
4782 depending on the specific C++ compiler being used.
4785 A function that converts a file name into a Dir instance relative to the
4789 The list of suffixes of files that will be scanned
4790 for imported D package files.
4791 The default list is:
4798 The TeX DVI file to PDF file converter.
4801 General options passed to the TeX DVI file to PDF file converter.
4804 The command line used to convert TeX DVI files into a PDF file.
4807 The TeX DVI file to PostScript converter.
4810 General options passed to the TeX DVI file to PostScript converter.
4813 A dictionary of environment variables
4814 to use when invoking commands. When ENV is used in a command all list
4815 values will be joined using the path separator and any other non-string
4816 values will simply be coerced to a string.
4817 Note that, by default,
4821 propagate the environment in force when you
4824 to the commands used to build target files.
4825 This is so that builds will be guaranteed
4826 repeatable regardless of the environment
4827 variables set at the time
4831 If you want to propagate your
4832 environment variables
4833 to the commands executed
4834 to build target files,
4835 you must do so explicitly:
4839 env = Environment(ENV = os.environ)
4843 Note that you can choose only to propagate
4844 certain environment variables.
4848 environment variable,
4851 uses the same utilities
4852 as the invoking shell (or other process):
4857 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4861 A function that will be called to escape shell special characters in
4862 command lines. The function should take one argument: the command line
4863 string to escape; and should return the escaped command line.
4866 The Fortran 77 compiler.
4867 You should normally set the $FORTRAN variable,
4868 which specifies the default Fortran compiler
4869 for all Fortran versions.
4870 You only need to set $F77 if you need to use a specific compiler
4871 or compiler version for Fortran 77 files.
4874 The command line used to compile a Fortran 77 source file to an object file.
4875 You only need to set $F77COM if you need to use a specific
4876 command line for Fortran 77 files.
4877 You should normally set the $FORTRANCOM variable,
4878 which specifies the default command line
4879 for all Fortran versions.
4882 General user-specified options that are passed to the Fortran 77 compiler.
4883 Note that this variable does
4887 (or similar) include search path options
4888 that scons generates automatically from $F77PATH.
4892 for the variable that expands to those options.
4893 You only need to set $F77FLAGS if you need to define specific
4894 user options for Fortran 77 files.
4895 You should normally set the $FORTRANFLAGS variable,
4896 which specifies the user-specified options
4897 passed to the default Fortran compiler
4898 for all Fortran versions.
4901 An automatically-generated construction variable
4902 containing the Fortran 77 compiler command-line options
4903 for specifying directories to be searched for include files.
4904 The value of $_F77INCFLAGS is created
4905 by appending $INCPREFIX and $INCSUFFIX
4906 to the beginning and end
4907 of each directory in $F77PATH.
4910 The list of directories that the Fortran 77 compiler will search for include
4911 directories. The implicit dependency scanner will search these
4912 directories for include files. Don't explicitly put include directory
4913 arguments in $F77FLAGS because the result will be non-portable
4914 and the directories will not be searched by the dependency scanner. Note:
4915 directory names in $F77PATH will be looked-up relative to the SConscript
4916 directory when they are used in a command. To force
4918 to look-up a directory relative to the root of the source tree use #:
4919 You only need to set $F77PATH if you need to define a specific
4920 include path for Fortran 77 files.
4921 You should normally set the $FORTRANPATH variable,
4922 which specifies the include path
4923 for the default Fortran compiler
4924 for all Fortran versions.
4927 env = Environment(F77PATH='#/include')
4931 The directory look-up can also be forced using the
4936 include = Dir('include')
4937 env = Environment(F77PATH=include)
4941 The directory list will be added to command lines
4942 through the automatically-generated
4944 construction variable,
4945 which is constructed by
4946 appending the values of the
4947 $INCPREFIX and $INCSUFFIX
4948 construction variables
4949 to the beginning and end
4950 of each directory in $F77PATH.
4951 Any command lines you define that need
4952 the F77PATH directory list should
4953 include $_F77INCFLAGS:
4956 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4960 The command line used to compile a Fortran 77 source file to an object file
4961 after first running the file through the C preprocessor.
4962 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4963 are included on this command line.
4964 You only need to set $F77PPCOM if you need to use a specific
4965 C-preprocessor command line for Fortran 77 files.
4966 You should normally set the $FORTRANPPCOM variable,
4967 which specifies the default C-preprocessor command line
4968 for all Fortran versions.
4971 The Fortran 90 compiler.
4972 You should normally set the $FORTRAN variable,
4973 which specifies the default Fortran compiler
4974 for all Fortran versions.
4975 You only need to set $F90 if you need to use a specific compiler
4976 or compiler version for Fortran 90 files.
4979 The command line used to compile a Fortran 90 source file to an object file.
4980 You only need to set $F90COM if you need to use a specific
4981 command line for Fortran 90 files.
4982 You should normally set the $FORTRANCOM variable,
4983 which specifies the default command line
4984 for all Fortran versions.
4987 General user-specified options that are passed to the Fortran 90 compiler.
4988 Note that this variable does
4992 (or similar) include search path options
4993 that scons generates automatically from $F90PATH.
4997 for the variable that expands to those options.
4998 You only need to set $F90FLAGS if you need to define specific
4999 user options for Fortran 90 files.
5000 You should normally set the $FORTRANFLAGS variable,
5001 which specifies the user-specified options
5002 passed to the default Fortran compiler
5003 for all Fortran versions.
5006 An automatically-generated construction variable
5007 containing the Fortran 90 compiler command-line options
5008 for specifying directories to be searched for include files.
5009 The value of $_F90INCFLAGS is created
5010 by appending $INCPREFIX and $INCSUFFIX
5011 to the beginning and end
5012 of each directory in $F90PATH.
5015 The list of directories that the Fortran 90 compiler will search for include
5016 directories. The implicit dependency scanner will search these
5017 directories for include files. Don't explicitly put include directory
5018 arguments in $F90FLAGS because the result will be non-portable
5019 and the directories will not be searched by the dependency scanner. Note:
5020 directory names in $F90PATH will be looked-up relative to the SConscript
5021 directory when they are used in a command. To force
5023 to look-up a directory relative to the root of the source tree use #:
5024 You only need to set $F90PATH if you need to define a specific
5025 include path for Fortran 90 files.
5026 You should normally set the $FORTRANPATH variable,
5027 which specifies the include path
5028 for the default Fortran compiler
5029 for all Fortran versions.
5032 env = Environment(F90PATH='#/include')
5036 The directory look-up can also be forced using the
5041 include = Dir('include')
5042 env = Environment(F90PATH=include)
5046 The directory list will be added to command lines
5047 through the automatically-generated
5049 construction variable,
5050 which is constructed by
5051 appending the values of the
5052 $INCPREFIX and $INCSUFFIX
5053 construction variables
5054 to the beginning and end
5055 of each directory in $F90PATH.
5056 Any command lines you define that need
5057 the F90PATH directory list should
5058 include $_F90INCFLAGS:
5061 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5065 The command line used to compile a Fortran 90 source file to an object file
5066 after first running the file through the C preprocessor.
5067 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5068 are included on this command line.
5069 You only need to set $F90PPCOM if you need to use a specific
5070 C-preprocessor command line for Fortran 90 files.
5071 You should normally set the $FORTRANPPCOM variable,
5072 which specifies the default C-preprocessor command line
5073 for all Fortran versions.
5076 The Fortran 95 compiler.
5077 You should normally set the $FORTRAN variable,
5078 which specifies the default Fortran compiler
5079 for all Fortran versions.
5080 You only need to set $F95 if you need to use a specific compiler
5081 or compiler version for Fortran 95 files.
5084 The command line used to compile a Fortran 95 source file to an object file.
5085 You only need to set $F95COM if you need to use a specific
5086 command line for Fortran 95 files.
5087 You should normally set the $FORTRANCOM variable,
5088 which specifies the default command line
5089 for all Fortran versions.
5092 General user-specified options that are passed to the Fortran 95 compiler.
5093 Note that this variable does
5097 (or similar) include search path options
5098 that scons generates automatically from $F95PATH.
5102 for the variable that expands to those options.
5103 You only need to set $F95FLAGS if you need to define specific
5104 user options for Fortran 95 files.
5105 You should normally set the $FORTRANFLAGS variable,
5106 which specifies the user-specified options
5107 passed to the default Fortran compiler
5108 for all Fortran versions.
5111 An automatically-generated construction variable
5112 containing the Fortran 95 compiler command-line options
5113 for specifying directories to be searched for include files.
5114 The value of $_F95INCFLAGS is created
5115 by appending $INCPREFIX and $INCSUFFIX
5116 to the beginning and end
5117 of each directory in $F95PATH.
5120 The list of directories that the Fortran 95 compiler will search for include
5121 directories. The implicit dependency scanner will search these
5122 directories for include files. Don't explicitly put include directory
5123 arguments in $F95FLAGS because the result will be non-portable
5124 and the directories will not be searched by the dependency scanner. Note:
5125 directory names in $F95PATH will be looked-up relative to the SConscript
5126 directory when they are used in a command. To force
5128 to look-up a directory relative to the root of the source tree use #:
5129 You only need to set $F95PATH if you need to define a specific
5130 include path for Fortran 95 files.
5131 You should normally set the $FORTRANPATH variable,
5132 which specifies the include path
5133 for the default Fortran compiler
5134 for all Fortran versions.
5137 env = Environment(F95PATH='#/include')
5141 The directory look-up can also be forced using the
5146 include = Dir('include')
5147 env = Environment(F95PATH=include)
5151 The directory list will be added to command lines
5152 through the automatically-generated
5154 construction variable,
5155 which is constructed by
5156 appending the values of the
5157 $INCPREFIX and $INCSUFFIX
5158 construction variables
5159 to the beginning and end
5160 of each directory in $F95PATH.
5161 Any command lines you define that need
5162 the F95PATH directory list should
5163 include $_F95INCFLAGS:
5166 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5170 The command line used to compile a Fortran 95 source file to an object file
5171 after first running the file through the C preprocessor.
5172 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5173 are included on this command line.
5174 You only need to set $F95PPCOM if you need to use a specific
5175 C-preprocessor command line for Fortran 95 files.
5176 You should normally set the $FORTRANPPCOM variable,
5177 which specifies the default C-preprocessor command line
5178 for all Fortran versions.
5181 The default Fortran compiler
5182 for all versions of Fortran.
5185 The command line used to compile a Fortran source file to an object file.
5186 By default, any options specified
5187 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5188 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5189 are included on this command line.
5192 General user-specified options that are passed to the Fortran compiler.
5193 Note that this variable does
5197 (or similar) include or module search path options
5198 that scons generates automatically from $FORTRANPATH.
5200 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5202 for the variables that expand those options.
5204 .IP _FORTRANINCFLAGS
5205 An automatically-generated construction variable
5206 containing the Fortran compiler command-line options
5207 for specifying directories to be searched for include
5208 files and module files.
5209 The value of $_FORTRANINCFLAGS is created
5210 by prepending/appending $INCPREFIX and $INCSUFFIX
5211 to the beginning and end
5212 of each directory in $FORTRANPATH.
5215 Directory location where the Fortran compiler should place
5216 any module files it generates. This variable is empty, by default. Some
5217 Fortran compilers will internally append this directory in the search path
5218 for module files, as well
5220 .IP FORTRANMODDIRPREFIX
5221 The prefix used to specify a module directory on the Fortran compiler command
5223 This will be appended to the beginning of the directory
5224 in the $FORTRANMODDIR construction variables
5225 when the $_FORTRANMODFLAG variables is automatically generated.
5227 .IP FORTRANMODDIRSUFFIX
5228 The suffix used to specify a module directory on the Fortran compiler command
5230 This will be appended to the beginning of the directory
5231 in the $FORTRANMODDIR construction variables
5232 when the $_FORTRANMODFLAG variables is automatically generated.
5235 An automatically-generated construction variable
5236 containing the Fortran compiler command-line option
5237 for specifying the directory location where the Fortran
5238 compiler should place any module files that happen to get
5239 generated during compilation.
5240 The value of $_FORTRANMODFLAG is created
5241 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5242 to the beginning and end of the directory in $FORTRANMODDIR.
5244 .IP FORTRANMODPREFIX
5245 The module file prefix used by the Fortran compiler. SCons assumes that
5246 the Fortran compiler follows the quasi-standard naming convention for
5248 .I <module_name>.mod.
5249 As a result, this variable is left empty, by default. For situations in
5250 which the compiler does not necessarily follow the normal convention,
5251 the user may use this variable. Its value will be appended to every
5252 module file name as scons attempts to resolve dependencies.
5254 .IP FORTRANMODSUFFIX
5255 The module file suffix used by the Fortran compiler. SCons assumes that
5256 the Fortran compiler follows the quasi-standard naming convention for
5258 .I <module_name>.mod.
5259 As a result, this variable is set to ".mod", by default. For situations
5260 in which the compiler does not necessarily follow the normal convention,
5261 the user may use this variable. Its value will be appended to every
5262 module file name as scons attempts to resolve dependencies.
5265 The list of directories that the Fortran compiler will search for
5266 include files and (for some compilers) module files. The Fortran implicit
5267 dependency scanner will search these directories for include files (but
5268 not module files since they are autogenerated and, as such, may not
5269 actually exist at the time the scan takes place). Don't explicitly put
5270 include directory arguments in FORTRANFLAGS because the result will be
5271 non-portable and the directories will not be searched by the dependency
5272 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5273 to the SConscript directory when they are used in a command. To force
5275 to look-up a directory relative to the root of the source tree use #:
5278 env = Environment(FORTRANPATH='#/include')
5282 The directory look-up can also be forced using the
5287 include = Dir('include')
5288 env = Environment(FORTRANPATH=include)
5292 The directory list will be added to command lines
5293 through the automatically-generated
5295 construction variable,
5296 which is constructed by
5297 appending the values of the
5298 $INCPREFIX and $INCSUFFIX
5299 construction variables
5300 to the beginning and end
5301 of each directory in $FORTRANPATH.
5302 Any command lines you define that need
5303 the FORTRANPATH directory list should
5304 include $_FORTRANINCFLAGS:
5307 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5311 The command line used to compile a Fortran source file to an object file
5312 after first running the file through the C preprocessor.
5313 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5314 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5315 construction variables are included on this command line.
5318 The list of suffixes of files that will be scanned
5319 for Fortran implicit dependencies
5320 (INCLUDE lines & USE statements).
5321 The default list is:
5324 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5325 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5329 A function that converts a file name into a File instance relative to the
5333 The Ghostscript program used to convert PostScript to PDF files.
5336 General options passed to the Ghostscript program
5337 when converting PostScript to PDF files.
5340 The Ghostscript command line used to convert PostScript to PDF files.
5343 The list of suffixes of files that will be scanned
5344 for IDL implicit dependencies
5345 (#include or import lines).
5346 The default list is:
5353 The prefix used to specify an include directory on the C compiler command
5355 This will be appended to the beginning of each directory
5356 in the $CPPPATH and $FORTRANPATH construction variables
5357 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5358 variables are automatically generated.
5361 The suffix used to specify an include directory on the C compiler command
5363 This will be appended to the end of each directory
5364 in the $CPPPATH and $FORTRANPATH construction variables
5365 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5366 variables are automatically generated.
5369 A function to be called to install a file into a
5370 destination file name.
5371 The default function copies the file into the destination
5372 (and sets the destination file's mode and permission bits
5373 to match the source file's).
5374 The function takes the following arguments:
5377 def install(dest, source, env):
5381 is the path name of the destination file.
5383 is the path name of the source file.
5385 is the construction environment
5386 (a dictionary of construction values)
5387 in force for this file installation.
5390 The Java archive tool.
5393 The directory to which the Java archive tool should change
5399 The command line used to call the Java archive tool.
5402 General options passed to the Java archive tool.
5403 By default this is set to
5405 to create the necessary
5410 The suffix for Java archives:
5418 The command line used to compile a directory tree containing
5419 Java source files to
5420 corresponding Java class files.
5421 Any options specified in the $JAVACFLAGS construction variable
5422 are included on this command line.
5425 General options that are passed to the Java compiler.
5428 The directory in which Java class files may be found.
5429 This is stripped from the beginning of any Java .class
5430 file names supplied to the
5435 The suffix for Java class files;
5440 The Java generator for C header and stub files.
5443 The command line used to generate C header and stub files
5445 Any options specified in the $JAVAHFLAGS construction variable
5446 are included on this command line.
5449 General options passed to the C header and stub file generator
5453 The suffix for Java files;
5458 The LaTeX structured formatter and typesetter.
5461 The command line used to call the LaTeX structured formatter and typesetter.
5464 General options passed to the LaTeX structured formatter and typesetter.
5467 The lexical analyzer generator.
5470 General options passed to the lexical analyzer generator.
5473 The command line used to call the lexical analyzer generator
5474 to generate a source file.
5477 An automatically-generated construction variable
5478 containing the linker command-line options
5479 for specifying directories to be searched for library.
5480 The value of $_LIBDIRFLAGS is created
5481 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5482 to the beginning and end
5483 of each directory in $LIBPATH.
5486 The prefix used to specify a library directory on the linker command line.
5487 This will be appended to the beginning of each directory
5488 in the $LIBPATH construction variable
5489 when the $_LIBDIRFLAGS variable is automatically generated.
5492 The suffix used to specify a library directory on the linker command line.
5493 This will be appended to the end of each directory
5494 in the $LIBPATH construction variable
5495 when the $_LIBDIRFLAGS variable is automatically generated.
5498 An automatically-generated construction variable
5499 containing the linker command-line options
5500 for specifying libraries to be linked with the resulting target.
5501 The value of $_LIBFLAGS is created
5502 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5503 to the beginning and end
5504 of each directory in $LIBS.
5507 The prefix used to specify a library to link on the linker command line.
5508 This will be appended to the beginning of each library
5509 in the $LIBS construction variable
5510 when the $_LIBFLAGS variable is automatically generated.
5513 The suffix used to specify a library to link on the linker command line.
5514 This will be appended to the end of each library
5515 in the $LIBS construction variable
5516 when the $_LIBFLAGS variable is automatically generated.
5519 The list of directories that will be searched for libraries.
5520 The implicit dependency scanner will search these
5521 directories for include files. Don't explicitly put include directory
5522 arguments in $LINKFLAGS or $SHLINKFLAGS
5523 because the result will be non-portable
5524 and the directories will not be searched by the dependency scanner. Note:
5525 directory names in LIBPATH will be looked-up relative to the SConscript
5526 directory when they are used in a command. To force
5528 to look-up a directory relative to the root of the source tree use #:
5531 env = Environment(LIBPATH='#/libs')
5535 The directory look-up can also be forced using the
5541 env = Environment(LIBPATH=libs)
5545 The directory list will be added to command lines
5546 through the automatically-generated
5548 construction variable,
5549 which is constructed by
5550 appending the values of the
5551 $LIBDIRPREFIX and $LIBDIRSUFFIX
5552 construction variables
5553 to the beginning and end
5554 of each directory in $LIBPATH.
5555 Any command lines you define that need
5556 the LIBPATH directory list should
5557 include $_LIBDIRFLAGS:
5560 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5564 The prefix used for (static) library file names.
5565 A default value is set for each platform
5566 (posix, win32, os2, etc.),
5567 but the value is overridden by individual tools
5568 (ar, mslib, sgiar, sunar, tlib, etc.)
5569 to reflect the names of the libraries they create.
5572 An array of legal prefixes for library file names.
5575 A list of one or more libraries
5576 that will be linked with
5577 any executable programs
5578 created by this environment.
5581 The library list will be added to command lines
5582 through the automatically-generated
5584 construction variable,
5585 which is constructed by
5586 appending the values of the
5587 $LIBLINKPREFIX and $LIBLINKSUFFIX
5588 construction variables
5589 to the beginning and end
5590 of each directory in $LIBS.
5591 Any command lines you define that need
5592 the LIBS library list should
5596 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5600 The suffix used for (static) library file names.
5601 A default value is set for each platform
5602 (posix, win32, os2, etc.),
5603 but the value is overridden by individual tools
5604 (ar, mslib, sgiar, sunar, tlib, etc.)
5605 to reflect the names of the libraries they create.
5608 An array of legal suffixes for library file names.
5614 General user options passed to the linker.
5615 Note that this variable should
5619 (or similar) options for linking with the libraries listed in $LIBS,
5622 (or similar) library search path options
5623 that scons generates automatically from $LIBPATH.
5627 for the variable that expands to library-link options,
5631 for the variable that expands to library search path options.
5634 The command line used to link object files into an executable.
5637 The M4 macro preprocessor.
5640 General options passed to the M4 macro preprocessor.
5643 The command line used to pass files through the macro preprocessor.
5646 The maximum number of characters allowed on an external command line.
5648 link lines longer than this many characters
5649 are linke via a temporary file name.
5652 When the Microsoft Visual Studio tools are initialized, they set up
5653 this dictionary with the following keys:
5656 the version of MSVS being used (can be set via
5660 the available versions of MSVS installed
5663 installed directory of Visual C++
5666 installed directory of Visual Studio
5669 installed directory of the .NET framework
5671 .B FRAMEWORKVERSIONS:
5672 list of installed versions of the .NET framework, sorted latest to oldest.
5674 .B FRAMEWORKVERSION:
5675 latest installed version of the .NET framework
5678 installed location of the .NET SDK.
5681 installed location of the Platform SDK.
5683 .B PLATFORMSDK_MODULES:
5684 dictionary of installed Platform SDK modules,
5685 where the dictionary keys are keywords for the various modules, and
5686 the values are 2-tuples where the first is the release date, and the
5687 second is the version number.
5689 If a value isn't set, it wasn't available in the registry.
5691 .IP MSVS_IGNORE_IDE_PATHS
5692 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5693 instead of the settings from the IDE.
5695 For Visual Studio, SCons will (by default) automatically determine
5696 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5697 set by the IDE. You can override this behavior by setting these
5698 variables after Environment initialization, or by setting
5699 .B MSVS_IGNORE_IDE_PATHS = 1
5700 in the Environment initialization.
5701 Specifying this will not leave these unset, but will set them to a
5702 minimal set of paths needed to run the tools successfully.
5705 For VS6, the mininimal set is:
5706 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5707 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5708 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5710 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5711 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5712 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5716 Where '<VSDir>' is the installed location of Visual Studio.
5718 .IP MSVS_USE_MFC_DIRS
5719 Tells the MS Visual Studio tool(s) to use
5720 the MFC directories in its default paths
5721 for compiling and linking.
5722 Under MSVS version 6,
5724 .B MSVS_USE_MFC_DIRS
5733 external environment variable,
5739 external environment variable.
5740 Under MSVS version 7,
5742 .B MSVS_USE_MFC_DIRS
5745 .B "atlmfc\\\\include"
5746 directory to the default
5748 external environment variable,
5751 directory to the default
5753 external environment variable.
5754 The current default value is
5756 which means these directories
5757 are added to the paths by default.
5758 This default value is likely to change
5759 in a future release,
5760 so users who want the ATL and MFC
5761 values included in their paths
5762 are encouraged to enable the
5763 .B MSVS_USE_MFC_DIRS
5765 to avoid future incompatibility.
5766 This variable has no effect if the
5770 environment variables are set explictly.
5773 Sets the preferred version of MSVS to use.
5775 SCons will (by default) select the latest version of MSVS
5776 installed on your machine. So, if you have version 6 and version 7
5777 (MSVS .NET) installed, it will prefer version 7. You can override this by
5780 variable in the Environment initialization, setting it to the
5781 appropriate version ('6.0' or '7.0', for example).
5782 If the given version isn't installed, tool initialization will fail.
5785 The action used to generate Microsoft Visual Studio
5786 project and solution files.
5788 .IP MSVSPROJECTSUFFIX
5789 The suffix used for Microsoft Visual Studio project (DSP) files.
5790 The default value is
5792 when using Visual Studio version 7.x (.NET),
5795 when using earlier versions of Visual Studio.
5797 .IP MSVSSOLUTIONSUFFIX
5798 The suffix used for Microsoft Visual Studio solution (DSW) files.
5799 The default value is
5801 when using Visual Studio version 7.x (.NET),
5804 when using earlier versions of Visual Studio.
5807 When set to non-zero,
5808 suppresses creation of a corresponding Win32 static import lib by the
5810 builder when used with
5811 MinGW or Microsoft Visual Studio.
5812 This also suppresses creation
5813 of an export (.exp) file
5814 when using Microsoft Visual Studio.
5817 The prefix used for (static) object file names.
5820 The suffix used for (static) object file names.
5823 The Perforce executable.
5826 The command line used to
5827 fetch source files from Perforce.
5830 General options that are passed to Perforce.
5833 The Microsoft Visual C++ precompiled header that will be used when compiling
5834 object files. This variable is ignored by tools other than Microsoft Visual C++.
5835 When this variable is
5836 defined SCons will add options to the compiler command line to
5837 cause it to use the precompiled header, and will also set up the
5838 dependencies for the PCH file. Example:
5841 env['PCH'] = 'StdAfx.pch'
5845 This variable specifies how much of a source file is precompiled. This
5846 variable is ignored by tools other than Microsoft Visual C++, or when
5847 the PCH variable is not being used. When this variable is define it
5848 must be a string that is the name of the header that
5849 is included at the end of the precompiled portion of the source files, or
5850 the empty string if the "#pragma hrdstop" construct is being used:
5853 env['PCHSTOP'] = 'StdAfx.h'
5857 The Microsoft Visual C++ PDB file that will store debugging information for
5858 object files, shared libraries, and programs. This variable is ignored by
5859 tools other than Microsoft Visual C++.
5860 When this variable is
5861 defined SCons will add options to the compiler and linker command line to
5862 cause them to generate external debugging information, and will also set up the
5863 dependencies for the PDB file. Example:
5866 env['PDB'] = 'hello.pdb'
5870 A deprecated synonym for $DVIPDFCOM.
5873 The prefix used for PDF file names.
5876 The suffix used for PDF file names.
5879 The name of the platform used to create the Environment. If no platform is
5880 specified when the Environment is created,
5882 autodetects the platform.
5885 env = Environment(tools = [])
5886 if env['PLATFORM'] == 'cygwin':
5892 .IP PRINT_CMD_LINE_FUNC
5893 A Python function used to print the command lines as they are executed
5894 (assuming command printing is not disabled by the
5898 options or their equivalents).
5899 The function should take four arguments:
5901 the command being executed (a string),
5903 the target being built (file node, list, or string name(s)),
5905 the source(s) used (file node, list, or string name(s)), and
5907 the environment being used.
5909 The function must do the printing itself. The default implementation,
5910 used if this variable is not set or is None, is:
5912 def print_cmd_line(s, target, source, env):
5913 sys.stdout.write(s + "\n")
5916 Here's an example of a more interesting function:
5918 def print_cmd_line(s, target, source, env):
5919 sys.stdout.write("Building %s -> %s...\n" %
5920 (' and '.join([str(x) for x in source]),
5921 ' and '.join([str(x) for x in target])))
5922 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
5923 env.Program('foo', 'foo.c')
5926 This just prints "Building <targetname> from <sourcename>..." instead
5927 of the actual commands.
5928 Such a function could also log the actual commands to a log file,
5932 The prefix used for executable file names.
5935 The suffix used for executable file names.
5938 The command line used to convert TeX DVI files into a PostScript file.
5941 The prefix used for PostScript file names.
5944 The prefix used for PostScript file names.
5947 The qt tool tries to take this from os.environ.
5948 It also initializes all QT_*
5949 construction variables listed below.
5950 (Note that all paths are constructed
5951 with python's os.path.join() method,
5952 but are listed here with the '/' separator
5953 for easier reading.)
5954 In addition, the construction environment
5955 variables CPPPATH, LIBPATH and LIBS may be modified
5957 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5958 are modified. Because the build-performance is affected when using this tool,
5959 you have to explicitly specify it at Environment creation:
5962 Environment(tools=['default','qt'])
5965 The qt tool supports the following operations:
5967 .B Automatic moc file generation from header files.
5968 You do not have to specify moc files explicitly, the tool does it for you.
5969 However, there are a few preconditions to do so: Your header file must have
5970 the same filebase as your implementation file and must stay in the same
5971 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
5972 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
5973 See also the corresponding builder method
5976 .B Automatic moc file generation from cxx files.
5977 As stated in the qt documentation, include the moc file at the end of
5978 the cxx file. Note that you have to include the file, which is generated
5979 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
5980 <basename>.moc. A warning is generated after building the moc file, if you
5981 do not include the correct file. If you are using BuildDir, you may
5982 need to specify duplicate=1. You can turn off automatic moc file generation
5983 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
5986 .B Automatic handling of .ui files.
5987 The implementation files generated from .ui files are handled much the same
5988 as yacc or lex files. Each .ui file given as a source of Program, Library or
5989 SharedLibrary will generate three files, the declaration file, the
5990 implementation file and a moc file. Because there are also generated headers,
5991 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
5995 Turn off scanning for mocable files. Use the Moc Builder to explicitely
5996 specify files to run moc on.
5999 The path where the qt binaries are installed.
6000 The default value is '$QTDIR/bin'.
6003 The path where the qt header files are installed.
6004 The default value is '$QTDIR/include'.
6005 Note: If you set this variable to None, the tool won't change the CPPPATH
6006 construction variable.
6009 Prints lots of debugging information while scanning for moc files.
6012 The path where the qt libraries are installed.
6013 The default value is '$QTDIR/lib'.
6014 Note: If you set this variable to None, the tool won't change the LIBPATH
6015 construction variable.
6018 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6019 this variable to None, the tool won't change the LIBS variable.
6022 Default value is '$QT_BINPATH/moc'.
6025 Default value is ''. Prefix for moc output files, when source is a cxx file.
6028 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6031 .IP QT_MOCFROMCPPFLAGS
6032 Default value is '-i'. These flags are passed to moc, when moccing a
6035 .IP QT_MOCFROMCXXCOM
6036 Command to generate a moc file from a cpp file.
6039 Command to generate a moc file from a header.
6041 .IP QT_MOCFROMHFLAGS
6042 Default value is ''. These flags are passed to moc, when moccing a header
6046 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6049 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6053 Default value is '$QT_BINPATH/uic'.
6056 Command to generate header files from .ui files.
6059 Default value is ''. These flags are passed to uic, when creating a a h
6060 file from a .ui file.
6062 .IP QT_UICDECLPREFIX
6063 Default value is ''. Prefix for uic generated header files.
6065 .IP QT_UICDECLSUFFIX
6066 Default value is '.h'. Suffix for uic generated header files.
6069 Command to generate cxx files from .ui files.
6072 Default value is ''. These flags are passed to uic, when creating a cxx
6073 file from a .ui file.
6075 .IP QT_UICIMPLPREFIX
6076 Default value is 'uic_'. Prefix for uic generated implementation files.
6078 .IP QT_UICIMPLSUFFIX
6079 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6083 Default value is '.ui'. Suffix of designer input files.
6086 The archive indexer.
6089 General options passed to the archive indexer.
6092 The resource compiler used by the RES builder.
6095 The command line used by the RES builder.
6098 The flags passed to the resource compiler by the RES builder.
6102 Note that this variable is not actually used
6103 for the command to fetch source files from RCS;
6106 construction variable, below.
6109 The RCS "checkout" executable,
6110 used to fetch source files from RCS.
6113 The command line used to
6114 fetch (checkout) source files from RCS.
6117 Options that are passed to the $RCS_CO command.
6120 A function that converts a file name into a list of Dir instances by
6121 searching the repositories.
6124 The Java RMI stub compiler.
6127 The command line used to compile stub
6128 and skeleton class files
6129 from Java classes that contain RMI implementations.
6130 Any options specified in the $RMICFLAGS construction variable
6131 are included on this command line.
6134 General options passed to the Java RMI stub compiler.
6137 The RPC protocol compiler.
6139 .IP RPCGENCLIENTFLAGS
6140 Options passed to the RPC protocol compiler
6141 when generating client side stubs.
6142 These are in addition to any flags specified in the
6144 construction variable.
6147 General options passed to the RPC protocol compiler.
6149 .IP RPCGENHEADERFLAGS
6150 Options passed to the RPC protocol compiler
6151 when generating a header file.
6152 These are in addition to any flags specified in the
6154 construction variable.
6156 .IP RPCGENSERVICEFLAGS
6157 Options passed to the RPC protocol compiler
6158 when generating server side stubs.
6159 These are in addition to any flags specified in the
6161 construction variable.
6164 Options passed to the RPC protocol compiler
6165 when generating XDR routines.
6166 These are in addition to any flags specified in the
6168 construction variable.
6171 A list of paths to search for shared libraries when running programs.
6172 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6173 Ignored on platforms and toolchains that don't support it.
6174 Note that the paths added to RPATH
6175 are not transformed by
6177 in any way: if you want an absolute
6178 path, you must make it absolute yourself.
6181 A list of the available implicit dependency scanners.
6182 New file scanners may be added by
6183 appending to this list,
6184 although the more flexible approach
6185 is to associate scanners
6186 with a specific Builder.
6187 See the sections "Builder Objects"
6188 and "Scanner Objects,"
6189 below, for more information.
6192 The SCCS executable.
6195 The command line used to
6196 fetch source files from SCCS.
6199 General options that are passed to SCCS.
6202 Options that are passed specifically to the SCCS "get" subcommand.
6203 This can be set, for example, to
6205 to check out editable files from SCCS.
6208 The C compiler used for generating shared-library objects.
6211 The command line used to compile a C source file
6212 to a shared-library object file.
6213 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6214 are included on this command line.
6217 Options that are passed to the C compiler
6218 to generate shared-library objects.
6221 The C++ compiler used for generating shared-library objects.
6224 The command line used to compile a C++ source file
6225 to a shared-library object file.
6226 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6227 are included on this command line.
6230 Options that are passed to the C++ compiler
6231 to generate shared-library objects.
6234 A string naming the shell program that will be passed to the
6239 construction variable for more information.
6242 The Fortran 77 compiler used for generating shared-library objects.
6243 You should normally set the $SHFORTRANC variable,
6244 which specifies the default Fortran compiler
6245 for all Fortran versions.
6246 You only need to set $SHF77 if you need to use a specific compiler
6247 or compiler version for Fortran 77 files.
6250 The command line used to compile a Fortran 77 source file
6251 to a shared-library object file.
6252 You only need to set $SHF77COM if you need to use a specific
6253 command line for Fortran 77 files.
6254 You should normally set the $SHFORTRANCOM variable,
6255 which specifies the default command line
6256 for all Fortran versions.
6259 Options that are passed to the Fortran 77 compiler
6260 to generated shared-library objects.
6261 You only need to set $SHF77FLAGS if you need to define specific
6262 user options for Fortran 77 files.
6263 You should normally set the $SHFORTRANFLAGS variable,
6264 which specifies the user-specified options
6265 passed to the default Fortran compiler
6266 for all Fortran versions.
6269 The command line used to compile a Fortran 77 source file to a
6270 shared-library object file
6271 after first running the file through the C preprocessor.
6272 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6273 are included on this command line.
6274 You only need to set $SHF77PPCOM if you need to use a specific
6275 C-preprocessor command line for Fortran 77 files.
6276 You should normally set the $SHFORTRANPPCOM variable,
6277 which specifies the default C-preprocessor command line
6278 for all Fortran versions.
6281 The Fortran 90 compiler used for generating shared-library objects.
6282 You should normally set the $SHFORTRANC variable,
6283 which specifies the default Fortran compiler
6284 for all Fortran versions.
6285 You only need to set $SHF90 if you need to use a specific compiler
6286 or compiler version for Fortran 90 files.
6289 The command line used to compile a Fortran 90 source file
6290 to a shared-library object file.
6291 You only need to set $SHF90COM if you need to use a specific
6292 command line for Fortran 90 files.
6293 You should normally set the $SHFORTRANCOM variable,
6294 which specifies the default command line
6295 for all Fortran versions.
6298 Options that are passed to the Fortran 90 compiler
6299 to generated shared-library objects.
6300 You only need to set $SHF90FLAGS if you need to define specific
6301 user options for Fortran 90 files.
6302 You should normally set the $SHFORTRANFLAGS variable,
6303 which specifies the user-specified options
6304 passed to the default Fortran compiler
6305 for all Fortran versions.
6308 The command line used to compile a Fortran 90 source file to a
6309 shared-library object file
6310 after first running the file through the C preprocessor.
6311 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6312 are included on this command line.
6313 You only need to set $SHF90PPCOM if you need to use a specific
6314 C-preprocessor command line for Fortran 90 files.
6315 You should normally set the $SHFORTRANPPCOM variable,
6316 which specifies the default C-preprocessor command line
6317 for all Fortran versions.
6320 The Fortran 95 compiler used for generating shared-library objects.
6321 You should normally set the $SHFORTRANC variable,
6322 which specifies the default Fortran compiler
6323 for all Fortran versions.
6324 You only need to set $SHF95 if you need to use a specific compiler
6325 or compiler version for Fortran 95 files.
6328 The command line used to compile a Fortran 95 source file
6329 to a shared-library object file.
6330 You only need to set $SHF95COM if you need to use a specific
6331 command line for Fortran 95 files.
6332 You should normally set the $SHFORTRANCOM variable,
6333 which specifies the default command line
6334 for all Fortran versions.
6337 Options that are passed to the Fortran 95 compiler
6338 to generated shared-library objects.
6339 You only need to set $SHF95FLAGS if you need to define specific
6340 user options for Fortran 95 files.
6341 You should normally set the $SHFORTRANFLAGS variable,
6342 which specifies the user-specified options
6343 passed to the default Fortran compiler
6344 for all Fortran versions.
6347 The command line used to compile a Fortran 95 source file to a
6348 shared-library object file
6349 after first running the file through the C preprocessor.
6350 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6351 are included on this command line.
6352 You only need to set $SHF95PPCOM if you need to use a specific
6353 C-preprocessor command line for Fortran 95 files.
6354 You should normally set the $SHFORTRANPPCOM variable,
6355 which specifies the default C-preprocessor command line
6356 for all Fortran versions.
6359 The default Fortran compiler used for generating shared-library objects.
6362 The command line used to compile a Fortran source file
6363 to a shared-library object file.
6366 Options that are passed to the Fortran compiler
6367 to generate shared-library objects.
6370 The command line used to compile a Fortran source file to a
6371 shared-library object file
6372 after first running the file through the C preprocessor.
6373 Any options specified
6374 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6375 are included on this command line.
6378 The prefix used for shared library file names.
6381 The suffix used for shared library file names.
6384 The linker for programs that use shared libraries.
6387 General user options passed to the linker for programs using shared libraries.
6388 Note that this variable should
6392 (or similar) options for linking with the libraries listed in $LIBS,
6395 (or similar) include search path options
6396 that scons generates automatically from $LIBPATH.
6400 for the variable that expands to library-link options,
6404 for the variable that expands to library search path options.
6407 The prefix used for shared object file names.
6410 The suffix used for shared object file names.
6413 A reserved variable name
6414 that may not be set or used in a construction environment.
6415 (See "Variable Substitution," below.)
6418 A reserved variable name
6419 that may not be set or used in a construction environment.
6420 (See "Variable Substitution," below.)
6423 A command interpreter function that will be called to execute command line
6424 strings. The function must expect the following arguments:
6427 def spawn(shell, escape, cmd, args, env):
6431 is a string naming the shell program to use.
6433 is a function that can be called to escape shell special characters in
6436 is the path to the command to be executed.
6438 is the arguments to the command.
6440 is a dictionary of the environment variables
6441 in which the command should be executed.
6444 '\"The Subversion executable (usually named
6448 '\"The command line used to
6449 '\"fetch source files from a Subversion repository.
6452 '\"General options that are passed to Subversion.
6455 The scripting language wrapper and interface generator.
6458 The suffix that will be used for intermediate C
6459 source files generated by
6460 the scripting language wrapper and interface generator.
6461 The default value is
6462 .BR _wrap$CFILESUFFIX .
6463 By default, this value is used whenever the
6467 specified as part of the
6469 construction variable.
6472 The command line used to call
6473 the scripting language wrapper and interface generator.
6475 .IP SWIGCXXFILESUFFIX
6476 The suffix that will be used for intermediate C++
6477 source files generated by
6478 the scripting language wrapper and interface generator.
6479 The default value is
6480 .BR _wrap$CFILESUFFIX .
6481 By default, this value is used whenever the
6483 option is specified as part of the
6485 construction variable.
6488 General options passed to
6489 the scripting language wrapper and interface generator.
6490 This is where you should set
6494 or whatever other options you want to specify to SWIG.
6497 option in this variable,
6500 generate a C++ intermediate source file
6501 with the extension that is specified as the
6509 The command line used to call the tar archiver.
6512 General options passed to the tar archiver.
6515 A reserved variable name
6516 that may not be set or used in a construction environment.
6517 (See "Variable Substitution," below.)
6520 A reserved variable name
6521 that may not be set or used in a construction environment.
6522 (See "Variable Substitution," below.)
6525 The suffix used for tar file names.
6528 The TeX formatter and typesetter.
6531 The command line used to call the TeX formatter and typesetter.
6534 General options passed to the TeX formatter and typesetter.
6537 A list of the names of the Tool specifications
6538 that are part of this construction environment.
6540 .IP WIN32_INSERT_DEF
6541 When this is set to true,
6542 a library build of a WIN32 shared library (.dll file)
6543 will also build a corresponding .def file at the same time,
6544 if a .def file is not already listed as a build target.
6545 The default is 0 (do not build a .def file).
6548 The prefix used for WIN32 .def file names.
6551 The suffix used for WIN32 .def file names.
6554 The parser generator.
6557 The command line used to call the parser generator
6558 to generate a source file.
6561 General options passed to the parser generator.
6562 If $YACCFLAGS contains a \-d option,
6563 SCons assumes that the call will also create a .h file
6564 (if the yacc source file ends in a .y suffix)
6566 (if the yacc source file ends in a .yy suffix)
6569 The zip compression and file packaging utility.
6572 The command line used to call the zip utility,
6573 or the internal Python function used to create a
6582 module used by the internal Python function
6583 to control whether the zip archive
6584 is compressed or not.
6585 The default value is
6586 .BR zipfile.ZIP_DEFLATED ,
6587 which creates a compressed zip archive.
6588 This value has no effect when using Python 1.5.2
6591 module is otherwise unavailable.
6594 General options passed to the zip utility.
6597 Construction variables can be retrieved and set using the
6599 method of the construction environment:
6602 dict = env.Dictionary()
6606 or using the [] operator:
6612 Construction variables can also be passed to the construction environment
6616 env = Environment(CC="cc")
6619 or when copying a construction environment using the
6624 env2 = env.Copy(CC="cl.exe")
6627 .SS Configure Contexts
6631 .I configure contexts,
6632 an integrated mechanism similar to the
6633 various AC_CHECK macros in GNU autoconf
6634 for testing for the existence of C header
6635 files, libraries, etc.
6636 In contrast to autoconf,
6638 does not maintain an explicit cache of the tested values,
6639 but uses its normal dependency tracking to keep the checked values
6640 up to date. However, users may override this behaviour with the
6642 command line option.
6644 The following methods can be used to perform checks:
6647 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
6649 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
6650 This creates a configure context, which can be used to perform checks.
6652 specifies the environment for building the tests.
6653 This environment may be modified when performing checks.
6655 is a dictionary containing custom tests.
6656 See also the section about custom tests below.
6657 By default, no custom tests are added to the configure context.
6659 specifies a directory where the test cases are built.
6660 Note that this directory is not used for building
6662 The default value is the directory
6665 specifies a file which collects the output from commands
6666 that are executed to check for the existence of header files, libraries, etc.
6667 The default is the file #/config.log.
6668 If you are using the
6671 you may want to specify a subdirectory under your build directory.
6673 specifies a C header file where the results of tests
6674 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6675 The default is to not write a
6678 You can specify the same
6680 file in multiple calls to Configure,
6683 will concatenate all results in the specified file.
6685 uses its normal dependency checking
6686 to decide if it's necessary to rebuild
6690 This means that the file is not necessarily re-built each
6692 but is only rebuilt if its contents will have changed
6693 and some target that depends on the
6695 file is being built.
6700 instance has the following associated methods:
6703 .RI Configure.Finish( self )
6704 This method should be called after configuration is done.
6705 It returns the environment as modified
6706 by the configuration checks performed.
6707 After this method is called, no further checks can be performed
6708 with this configuration context.
6709 However, you can create a new
6711 context to perform additional checks.
6712 Only one context should be active at a time.
6714 The following Checks are predefined.
6715 (This list will likely grow larger as time
6716 goes by and developers contribute new useful tests.)
6719 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6722 is usable in the specified language.
6725 in which case the last item in the list
6726 is the header file to be checked,
6727 and the previous list items are
6730 lines should precede the
6731 header line being checked for.
6732 The optional argument
6735 a two character string, where the first character denotes the opening
6736 quote and the second character denotes the closing quote.
6737 By default, both characters are " (double quote).
6738 The optional argument
6744 and selects the compiler to be used for the check.
6745 Returns 1 on success and 0 on failure.
6748 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6749 This is a wrapper around
6750 .B Configure.CheckHeader
6753 is usable in the C language.
6756 in which case the last item in the list
6757 is the header file to be checked,
6758 and the previous list items are
6761 lines should precede the
6762 header line being checked for.
6763 The optional argument
6766 a two character string, where the first character denotes the opening
6767 quote and the second character denotes the closing quote (both default
6769 Returns 1 on success and 0 on failure.
6772 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6773 This is a wrapper around
6774 .B Configure.CheckHeader
6777 is usable in the C++ language.
6780 in which case the last item in the list
6781 is the header file to be checked,
6782 and the previous list items are
6785 lines should precede the
6786 header line being checked for.
6787 The optional argument
6790 a two character string, where the first character denotes the opening
6791 quote and the second character denotes the closing quote (both default
6793 Returns 1 on success and 0 on failure.
6796 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
6797 Checks if the specified
6798 C or C++ function is available.
6800 is the name of the function to check for.
6803 argument is a string
6807 that will be compiled
6808 to check if the function exists;
6814 char function_name();
6822 and selects the compiler to be used for the check;
6826 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
6833 is 1 and the library provides the specified
6835 appends the library to the LIBS construction environment variable.
6837 may also be None (the default),
6840 is checked with the current LIBS variable,
6841 or a list of library names,
6842 in which case each library in the list
6849 you can link against the specified
6857 and selects the compiler to be used for the check;
6859 The default value for
6862 It is assumed, that the C-language is used.
6863 This method returns 1 on success and 0 on error.
6866 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
6869 .RI Configure.CheckLib
6870 call, this call provides a more sophisticated way to check against libraries.
6873 specifies the library or a list of libraries to check.
6875 specifies a header to check for.
6878 in which case the last item in the list
6879 is the header file to be checked,
6880 and the previous list items are
6883 lines should precede the
6884 header line being checked for.
6886 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6888 can be any valid expression (with a trailing ';'). The default is 'main();'.
6890 specifies whether to add the library to the environment (only if the check
6891 succeeds). This method returns 1 on success and 0 on error.
6894 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
6895 Checks for the existence of a type defined by
6898 specifies the typedef name to check for.
6900 is a string containing one or more
6902 lines that will be inserted into the program
6903 that will be run to test for the existence of the type.
6910 and selects the compiler to be used for the check;
6914 Example of a typical Configure usage:
6918 conf = Configure( env )
6919 if not conf.CheckCHeader( 'math.h' ):
6920 print 'We really need math.h!'
6922 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6923 # do stuff for qt - usage, e.g.
6924 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6929 You can define your own custom checks.
6930 in addition to the predefined checks.
6931 These are passed in a dictionary to the Configure function.
6932 This dictionary maps the names of the checks
6933 to user defined Python callables
6934 (either Python functions or class instances implementing the
6937 The first argument of the call is always a
6939 instance followed by the arguments,
6940 which must be supplied by the user of the check.
6941 These CheckContext instances define the following methods:
6944 .RI CheckContext.Message( self ", " text )
6946 Usually called before the check is started.
6948 will be displayed to the user, e.g. 'Checking for library X...'
6951 .RI CheckContext.Result( self, ", " res )
6953 Usually called after the check is done.
6955 can be either an integer or a string. In the former case, 'ok' (res != 0)
6956 or 'failed' (res == 0) is displayed to the user, in the latter case the
6957 given string is displayed.
6960 .RI CheckContext.TryCompile( self ", " text ", " extension )
6961 Checks if a file with the specified
6963 (e.g. '.c') containing
6965 can be compiled using the environment's
6967 builder. Returns 1 on success and 0 on failure.
6970 .RI CheckContext.TryLink( self ", " text ", " extension )
6971 Checks, if a file with the specified
6973 (e.g. '.c') containing
6975 can be compiled using the environment's
6977 builder. Returns 1 on success and 0 on failure.
6980 .RI CheckContext.TryRun( self ", " text ", " extension )
6981 Checks, if a file with the specified
6983 (e.g. '.c') containing
6985 can be compiled using the environment's
6987 builder. On success, the program is run. If the program
6988 executes successfully
6989 (that is, its return status is 0),
6994 is the standard output of the
6996 If the program fails execution
6997 (its return status is non-zero),
6998 then (0, '') is returned.
7001 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7002 Checks if the specified
7004 with an optional source file (contents
7011 may be anything which can be converted to a
7018 is the content of the target file.
7024 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7025 Low level implementation for testing specific builds;
7026 the methods above are based on this method.
7027 Given the Builder instance
7031 of a source file with optional
7033 this method returns 1 on success and 0 on failure. In addition,
7035 is set to the build target node, if the build was successful.
7038 Example for implementing and using custom tests:
7041 def CheckQt(context, qtdir):
7042 context.Message( 'Checking for qt ...' )
7043 lastLIBS = context.env['LIBS']
7044 lastLIBPATH = context.env['LIBPATH']
7045 lastCPPPATH= context.env['CPPPATH']
7046 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7047 ret = context.TryLink("""
7049 int main(int argc, char **argv) {
7050 QApplication qapp(argc, argv);
7055 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7056 context.Result( ret )
7060 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7061 if not conf.CheckQt('/usr/lib/qt'):
7062 print 'We really need qt!'
7067 .SS Construction Variable Options
7069 Often when building software, various options need to be specified at build
7070 time that are not known when the SConstruct/SConscript files are
7071 written. For example, libraries needed for the build may be in non-standard
7072 locations, or site-specific compiler options may need to be passed to the
7075 provides a mechanism for overridding construction variables from the
7076 command line or a text-based SConscript file through an Options
7077 object. To create an Options object, call the Options() function:
7080 .RI Options([ files "], [" args ])
7081 This creates an Options object that will read construction variables from
7082 the file or list of filenames specified in
7084 If no files are specified,
7089 then no files will be read.
7090 The optional argument
7093 values that will override anything read from the specified files;
7094 it is primarily intended to be passed the
7096 dictionary that holds variables
7097 specified on the command line.
7101 opts = Options('custom.py')
7102 opts = Options('overrides.py', ARGUMENTS)
7103 opts = Options(None, {FOO:'expansion', BAR:7})
7106 Options objects have the following methods:
7109 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7110 This adds a customizable construction variable to the Options object.
7112 is the name of the variable.
7114 is the help text for the variable.
7116 is the default value of the variable;
7117 if the default value is
7119 and there is no explicit value specified,
7120 the construction variable will
7122 be added to the construction environment.
7124 is called to validate the value of the variable, and should take three
7125 arguments: key, value, and environment
7127 is called to convert the value before putting it in the environment, and
7128 should take a single argument: value. Example:
7131 opts.Add('CC', 'The C compiler')
7135 .RI AddOptions( list )
7136 A wrapper script that adds
7137 multiple customizable construction variables
7138 to an Options object.
7140 is a list of tuple or list objects
7141 that contain the arguments
7142 for an individual call to the
7149 ('CC', 'The C compiler'),
7150 ('VALIDATE', 'An option for testing validation',
7151 'notset', validator, None),
7156 .RI Update( env ", [" args ])
7157 This updates a construction environment
7159 with the customized construction variables. Normally this method is not
7160 called directly, but is called indirectly by passing the Options object to
7161 the Environment() function:
7164 env = Environment(options=opts)
7168 .RI Save( filename ", " env )
7169 This saves the currently set options into a script file named
7171 that can be used on the next invocation to automatically load the current
7172 settings. This method combined with the Options method can be used to
7173 support caching of options between runs.
7177 opts = Options(['options.cache', 'custom.py'])
7180 opts.Save('options.cache', env)
7184 .RI GenerateHelpText( env ", [" sort ])
7185 This generates help text documenting the customizable construction
7186 variables suitable to passing in to the Help() function.
7188 is the construction environment that will be used to get the actual values
7189 of customizable variables. Calling with
7193 will cause the output to be sorted
7194 by the specified argument.
7198 should take two arguments
7201 (like the standard Python
7206 Help(opts.GenerateHelpText(env))
7207 Help(opts.GenerateHelpText(env, sort=cmp))
7210 The text based SConscript file is executed as a Python script, and the
7211 global variables are queried for customizable construction
7218 To make it more convenient to work with customizable Options,
7220 provides a number of functions
7221 that make it easy to set up
7222 various types of Options:
7225 .RI BoolOption( key ", " help ", " default )
7226 Return a tuple of arguments
7227 to set up a Boolean option.
7231 have a default value of
7233 and display the specified
7236 The option will interpret the values
7258 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7259 Return a tuple of arguments
7261 whose value may be one
7262 of a specified list of legal enumerated values.
7266 have a default value of
7268 and display the specified
7271 The option will only support those
7277 argument is a dictionary
7278 that can be used to convert
7279 input values into specific legal values
7288 then the values are case-sensitive.
7293 then values will be matched
7299 then values will be matched
7301 and all input values will be
7302 converted to lower case.
7305 .RI ListOption( key ", " help ", " default ", " names )
7306 Return a tuple of arguments
7308 whose value may be one or more
7309 of a specified list of legal enumerated values.
7313 have a default value of
7315 and display the specified
7318 The option will only support the values
7321 or the values in the
7324 More than one value may be specified,
7325 with all values separated by commas.
7326 The default may be a string of
7327 comma-separated default values,
7328 or a list of the default values.
7331 .RI PackageOption( key ", " help ", " default )
7332 Return a tuple of arguments
7334 whose value is a path name
7335 of a package that may be
7336 enabled, disabled or
7337 given an explicit path name.
7341 have a default value of
7343 and display the specified
7346 The option will support the values
7353 in which case the specified
7356 or the option may be set to an
7358 (typically the path name to a package
7359 that is being enabled).
7360 The option will also support the values
7366 to disable use of the specified option.
7369 .RI PathOption( key ", " help ", " default ", [" validator ])
7370 Return a tuple of arguments
7372 whose value is expected to be a path name.
7376 have a default value of
7378 and display the specified
7384 that will be called to
7385 verify that the specified path
7388 following ready-made validators:
7389 .BR PathOption.PathExists
7391 which verifies that the specified path exists;
7392 .BR PathOption.PathIsFile ,
7393 which verifies that the specified path is an existing file;
7394 .BR PathOption.PathIsDir ,
7395 which verifies that the specified path is an existing directory;
7397 .BR PathOption.PathIsDirCreate ,
7398 which verifies that the specified path is a directory,
7399 and will create the specified directory if the path exist.
7400 You may supply your own
7403 which must take three arguments
7405 the name of the options variable to be set;
7407 the specified value being checked;
7410 the construction environment)
7411 and should raise an exception
7412 if the specified value is not acceptable.
7415 These functions make it
7416 convenient to create a number
7417 of options with consistent behavior
7418 in a single call to the
7424 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7425 EnumOption('debug', 'debug output and symbols', 'no'
7426 allowed_values=('yes', 'no', 'full'),
7427 map={}, ignorecase=0), # case sensitive
7428 ListOption('shared',
7429 'libraries to build as shared libraries',
7431 names = list_of_libs),
7432 PackageOption('x11',
7433 'use X11 installed here (yes = search some places)',
7435 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7436 PathOption('foopath', 'where the foo library is installed', foopath,
7437 PathOption.PathIsDir),
7442 .SS File and Directory Nodes
7452 Nodes, respectively.
7453 python objects, respectively.
7454 Those objects have several user-visible attributes
7455 and methods that are often useful:
7461 This path is relative to the top-level directory
7465 The build path is the same as the source path if
7470 The absolute build path of the given file or directory.
7480 object representing the
7489 # Get the current build dir's path, relative to top.
7491 # Current dir's absolute path
7493 # Next line is always '.', because it is the top dir's path relative to itself.
7495 File('foo.c').srcnode().path # source path of the given source file.
7497 # Builders also return File objects:
7498 foo = env.Program('foo.c')
7499 print "foo will be built in %s"%foo.path
7505 can be extended to build different types of targets
7506 by adding new Builder objects
7507 to a construction environment.
7509 you should only need to add a new Builder object
7510 when you want to build a new type of file or other external target.
7511 If you just want to invoke a different compiler or other tool
7512 to build a Program, Object, Library, or any other
7513 type of output file for which
7515 already has an existing Builder,
7516 it is generally much easier to
7517 use those existing Builders
7518 in a construction environment
7519 that sets the appropriate construction variables
7522 Builder objects are created
7528 function accepts the following arguments:
7531 The command line string used to build the target from the source.
7534 a list of strings representing the command
7535 to be executed and its arguments
7536 (suitable for enclosing white space in an argument),
7538 mapping source file name suffixes to
7539 any combination of command line strings
7540 (if the builder should accept multiple source file extensions),
7543 (see the next section);
7544 or a list of any of the above.
7547 takes three arguments:
7549 - a list of source nodes,
7551 - a list of target nodes,
7553 - the construction environment.
7556 The prefix that will be prepended to the target file name.
7557 This may be specified as a:
7567 - a function or other callable that takes
7568 two arguments (a construction environment and a list of sources)
7569 and returns a prefix,
7574 - specifies a mapping from a specific source suffix (of the first
7575 source specified) to a corresponding target prefix. Both the source
7576 suffix and target prefix specifications may use environment variable
7577 substitution, and the target prefix (the 'value' entries in the
7578 dictionary) may also be a callable object. The default target prefix
7579 may be indicated by a dictionary entry with a key value of None.
7584 b = Builder("build_it < $SOURCE > $TARGET"
7587 def gen_prefix(env, sources):
7588 return "file-" + env['PLATFORM'] + '-'
7589 b = Builder("build_it < $SOURCE > $TARGET",
7590 prefix = gen_prefix)
7592 b = Builder("build_it < $SOURCE > $TARGET",
7593 suffix = { None: "file-",
7594 "$SRC_SFX_A": gen_prefix })
7598 The suffix that will be appended to the target file name.
7599 This may be specified in the same manner as the prefix above.
7600 If the suffix is a string, then
7602 will append a '.' to the beginning of the suffix if it's not already
7603 there. The string returned by callable object (or obtained from the
7604 dictionary) is untouched and must append its own '.' to the beginning
7608 b = Builder("build_it < $SOURCE > $TARGET"
7611 def gen_suffix(env, sources):
7612 return "." + env['PLATFORM'] + "-file"
7613 b = Builder("build_it < $SOURCE > $TARGET",
7614 suffix = gen_suffix)
7616 b = Builder("build_it < $SOURCE > $TARGET",
7617 suffix = { None: ".sfx1",
7618 "$SRC_SFX_A": gen_suffix })
7622 The expected source file name suffix. This may be a string or a list
7626 A Scanner object that
7627 will be invoked to find
7628 implicit dependencies for this target file.
7629 This keyword argument should be used
7630 for Scanner objects that find
7631 implicit dependencies
7632 based only on the target file
7633 and the construction environment,
7636 (See the section "Scanner Objects," below,
7637 for information about creating Scanner objects.)
7640 A Scanner object that
7642 find implicit dependences in
7644 used to build this target file.
7645 This is where you would
7646 specify a scanner to
7649 lines in source files.
7650 (See the section "Scanner Objects," below,
7651 for information about creating Scanner objects.)
7654 A factory function that the Builder will use
7655 to turn any targets specified as strings into SCons Nodes.
7657 SCons assumes that all targets are files.
7658 Other useful target_factory
7661 for when a Builder creates a directory target,
7664 for when a Builder can create either a file
7665 or directory target.
7670 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7672 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7673 env.MakeDirectory('new_directory', [])
7677 A factory function that the Builder will use
7678 to turn any sources specified as strings into SCons Nodes.
7680 SCons assumes that all source are files.
7681 Other useful source_factory
7684 for when a Builder uses a directory as a source,
7687 for when a Builder can use files
7688 or directories (or both) as sources.
7693 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7695 env.Append(BUILDERS = {'Collect':CollectBuilder})
7696 env.Collect('archive', ['directory_name', 'file_name'])
7700 A function or list of functions to manipulate the target and source
7701 lists before dependencies are established
7702 and the target(s) are actually built.
7704 can also be a string containing a construction variable to expand
7705 to an emitter function or list of functions,
7706 or a dictionary mapping source file suffixes
7707 to emitter functions.
7708 (Only the suffix of the first source file
7709 is used to select the actual emitter function
7710 from an emitter dictionary.)
7713 takes three arguments:
7715 - a list of source nodes,
7717 - a list of target nodes,
7719 - the construction environment.
7720 An emitter must return a tuple containing two lists,
7721 the list of targets to be built by this builder,
7722 and the list of sources for this builder.
7727 def e(target, source, env):
7728 return (target + ['foo.foo'], source + ['foo.src'])
7730 # Simple association of an emitter function with a Builder.
7731 b = Builder("my_build < $TARGET > $SOURCE",
7734 def e2(target, source, env):
7735 return (target + ['bar.foo'], source + ['bar.src'])
7737 # Simple association of a list of emitter functions with a Builder.
7738 b = Builder("my_build < $TARGET > $SOURCE",
7741 # Calling an emitter function through a construction variable.
7742 env = Environment(MY_EMITTER = e)
7743 b = Builder("my_build < $TARGET > $SOURCE",
7744 emitter = '$MY_EMITTER')
7746 # Calling a list of emitter functions through a construction variable.
7747 env = Environment(EMITTER_LIST = [e, e2])
7748 b = Builder("my_build < $TARGET > $SOURCE",
7749 emitter = '$EMITTER_LIST')
7751 # Associating multiple emitters with different file
7752 # suffixes using a dictionary.
7753 def e_suf1(target, source, env):
7754 return (target + ['another_target_file'], source)
7755 def e_suf2(target, source, env):
7756 return (target, source + ['another_source_file'])
7757 b = Builder("my_build < $TARGET > $SOURCE",
7758 emitter = {'.suf1' : e_suf1,
7766 arguments must not both be used for the same Builder.
7769 Specifies whether this builder is allowed to be called multiple times for
7770 the same target file(s). The default is 0, which means the builder
7771 can not be called multiple times for the same target file(s). Calling a
7772 builder multiple times for the same target simply adds additional source
7773 files to the target; it is not allowed to change the environment associated
7774 with the target, specify addition environment overrides, or associate a different
7775 builder with the target.
7778 A construction environment that can be used
7779 to fetch source code using this Builder.
7780 (Note that this environment is
7782 used for normal builds of normal target files,
7783 which use the environment that was
7784 used to call the Builder for the target file.)
7787 A function that returns a list of actions that will be executed to build
7788 the target(s) from the source(s).
7789 The returned action(s) may be
7790 an Action object, or anything that
7791 can be converted into an Action object
7792 (see the next section).
7794 The generator function
7795 takes four arguments:
7797 - a list of source nodes,
7799 - a list of target nodes,
7801 - the construction environment,
7803 - a Boolean value that specifies
7804 whether the generator is being called
7805 for generating a build signature
7806 (as opposed to actually executing the command).
7810 def g(source, target, env, for_signature):
7811 return [["gcc", "-c", "-o"] + target + source]
7813 b = Builder(generator=g)
7817 Specifies a builder to use when a source file name suffix does not match
7818 any of the suffixes of the builder. Using this argument produces a
7819 multi-stage builder.
7822 Specifies that this builder expects exactly one source file per call. Giving
7823 more than one source files without target files results in implicitely calling
7824 the builder multiple times (once for each source given). Giving multiple
7825 source files together with target files results in a UserError exception.
7833 arguments must not both be used for the same Builder.
7836 A construction environment that can be used
7837 to fetch source code using this Builder.
7838 (Note that this environment is
7840 used for normal builds of normal target files,
7841 which use the environment that was
7842 used to call the Builder for the target file.)
7845 b = Builder(action="build < $SOURCE > $TARGET")
7846 env = Environment(BUILDERS = {'MyBuild' : b})
7847 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
7851 A directory from which scons
7858 a string or a directory Node,
7859 scons will change to the specified directory.
7862 is not a string or Node
7864 then scons will change to the
7865 target file's directory.
7867 Note that scons will
7869 automatically modify
7871 construction variables like
7875 when using the chdir
7876 keyword argument--that is,
7877 the expanded file names
7878 will still be relative to
7879 the top-level SConstruct directory,
7880 and consequently incorrect
7881 relative to the chdir directory.
7882 Builders created using chdir keyword argument,
7883 will need to use construction variable
7888 to use just the filename portion of the
7892 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
7894 env = Environment(BUILDERS = {'MyBuild' : b})
7895 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
7899 Any additional keyword arguments supplied
7900 when a Builder object is created
7901 (that is, when the Builder() function is called)
7902 will be set in the executing construction
7903 environment when the Builder object is called.
7904 The canonical example here would be
7905 to set a construction variable to
7906 the repository of a source code system.
7908 Any additional keyword arguments supplied
7912 will only be associated with the target
7913 created by that particular Builder call
7914 (and any other files built as a
7915 result of the call).
7917 These extra keyword arguments are passed to the
7918 following functions:
7919 command generator functions,
7921 and emitter functions.
7927 function will turn its
7929 keyword argument into an appropriate
7930 internal Action object.
7931 You can also explicity create Action objects
7935 which can then be passed to the
7938 This can be used to configure
7939 an Action object more flexibly,
7940 or it may simply be more efficient
7941 than letting each separate Builder object
7942 create a separate Action
7944 Builder objects need to do the same thing.
7949 returns an appropriate object for the action
7950 represented by the type of the first argument:
7953 If the first argument is already an Action object,
7954 the object is simply returned.
7957 If the first argument is a string,
7958 a command-line Action is returned.
7961 Action('$CC -c -o $TARGET $SOURCES')
7964 .\" XXX From Gary Ruben, 23 April 2002:
7965 .\" What would be useful is a discussion of how you execute command
7966 .\" shell commands ie. what is the process used to spawn the shell, pass
7967 .\" environment variables to it etc., whether there is one shell per
7968 .\" environment or one per command etc. It might help to look at the Gnu
7969 .\" make documentation to see what they think is important to discuss about
7970 .\" a build system. I'm sure you can do a better job of organising the
7971 .\" documentation than they have :-)
7975 If the first argument is a list,
7976 then a list of Action objects is returned.
7977 An Action object is created as necessary
7978 for each element in the list.
7981 the list is itself a list,
7982 the internal list is the
7983 command and arguments to be executed via
7985 This allows white space to be enclosed
7986 in an argument by defining
7987 a command in a list within a list:
7990 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7994 If the first argument is a Python function,
7995 a function Action is returned.
7996 The Python function takes three keyword arguments,
7998 (a Node object representing the target file),
8000 (a Node object representing the source file)
8003 (the construction environment
8004 used for building the target file).
8009 arguments may be lists of Node objects if there is
8010 more than one target file or source file.
8011 The actual target and source file name(s) may
8012 be retrieved from their Node objects
8013 via the built-in Python str() function:
8016 target_file_name = str(target)
8017 source_file_names = map(lambda x: str(x), source)
8020 The function should return
8024 to indicate a successful build of the target file(s).
8025 The function may raise an exception
8026 or return a non-zero exit status
8027 to indicate an unsuccessful build.
8030 def build_it(target = None, source = None, env = None):
8031 # build the target from the source
8034 a = Action(build_it)
8037 If the action argument is not one of the above,
8040 The second, optional argument
8041 is a Python function that returns
8042 a string to be printed to describe the action being executed.
8043 Like a function to build a file,
8044 this function takes three arguments:
8046 (a Node object representing the target file),
8048 (a Node object representing the source file)
8051 (a construction environment).
8056 arguments may be lists of Node objects if there is
8057 more than one target file or source file.
8061 def build_it(target, source, env):
8062 # build the target from the source
8065 def string_it(target, source, env):
8066 return "building '%s' from '%s'" % (target[0], source[0])
8068 # Use a positional argument.
8069 a = Action(build_it, string_it)
8071 # Alternatively, use a keyword argument.
8072 a = Action(build_it, strfunction=string_it)
8075 The third, also optional argument
8076 is a list of construction variables
8077 whose values will be included
8078 in the signature of the Action
8079 when deciding whether a target should
8080 be rebuilt because the action changed.
8081 This is necessary whenever you want a target to
8082 be rebuilt when a specific
8083 construction variable changes,
8084 because the underlying Python code for a function
8085 will not change when the value of the construction variable does.
8088 def build_it(target, source, env):
8089 # build the target from the 'XXX' construction variable
8090 open(target[0], 'w').write(env['XXX'])
8093 def string_it(target, source):
8094 return "building '%s' from '%s'" % (target[0], source[0])
8096 # Use positional arguments.
8097 a = Action(build_it, string_it, ['XXX'])
8099 # Alternatively, use a keyword argument.
8100 a = Action(build_it, varlist=['XXX'])
8110 which specifies that
8111 scons will execute the action
8112 after changing to the specified directory.
8113 If the chdir argument is
8114 a string or a directory Node,
8115 scons will change to the specified directory.
8116 If the chdir argument
8117 is not a string or Node
8119 then scons will change to the
8120 target file's directory.
8122 Note that scons will
8124 automatically modify
8126 construction variables like
8130 when using the chdir
8131 keyword argument--that is,
8132 the expanded file names
8133 will still be relative to
8134 the top-level SConstruct directory,
8135 and consequently incorrect
8136 relative to the chdir directory.
8137 Builders created using chdir keyword argument,
8138 will need to use construction variable
8143 to use just the filename portion of the
8147 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8151 .SS Miscellaneous Action Functions
8154 supplies a number of functions
8155 that arrange for various common
8156 file and directory manipulations
8158 These are similar in concept to "tasks" in the
8160 although the implementation is slightly different.
8161 These functions do not actually
8162 perform the specified action
8163 at the time the function is called,
8164 but instead return an Action object
8165 that can be executed at the
8167 (In Object-Oriented terminology,
8172 that return Action objects.)
8175 there are two natural ways
8178 are intended to be used.
8182 to perform the action
8183 at the time the SConscript
8187 global function to do so:
8189 Execute(Touch('file'))
8193 you can use these functions
8194 to supply Actions in a list
8198 This can allow you to
8199 perform more complicated
8200 sequences of file manipulation
8202 on platform-specific
8206 env = Environment(TMPBUILD = '/tmp/builddir')
8207 env.Command('foo.out', 'foo.in',
8208 [Mkdir('$TMPBUILD'),
8209 Copy('${SOURCE.dir}', '$TMPBUILD')
8210 "cd $TMPBUILD && make",
8211 Delete('$TMPBUILD')])
8215 .RI Chmod( dest ", " mode )
8216 Returns an Action object that
8217 changes the permissions on the specified
8219 file or directory to the specified
8224 Execute(Chmod('file', 0755))
8226 env.Command('foo.out', 'foo.in',
8227 [Copy('$TARGET', '$SOURCE'),
8228 Chmod('$TARGET', 0755)])
8232 .RI Copy( dest ", " src )
8233 Returns an Action object
8236 source file or directory to the
8238 destination file or directory.
8242 Execute(Copy('foo.output', 'foo.input'))
8244 env.Command('bar.out', 'bar.in',
8245 Copy('$TARGET', '$SOURCE'))
8249 .RI Delete( entry ", [" must_exist ])
8250 Returns an Action that
8251 deletes the specified
8253 which may be a file or a directory tree.
8254 If a directory is specified,
8255 the entire directory tree
8260 then a Python error will be thrown
8261 if the specified entry does not exist;
8264 that is, the Action will silently do nothing
8265 if the entry does not exist.
8269 Execute(Delete('/tmp/buildroot'))
8271 env.Command('foo.out', 'foo.in',
8272 [Delete('${TARGET.dir}'),
8275 Execute(Delete('file_that_must_exist', must_exist=1))
8281 that creates the specified
8287 Execute(Mkdir('/tmp/outputdir'))
8289 env.Command('foo.out', 'foo.in',
8290 [Mkdir('/tmp/builddir',
8291 Copy('$SOURCE', '/tmp/builddir')
8292 "cd /tmp/builddir && ])
8297 .RI Move( dest ", " src )
8299 that moves the specified
8301 file or directory to
8308 Execute(Move('file.destination', 'file.source'))
8310 env.Command('output_file', 'input_file',
8312 Move('$TARGET', 'file_created_by_MyBuildAction')])
8318 that updates the modification time
8324 Execute(Touch('file_to_be_touched'))
8326 env.Command('marker', 'input_file',
8331 .SS Variable Substitution
8333 Before executing a command,
8335 performs construction variable interpolation on the strings that make up
8336 the command line of builders.
8337 Variables are introduced by a
8340 Besides construction variables, scons provides the following
8341 variables for each command execution:
8344 The file name of the target being built, or the file name of the first
8345 target if multiple targets are being built.
8348 The file names of all targets being built.
8351 The file name of the source of the build command, or the file name of the
8352 first source if multiple sources are being built.
8355 The file names of the sources of the build command.
8357 (Note that the above variables are reserved
8358 and may not be set in a construction environment.)
8361 For example, given the construction variable CC='cc', targets=['foo'], and
8362 sources=['foo.c', 'bar.c']:
8365 action='$CC -c -o $TARGET $SOURCES'
8368 would produce the command line:
8371 cc -c -o foo foo.c bar.c
8374 Variable names may be surrounded by curly braces ({})
8375 to separate the name from the trailing characters.
8376 Within the curly braces, a variable name may have
8377 a Python slice subscript appended to select one
8378 or more items from a list.
8379 In the previous example, the string:
8391 Additionally, a variable name may
8392 have the following special
8393 modifiers appended within the enclosing curly braces
8394 to modify the interpolated string:
8397 The base path of the file name,
8398 including the directory path
8399 but excluding any suffix.
8402 The name of the directory in which the file exists.
8406 minus any directory portion.
8409 Just the basename of the file,
8411 and minus the directory.
8414 Just the file suffix.
8417 The absolute path name of the file.
8420 The POSIX form of the path,
8421 with directories separated by
8425 This is sometimes necessary on Win32 systems
8426 when a path references a file on other (POSIX) systems.
8429 The directory and file name to the source file linked to this file
8430 through BuildDir. If this file isn't linked, it just returns the
8431 directory and filename unchanged.
8434 The directory containing the source file linked to this file
8435 through BuildDir. If this file isn't linked, it just returns the
8436 directory part of the filename.
8439 The directory and file name to the source file linked to this file
8440 through BuildDir. If the file does not exist locally but exists in
8441 a Repository, the path in the Repository is returned.
8442 If this file isn't linked, it just returns the
8443 directory and filename unchanged.
8446 The Repository directory containing the source file linked to this file
8447 through BuildDir. If this file isn't linked, it just returns the
8448 directory part of the filename.
8451 For example, the specified target will
8452 expand as follows for the corresponding modifiers:
8455 $TARGET => sub/dir/file.x
8456 ${TARGET.base} => sub/dir/file
8457 ${TARGET.dir} => sub/dir
8458 ${TARGET.file} => file.x
8459 ${TARGET.filebase} => file
8460 ${TARGET.suffix} => .x
8461 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8463 BuildDir('sub/dir','src')
8464 $SOURCE => sub/dir/file.x
8465 ${SOURCE.srcpath} => src/file.x
8466 ${SOURCE.srcdir} => src
8468 Repository('/usr/repository')
8469 $SOURCE => sub/dir/file.x
8470 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8471 ${SOURCE.rsrcdir} => /usr/repository/src
8474 Lastly, a variable name
8475 may be a callable Python function
8477 construction variable in the environment.
8479 take four arguments:
8481 - a list of target nodes,
8483 - a list of source nodes,
8485 - the construction environment,
8487 - a Boolean value that specifies
8488 whether the function is being called
8489 for generating a build signature.
8490 SCons will insert whatever
8491 the called function returns
8492 into the expanded string:
8495 def foo(target, source, env, for_signature):
8498 # Will expand $BAR to "bar baz"
8499 env=Environment(FOO=foo, BAR="$FOO baz")
8502 You can use this feature to pass arguments to a
8503 Python function by creating a callable class
8504 that stores one or more arguments in an object,
8505 and then uses them when the
8508 Note that in this case,
8509 the entire variable expansion must
8510 be enclosed by curly braces
8511 so that the arguments will
8512 be associated with the
8513 instantiation of the class:
8517 def __init__(self, arg):
8520 def __call__(self, target, source, env, for_signature):
8523 # Will expand $BAR to "my argument bar baz"
8524 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8528 The special pseudo-variables
8532 may be used to surround parts of a command line
8535 causing a rebuild--that is,
8536 which are not included in the signature
8537 of target files built with this command.
8542 will be removed from the command line
8543 before it is added to file signatures,
8548 will be removed before the command is executed.
8549 For example, the command line:
8552 echo Last build occurred $( $TODAY $). > $TARGET
8556 would execute the command:
8559 echo Last build occurred $TODAY. > $TARGET
8563 but the command signature added to any target files would be:
8566 echo Last build occurred . > $TARGET
8569 SCons uses the following rules when converting construction variables into
8573 When the value is a string it is interpreted as a space delimited list of
8574 command line arguments.
8577 When the value is a list it is interpreted as a list of command line
8578 arguments. Each element of the list is converted to a string.
8581 Anything that is not a list or string is converted to a string and
8582 interpreted as a single command line argument.
8585 Newline characters (\\n) delimit lines. The newline parsing is done after
8586 all other parsing, so it is not possible for arguments (e.g. file names) to
8587 contain embedded newline characters. This limitation will likely go away in
8588 a future version of SCons.
8596 new file types for implicit dependencies.
8597 Scanner accepts the following arguments:
8600 A Python function that will process
8602 and return a list of strings (file names)
8603 representing the implicit
8604 dependencies found in the contents.
8605 The function takes three or four arguments:
8607 def scanner_function(node, env, path):
8609 def scanner_function(node, env, path, arg):
8613 argument is the internal
8614 SCons node representing the file.
8617 to fetch the name of the file, and
8618 .B node.get_contents()
8619 to fetch contents of the file.
8623 argument is the construction environment for the scan.
8624 Fetch values from it using the
8630 argument is a tuple (or list)
8631 of directories that can be searched
8633 This will usually be the tuple returned by the
8635 argument (see below).
8639 argument is the argument supplied
8640 when the scanner was created, if any.
8643 The name of the Scanner.
8645 to identify the Scanner internally.
8648 An optional argument that, if specified,
8649 will be passed to the scanner function
8651 and the path function
8655 An optional list that can be used to
8656 determine which scanner should be used for
8658 In the usual case of scanning for file names,
8659 this argument will be a list of suffixes
8660 for the different file types that this
8661 Scanner knows how to scan.
8662 If the argument is a string,
8663 then it will be expanded
8664 into a list by the current environment.
8667 A Python function that takes
8668 two or three arguments:
8669 a construction environment, directory Node,
8670 and optional argument supplied
8671 when the scanner was created.
8674 returns a tuple of directories
8675 that can be searched for files to be returned
8676 by this Scanner object.
8679 The class of Node that should be returned
8680 by this Scanner object.
8681 Any strings or other objects returned
8682 by the scanner function
8683 that are not of this class
8684 will be run through the
8689 A Python function that will take a string
8691 and turn it into the appropriate class of Node
8692 to be returned by this Scanner object.
8695 An optional Python function that takes two arguments,
8696 a Node (file) and a construction environment,
8697 and returns whether the
8698 Node should, in fact,
8699 be scanned for dependencies.
8700 This check can be used to eliminate unnecessary
8701 calls to the scanner function when,
8702 for example, the underlying file
8703 represented by a Node does not yet exist.
8706 An optional flag that
8707 specifies whether this scanner should be re-invoked
8708 on the dependency files returned by the scanner.
8709 When this flag is not set,
8710 the Node subsystem will
8711 only invoke the scanner on the file being scanned,
8712 and not (for example) also on the files
8713 specified by the #include lines
8714 in the file being scanned.
8716 .SH SYSTEM-SPECIFIC BEHAVIOR
8717 SCons and its configuration files are very portable,
8718 due largely to its implementation in Python.
8719 There are, however, a few portability
8720 issues waiting to trap the unwary.
8722 SCons handles the upper-case
8724 file suffix differently,
8725 depending on the capabilities of
8726 the underlying system.
8727 On a case-sensitive system
8728 such as Linux or UNIX,
8729 SCons treats a file with a
8731 suffix as a C++ source file.
8732 On a case-insensitive system
8734 SCons treats a file with a
8736 suffix as a C source file.
8738 SCons handles the upper-case
8740 file suffix differently,
8741 depending on the capabilities of
8742 the underlying system.
8743 On a case-sensitive system
8744 such as Linux or UNIX,
8745 SCons treats a file with a
8747 suffix as a Fortran source file
8748 that is to be first run through
8749 the standard C preprocessor.
8750 On a case-insensitive system
8752 SCons treats a file with a
8754 suffix as a Fortran source file that should
8756 be run through the C preprocessor.
8757 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
8758 Cygwin supplies a set of tools and utilities
8759 that let users work on a
8760 Windows system using a more POSIX-like environment.
8761 The Cygwin tools, including Cygwin Python,
8763 by sharing an ability to interpret UNIX-like path names.
8764 For example, the Cygwin tools
8765 will internally translate a Cygwin path name
8766 like /cygdrive/c/mydir
8767 to an equivalent Windows pathname
8768 of C:/mydir (equivalent to C:\\mydir).
8771 that are built for native Windows execution,
8772 such as the python.org and ActiveState versions,
8773 do not have the Cygwin path name semantics.
8774 This means that using a native Windows version of Python
8775 to build compiled programs using Cygwin tools
8776 (such as gcc, bison, and flex)
8777 may yield unpredictable results.
8778 "Mixing and matching" in this way
8779 can be made to work,
8780 but it requires careful attention to the use of path names
8781 in your SConscript files.
8783 In practice, users can sidestep
8784 the issue by adopting the following rules:
8786 use the Cygwin-supplied Python interpreter
8788 when using Microsoft Visual C/C++
8789 (or some other Windows compiler)
8790 use the python.org or ActiveState version of Python
8792 .SS WIN32: scons.bat file
8794 SCons is executed via a wrapper
8797 This has (at least) two ramifications:
8799 First, Windows command-line users
8800 that want to use variable assignment
8802 may have to put double quotes
8803 around the assignments:
8806 scons "FOO=BAR" "BAZ=BLEH"
8809 Second, the Cygwin shell does not
8810 recognize this file as being the same
8813 command issued at the command-line prompt.
8814 You can work around this either by
8817 from the Cygwin command line,
8818 or by creating a wrapper shell
8824 The MinGW bin directory must be in your PATH environment variable or the
8825 PATH variable under the ENV construction variable for SCons
8826 to detect and use the MinGW tools. When running under the native Windows
8827 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8828 tools, if they are both installed, regardless of the order of the bin
8829 directories in the PATH variable. If you have both MSVC and MinGW
8830 installed and you want to use MinGW instead of MSVC,
8831 then you must explictly tell SCons to use MinGW by passing
8837 to the Environment() function, because SCons will prefer the MSVC tools
8838 over the MinGW tools.
8842 To help you get started using SCons,
8843 this section contains a brief overview of some common tasks.
8845 .SS Basic Compilation From a Single Source File
8849 env.Program(target = 'foo', source = 'foo.c')
8852 Note: Build the file by specifying
8853 the target as an argument
8854 ("scons foo" or "scons foo.exe").
8855 or by specifying a dot ("scons .").
8857 .SS Basic Compilation From Multiple Source Files
8861 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8864 .SS Setting a Compilation Flag
8867 env = Environment(CCFLAGS = '-g')
8868 env.Program(target = 'foo', source = 'foo.c')
8871 .SS Search The Local Directory For .h Files
8875 need to set CCFLAGS to specify -I options by hand.
8876 SCons will construct the right -I options from CPPPATH.
8879 env = Environment(CPPPATH = ['.'])
8880 env.Program(target = 'foo', source = 'foo.c')
8883 .SS Search Multiple Directories For .h Files
8886 env = Environment(CPPPATH = ['include1', 'include2'])
8887 env.Program(target = 'foo', source = 'foo.c')
8890 .SS Building a Static Library
8894 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8895 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8898 .SS Building a Shared Library
8902 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8903 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8906 .SS Linking a Local Library Into a Program
8909 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8910 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8911 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8914 .SS Defining Your Own Builder Object
8916 Notice that when you invoke the Builder,
8917 you can leave off the target file suffix,
8918 and SCons will add it automatically.
8921 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8923 src_suffix = '.tex')
8924 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8925 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8927 # The following creates "bar.pdf" from "bar.tex"
8928 env.PDFBuilder(target = 'bar', source = 'bar')
8931 Note also that the above initialization
8932 overwrites the default Builder objects,
8933 so the Environment created above
8934 can not be used call Builders like env.Program(),
8935 env.Object(), env.StaticLibrary(), etc.
8937 .SS Adding Your Own Builder Object to an Environment
8940 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8942 src_suffix = '.tex')
8944 env.Append(BUILDERS = {'PDFBuilder' : bld})
8945 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8946 env.Program(target = 'bar', source = 'bar.c')
8949 You also can use other Pythonic techniques to add
8950 to the BUILDERS construction variable, such as:
8954 env['BUILDERS]['PDFBuilder'] = bld
8957 .SS Defining Your Own Scanner Object
8962 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8964 def kfile_scan(node, env, path, arg):
8965 contents = node.get_contents()
8966 includes = include_re.findall(contents)
8969 kscan = Scanner(name = 'kfile',
8970 function = kfile_scan,
8973 scanners = Environment().Dictionary('SCANNERS')
8974 env = Environment(SCANNERS = scanners + [kscan])
8976 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8978 bar_in = File('bar.in')
8979 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8980 bar_in.target_scanner = kscan
8983 .SS Creating a Hierarchical Build
8985 Notice that the file names specified in a subdirectory's
8987 file are relative to that subdirectory.
8993 env.Program(target = 'foo', source = 'foo.c')
8995 SConscript('sub/SConscript')
9000 # Builds sub/foo from sub/foo.c
9001 env.Program(target = 'foo', source = 'foo.c')
9003 SConscript('dir/SConscript')
9008 # Builds sub/dir/foo from sub/dir/foo.c
9009 env.Program(target = 'foo', source = 'foo.c')
9012 .SS Sharing Variables Between SConscript Files
9014 You must explicitly Export() and Import() variables that
9015 you want to share between SConscript files.
9021 env.Program(target = 'foo', source = 'foo.c')
9024 SConscript('subdirectory/SConscript')
9026 subdirectory/SConscript:
9029 env.Program(target = 'foo', source = 'foo.c')
9032 .SS Building Multiple Variants From the Same Source
9034 Use the BuildDir() method to establish
9035 one or more separate build directories for
9036 a given source directory,
9037 then use the SConscript() method
9038 to specify the SConscript files
9039 in the build directories:
9046 BuildDir('foo', 'src')
9047 SConscript('foo/SConscript')
9051 BuildDir('bar', 'src')
9052 SConscript('bar/SConscript')
9057 env = Environment(CCFLAGS = ccflags)
9058 env.Program(target = 'src', source = 'src.c')
9061 Note the use of the Export() method
9062 to set the "ccflags" variable to a different
9063 value for each variant build.
9065 .SS Hierarchical Build of Two Libraries Linked With a Program
9070 env = Environment(LIBPATH = ['#libA', '#libB'])
9072 SConscript('libA/SConscript')
9073 SConscript('libB/SConscript')
9074 SConscript('Main/SConscript')
9079 env.Library('a', Split('a1.c a2.c a3.c'))
9084 env.Library('b', Split('b1.c b2.c b3.c'))
9089 e = env.Copy(LIBS = ['a', 'b'])
9090 e.Program('foo', Split('m1.c m2.c m3.c'))
9093 The '#' in the LIBPATH directories specify that they're relative to the
9094 top-level directory, so they don't turn into "Main/libA" when they're
9095 used in Main/SConscript.
9097 Specifying only 'a' and 'b' for the library names
9098 allows SCons to append the appropriate library
9099 prefix and suffix for the current platform
9100 (for example, 'liba.a' on POSIX systems,
9101 'a.lib' on Windows).
9103 .SS Customizing contruction variables from the command line.
9105 The following would allow the C compiler to be specified on the command
9106 line or in the file custom.py.
9109 opts = Options('custom.py')
9110 opts.Add('CC', 'The C compiler.')
9111 env = Environment(options=opts)
9112 Help(opts.GenerateHelpText(env))
9115 The user could specify the C compiler on the command line:
9121 or in the custom.py file:
9127 or get documentation on the options:
9138 .SS Using Microsoft Visual C++ precompiled headers
9140 Since windows.h includes everything and the kitchen sink, it can take quite
9141 some time to compile it over and over again for a bunch of object files, so
9142 Microsoft provides a mechanism to compile a set of headers once and then
9143 include the previously compiled headers in any object file. This
9144 technology is called precompiled headers. The general recipe is to create a
9145 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9146 then include every header you want to precompile in "StdAfx.h", and finally
9147 include "StdAfx.h" as the first header in all the source files you are
9148 compiling to object files. For example:
9152 #include <windows.h>
9153 #include <my_big_header.h>
9172 /* do some other stuff */
9178 env['PCHSTOP'] = 'StdAfx.h'
9179 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9180 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9183 For more information see the document for the PCH builder, and the PCH and
9184 PCHSTOP construction variables. To learn about the details of precompiled
9185 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9187 .SS Using Microsoft Visual C++ external debugging information
9189 Since including debugging information in programs and shared libraries can
9190 cause their size to increase significantly, Microsoft provides a mechanism
9191 for including the debugging information in an external file called a PDB
9192 file. SCons supports PDB files through the PDB construction
9198 env['PDB'] = 'MyApp.pdb'
9199 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9202 For more information see the document for the PDB construction variable.
9207 Specifies the directory that contains the SCons Python module directory
9208 (e.g. /home/aroach/scons-src-0.01/src/engine).
9211 A string of options that will be used by scons in addition to those passed
9212 on the command line.
9223 Steven Knight <knight@baldmt.com>
9225 Anthony Roach <aroach@electriceyeball.com>