3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be included
12 .\" in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
24 .\" ES - Example Start - indents and turns off line fill
29 .\" EE - Example End - ends indent and turns line fill back on
34 .TH SCONS 1 "January 2005"
36 scons \- a software construction tool
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found.
65 An alternate file name may be
72 file can specify subsidiary
73 configuration files using the
77 these subsidiary files are named
79 although any name may be used.
80 (Because of this naming convention,
81 the term "SConscript files"
82 is sometimes used to refer
86 regardless of actual file name.)
88 The configuration files
89 specify the target files to be built, and
90 (optionally) the rules to build those targets. Reasonable default
91 rules exist for building common software components (executable
92 programs, object files, libraries), so that for most software
93 projects, only the target and input files need be specified.
96 reads and executes the SConscript files as Python scripts,
97 so you may use normal Python scripting capabilities
98 (such as flow control, data manipulation, and imported Python libraries)
99 to handle complicated build situations.
101 however, reads and executes all of the SConscript files
103 it begins building any targets.
104 To make this obvious,
106 prints the following messages about what it is doing:
110 scons: Reading SConscript files ...
111 scons: done reading SConscript files.
112 scons: Building targets ...
114 scons: done building targets.
119 (everything except the line that reads "cp foo.in foo.out")
120 may be suppressed using the
125 does not automatically propagate
126 the external environment used to execute
128 to the commands used to build target files.
129 This is so that builds will be guaranteed
130 repeatable regardless of the environment
131 variables set at the time
134 This also means that if the compiler or other commands
135 that you want to use to build your target files
136 are not in standard system locations,
138 will not find them unless
139 you explicitly set the PATH
140 to include those locations.
141 Whenever you create an
143 construction environment,
144 you can propagate the value of PATH
145 from your external environment as follows:
149 env = Environment(ENV = {'PATH' : os.environ['PATH']})
153 can scan known input files automatically for dependency
154 information (for example, #include statements
155 in C or C++ files) and will rebuild dependent files appropriately
156 whenever any "included" input file changes.
159 ability to define new scanners for unknown input file types.
162 knows how to fetch files automatically from
163 SCCS or RCS subdirectories
164 using SCCS, RCS or BitKeeper.
167 is normally executed in a top-level directory containing a
169 file, optionally specifying
170 as command-line arguments
171 the target file or files to be built.
173 By default, the command
179 will build all target files in or below the current directory.
180 Explicit default targets
181 (to be built when no targets are specified on the command line)
182 may be defined the SConscript file(s)
185 function, described below.
189 targets are specified in the SConscript file(s),
190 all target files in or below the current directory
191 may be built by explicitly specifying
192 the current directory (.)
193 as a command-line target:
199 Building all target files,
200 including any files outside of the current directory,
201 may be specified by supplying a command-line target
202 of the root directory (on POSIX systems):
208 or the path name(s) of the volume(s) in which all the targets
209 should be built (on Windows systems):
215 To build only specific targets,
216 supply them as command-line arguments:
222 in which case only the specified targets will be built
223 (along with any derived files on which they depend).
225 Specifying "cleanup" targets in SConscript files is not
228 flag removes all files
229 necessary to build the specified target:
235 to remove all target files, or:
238 scons -c build export
241 to remove target files under build and export.
242 Additional files or directories to remove can be specified using the
245 A subset of a hierarchical tree may be built by
246 remaining at the top-level directory (where the
248 file lives) and specifying the subdirectory as the target to be
255 or by changing directory and invoking scons with the
257 option, which traverses up the directory
258 hierarchy until it finds the
260 file, and then builds
261 targets relatively to the current subdirectory:
269 supports building multiple targets in parallel via a
271 option that takes, as its argument, the number
272 of simultaneous tasks that may be spawned:
278 builds four targets in parallel, for example.
281 can maintain a cache of target (derived) files that can
282 be shared between multiple builds. When caching is enabled in a
283 SConscript file, any target files built by
286 to the cache. If an up-to-date target file is found in the cache, it
287 will be retrieved from the cache instead of being rebuilt locally.
288 Caching behavior may be disabled and controlled in other ways by the
290 .BR --cache-disable ,
293 command-line options. The
295 option is useful to prevent multiple builds
296 from trying to update the cache simultaneously.
298 Values of variables to be passed to the SConscript file(s)
299 may be specified on the command line:
305 These variables are available in SConscript files
306 through the ARGUMENTS dictionary,
307 and can be used in the SConscript file(s) to modify
308 the build in any way:
311 if ARGUMENTS.get('debug', 0):
312 env = Environment(CCFLAGS = '-g')
317 The command-line variable arguments are also available
319 indexed by their order on the command line.
320 This allows you to process them in order rather than by name,
322 ARGLIST[0] returns a tuple
323 containing (argname, argvalue).
324 A Python exception is thrown if you
325 try to access a list member that
329 requires Python version 1.5.2 or later.
330 There should be no other dependencies or requirements to run
333 .\" The following paragraph reflects the default tool search orders
334 .\" currently in SCons/Tool/__init__.py. If any of those search orders
335 .\" change, this documentation should change, too.
338 knows how to search for available programming tools
342 searches in order for the
343 Microsoft Visual C++ tools,
344 the MinGW tool chain,
345 the Intel compiler tools,
346 and the PharLap ETS compiler.
349 searches in order for the
352 and the Microsoft Visual C++ tools,
353 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
355 searches for the native compiler tools
356 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
357 and the GCC tool chain.
358 On all other platforms,
359 including POSIX (Linux and UNIX) platforms,
362 for the GCC tool chain,
363 the Microsoft Visual C++ tools,
364 and the Intel compiler tools.
365 You may, of course, override these default values
366 by appropriate configuration of
367 Environment construction variables.
372 supports the same command-line options as GNU
374 and many of those supported by
379 Ignored for compatibility with non-GNU versions of
383 -c, --clean, --remove
384 Clean up by removing all target files for which a construction
385 command is specified.
386 Also remove any files or directories associated to the construction command
387 using the Clean() function.
390 --cache-disable, --no-cache
391 Disable the derived-file caching specified by
394 will neither retrieve files from the cache
395 nor copy files to the cache.
398 --cache-force, --cache-populate
401 populate a cache by copying any already-existing, up-to-date
402 derived files to the cache,
403 in addition to files built by this invocation.
404 This is useful to populate a new cache with
405 all the current derived files,
406 or to add to the cache any derived files
407 recently built with caching disabled via the
415 and retrieving a derived file from the cache,
417 that would have been executed to build the file,
418 instead of the usual report,
419 "Retrieved `file' from cache."
420 This will produce consistent output for build logs,
421 regardless of whether a target
422 file was rebuilt or retrieved from the cache.
426 This specifies how the
428 call should use or generate the
429 results of configuration tests.
430 The option should be specified from
431 among the following choices:
435 scons will use its normal dependency mechanisms
436 to decide if a test must be rebuilt or not.
437 This saves time by not running the same configuration tests
438 every time you invoke scons,
439 but will overlook changes in system header files
440 or external commands (such as compilers)
441 if you don't specify those dependecies explicitly.
442 This is the default behavior.
446 If this option is specified,
447 all configuration tests will be re-run
448 regardless of whether the
449 cached results are out of date.
450 This can be used to explicitly
451 force the configuration tests to be updated
452 in response to an otherwise unconfigured change
453 in a system header file or compiler.
457 If this option is specified,
458 no configuration tests will be rerun
459 and all results will be taken from cache.
460 Note that scons will still consider it an error
461 if --config=cache is specified
462 and a necessary test does not
463 yet have any results in the cache.
466 .RI "-C" " directory" ", --directory=" directory
467 Change to the specified
469 before searching for the
474 file, or doing anything
477 options are interpreted
478 relative to the previous one, and the right-most
480 option wins. (This option is nearly
482 .BR "-f directory/SConstruct" ,
483 except that it will search for
488 in the specified directory.)
492 .\" Display dependencies while building target files. Useful for
493 .\" figuring out why a specific file is being rebuilt, as well as
494 .\" general debugging of the build process.
498 Works exactly the same way as the
500 option except for the way default targets are handled.
501 When this option is used and no targets are specified on the command line,
502 all default targets are built, whether or not they are below the current
507 Debug the build process.
509 specifies what type of debugging:
513 Print how many objects are created
514 of the various classes used internally by SCons
515 before and after reading the SConscript files
516 and before and after building targets.
517 This only works when run under Python 2.1 or later.
521 Print the dependency tree
522 after each top-level target is built. This prints out only derived files.
526 Instruct the scanner that searches for libraries
527 to print a message about each potential library
528 name it is searching for,
529 and about the actual libraries it finds.
533 Print the include tree after each top-level target is built.
534 This is generally used to find out what files are included by the sources
535 of a given derived file:
538 $ scons --debug=includes foo.o
543 Prints a summary of hits and misses in the Memoizer,
544 the internal SCons subsystem for caching
545 various values in memory instead of
546 recomputing them each time they're needed.
550 Prints how much memory SCons uses
551 before and after reading the SConscript files
552 and before and after building targets.
556 Disables use of the Memoizer,
557 the internal SCons subsystem for caching
558 various values in memory instead of
559 recomputing them each time they're needed.
560 This provides more accurate counts of the
561 underlying function calls in the
562 Python profiler output when using the
565 (When the Memoizer is used,
566 the profiler counts all
567 memoized functions as being executed
568 by the Memoizer's wrapper calls.)
572 Prints a list of the various objects
573 of the various classes used internally by SCons.
574 This only works when run under Python 2.1 or later.
578 Re-run SCons under the control of the
585 Print the raw command line used to build each target
586 before the construction environment variables are substituted.
587 Also shows which targets are being built by this command.
588 Output looks something like this:
590 $ scons --debug=presub
591 Building myprog.o with action(s):
592 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
598 Prints an internal Python stack trace
599 when encountering an otherwise unexplained error.
603 Print the dependency tree along with status information. This is the
604 same as the debug=tree option, but additional status information is
605 provided for each node in the tree.
609 Prints various time profiling information: the time spent
610 executing each build command, the total build time, the total time spent
611 executing build commands, the total time spent executing SConstruct and
612 SConscript files, and the total time spent executing SCons itself.
616 Print the dependency tree
617 after each top-level target is built. This prints out the complete
618 dependency tree including implicit dependencies and ignored
622 .\" -e, --environment-overrides
623 .\" Variables from the execution environment override construction
624 .\" variables from the SConscript files.
627 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
630 as the initial SConscript file.
634 Print a local help message for this build, if one is defined in
635 the SConscript file(s), plus a line that describes the
637 option for command-line option help. If no local help message
638 is defined, prints the standard help message about command-line
639 options. Exits after displaying the appropriate message.
643 Print the standard help message about command-line options and
648 Ignore all errors from commands executed to rebuild files.
651 .RI -I " directory" ", --include-dir=" directory
655 imported Python modules. If several
658 are used, the directories are searched in the order specified.
662 Cache implicit dependencies. This can cause
664 to miss changes in the implicit dependencies in cases where a new implicit
665 dependency is added earlier in the implicit dependency search path
666 (e.g. CPPPATH) than a current implicit dependency with the same name.
669 --implicit-deps-changed
670 Force SCons to ignore the cached implicit dependencies. This causes the
671 implicit dependencies to be rescanned and recached. This implies
672 .BR --implicit-cache .
675 --implicit-deps-unchanged
676 Force SCons to ignore changes in the implicit dependencies.
677 This causes cached implicit dependencies to always be used.
679 .BR --implicit-cache .
682 .RI -j " N" ", --jobs=" N
683 Specifies the number of jobs (commands) to run simultaneously.
684 If there is more than one
686 option, the last one is effective.
690 .\" is specified without an argument,
692 .\" will not limit the number of
693 .\" simultaneous jobs.
697 Continue as much as possible after an error. The target that
698 failed and those that depend on it will not be remade, but other
699 targets specified on the command line will still be processed.
702 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
703 .\" No new jobs (commands) will be started if
704 .\" there are other jobs running and the system load
705 .\" average is at least
707 .\" (a floating-point number).
710 .RI --duplicate= ORDER
711 There are three ways to duplicate files in a build tree: hard links,
712 soft (symbolic) links and copies. The default behaviour of SCons is to
713 prefer hard links to soft links to copies. You can specify different
714 behaviours with this option.
724 SCons will attempt to duplicate files using
725 the mechanisms in the specified order.
730 .\" List derived files (targets, dependencies) that would be built,
731 .\" but do not build them.
732 .\" [XXX This can probably go away with the right
733 .\" combination of other options. Revisit this issue.]
737 .\" List derived files that would be built, with the actions
738 .\" (commands) that build them. Does not build the files.
739 .\" [XXX This can probably go away with the right
740 .\" combination of other options. Revisit this issue.]
744 .\" List derived files that would be built, plus where the file is
745 .\" defined (file name and line number). Does not build the files.
746 .\" [XXX This can probably go away with the right
747 .\" combination of other options. Revisit this issue.]
751 Ignored for compatibility with non-GNU versions of
755 .RI --max-drift= SECONDS
756 Set the maximum expected drift in the modification time of files to
758 This value determines how long a file must be unmodified
759 before its cached content signature
760 will be used instead of
761 calculating a new content signature (MD5 checksum)
762 of the file's contents.
763 The default value is 2 days, which means a file must have a
764 modification time of at least two days ago in order to have its
765 cached content signature used.
766 A negative value means to never cache the content
767 signature and to ignore the cached value if there already is one. A value
768 of 0 means to always use the cached signature,
769 no matter how old the file is.
772 -n, --just-print, --dry-run, --recon
773 No execute. Print the commands that would be executed to build
774 any out-of-date target files, but do not execute the commands.
777 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
781 .\" not rebuild anything due to changes in the contents of
784 .\" .RI --override " file"
785 .\" Read values to override specific build environment variables
786 .\" from the specified
790 .\" Print the data base (construction environments,
791 .\" Builder and Scanner objects) that are defined
792 .\" after reading the SConscript files.
793 .\" After printing, a normal build is performed
794 .\" as usual, as specified by other command-line options.
795 .\" This also prints version information
800 .\" To print the database without performing a build do:
808 Run SCons under the Python profiler
809 and save the results in the specified
811 The results may be analyzed using the Python
815 Do not run any commands, or print anything. Just return an exit
816 status that is zero if the specified targets are already up to
817 date, non-zero otherwise.
820 Quiets SCons status messages about
821 reading SConscript files,
823 and entering directories.
824 Commands that are executed
825 to rebuild target files are still printed.
828 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
829 .\" Clear the default construction variables. Construction
830 .\" environments that are created will be completely empty.
834 Build dependencies in a random order. This is useful when
835 building multiple trees simultaneously with caching enabled,
836 to prevent multiple builds from simultaneously trying to build
837 or retrieve the same target files.
840 -s, --silent, --quiet
841 Silent. Do not print commands that are executed to rebuild
843 Also suppresses SCons status messages.
846 -S, --no-keep-going, --stop
847 Ignored for compatibility with GNU
852 Ignored for compatibility with GNU
854 (Touching a file to make it
855 appear up-to-date is unnecessary when using
859 -u, --up, --search-up
860 Walks up the directory structure until an
865 file is found, and uses that
866 as the top of the directory tree.
867 If no targets are specified on the command line,
868 only targets at or below the
869 current directory will be built.
873 Works exactly the same way as the
875 option except for the way default targets are handled.
876 When this option is used and no targets are specified on the command line,
877 all default targets that are defined in the SConscript(s) in the current
878 directory are built, regardless of what directory the resultant targets end
885 version, copyright information,
886 list of authors, and any other relevant information.
890 -w, --print-directory
891 Print a message containing the working directory before and
892 after other processing.
895 .RI --warn= type ", --warn=no-" type
896 Enable or disable warnings.
898 specifies the type of warnings to be enabled or disabled:
901 --warn=all, --warn=no-all
902 Enables or disables all warnings.
905 --warn=dependency, --warn=no-dependency
906 Enables or disables warnings about dependencies.
907 These warnings are disabled by default.
910 --warn=deprecated, --warn=no-deprecated
911 Enables or disables warnings about use of deprecated features.
912 These warnings are enabled by default.
915 --warn=missing-sconscript, --warn=no-missing-sconscript
916 Enables or disables warnings about missing SConscript files.
917 These warnings are enabled by default.
921 Turn off -w, even if it was turned on implicitly.
924 .\" .RI --write-filenames= file
925 .\" Write all filenames considered into
929 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
930 .\" Pretend that the target
933 .\" modified. When used with the
936 .\" show you what would be rebuilt if you were to modify that file.
942 .\" --warn-undefined-variables
943 .\" Warn when an undefined variable is referenced.
946 .RI -Y " repository" ", --repository=" repository
947 Search the specified repository for any input and target
948 files not found in the local directory hierarchy. Multiple
950 options may specified, in which case the
951 repositories are searched in the order specified.
953 .SH CONFIGURATION FILE REFERENCE
954 .\" .SS Python Basics
955 .\" XXX Adding this in the future would be a help.
956 .SS Construction Environments
957 A construction environment is the basic means by which the SConscript
958 files communicate build information to
960 A new construction environment is created using the
968 By default, a new construction environment is
969 initialized with a set of builder methods
970 and construction variables that are appropriate
971 for the current platform.
972 An optional platform keyword argument may be
973 used to specify that an environment should
974 be initialized for a different platform:
977 env = Environment(platform = 'cygwin')
978 env = Environment(platform = 'os2')
979 env = Environment(platform = 'posix')
980 env = Environment(platform = 'win32')
983 Specifying a platform initializes the appropriate
984 construction variables in the environment
985 to use and generate file names with prefixes
986 and suffixes appropriate for the platform.
992 variable from the user's external environment
993 to the construction environment's
996 This is so that any executed commands
997 that use sockets to connect with other systems
998 (such as fetching source files from
999 external CVS repository specifications like
1000 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1001 will work on Win32 systems.
1003 The platform argument may be function or callable object,
1004 in which case the Environment() method
1005 will call the specified argument to update
1006 the new construction environment:
1009 def my_platform(env):
1010 env['VAR'] = 'xyzzy'
1012 env = Environment(platform = my_platform)
1015 Additionally, a specific set of tools
1016 with which to initialize the environment
1017 may specified as an optional keyword argument:
1020 env = Environment(tools = ['msvc', 'lex'])
1023 Non-built-in tools may be specified using the toolpath argument:
1026 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1029 This looks for a tool specification in tools/foo.py (as well as
1030 using the ordinary default tools for the platform). foo.py should
1031 have two functions: generate(env, **kw) and exists(env).
1035 modifies the passed-in environment
1036 to set up variables so that the tool
1038 it may use any keyword arguments
1039 that the user supplies (see below)
1040 to vary its initialization.
1043 function should return a true
1044 value if the tool is available.
1045 Tools in the toolpath are used before
1046 any of the built-in ones. For example, adding gcc.py to the toolpath
1047 would override the built-in gcc tool.
1048 Also note that the toolpath is
1049 stored in the environment for use
1057 base = Environment(toolpath=['custom_path'])
1058 derived = base.Copy(tools=['custom_tool'])
1059 derived.CustomBuilder()
1062 The elements of the tools list may also
1063 be functions or callable objects,
1064 in which case the Environment() method
1065 will call the specified elements
1066 to update the new construction environment:
1070 env['XYZZY'] = 'xyzzy'
1072 env = Environment(tools = [my_tool])
1075 The individual elements of the tools list
1076 may also themselves be two-element lists of the form
1077 .RI ( toolname ", " kw_dict ).
1078 SCons searches for the
1080 specification file as described above, and
1083 which must be a dictionary, as keyword arguments to the tool's
1088 function can use the arguments to modify the tool's behavior
1089 by setting up the environment in different ways
1090 or otherwise changing its initialization.
1093 # in tools/my_tool.py:
1094 def generate(env, **kw):
1095 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1096 env['MY_TOOL'] = kw.get('arg1', '1')
1101 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1105 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1106 the environment it receives to customize the tool for different platforms.
1108 If no tool list is specified, then SCons will auto-detect the installed
1109 tools using the PATH variable in the ENV construction variable and the
1110 platform name when the Environment is constructed. Changing the PATH
1111 variable after the Environment is constructed will not cause the tools to
1114 SCons supports the following tool specifications out of the box:
1190 Additionally, there is a "tool" named
1192 which configures the
1193 environment with a default set of tools for the current platform.
1195 On posix and cygwin platforms
1196 the GNU tools (e.g. gcc) are preferred by SCons,
1197 on win32 the Microsoft tools (e.g. msvc)
1198 followed by MinGW are preferred by SCons,
1199 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1203 Build rules are specified by calling a construction
1204 environment's builder methods.
1205 The arguments to the builder methods are
1207 (a list of target files)
1210 (a list of source files).
1212 Because long lists of file names
1213 can lead to a lot of quoting,
1218 and a same-named environment method
1219 that split a single string
1220 into a list, separated on
1221 strings of white-space characters.
1222 (These are similar to the
1223 string.split() method
1224 from the standard Python library,
1225 but work even if the input isn't a string.)
1227 Like all Python arguments,
1228 the target and source arguments to a builder method
1229 can be specified either with or without
1230 the "target" and "source" keywords.
1231 When the keywords are omitted,
1232 the target is first,
1233 followed by the source.
1234 The following are equivalent examples of calling the Program builder method:
1237 env.Program('bar', ['bar.c', 'foo.c'])
1238 env.Program('bar', Split('bar.c foo.c'))
1239 env.Program('bar', env.Split('bar.c foo.c'))
1240 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1241 env.Program(target = 'bar', Split('bar.c foo.c'))
1242 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1243 env.Program('bar', source = string.split('bar.c foo.c'))
1246 When the target shares the same base name
1247 as the source and only the suffix varies,
1248 and if the builder method has a suffix defined for the target file type,
1249 then the target argument may be omitted completely,
1252 will deduce the target file name from
1253 the source file name.
1254 The following examples all build the
1260 (on Windows systems)
1261 from the bar.c source file:
1264 env.Program(target = 'bar', source = 'bar.c')
1265 env.Program('bar', source = 'bar.c')
1266 env.Program(source = 'bar.c')
1267 env.Program('bar.c')
1270 It is possible to override or add construction variables when calling a
1271 builder method by passing additional keyword arguments.
1272 These overridden or added
1273 variables will only be in effect when building the target, so they will not
1274 affect other parts of the build. For example, if you want to add additional
1275 libraries for just one program:
1278 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1281 or generate a shared library with a nonstandard suffix:
1284 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1287 Although the builder methods defined by
1290 methods of a construction environment object,
1291 they may also be called without an explicit environment:
1294 Program('hello', 'hello.c')
1295 SharedLibrary('word', 'word.cpp')
1299 the methods are called internally using a default construction
1300 environment that consists of the tools and values that
1302 has determined are appropriate for the local system.
1304 Builder methods that can be called without an explicit
1305 environment may be called from custom Python modules that you
1306 import into an SConscript file by adding the following
1307 to the Python module:
1310 from SCons.Script import *
1313 All builder methods return a list of Nodes
1314 that represent the target or targets that will be built.
1317 is an internal SCons object
1319 build targets or sources.
1321 The returned Node(s)
1322 can be passed to other builder methods as source(s)
1323 or passed to any SCons function or method
1324 where a filename would normally be accepted.
1325 For example, if it were necessary
1328 flag when compiling one specific object file:
1331 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1332 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1335 Using a Node in this way
1336 makes for a more portable build
1337 by avoiding having to specify
1338 a platform-specific object suffix
1339 when calling the Program() builder method.
1341 Note that Builder calls will automatically "flatten"
1342 the source and target file lists,
1343 so it's all right to have the bar_obj list
1344 return by the StaticObject() call
1345 in the middle of the source file list.
1346 If you need to manipulate a list of lists returned by Builders
1347 directly using Python,
1348 you can either build the list by hand:
1351 foo = Object('foo.c')
1352 bar = Object('bar.c')
1353 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1354 for object in objects:
1361 to create a list containing just the Nodes,
1362 which may be more convenient:
1365 foo = Object('foo.c')
1366 bar = Object('bar.c')
1367 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1368 for object in objects:
1372 The path name for a Node's file may be used
1373 by passing the Node to the Python-builtin
1378 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1379 print "The path to bar_obj is:", str(bar_obj_list[0])
1382 Note again that because the Builder call returns a list,
1383 we have to access the first element in the list
1384 .B (bar_obj_list[0])
1385 to get at the Node that actually represents
1388 Builder calls support a
1390 keyword argument that
1391 specifies that the Builder's action(s)
1393 after changing directory.
1397 a string or a directory Node,
1398 scons will change to the specified directory.
1401 is not a string or Node
1403 then scons will change to the
1404 target file's directory.
1407 # scons will change to the "sub" subdirectory
1408 # before executing the "cp" command.
1409 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1410 "cp dir/foo.in dir/foo.out",
1413 # Because chdir is not a string, scons will change to the
1414 # target's directory ("sub/dir") before executing the
1416 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1417 "cp foo.in foo.out",
1421 Note that scons will
1423 automatically modify
1425 construction variables like
1429 when using the chdir
1430 keyword argument--that is,
1431 the expanded file names
1432 will still be relative to
1433 the top-level SConstruct directory,
1434 and consequently incorrect
1435 relative to the chdir directory.
1436 If you use the chdir keyword argument,
1437 you will typically need to supply a different
1443 to use just the filename portion of the
1447 provides the following builder methods:
1449 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1452 Builds a C source file given a lex (.l) or yacc (.y) input file.
1453 The suffix specified by the $CFILESUFFIX construction variable
1455 is automatically added to the target
1456 if it is not already present. Example:
1460 env.CFile(target = 'foo.c', source = 'foo.l')
1462 env.CFile(target = 'bar', source = 'bar.y')
1465 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1468 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1470 The suffix specified by the $CXXFILESUFFIX construction variable
1472 is automatically added to the target
1473 if it is not already present. Example:
1477 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1479 env.CXXFile(target = 'bar', source = 'bar.yy')
1482 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1485 Builds a .dvi file from a .tex, .ltx or .latex input file.
1486 If the source file suffix is .tex,
1488 will examine the contents of the file;
1493 is found, the file is assumed to be a LaTeX file and
1494 the target is built by invoking the $LATEXCOM command line;
1495 otherwise, the $TEXCOM command line is used.
1496 If the file is a LaTeX file,
1499 builder method will also examine the contents
1502 and invoke the $BIBTEX command line
1506 and will examine the contents
1508 file and re-run the $LATEXCOM command
1509 if the log file says it is necessary.
1512 (hard-coded within TeX itself)
1513 is automatically added to the target
1514 if it is not already present. Examples:
1517 # builds from aaa.tex
1518 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1520 env.DVI(target = 'bbb', source = 'bbb.ltx')
1521 # builds from ccc.latex
1522 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1525 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1528 Builds a Java archive (.jar) file
1529 from a source tree of .class files.
1530 If the $JARCHDIR value is set, the
1532 command will change to the specified directory using the
1535 If the contents any of the source files begin with the string
1536 .BR Manifest-Version ,
1537 the file is assumed to be a manifest
1538 and is passed to the
1545 env.Jar(target = 'foo.jar', source = 'classes')
1548 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1551 Builds one or more Java class files
1552 from one or more source trees of .java files.
1553 The class files will be placed underneath
1554 the specified target directory.
1555 SCons will parse each source .java file
1557 (including inner classes)
1558 defined within that file,
1559 and from that figure out the
1560 target .class files that will be created.
1561 SCons will also search each Java file
1562 for the Java package name,
1563 which it assumes can be found on a line
1564 beginning with the string
1566 in the first column;
1567 the resulting .class files
1568 will be placed in a directory reflecting
1569 the specified package name.
1573 defining a single public
1576 containing a package name of
1578 will generate a corresponding
1579 .IR sub/dir/Foo.class
1585 env.Java(target = 'classes', source = 'src')
1586 env.Java(target = 'classes', source = ['src1', 'src2'])
1589 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1592 Builds C header and source files for
1593 implementing Java native methods.
1594 The target can be either a directory
1595 in which the header files will be written,
1596 or a header file name which
1597 will contain all of the definitions.
1598 The source can be either the names of .class files,
1599 or the objects returned from the
1603 If the construction variable
1605 is set, either in the environment
1606 or in the call to the
1608 builder method itself,
1609 then the value of the variable
1610 will be stripped from the
1611 beginning of any .class file names.
1616 # builds java_native.h
1617 classes = env.Java(target = 'classdir', source = 'src')
1618 env.JavaH(target = 'java_native.h', source = classes)
1620 # builds include/package_foo.h and include/package_bar.h
1621 env.JavaH(target = 'include',
1622 source = ['package/foo.class', 'package/bar.class'])
1624 # builds export/foo.h and export/bar.h
1625 env.JavaH(target = 'export',
1626 source = ['classes/foo.class', 'classes/bar.class'],
1627 JAVACLASSDIR = 'classes')
1630 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1637 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1638 .IP LoadableModule()
1639 .IP env.LoadableModule()
1642 .BR SharedLibrary ().
1643 On Mac OS X (Darwin) platforms,
1644 this creates a loadable module bundle.
1647 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1650 Builds an output file from an M4 input file.
1651 This uses a default $M4FLAGS value of
1653 which considers all warnings to be fatal
1654 and stops on the first warning
1655 when using the GNU version of m4.
1659 env.M4(target = 'foo.c', source = 'foo.c.m4')
1662 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1665 Builds an output file from a moc input file. Moc input files are either
1666 header files or cxx files. This builder is only available after using the
1667 tool 'qt'. See the QTDIR variable for more information.
1671 env.Moc('foo.h') # generates moc_foo.cc
1672 env.Moc('foo.cpp') # generates foo.moc
1675 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1677 .IP env.MSVSProject()
1678 Builds Microsoft Visual Studio project files.
1679 This builds a Visual Studio project file, based on the version of
1680 Visual Studio that is configured (either the latest installed version,
1681 or the version set by
1683 in the Environment constructor).
1684 For VS 6, it will generate
1688 files, for VS 7, it will
1695 It takes several lists of filenames to be placed into the project
1696 file, currently these are limited to
1697 .B srcs, incs, localincs, resources,
1700 These are pretty self explanatory, but it
1701 should be noted that the 'srcs' list is NOT added to the $SOURCES
1702 environment variable. This is because it represents a list of files
1703 to be added to the project file, not the source used to build the
1704 project file (in this case, the 'source' is the SConscript file used
1705 to call MSVSProject).
1707 In addition to these values (which are all optional, although not
1708 specifying any of them results in an empty project file), the
1709 following values must be specified:
1711 target: The name of the target .dsp or .vcproj file. The correct
1712 suffix for the version of Visual Studio must be used, but the value
1714 env['MSVSPROJECTSUFFIX']
1716 will be defined to the correct value (see example below).
1718 variant: The name of this particular variant. These are typically
1719 things like "Debug" or "Release", but really can be anything you want.
1720 Multiple calls to MSVSProject with different variants are allowed: all
1721 variants will be added to the project file with their appropriate
1722 build targets and sources.
1724 buildtarget: A list of SCons.Node.FS objects which is returned from
1725 the command which builds the target. This is used to tell SCons what
1726 to build when the 'build' button is pressed inside of the IDE.
1731 barsrcs = ['bar.cpp'],
1732 barincs = ['bar.h'],
1733 barlocalincs = ['StdAfx.h']
1734 barresources = ['bar.rc','resource.h']
1735 barmisc = ['bar_readme.txt']
1737 dll = local.SharedLibrary(target = 'bar.dll',
1740 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1743 localincs = barlocalincs,
1744 resources = barresources,
1747 variant = 'Release')
1750 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1757 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1760 Builds a Microsoft Visual C++ precompiled header.
1761 Calling this builder method
1762 returns a list of two targets: the PCH as the first element, and the object
1763 file as the second element. Normally the object file is ignored.
1764 This builder method is only
1765 provided when Microsoft Visual C++ is being used as the compiler.
1766 The PCH builder method is generally used in
1767 conjuction with the PCH construction variable to force object files to use
1768 the precompiled header:
1771 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1774 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1777 Builds a .pdf file from a .dvi input file
1778 (or, by extension, a .tex, .ltx, or .latex input file).
1779 The suffix specified by the $PDFSUFFIX construction variable
1781 is added automatically to the target
1782 if it is not already present. Example:
1785 # builds from aaa.tex
1786 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1787 # builds bbb.pdf from bbb.dvi
1788 env.PDF(target = 'bbb', source = 'bbb.dvi')
1791 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1793 .IP env.PostScript()
1794 Builds a .ps file from a .dvi input file
1795 (or, by extension, a .tex, .ltx, or .latex input file).
1796 The suffix specified by the $PSSUFFIX construction variable
1798 is added automatically to the target
1799 if it is not already present. Example:
1802 # builds from aaa.tex
1803 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1804 # builds bbb.ps from bbb.dvi
1805 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1808 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1811 Builds an executable given one or more object files
1812 or C, C++, D, or Fortran source files.
1813 If any C, C++, D or Fortran source files are specified,
1814 then they will be automatically
1815 compiled to object files using the
1818 see that builder method's description for
1819 a list of legal source file suffixes
1820 and how they are interpreted.
1821 The target executable file prefix
1822 (specified by the $PROGPREFIX construction variable; nothing by default)
1824 (specified by the $PROGSUFFIX construction variable;
1825 by default, .exe on Windows systems, nothing on POSIX systems)
1826 are automatically added to the target if not already present.
1830 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1833 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1836 Builds a Microsoft Visual C++ resource file.
1837 This builder method is only provided
1838 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1842 for MinGW) suffix is added to the target name if no other suffix is given. The source
1843 file is scanned for implicit dependencies as though it were a C file. Example:
1846 env.RES('resource.rc')
1849 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1852 Builds stub and skeleton class files
1854 from Java .class files.
1855 The target is a directory
1856 relative to which the stub
1857 and skeleton class files will be written.
1858 The source can be the names of .class files,
1859 or the objects return from the
1863 If the construction variable
1865 is set, either in the environment
1866 or in the call to the
1868 builder method itself,
1869 then the value of the variable
1870 will be stripped from the
1871 beginning of any .class file names.
1874 classes = env.Java(target = 'classdir', source = 'src')
1875 env.RMIC(target = 'outdir1', source = classes)
1877 env.RMIC(target = 'outdir2',
1878 source = ['package/foo.class', 'package/bar.class'])
1880 env.RMIC(target = 'outdir3',
1881 source = ['classes/foo.class', 'classes/bar.class'],
1882 JAVACLASSDIR = 'classes')
1885 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1887 .IP env.RPCGenClient()
1888 Generates an RPC client stub (_clnt.c) file
1889 from a specified RPC (.x) source file.
1890 Because rpcgen only builds output files
1891 in the local directory,
1892 the command will be executed
1893 in the source file's directory by default.
1896 # Builds src/rpcif_clnt.c
1897 env.RPCGenClient('src/rpcif.x')
1900 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1902 .IP env.RPCGenHeader()
1903 Generates an RPC header (.h) file
1904 from a specified RPC (.x) source file.
1905 Because rpcgen only builds output files
1906 in the local directory,
1907 the command will be executed
1908 in the source file's directory by default.
1911 # Builds src/rpcif.h
1912 env.RPCGenHeader('src/rpcif.x')
1915 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1917 .IP env.RPCGenService()
1918 Generates an RPC server-skeleton (_svc.c) file
1919 from a specified RPC (.x) source file.
1920 Because rpcgen only builds output files
1921 in the local directory,
1922 the command will be executed
1923 in the source file's directory by default.
1926 # Builds src/rpcif_svc.c
1927 env.RPCGenClient('src/rpcif.x')
1930 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1933 Generates an RPC XDR routine (_xdr.c) file
1934 from a specified RPC (.x) source file.
1935 Because rpcgen only builds output files
1936 in the local directory,
1937 the command will be executed
1938 in the source file's directory by default.
1941 # Builds src/rpcif_xdr.c
1942 env.RPCGenClient('src/rpcif.x')
1945 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1947 .IP env.SharedLibrary()
1948 Builds a shared library
1949 (.so on a POSIX system, .dll on WIN32)
1950 given one or more object files
1951 or C, C++, D or Fortran source files.
1952 If any source files are given,
1953 then they will be automatically
1954 compiled to object files.
1955 The static library prefix and suffix (if any)
1956 are automatically added to the target.
1957 The target library file prefix
1958 (specified by the $SHLIBPREFIX construction variable;
1959 by default, lib on POSIX systems, nothing on Windows systems)
1961 (specified by the $SHLIBSUFFIX construction variable;
1962 by default, .dll on Windows systems, .so on POSIX systems)
1963 are automatically added to the target if not already present.
1967 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1970 On WIN32 systems, the
1972 builder method will always build an import (.lib) library
1973 in addition to the shared (.dll) library,
1974 adding a .lib library with the same basename
1975 if there is not already a .lib file explicitly
1976 listed in the targets.
1978 Any object files listed in the
1980 must have been built for a shared library
1985 will raise an error if there is any mismatch.
1987 On WIN32 systems, specifying "register=1" will cause the dll to be
1988 registered after it is built using REGSVR32. The command that is run
1989 ("regsvr32" by default) is determined by $REGSVR construction
1990 variable, and the flags passed are determined by $REGSVRFLAGS. By
1991 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1992 up and requiring user attention when it is run. If you change
1993 $REGSVRFLAGS, be sure to include "/s". For example,
1996 env.SharedLibrary(target = 'bar',
1997 source = ['bar.cxx', 'foo.obj'],
2002 will register "bar.dll" as a COM object when it is done linking it.
2004 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2006 .IP env.SharedObject()
2007 Builds an object file for
2008 inclusion in a shared library.
2009 Source files must have one of the same set of extensions
2010 specified above for the
2013 On some platforms building a shared object requires additional
2014 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
2015 normal (static) object, but on some platforms there is no difference between a
2016 shared object and a normal (static) one. When there is a difference, SCons
2017 will only allow shared objects to be linked into a shared library, and will
2018 use a different suffix for shared objects. On platforms where there is no
2019 difference, SCons will allow both normal (static)
2020 and shared objects to be linked into a
2021 shared library, and will use the same suffix for shared and normal
2023 The target object file prefix
2024 (specified by the $SHOBJPREFIX construction variable;
2025 by default, the same as $OBJPREFIX)
2027 (specified by the $SHOBJSUFFIX construction variable)
2028 are automatically added to the target if not already present.
2032 env.SharedObject(target = 'ddd', source = 'ddd.c')
2033 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2034 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2037 Note that the source files will be scanned
2038 according to the suffix mappings in
2039 .B SourceFileScanner
2041 See the section "Scanner Objects,"
2042 below, for a more information.
2044 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2046 .IP env.StaticLibrary()
2047 Builds a static library given one or more object files
2048 or C, C++, D or Fortran source files.
2049 If any source files are given,
2050 then they will be automatically
2051 compiled to object files.
2052 The static library prefix and suffix (if any)
2053 are automatically added to the target.
2054 The target library file prefix
2055 (specified by the $LIBPREFIX construction variable;
2056 by default, lib on POSIX systems, nothing on Windows systems)
2058 (specified by the $LIBSUFFIX construction variable;
2059 by default, .lib on Windows systems, .a on POSIX systems)
2060 are automatically added to the target if not already present.
2064 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2068 Any object files listed in the
2070 must have been built for a static library
2075 will raise an error if there is any mismatch.
2077 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2079 .IP env.StaticObject()
2080 Builds a static object file
2081 from one or more C, C++, D, or Fortran source files.
2082 Source files must have one of the following extensions:
2085 .asm assembly language file
2086 .ASM assembly language file
2098 .F WIN32: Fortran file
2099 POSIX: Fortran file + C pre-processor
2102 .fpp Fortran file + C pre-processor
2103 .FPP Fortran file + C pre-processor
2105 .mm Objective C++ file
2106 .s assembly language file
2107 .S WIN32: assembly language file
2108 POSIX: assembly language file + C pre-processor
2109 .spp assembly language file + C pre-processor
2110 .SPP assembly language file + C pre-processor
2113 The target object file prefix
2114 (specified by the $OBJPREFIX construction variable; nothing by default)
2116 (specified by the $OBJSUFFIX construction variable;
2117 \.obj on Windows systems, .o on POSIX systems)
2118 are automatically added to the target if not already present.
2122 env.StaticObject(target = 'aaa', source = 'aaa.c')
2123 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2124 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2127 Note that the source files will be scanned
2128 according to the suffix mappings in
2129 .B SourceFileScanner
2131 See the section "Scanner Objects,"
2132 below, for a more information.
2134 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2137 Builds a tar archive of the specified files
2139 Unlike most builder methods,
2142 builder method may be called multiple times
2144 each additional call
2145 adds to the list of entries
2146 that will be built into the archive.
2147 Any source directories will
2148 be scanned for changes to
2150 regardless of whether or not
2152 knows about them from other Builder or function calls.
2155 env.Tar('src.tar', 'src')
2157 # Create the stuff.tar file.
2158 env.Tar('stuff', ['subdir1', 'subdir2'])
2159 # Also add "another" to the stuff.tar file.
2160 env.Tar('stuff', 'another')
2162 # Set TARFLAGS to create a gzip-filtered archive.
2163 env = Environment(TARFLAGS = '-c -z')
2164 env.Tar('foo.tar.gz', 'foo')
2166 # Also set the suffix to .tgz.
2167 env = Environment(TARFLAGS = '-c -z',
2172 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2174 .IP env.TypeLibrary()
2175 Builds a Windows type library (.tlb) file from and input IDL file
2176 (.idl). In addition, it will build the associated inteface stub and
2177 proxy source files. It names them according to the base name of the .idl file.
2182 env.TypeLibrary(source="foo.idl")
2185 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2187 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2190 Builds a header file, an implementation file and a moc file from an ui file.
2191 and returns the corresponding nodes in the above order.
2192 This builder is only available after using the tool 'qt'. Note: you can
2193 specify .ui files directly as inputs for Program, Library and SharedLibrary
2194 without using this builder. Using the builder lets you override the standard
2195 naming conventions (be careful: prefixes are always prepended to names of
2196 built files; if you don't want prefixes, you may set them to ``).
2197 See the QTDIR variable for more information.
2201 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2202 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2203 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2209 Builds a zip archive of the specified files
2211 Unlike most builder methods,
2214 builder method may be called multiple times
2216 each additional call
2217 adds to the list of entries
2218 that will be built into the archive.
2219 Any source directories will
2220 be scanned for changes to
2222 regardless of whether or not
2224 knows about them from other Builder or function calls.
2227 env.Zip('src.zip', 'src')
2229 # Create the stuff.zip file.
2230 env.Zip('stuff', ['subdir1', 'subdir2'])
2231 # Also add "another" to the stuff.tar file.
2232 env.Zip('stuff', 'another')
2236 targets of builder methods automatically depend on their sources.
2237 An explicit dependency can
2238 be specified using the
2240 method of a construction environment (see below).
2245 source files for various programming languages,
2246 so the dependencies do not need to be specified explicitly.
2247 By default, SCons can
2250 Fortran source files with
2252 (POSIX systems only),
2257 and assembly language files with
2259 (POSIX systems only),
2264 for C preprocessor dependencies.
2265 SCons also has default support
2266 for scanning D source files,
2267 You can also write your own Scanners
2268 to add support for additional source file types.
2269 These can be added to the default
2270 Scanner object used by
2276 Builders by adding them
2278 .B SourceFileScanner
2281 See the section "Scanner Objects,"
2282 below, for a more information about
2283 defining your own Scanner objects.
2285 .SS Methods and Functions to Do Things
2286 In addition to Builder methods,
2288 provides a number of other construction environment methods
2289 and global functions to
2290 manipulate the build configuration.
2292 Usually, a construction environment method
2293 and global function with the same name both exist
2294 so that you don't have to remember whether
2295 to a specific bit of functionality
2296 must be called with or without a construction environment.
2297 In the following list,
2298 if you call something as a global function
2301 .RI Function( arguments )
2303 and if you call something through a construction
2304 environment it looks like:
2306 .RI env.Function( arguments )
2308 If you can call the functionality in both ways,
2309 then both forms are listed.
2311 Global functions may be called from custom Python modules that you
2312 import into an SConscript file by adding the following
2313 to the Python module:
2316 from SCons.Script import *
2319 Except where otherwise noted,
2321 construction environment method
2323 provide the exact same functionality.
2324 The only difference is that,
2326 calling the functionality through a construction environment will
2327 substitute construction variables into
2328 any supplied strings.
2331 env = Environment(FOO = 'foo')
2335 the first call to the global
2337 function will actually add a target named
2339 to the list of default targets,
2340 while the second call to the
2342 construction environment method
2343 will expand the value
2344 and add a target named
2346 to the list of default targets.
2347 For more on construction variable expansion,
2348 see the next section on
2349 construction variables.
2351 Construction environment methods
2352 and global functions supported by
2356 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2358 .RI Action( action ", [" strfunction ", " varlist ])
2360 .RI env.Action( action ", [" strfunction ", " varlist ])
2361 Creates an Action object for
2364 See the section "Action Objects,"
2365 below, for a complete explanation of the arguments and behavior.
2367 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2369 .RI AddPostAction( target ", " action )
2371 .RI env.AddPostAction( target ", " action )
2372 Arranges for the specified
2378 The specified action(s) may be
2379 an Action object, or anything that
2380 can be converted into an Action object
2383 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2385 .RI AddPreAction( target ", " action )
2387 .RI env.AddPreAction( target ", " action )
2388 Arranges for the specified
2391 before the specified
2394 The specified action(s) may be
2395 an Action object, or anything that
2396 can be converted into an Action object
2399 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2401 .RI Alias( alias ", [" targets ", [" action ]])
2403 .RI env.Alias( alias ", [" targets ", [" action ]])
2404 Creates one or more phony targets that
2405 expand to one or more other targets.
2410 can be specified that will be executed
2411 whenever the any of the alias targets are out-of-date.
2412 Returns the Node object representing the alias,
2413 which exists outside of any file system.
2414 This Node object, or the alias name,
2415 may be used as a dependency of any other target,
2416 including another alias.
2418 can be called multiple times for the same
2419 alias to add additional targets to the alias,
2420 or additional actions to the list for this alias.
2424 Alias('install', '/usr/bin')
2425 Alias(['install', 'install-lib'], '/usr/local/lib')
2427 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2428 env.Alias('install', ['/usr/local/man'])
2430 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2433 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2435 .RI AlwaysBuild( target ", ...)"
2437 .RI env.AlwaysBuild( target ", ...)"
2440 so that it is always assumed to be out of date,
2441 and will always be rebuilt if needed.
2444 does not add its target(s) to the default target list,
2445 so the targets will only be built
2446 if they are specified on the command line,
2447 or are a dependent of a target specified on the command line--but
2450 be built if so specified.
2451 Multiple targets can be passed in to a single call to
2454 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2456 .RI env.Append( key = val ", [...])"
2457 Appends the specified keyword arguments
2458 to the end of construction variables in the environment.
2459 If the Environment does not have
2460 the specified construction variable,
2461 it is simply added to the environment.
2462 If the values of the construction variable
2463 and the keyword argument are the same type,
2464 then the two values will be simply added together.
2465 Otherwise, the construction variable
2466 and the value of the keyword argument
2467 are both coerced to lists,
2468 and the lists are added together.
2469 (See also the Prepend method, below.)
2472 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2475 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2477 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2478 This appends new path elements to the given path in the
2479 specified external environment
2483 any particular path once (leaving the last one it encounters and
2484 ignoring the rest, to preserve path order),
2485 and to help assure this,
2486 will normalize all paths (using
2489 .BR os.path.normcase ).
2490 This can also handle the
2491 case where the given old path variable is a list instead of a
2492 string, in which case a list will be returned instead of a string.
2496 print 'before:',env['ENV']['INCLUDE']
2497 include_path = '/foo/bar:/foo'
2498 env.PrependENVPath('INCLUDE', include_path)
2499 print 'after:',env['ENV']['INCLUDE']
2503 after: /biz:/foo/bar:/foo
2506 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2508 .RI env.AppendUnique( key = val ", [...])"
2509 Appends the specified keyword arguments
2510 to the end of construction variables in the environment.
2511 If the Environment does not have
2512 the specified construction variable,
2513 it is simply added to the environment.
2514 If the construction variable being appended to is a list,
2515 then any value(s) that already exist in the
2516 construction variable will
2518 be added again to the list.
2521 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2524 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2527 A factory function that
2528 returns a Builder object
2529 to be used to fetch source files
2531 The returned Builder
2532 is intended to be passed to the
2537 env.SourceCode('.', env.BitKeeper())
2540 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2542 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2544 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2545 This specifies a build directory
2547 in which to build all derived files
2548 that would normally be built under
2550 Multiple build directories can be set up for multiple build variants, for
2553 must be underneath the SConstruct file's directory,
2556 may not be underneath the
2559 The default behavior is for
2561 to duplicate all of the files in the tree underneath
2565 and then build the derived files within the copied tree.
2566 (The duplication is performed by
2568 depending on the platform; see also the
2571 This guarantees correct builds
2572 regardless of whether intermediate source files
2573 are generated during the build,
2574 where preprocessors or other scanners search
2576 or whether individual compilers or other invoked tools
2577 are hard-coded to put derived files in the same directory as source files.
2579 This behavior of making a complete copy of the source tree
2580 may be disabled by setting
2585 to invoke Builders using the
2586 path names of source files in
2588 and the path names of derived files within
2590 This is always more efficient than
2592 and is usually safe for most builds.
2596 may cause build problems
2597 if source files are generated during the build,
2598 if any invoked tools are hard-coded to
2599 put derived files in the same directory as the source files.
2601 Note that specifying a
2603 works most naturally
2604 with a subsidiary SConscript file
2605 in the source directory.
2607 you would then call the subsidiary SConscript file
2608 not in the source directory,
2613 had made a virtual copy of the source tree
2614 regardless of the value of
2616 This is how you tell
2618 which variant of a source tree to build.
2622 BuildDir('build-variant1', 'src')
2623 SConscript('build-variant1/SConscript')
2624 BuildDir('build-variant2', 'src')
2625 SConscript('build-variant2/SConscript')
2631 function, described below,
2633 specify a build directory
2634 in conjunction with calling a subsidiary
2637 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2639 .RI Builder( action ", [" arguments ])
2641 .RI env.Builder( action ", [" arguments ])
2642 Creates a Builder object for
2645 See the section "Builder Objects,"
2646 below, for a complete explanation of the arguments and behavior.
2648 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2650 .RI CacheDir( cache_dir )
2652 .RI env.CacheDir( cache_dir )
2655 will maintain a cache of derived files in
2657 The derived files in the cache will be shared
2658 among all the builds using the same
2666 finds a derived file that needs to be rebuilt,
2667 it will first look in the cache to see if a
2668 derived file has already been built
2669 from identical input files and an identical build action
2670 (as incorporated into the MD5 build signature).
2673 will retrieve the file from the cache.
2674 If the derived file is not present in the cache,
2677 then place a copy of the built file in the cache
2678 (identified by its MD5 build signature),
2679 so that it may be retrieved by other
2680 builds that need to build the same derived file
2681 from identical inputs.
2685 may be disabled for any invocation
2694 will place a copy of
2696 derived files in the cache,
2697 even if they already existed
2698 and were not built by this invocation.
2699 This is useful to populate a cache
2702 is added to a build,
2711 "Retrieved `file' from cache,"
2714 option is being used.
2719 will print the action that
2721 have been used to build the file,
2722 without any indication that
2723 the file was actually retrieved from the cache.
2724 This is useful to generate build logs
2725 that are equivalent regardless of whether
2726 a given derived file has been built in-place
2727 or retrieved from the cache.
2729 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2731 .RI Clean( targets ", " files_or_dirs )
2733 .RI env.Clean( targets ", " files_or_dirs )
2734 This specifies a list of files or directories which should be removed
2735 whenever the targets are specified with the
2737 command line option.
2738 The specified targets may be a list
2739 or an individual target.
2743 and create new targets or add files and directories to the
2744 clean list for the specified targets.
2746 Multiple files or directories should be specified
2747 either as separate arguments to the
2749 method, or as a list.
2751 will also accept the return value of any of the construction environment
2756 Clean('foo', ['bar', 'baz'])
2757 Clean('dist', env.Program('hello', 'hello.c'))
2758 Clean(['foo', 'bar'], 'something_else_to_clean')
2761 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2763 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2765 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2766 Executes a specific action
2767 (or list of actions)
2768 to build a target file or files.
2769 This is more convenient
2770 than defining a separate Builder object
2771 for a single special-case build.
2773 As a special case, the
2775 keyword argument can
2778 that will be used to scan the sources.
2782 if any of the sources will be directories
2783 that must be scanned on-disk for
2784 changes to files that aren't
2785 already specified in other Builder of function calls.)
2787 Any other keyword arguments specified override any
2788 same-named existing construction variables.
2790 An action can be an external command,
2791 specified as a string,
2792 or a callable Python object;
2793 see "Action Objects," below,
2794 for more complete information.
2795 Also note that a string specifying an external command
2796 may be preceded by an
2799 to suppress printing the command in question,
2803 to ignore the exit status of the external command.
2807 env.Command('foo.out', 'foo.in',
2808 "$FOO_BUILD < $SOURCES > $TARGET")
2810 env.Command('bar.out', 'bar.in',
2812 "$BAR_BUILD < $SOURCES > $TARGET"],
2813 ENV = {'PATH' : '/usr/local/bin/'})
2815 def rename(env, target, source):
2817 os.rename('.tmp', str(target[0]))
2819 env.Command('baz.out', 'baz.in',
2820 ["$BAZ_BUILD < $SOURCES > .tmp",
2824 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2826 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2828 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2829 Creates a Configure object for integrated
2830 functionality similar to GNU autoconf.
2831 See the section "Configure Contexts,"
2832 below, for a complete explanation of the arguments and behavior.
2834 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2836 .RI env.Copy([ key = val ", ...])"
2837 Return a separate copy of a construction environment.
2838 If there are any keyword arguments specified,
2839 they are added to the returned copy,
2840 overwriting any existing values
2845 env3 = env.Copy(CCFLAGS = '-g')
2848 Additionally, a list of tools and a toolpath may be specified, as in
2849 the Environment constructor:
2852 def MyTool(env): env['FOO'] = 'bar'
2853 env4 = env.Copy(tools = ['msvc', MyTool])
2856 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2858 .RI env.CVS( repository ", " module )
2859 A factory function that
2860 returns a Builder object
2861 to be used to fetch source files
2865 The returned Builder
2866 is intended to be passed to the
2870 The optional specified
2872 will be added to the beginning
2873 of all repository path names;
2874 this can be used, in essence,
2875 to strip initial directory names
2876 from the repository path names,
2877 so that you only have to
2878 replicate part of the repository
2879 directory hierarchy in your
2880 local build directory:
2883 # Will fetch foo/bar/src.c
2884 # from /usr/local/CVSROOT/foo/bar/src.c.
2885 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2887 # Will fetch bar/src.c
2888 # from /usr/local/CVSROOT/foo/bar/src.c.
2889 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2892 # from /usr/local/CVSROOT/foo/bar/src.c.
2893 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2896 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2898 .RI Default( targets )
2900 .RI env.Default( targets )
2901 This specifies a list of default targets,
2902 which will be built by
2904 if no explicit targets are given on the command line.
2908 and add to the list of default targets.
2910 Multiple targets should be specified as
2911 separate arguments to the
2913 method, or as a list.
2915 will also accept the Node returned by any
2916 of a construction environment's
2921 Default('foo', 'bar', 'baz')
2922 env.Default(['a', 'b', 'c'])
2923 hello = env.Program('hello', 'hello.c')
2931 will clear all default targets.
2934 will add to the (now empty) default-target list
2937 The current list of targets added using the
2939 function or method is available in the
2944 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2946 .RI DefaultEnvironment([ args ])
2947 Creates and returns a default construction environment object.
2948 This construction environment is used internally by SCons
2949 in order to execute many of the global functions in this list,
2950 and to fetch source files transparently
2951 from source code management systems.
2953 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2955 .RI Depends( target ", " dependency )
2957 .RI env.Depends( target ", " dependency )
2958 Specifies an explicit dependency;
2959 the target file(s) will be rebuilt
2960 whenever the dependency file(s) has changed.
2961 This should only be necessary
2962 for cases where the dependency
2963 is not caught by a Scanner
2967 env.Depends('foo', 'other-input-file-for-foo')
2970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2972 .RI env.Dictionary([ vars ])
2973 Returns a dictionary object
2974 containing copies of all of the
2975 construction variables in the environment.
2976 If there are any variable names specified,
2977 only the specified construction
2978 variables are returned in the dictionary.
2981 dict = env.Dictionary()
2982 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2985 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2987 .RI Dir( name ", [" directory ])
2989 .RI env.Dir( name ", [" directory ])
2990 This returns a Directory Node,
2991 an object that represents the specified directory
2994 can be a relative or absolute path.
2996 is an optional directory that will be used as the parent directory.
2999 is specified, the current script's directory is used as the parent.
3001 Directory Nodes can be used anywhere you
3002 would supply a string as a directory name
3003 to a Builder method or function.
3004 Directory Nodes have attributes and methods
3005 that are useful in many situations;
3006 see "File and Directory Nodes," below.
3008 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3010 .RI env.Dump([ key ])
3011 Returns a pretty printable representation of the environment.
3015 should be a string containing the name of the variable of interest.
3020 print env.Dump('CCCOM')
3024 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3034 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3037 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3042 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3044 .RI EnsurePythonVersion( major ", " minor )
3046 .RI env.EnsurePythonVersion( major ", " minor )
3047 Ensure that the Python version is at least
3050 print out an error message and exit SCons with a non-zero exit code if the
3051 actual Python version is not late enough.
3054 EnsurePythonVersion(2,2)
3057 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3059 .RI EnsureSConsVersion( major ", " minor )
3061 .RI env.EnsureSConsVersion( major ", " minor )
3062 Ensure that the SCons version is at least
3065 print out an error message and exit SCons with a non-zero exit code if the
3066 actual SCons version is not late enough.
3069 EnsureSConsVersion(0,9)
3072 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3074 .RI Environment([ key = value ", ...])"
3076 .RI env.Environment([ key = value ", ...])"
3077 Return a new construction environment
3078 initialized with the specified
3082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3084 .RI Execute( action ", [" strfunction ", " varlist ])
3086 .RI env.Execute( action ", [" strfunction ", " varlist ])
3087 Executes an Action object.
3090 may be an Action object
3091 (see the section "Action Objects,"
3092 below, for a complete explanation of the arguments and behavior),
3093 or it may be a command-line string,
3095 or executable Python function,
3096 each of which will be converted
3097 into an Action object
3099 The exit value of the command
3100 or return value of the Python function
3103 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3107 .RI env.Exit([ value ])
3113 A default exit value of
3116 is used if no value is specified.
3118 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3122 .RI env.Export( vars )
3125 to export a list of variables from the current
3126 SConscript file to all other SConscript files.
3127 The exported variables are kept in a global collection,
3128 so subsequent calls to
3130 will over-write previous exports that have the same name.
3131 Multiple variable names can be passed to
3133 as separate arguments or as a list. A dictionary can be used to map
3134 variables to a different name when exported. Both local variables and
3135 global variables can be exported.
3140 # Make env available for all SConscript files to Import().
3144 # Make env and package available for all SConscript files:.
3145 Export("env", "package")
3147 # Make env and package available for all SConscript files:
3148 Export(["env", "package"])
3150 # Make env available using the name debug:.
3151 Export({"debug":env})
3157 function supports an
3159 argument that makes it easier to to export a variable or
3160 set of variables to a single SConscript file.
3161 See the description of the
3165 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3167 .RI File( name ", [" directory ])
3169 .RI env.File( name ", [" directory ])
3172 an object that represents the specified file
3175 can be a relative or absolute path.
3177 is an optional directory that will be used as the parent directory.
3179 File Nodes can be used anywhere you
3180 would supply a string as a file name
3181 to a Builder method or function.
3182 File Nodes have attributes and methods
3183 that are useful in many situations;
3184 see "File and Directory Nodes," below.
3186 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3188 .RI FindFile( file ", " dirs )
3190 .RI env.FindFile( file ", " dirs )
3193 in the path specified by
3196 may be a list of file names or a single file name. In addition to searching
3197 for files that exist in the filesytem, this function also searches for
3198 derived files that have not yet been built.
3201 foo = env.FindFile('foo', ['dir1', 'dir2'])
3204 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3206 .RI Flatten( sequence )
3208 .RI env.Flatten( sequence )
3209 Takes a sequence (that is, a Python list or tuple)
3210 that may contain nested sequences
3211 and returns a flattened list containing
3212 all of the individual elements in any sequence.
3213 This can be helpful for collecting
3214 the lists returned by calls to Builders;
3215 other Builders will automatically
3216 flatten lists specified as input,
3217 but direct Python manipulation of
3218 these lists does not:
3221 foo = Object('foo.c')
3222 bar = Object('bar.c')
3224 # Because `foo' and `bar' are lists returned by the Object() Builder,
3225 # `objects' will be a list containing nested lists:
3226 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3228 # Passing such a list to another Builder is all right because
3229 # the Builder will flatten the list automatically:
3230 Program(source = objects)
3232 # If you need to manipulate the list directly using Python, you need to
3233 # call Flatten() yourself, or otherwise handle nested lists:
3234 for object in Flatten(objects):
3238 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3240 .RI GetBuildPath( file ", [" ... ])
3242 .RI env.GetBuildPath( file ", [" ... ])
3245 path name (or names) for the specified
3253 Nodes or strings representing path names.
3255 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3259 .RI env.GetLaunchDir()
3260 Returns the absolute path name of the directory from which
3263 was initially invoked.
3264 This can be useful when using the
3269 options, which internally
3270 change to the directory in which the
3274 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3276 .RI GetOption( name )
3278 .RI env.GetOption( name )
3279 This function provides a way to query a select subset of the scons command line
3280 options from a SConscript file. See
3282 for a description of the options available.
3284 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3286 '\".RI GlobalBuilders( flag )
3290 '\"adds the names of the default builders
3291 '\"(Program, Library, etc.)
3292 '\"to the global name space
3293 '\"so they can be called without an explicit construction environment.
3294 '\"(This is the default.)
3298 '\"the names of the default builders are removed
3299 '\"from the global name space
3300 '\"so that an explicit construction environment is required
3301 '\"to call all builders.
3303 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3307 .RI env.Help( text )
3308 This specifies help text to be printed if the
3310 argument is given to
3314 is called multiple times, the text is appended together in the order
3319 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3321 .RI Ignore( target ", " dependency )
3323 .RI env.Ignore( target ", " dependency )
3324 The specified dependency file(s)
3325 will be ignored when deciding if
3326 the target file(s) need to be rebuilt.
3329 env.Ignore('foo', 'foo.c')
3330 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3333 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3337 .RI env.Import( vars )
3340 to import a list of variables into the current SConscript file. This
3341 will import variables that were exported with
3347 Variables exported by
3350 Multiple variable names can be passed to
3352 as separate arguments or as a list. The variable "*" can be used
3353 to import all variables.
3358 Import("env", "variable")
3359 Import(["env", "variable"])
3363 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3365 .RI Install( dir ", " source )
3367 .RI env.Install( dir ", " source )
3368 Installs one or more files in a destination directory.
3369 The file names remain the same.
3372 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3375 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3377 .RI InstallAs( target ", " source )
3379 .RI env.InstallAs( target ", " source )
3380 Installs one or more files as specific file names,
3381 allowing changing a file name as part of the
3383 It is an error if the target and source
3384 list different numbers of files.
3387 env.InstallAs(target = '/usr/local/bin/foo',
3388 source = 'foo_debug')
3389 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3390 source = ['libFOO.a', 'libBAR.a'])
3393 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3395 .RI Literal( string )
3397 .RI env.Literal( string )
3400 will be preserved as-is
3401 and not have construction variables expanded.
3403 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3405 .RI Local( targets )
3407 .RI env.Local( targets )
3410 will have copies made in the local tree,
3411 even if an already up-to-date copy
3412 exists in a repository.
3413 Returns a list of the target Node or Nodes.
3415 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3417 .RI env.ParseConfig( command ", [" function ", " unique ])
3420 to modify the environment as specified by the output of
3424 expects the output of a typical
3428 and adds the options
3429 to the appropriate construction variables.
3431 duplicate values are not
3432 added to any construction variables;
3455 construction variables,
3459 option gets added to both the
3466 option gets added to the
3469 Any other strings not associated with options
3470 are assumed to be the names of libraries
3473 construction variable.
3475 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3477 .RI ParseDepends( filename ", [" must_exist ])
3479 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3480 Parses the contents of the specified
3482 as a list of dependencies in the style of
3486 and explicitly establishes all of the listed dependencies.
3495 argument may be set to a non-zero
3498 throw an exception and
3499 generate an error if the file does not exist,
3500 or is otherwise inaccessible.
3504 argument may be set to a non-zero
3507 thrown an exception and
3509 if the file contains dependency
3510 information for more than one target.
3511 This can provide a small sanity check
3512 for files intended to be generated
3513 by, for example, the
3516 which should typically only
3517 write dependency information for
3518 one output file into a corresponding
3524 and all of the files listed therein
3525 will be interpreted relative to
3526 the directory of the
3528 file which calls the
3532 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3535 A factory function that
3536 returns a Builder object
3537 to be used to fetch source files
3538 from the Perforce source code management system.
3539 The returned Builder
3540 is intended to be passed to the
3545 env.SourceCode('.', env.Perforce())
3548 Perforce uses a number of external
3549 environment variables for its operation.
3550 Consequently, this function adds the
3551 following variables from the user's external environment
3552 to the construction environment's
3565 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3567 .RI Platform( string )
3568 Returns a callable object
3569 that can be used to initialize
3570 a construction environment using the
3571 platform keyword of the Environment() method:
3574 env = Environment(platform = Platform('win32'))
3577 .RI env.Platform( string )
3578 Applies the callable object for the specified platform
3580 to the environment through which the method was called.
3583 env.Platform('posix')
3590 variable from the user's external environment
3591 to the construction environment's
3594 This is so that any executed commands
3595 that use sockets to connect with other systems
3596 (such as fetching source files from
3597 external CVS repository specifications like
3598 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3599 will work on Win32 systems.
3601 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3603 .RI Precious( target ", ...)"
3605 .RI env.Precious( target ", ...)"
3608 as precious so it is not deleted before it is rebuilt. Normally
3610 deletes a target before building it.
3611 Multiple targets can be passed in to a single call to
3614 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3616 .RI env.Prepend( key = val ", [...])"
3617 Appends the specified keyword arguments
3618 to the beginning of construction variables in the environment.
3619 If the Environment does not have
3620 the specified construction variable,
3621 it is simply added to the environment.
3622 If the values of the construction variable
3623 and the keyword argument are the same type,
3624 then the two values will be simply added together.
3625 Otherwise, the construction variable
3626 and the value of the keyword argument
3627 are both coerced to lists,
3628 and the lists are added together.
3629 (See also the Append method, above.)
3632 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3635 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3637 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3638 This appends new path elements to the given path in the
3639 specified external environment
3643 any particular path once (leaving the first one it encounters and
3644 ignoring the rest, to preserve path order),
3645 and to help assure this,
3646 will normalize all paths (using
3649 .BR os.path.normcase ).
3650 This can also handle the
3651 case where the given old path variable is a list instead of a
3652 string, in which case a list will be returned instead of a string.
3656 print 'before:',env['ENV']['INCLUDE']
3657 include_path = '/foo/bar:/foo'
3658 env.PrependENVPath('INCLUDE', include_path)
3659 print 'after:',env['ENV']['INCLUDE']
3663 after: /foo/bar:/foo:/biz
3666 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3668 .RI env.AppendUnique( key = val ", [...])"
3669 Appends the specified keyword arguments
3670 to the beginning of construction variables in the environment.
3671 If the Environment does not have
3672 the specified construction variable,
3673 it is simply added to the environment.
3674 If the construction variable being appended to is a list,
3675 then any value(s) that already exist in the
3676 construction variable will
3678 be added again to the list.
3681 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3684 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3687 A factory function that
3688 returns a Builder object
3689 to be used to fetch source files
3691 The returned Builder
3692 is intended to be passed to the
3697 env.SourceCode('.', env.RCS())
3702 will fetch source files
3703 from RCS subdirectories automatically,
3705 as demonstrated in the above example
3706 should only be necessary if
3707 you are fetching from
3710 directory as the source files,
3711 or if you need to explicitly specify RCS
3712 for a specific subdirectory.
3714 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3716 .RI env.Replace( key = val ", [...])"
3717 Replaces construction variables in the Environment
3718 with the specified keyword arguments.
3721 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3724 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3726 .RI Repository( directory )
3728 .RI env.Repository( directory )
3731 is a repository to be searched for files.
3735 and each one adds to the list of
3736 repositories that will be searched.
3740 a repository is a copy of the source tree,
3741 from the top-level directory on down,
3743 both source files and derived files
3744 that can be used to build targets in
3745 the local source tree.
3746 The canonical example would be an
3747 official source tree maintained by an integrator.
3748 If the repository contains derived files,
3749 then the derived files should have been built using
3751 so that the repository contains the necessary
3752 signature information to allow
3754 to figure out when it is appropriate to
3755 use the repository copy of a derived file,
3756 instead of building one locally.
3758 Note that if an up-to-date derived file
3759 already exists in a repository,
3763 make a copy in the local directory tree.
3764 In order to guarantee that a local copy
3770 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3775 what variable(s) to use as the return value(s) of the current SConscript
3776 file. These variables will be returned to the "calling" SConscript file
3777 as the return value(s) of
3779 Multiple variable names should be passed to
3785 Return(["foo", "bar"])
3788 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3790 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3792 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3793 Creates a Scanner object for
3796 See the section "Scanner Objects,"
3797 below, for a complete explanation of the arguments and behavior.
3799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3802 A factory function that
3803 returns a Builder object
3804 to be used to fetch source files
3806 The returned Builder
3807 is intended to be passed to the
3812 env.SourceCode('.', env.SCCS())
3817 will fetch source files
3818 from SCCS subdirectories automatically,
3820 as demonstrated in the above example
3821 should only be necessary if
3822 you are fetching from
3825 directory as the source files,
3826 or if you need to explicitly specify SCCS
3827 for a specific subdirectory.
3829 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3831 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3833 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3835 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3837 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3841 one or more subsidiary SConscript (configuration) files.
3842 There are two ways to call the
3846 The first way you can call
3848 is to explicitly specify one or more
3850 as the first argument.
3851 A single script may be specified as a string;
3852 multiple scripts must be specified as a list
3853 (either explicitly or as created by
3857 The second way you can call
3859 is to specify a list of (sub)directory names
3866 execute a subsidiary configuration file named
3868 in each of the specified directories.
3869 You may specify a name other than
3871 by supplying an optional
3877 argument provides a list of variable names or a dictionary of
3878 named values to export to the
3880 These variables are locally exported only to the specified
3882 and do not affect the
3883 global pool of variables used by
3887 '\"If multiple dirs are provided,
3888 '\"each script gets a fresh export.
3893 function to import the variables.
3897 argument specifies that all of the target files
3898 (for example, object files and executables)
3899 that would normally be built in the subdirectory in which
3901 resides should actually
3905 is interpreted relative to the directory
3906 of the calling SConscript file.
3910 argument specifies that the
3911 source files from which
3912 the target files should be built
3916 is interpreted relative to the directory
3917 of the calling SConscript file.
3921 will link or copy (depending on the platform)
3922 all the source files into the build directory.
3923 This behavior may be disabled by
3924 setting the optional
3927 (it is set to 1 by default),
3930 will refer directly to
3931 the source files in their source directory
3932 when building target files.
3935 is usually safe, and always more efficient
3938 but it may cause build problems in certain end-cases,
3939 such as compiling from source files that
3940 are generated by the build.)
3942 Any variables returned by
3946 will be returned by the call to
3952 SConscript('subdir/SConscript')
3953 foo = SConscript('sub/SConscript', exports='env')
3954 SConscript('dir/SConscript', exports=['env', 'variable'])
3955 SConscript('src/SConscript', build_dir='build', duplicate=0)
3956 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3957 SConscript(dirs=['sub1', 'sub2'])
3958 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3961 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3963 .RI SConscriptChdir( value )
3965 .RI env.SConscriptChdir( value )
3968 changes its working directory
3969 to the directory in which each
3970 subsidiary SConscript file lives.
3971 This behavior may be disabled
3972 by specifying either:
3976 env.SConscriptChdir(0)
3981 will stay in the top-level directory
3982 while reading all SConscript files.
3983 (This may be necessary when building from repositories,
3984 when all the directories in which SConscript files may be found
3985 don't necessarily exist locally.)
3987 You may enable and disable
3988 this ability by calling
3995 SConscript('foo/SConscript') # will not chdir to foo
3996 env.SConscriptChdir(1)
3997 SConscript('bar/SConscript') # will chdir to bar
4000 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4002 .RI SConsignFile([ file , dbm_module ])
4004 .RI env.SConsignFile([ file , dbm_module ])
4007 to store all file signatures
4008 in the specified database
4015 (The actual file name(s) stored on disk
4016 may have an appropriated suffix appended
4021 is not an absolute path name,
4022 the file is placed in the same directory as the top-level
4032 will store file signatures
4035 file in each directory,
4036 not in one global database file.
4037 (This was the default behavior
4038 prior to SCons 0.96.91 and 0.97.)
4042 argument can be used to specify
4043 which Python database module
4044 The default is to use a custom
4046 module that uses pickled
4047 Python data structures,
4048 and which works on all Python versions from 1.5.2 on.
4053 # Explicitly stores signatures in ".sconsign.dblite"
4054 # in the top-level SConstruct directory (the
4055 # default behavior).
4058 # Stores signatures in the file "etc/scons-signatures"
4059 # relative to the top-level SConstruct directory.
4060 SConsignFile("etc/scons-signatures")
4062 # Stores signatures in the specified absolute file name.
4063 SConsignFile("/home/me/SCons/signatures")
4065 # Stores signatures in a separate .sconsign file
4066 # in each directory.
4070 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4072 .RI env.SetDefault(key = val ", [...])"
4073 Sets construction variables to default values specified with the keyword
4074 arguments if (and only if) the variables are not already set.
4075 The following statements are equivalent:
4078 env.SetDefault(FOO = 'foo')
4080 if not env.has_key('FOO'): env['FOO'] = 'foo'
4083 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4085 .RI SetOption( name ", " value )
4087 .RI env.SetOption( name ", " value )
4088 This function provides a way to set a select subset of the scons command
4089 line options from a SConscript file. The options supported are:
4091 which corresponds to -c, --clean, and --remove;
4094 corresponds to --duplicate;
4096 which corresponds to --implicit-cache;
4098 which corresponds to --max-drift;
4100 which corresponds to -j and --jobs.
4101 See the documentation for the
4102 corresponding command line object for information about each specific
4106 SetOption('max_drift', 1)
4109 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4111 .RI SideEffect( side_effect ", " target )
4113 .RI env.SideEffect( side_effect ", " target )
4116 as a side effect of building
4122 can be a list, a file name, or a node.
4123 A side effect is a target that is created
4124 as a side effect of building other targets.
4125 For example, a Windows PDB
4126 file is created as a side effect of building the .obj
4127 files for a static library.
4128 If a target is a side effect of multiple build commands,
4130 will ensure that only one set of commands
4131 is executed at a time.
4132 Consequently, you only need to use this method
4133 for side-effect targets that are built as a result of
4134 multiple build commands.
4136 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4138 .RI SourceCode( entries ", " builder )
4140 .RI env.SourceCode( entries ", " builder )
4141 Arrange for non-existent source files to
4142 be fetched from a source code management system
4147 may be a Node, string or list of both,
4148 and may represent either individual
4149 source files or directories in which
4150 source files can be found.
4152 For any non-existent source files,
4154 will search up the directory tree
4164 will not use a builder to fetch
4165 source files for the specified
4169 builder has been specified
4170 for a directory higher up the tree.
4174 fetch files from SCCS or RCS subdirectories
4175 without explicit configuration.
4176 This takes some extra processing time
4177 to search for the necessary
4178 source code management files on disk.
4179 You can avoid these extra searches
4180 and speed up your build a little
4181 by disabling these searches as follows:
4184 env.SourceCode('.', None)
4188 Note that if the specified
4190 is one you create by hand,
4191 it must have an associated
4192 construction environment to use
4193 when fetching a source file.
4196 provides a set of canned factory
4197 functions that return appropriate
4198 Builders for various popular
4199 source code management systems.
4200 Canonical examples of invocation include:
4203 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4204 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4205 env.SourceCode('/', env.RCS())
4206 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4207 env.SourceCode('no_source.c', None)
4209 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4211 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4213 .RI env.subst( string )
4214 Performs construction variable interpolation
4215 on the specified string argument.
4218 print env.subst("The C compiler is: $CC")
4220 def compile(target, source, env):
4221 sourceDir = env.subst("${SOURCE.srcdir}")
4224 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4226 '\".RI Subversion( repository ", " module )
4227 '\"A factory function that
4228 '\"returns a Builder object
4229 '\"to be used to fetch source files
4230 '\"from the specified Subversion
4232 '\"The returned Builder
4233 '\"is intended to be passed to the
4237 '\"The optional specified
4239 '\"will be added to the beginning
4240 '\"of all repository path names;
4241 '\"this can be used, in essence,
4242 '\"to strip initial directory names
4243 '\"from the repository path names,
4244 '\"so that you only have to
4245 '\"replicate part of the repository
4246 '\"directory hierarchy in your
4247 '\"local build directory:
4250 '\"# Will fetch foo/bar/src.c
4251 '\"# from /usr/local/Subversion/foo/bar/src.c.
4252 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4254 '\"# Will fetch bar/src.c
4255 '\"# from /usr/local/Subversion/foo/bar/src.c.
4256 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4258 '\"# Will fetch src.c
4259 '\"# from /usr/local/Subversion/foo/bar/src.c.
4260 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4263 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4265 .RI SourceSignatures( type )
4267 .RI env.SourceSignatures( type )
4268 This function tells SCons what type of signature to use for source files:
4272 If the environment method is used,
4273 the specified type of source signature
4274 is only used when deciding whether targets
4275 built with that environment are up-to-date or must be rebuilt.
4276 If the global function is used,
4277 the specified type of source signature becomes the default
4278 used for all decisions
4279 about whether targets are up-to-date.
4281 "MD5" means the signature of a source file
4282 is the MD5 checksum of its contents.
4283 "timestamp" means the signature of a source file
4284 is its timestamp (modification time).
4285 There is no different between the two behaviors
4289 "MD5" signatures take longer to compute,
4290 but are more accurate than "timestamp" signatures.
4291 The default is "MD5".
4293 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4297 .RI env.Split( arg )
4298 Returns a list of file names or other objects.
4300 it will be split on strings of white-space characters
4302 making it easier to write long lists of file names.
4303 If arg is already a list,
4304 the list will be returned untouched.
4305 If arg is any other type of object,
4306 it will be returned as a list
4307 containing just the object.
4310 files = Split("f1.c f2.c f3.c")
4311 files = env.Split("f4.c f5.c f6.c")
4319 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4321 .RI TargetSignatures( type )
4323 .RI env.TargetSignatures( type )
4324 This function tells SCons what type of signatures to use
4329 If the environment method is used,
4330 the specified type of signature is only used
4331 for targets built with that environment.
4332 If the global function is used,
4333 the specified type of signature becomes the default
4334 used for all target files that
4335 don't have an explicit target signature type
4336 specified for their environments.
4338 "build" means the signature of a target file
4339 is made by concatenating all of the
4340 signatures of all its source files.
4341 "content" means the signature of a target
4342 file is an MD5 checksum of its contents.
4343 "build" signatures are usually faster to compute,
4344 but "content" signatures can prevent unnecessary rebuilds
4345 when a target file is rebuilt to the exact same contents
4346 as the previous build.
4347 The default is "build".
4349 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4351 .RI Tool( string [, toolpath ", " **kw ])
4352 Returns a callable object
4353 that can be used to initialize
4354 a construction environment using the
4355 tools keyword of the Environment() method.
4356 The object may be called with a construction
4357 environment as an argument,
4358 in which case the object will
4359 add the necessary variables
4360 to the construction environment
4361 and the name of the tool will be added to the
4363 construction variable.
4365 Additional keyword arguments are passed to the tool's
4370 env = Environment(tools = [ Tool('msvc') ])
4374 t(env) # adds 'msvc' to the TOOLS variable
4375 u = Tool('opengl', toolpath = ['tools'])
4376 u(env) # adds 'opengl' to the TOOLS variable
4379 .RI env.Tool( string [, toolpath ", " **kw ])
4380 Applies the callable object for the specified tool
4382 to the environment through which the method was called.
4384 Additional keyword arguments are passed to the tool's
4390 env.Tool('opengl', toolpath = ['build/tools'])
4393 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4397 .RI env.Value( value )
4398 Returns a Node object representing the specified Python value. Value
4399 nodes can be used as dependencies of targets. If the result of
4402 changes between SCons runs, any targets depending on
4404 will be rebuilt. When using timestamp source signatures, Value nodes'
4405 timestamps are equal to the system time when the node is created.
4408 def create(target, source, env):
4409 f = open(str(target[0]), 'wb')
4410 f.write('prefix=' + source[0].get_contents())
4412 prefix = ARGUMENTS.get('prefix', '/usr/local')
4414 env['BUILDERS']['Config'] = Builder(action = create)
4415 env.Config(target = 'package-config', source = Value(prefix))
4418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4420 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4422 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4424 Searches for the specified executable
4426 returning the full path name to the program
4428 and returning None if not.
4429 Searches the specified
4431 the value of the calling environment's PATH
4432 (env['ENV']['PATH']),
4433 or the user's current external PATH
4434 (os.environ['PATH'])
4436 On Win32 systems, searches for executable
4437 programs with any of the file extensions
4438 listed in the specified
4440 the calling environment's PATHEXT
4441 (env['ENV']['PATHEXT'])
4442 or the user's current PATHEXT
4443 (os.environ['PATHEXT'])
4451 .SS SConscript Variables
4452 In addition to the global functions and methods,
4454 supports a number of Python variables
4455 that can be used in SConscript files
4456 to affect how you want the build to be performed.
4457 These variables may be accessed from custom Python modules that you
4458 import into an SConscript file by adding the following
4459 to the Python module:
4462 from SCons.Script import *
4465 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4470 arguments specified on the command line.
4471 Each element in the list is a tuple
4473 .RI ( keyword , value )
4479 elements of the tuple
4481 subscripting for element
4485 of the tuple, respectively.
4488 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4489 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4490 third_tuple = ARGLIST[2]
4491 print "third keyword, value =", third_tuple[0], third_tuple[1]
4492 for key, value in ARGLIST:
4493 # process key and value
4496 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4499 A dictionary of all the
4501 arguments specified on the command line.
4502 The dictionary is not in order,
4503 and if a given keyword has
4504 more than one value assigned to it
4505 on the command line,
4506 the last (right-most) value is
4512 if ARGUMENTS.get('debug', 0):
4513 env = Environment(CCFLAGS = '-g')
4518 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4521 A list of the targets which
4523 will actually try to build,
4524 regardless of whether they were specified on
4525 the command line or via the
4528 The elements of this list may be strings
4530 nodes, so you should run the list through the Python
4532 function to make sure any Node path names
4533 are converted to strings.
4535 Because this list may be taken from the
4536 list of targets specified using the
4539 the contents of the list may change
4540 on each successive call to
4545 for additional information.
4548 if 'foo' in BUILD_TARGETS:
4549 print "Don't forget to test the `foo' program!"
4550 if 'special/program' in BUILD_TARGETS:
4551 SConscript('special')
4556 list only contains targets expected listed
4557 on the command line or via calls to the
4562 contain all dependent targets that will be built as
4563 a result of making the sure the explicitly-specified
4564 targets are up to date.
4566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4568 COMMAND_LINE_TARGETS
4569 A list of the targets explicitly specified on
4571 If there are no targets specified on the command line,
4573 This can be used, for example,
4574 to take specific actions only
4575 when a certain target or targets
4576 is explicitly being built:
4579 if 'foo' in COMMAND_LINE_TARGETS:
4580 print "Don't forget to test the `foo' program!"
4581 if 'special/program' in COMMAND_LINE_TARGETS:
4582 SConscript('special')
4585 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4588 A list of the target
4590 that have been specified using the
4593 The elements of the list are nodes,
4594 so you need to run them through the Python
4596 function to get at the path name for each Node.
4599 print str(DEFAULT_TARGETS[0])
4600 if 'foo' in map(str, DEFAULT_TARGETS):
4601 print "Don't forget to test the `foo' program!"
4606 list change on on each successive call to the
4611 print map(str, DEFAULT_TARGETS) # originally []
4613 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4615 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4617 print map(str, DEFAULT_TARGETS) # back to []
4620 Consequently, be sure to use
4622 only after you've made all of your
4625 or else simply be careful of the order
4626 of these statements in your SConscript files
4627 so that you don't look for a specific
4628 default target before it's actually been added to the list.
4630 .SS Construction Variables
4631 .\" XXX From Gary Ruben, 23 April 2002:
4632 .\" I think it would be good to have an example with each construction
4633 .\" variable description in the documentation.
4635 .\" CC The C compiler
4636 .\" Example: env["CC"] = "c68x"
4637 .\" Default: env["CC"] = "cc"
4639 .\" CCCOM The command line ...
4641 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4642 .\" env["CC"] = "c68x"
4643 .\" env["CFLAGS"] = "-ps -qq -mr"
4644 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4646 .\" (I dunno what this is ;-)
4647 A construction environment has an associated dictionary of
4648 .I construction variables
4649 that are used by built-in or user-supplied build rules.
4650 Construction variables must follow the same rules for
4652 the initial character must be an underscore or letter,
4653 followed by any number of underscores, letters, or digits.
4655 A number of useful construction variables are automatically defined by
4656 scons for each supported platform, and additional construction variables
4657 can be defined by the user. The following is a list of the automatically
4658 defined construction variables:
4661 The static library archiver.
4664 The command line used to generate a static library from object files.
4667 The string displayed when an object file
4668 is generated from an assembly-language source file.
4669 If this is not set, then $ARCOM (the command line) is displayed.
4672 env = Environment(ARCOMSTR = "Archiving $TARGET")
4676 General options passed to the static library archiver.
4682 The command line used to generate an object file
4683 from an assembly-language source file.
4686 The string displayed when an object file
4687 is generated from an assembly-language source file.
4688 If this is not set, then $ASCOM (the command line) is displayed.
4691 env = Environment(ASCOMSTR = "Assembling $TARGET")
4695 General options passed to the assembler.
4698 The command line used to assemble an assembly-language
4699 source file into an object file
4700 after first running the file through the C preprocessor.
4701 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4702 are included on this command line.
4705 The string displayed when an object file
4706 is generated from an assembly-language source file
4707 after first running the file through the C preprocessor.
4708 If this is not set, then $ASPPCOM (the command line) is displayed.
4711 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4715 General options when an assembling an assembly-language
4716 source file into an object file
4717 after first running the file through the C preprocessor.
4718 The default is to use the value of $ASFLAGS.
4721 The bibliography generator for the TeX formatter and typesetter and the
4722 LaTeX structured formatter and typesetter.
4725 The command line used to call the bibliography generator for the
4726 TeX formatter and typesetter and the LaTeX structured formatter and
4730 The string displayed when generating a bibliography
4732 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4735 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4740 General options passed to the bibliography generator for the TeX formatter
4741 and typesetter and the LaTeX structured formatter and typesetter.
4744 The BitKeeper executable.
4747 The command line for
4748 fetching source files using BitKeeper.
4751 The string displayed when fetching
4752 a source file using BitKeeper.
4753 If this is not set, then $BITKEEPERCOM
4754 (the command line) is displayed.
4757 The command ($BITKEEPER) and subcommand
4758 for fetching source files using BitKeeper.
4760 .IP BITKEEPERGETFLAGS
4761 Options that are passed to the BitKeeper
4766 A dictionary mapping the names of the builders
4767 available through this environment
4768 to underlying Builder objects.
4770 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4771 are available by default.
4772 If you initialize this variable when an
4773 Environment is created:
4776 env = Environment(BUILDERS = {'NewBuilder' : foo})
4779 the default Builders will no longer be available.
4780 To use a new Builder object in addition to the default Builders,
4781 add your new Builder object like this:
4785 env.Append(BUILDERS = {'NewBuilder' : foo})
4792 env['BUILDERS]['NewBuilder'] = foo
4799 The command line used to compile a C source file to a (static) object file.
4800 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4801 are included on this command line.
4804 The string displayed when a C source file
4805 is compiled to a (static) object file.
4806 If this is not set, then $CCCOM (the command line) is displayed.
4809 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4813 General options that are passed to the C compiler.
4816 The suffix for C source files.
4817 This is used by the internal CFile builder
4818 when generating C files from Lex (.l) or YACC (.y) input files.
4819 The default suffix, of course, is
4822 On case-insensitive systems (like Win32),
4829 The version number of the C compiler.
4830 This may or may not be set,
4831 depending on the specific C compiler being used.
4834 A function used to produce variables like $_CPPINCFLAGS. It takes
4836 arguments: a prefix to concatenate onto each element, a list of
4837 elements, a suffix to concatenate onto each element, an environment
4838 for variable interpolation, and an optional function that will be
4839 called to transform the list before concatenation.
4842 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4846 A platform independent specification of C preprocessor definitions.
4847 The definitions will be added to command lines
4848 through the automatically-generated
4849 $_CPPDEFFLAGS construction variable (see below),
4850 which is constructed according to
4851 the type of value of $CPPDEFINES:
4854 If $CPPDEFINES is a string,
4856 $CPPDEFPREFIX and $CPPDEFSUFFIX
4857 construction variables
4858 will be added to the beginning and end.
4861 # Will add -Dxyz to POSIX compiler command lines,
4862 # and /Dxyz to Microsoft Visual C++ command lines.
4863 env = Environment(CPPDEFINES='xyz')
4867 If $CPPDEFINES is a list,
4869 $CPPDEFPREFIX and $CPPDEFSUFFIX
4870 construction variables
4871 will be appended to the beginning and end
4872 of each element in the list.
4873 If any element is a list or tuple,
4874 then the first item is the name being
4875 defined and the second item is its value:
4878 # Will add -DB=2 -DA to POSIX compiler command lines,
4879 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4880 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4884 If $CPPDEFINES is a dictionary,
4886 $CPPDEFPREFIX and $CPPDEFSUFFIX
4887 construction variables
4888 will be appended to the beginning and end
4889 of each item from the dictionary.
4890 The key of each dictionary item
4891 is a name being defined
4892 to the dictionary item's corresponding value;
4895 then the name is defined without an explicit value.
4896 Note that the resulting flags are sorted by keyword
4897 to ensure that the order of the options on the
4898 command line is consistent each time
4903 # Will add -DA -DB=2 to POSIX compiler command lines,
4904 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4905 env = Environment(CPPDEFINES={'B':2, 'A':None})
4909 An automatically-generated construction variable
4910 containing the C preprocessor command-line options
4912 The value of $_CPPDEFFLAGS is created
4913 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4914 to the beginning and end
4915 of each directory in $CPPDEFINES.
4918 The prefix used to specify preprocessor definitions
4919 on the C compiler command line.
4920 This will be appended to the beginning of each definition
4921 in the $CPPDEFINES construction variable
4922 when the $_CPPDEFFLAGS variable is automatically generated.
4925 The suffix used to specify preprocessor definitions
4926 on the C compiler command line.
4927 This will be appended to the end of each definition
4928 in the $CPPDEFINES construction variable
4929 when the $_CPPDEFFLAGS variable is automatically generated.
4932 User-specified C preprocessor options.
4933 These will be included in any command that uses the C preprocessor,
4934 including not just compilation of C and C++ source files
4935 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4936 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4937 $F77PPCOM and $SHF77PPCOM command lines
4938 used to compile a Fortran source file,
4939 and the $ASPPCOM command line
4940 used to assemble an assembly language source file,
4941 after first running each file through the C preprocessor.
4942 Note that this variable does
4946 (or similar) include search path options
4947 that scons generates automatically from $CPPPATH.
4951 for the variable that expands to those options.
4954 An automatically-generated construction variable
4955 containing the C preprocessor command-line options
4956 for specifying directories to be searched for include files.
4957 The value of $_CPPINCFLAGS is created
4958 by appending $INCPREFIX and $INCSUFFIX
4959 to the beginning and end
4960 of each directory in $CPPPATH.
4963 The list of directories that the C preprocessor will search for include
4964 directories. The C/C++ implicit dependency scanner will search these
4965 directories for include files. Don't explicitly put include directory
4966 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4967 and the directories will not be searched by the dependency scanner. Note:
4968 directory names in CPPPATH will be looked-up relative to the SConscript
4969 directory when they are used in a command. To force
4971 to look-up a directory relative to the root of the source tree use #:
4974 env = Environment(CPPPATH='#/include')
4978 The directory look-up can also be forced using the
4983 include = Dir('include')
4984 env = Environment(CPPPATH=include)
4988 The directory list will be added to command lines
4989 through the automatically-generated
4991 construction variable,
4992 which is constructed by
4993 appending the values of the
4994 $INCPREFIX and $INCSUFFIX
4995 construction variables
4996 to the beginning and end
4997 of each directory in $CPPPATH.
4998 Any command lines you define that need
4999 the CPPPATH directory list should
5000 include $_CPPINCFLAGS:
5003 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5007 The list of suffixes of files that will be scanned
5008 for C preprocessor implicit dependencies
5010 The default list is:
5013 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5014 ".h", ".H", ".hxx", ".hpp", ".hh",
5015 ".F", ".fpp", ".FPP",
5017 ".S", ".spp", ".SPP"]
5024 Options that are passed to the CVS checkout subcommand.
5027 The command line used to
5028 fetch source files from a CVS repository.
5031 The string displayed when fetching
5032 a source file from a CVS repository.
5033 If this is not set, then $CVSCOM
5034 (the command line) is displayed.
5037 General options that are passed to CVS.
5038 By default, this is set to
5040 to specify from where the files must be fetched.
5043 The path to the CVS repository.
5044 This is referenced in the default
5051 The suffix for C++ source files.
5052 This is used by the internal CXXFile builder
5053 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
5054 The default suffix is
5056 SCons also treats files with the suffixes
5065 suffixes as Objective C++ files.
5066 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5073 The command line used to compile a C++ source file to an object file.
5074 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
5075 are included on this command line.
5078 The string displayed when a C++ source file
5079 is compiled to a (static) object file.
5080 If this is not set, then $CXXCOM (the command line) is displayed.
5083 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5087 General options that are passed to the C++ compiler.
5088 By default, this includes the value of $CCFLAGS,
5089 so that setting $CCFLAGS affects both C and C++ compilation.
5090 If you want to add C++-specific flags,
5091 you must set or override the value of $CXXFLAGS.
5094 The version number of the C++ compiler.
5095 This may or may not be set,
5096 depending on the specific C++ compiler being used.
5099 A function that converts a file name into a Dir instance relative to the
5103 The list of suffixes of files that will be scanned
5104 for imported D package files.
5105 The default list is:
5112 The TeX DVI file to PDF file converter.
5115 General options passed to the TeX DVI file to PDF file converter.
5118 The command line used to convert TeX DVI files into a PDF file.
5121 The string displayed when a TeX DVI file
5122 is converted into a PDF file.
5123 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5126 The TeX DVI file to PostScript converter.
5129 General options passed to the TeX DVI file to PostScript converter.
5132 A dictionary of environment variables
5133 to use when invoking commands. When ENV is used in a command all list
5134 values will be joined using the path separator and any other non-string
5135 values will simply be coerced to a string.
5136 Note that, by default,
5140 propagate the environment in force when you
5143 to the commands used to build target files.
5144 This is so that builds will be guaranteed
5145 repeatable regardless of the environment
5146 variables set at the time
5150 If you want to propagate your
5151 environment variables
5152 to the commands executed
5153 to build target files,
5154 you must do so explicitly:
5158 env = Environment(ENV = os.environ)
5162 Note that you can choose only to propagate
5163 certain environment variables.
5167 environment variable,
5170 uses the same utilities
5171 as the invoking shell (or other process):
5176 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5180 A function that will be called to escape shell special characters in
5181 command lines. The function should take one argument: the command line
5182 string to escape; and should return the escaped command line.
5185 The Fortran 77 compiler.
5186 You should normally set the $FORTRAN variable,
5187 which specifies the default Fortran compiler
5188 for all Fortran versions.
5189 You only need to set $F77 if you need to use a specific compiler
5190 or compiler version for Fortran 77 files.
5193 The command line used to compile a Fortran 77 source file to an object file.
5194 You only need to set $F77COM if you need to use a specific
5195 command line for Fortran 77 files.
5196 You should normally set the $FORTRANCOM variable,
5197 which specifies the default command line
5198 for all Fortran versions.
5201 The string displayed when a Fortran 77 source file
5202 is compiled to an object file.
5203 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5206 General user-specified options that are passed to the Fortran 77 compiler.
5207 Note that this variable does
5211 (or similar) include search path options
5212 that scons generates automatically from $F77PATH.
5216 for the variable that expands to those options.
5217 You only need to set $F77FLAGS if you need to define specific
5218 user options for Fortran 77 files.
5219 You should normally set the $FORTRANFLAGS variable,
5220 which specifies the user-specified options
5221 passed to the default Fortran compiler
5222 for all Fortran versions.
5225 An automatically-generated construction variable
5226 containing the Fortran 77 compiler command-line options
5227 for specifying directories to be searched for include files.
5228 The value of $_F77INCFLAGS is created
5229 by appending $INCPREFIX and $INCSUFFIX
5230 to the beginning and end
5231 of each directory in $F77PATH.
5234 The list of directories that the Fortran 77 compiler will search for include
5235 directories. The implicit dependency scanner will search these
5236 directories for include files. Don't explicitly put include directory
5237 arguments in $F77FLAGS because the result will be non-portable
5238 and the directories will not be searched by the dependency scanner. Note:
5239 directory names in $F77PATH will be looked-up relative to the SConscript
5240 directory when they are used in a command. To force
5242 to look-up a directory relative to the root of the source tree use #:
5243 You only need to set $F77PATH if you need to define a specific
5244 include path for Fortran 77 files.
5245 You should normally set the $FORTRANPATH variable,
5246 which specifies the include path
5247 for the default Fortran compiler
5248 for all Fortran versions.
5251 env = Environment(F77PATH='#/include')
5255 The directory look-up can also be forced using the
5260 include = Dir('include')
5261 env = Environment(F77PATH=include)
5265 The directory list will be added to command lines
5266 through the automatically-generated
5268 construction variable,
5269 which is constructed by
5270 appending the values of the
5271 $INCPREFIX and $INCSUFFIX
5272 construction variables
5273 to the beginning and end
5274 of each directory in $F77PATH.
5275 Any command lines you define that need
5276 the F77PATH directory list should
5277 include $_F77INCFLAGS:
5280 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5284 The command line used to compile a Fortran 77 source file to an object file
5285 after first running the file through the C preprocessor.
5286 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5287 are included on this command line.
5288 You only need to set $F77PPCOM if you need to use a specific
5289 C-preprocessor command line for Fortran 77 files.
5290 You should normally set the $FORTRANPPCOM variable,
5291 which specifies the default C-preprocessor command line
5292 for all Fortran versions.
5295 The Fortran 90 compiler.
5296 You should normally set the $FORTRAN variable,
5297 which specifies the default Fortran compiler
5298 for all Fortran versions.
5299 You only need to set $F90 if you need to use a specific compiler
5300 or compiler version for Fortran 90 files.
5303 The command line used to compile a Fortran 90 source file to an object file.
5304 You only need to set $F90COM if you need to use a specific
5305 command line for Fortran 90 files.
5306 You should normally set the $FORTRANCOM variable,
5307 which specifies the default command line
5308 for all Fortran versions.
5311 The string displayed when a Fortran 90 source file
5312 is compiled to an object file.
5313 If this is not set, then $F90COM or $FORTRANCOM
5314 (the command line) is displayed.
5317 General user-specified options that are passed to the Fortran 90 compiler.
5318 Note that this variable does
5322 (or similar) include search path options
5323 that scons generates automatically from $F90PATH.
5327 for the variable that expands to those options.
5328 You only need to set $F90FLAGS if you need to define specific
5329 user options for Fortran 90 files.
5330 You should normally set the $FORTRANFLAGS variable,
5331 which specifies the user-specified options
5332 passed to the default Fortran compiler
5333 for all Fortran versions.
5336 An automatically-generated construction variable
5337 containing the Fortran 90 compiler command-line options
5338 for specifying directories to be searched for include files.
5339 The value of $_F90INCFLAGS is created
5340 by appending $INCPREFIX and $INCSUFFIX
5341 to the beginning and end
5342 of each directory in $F90PATH.
5345 The list of directories that the Fortran 90 compiler will search for include
5346 directories. The implicit dependency scanner will search these
5347 directories for include files. Don't explicitly put include directory
5348 arguments in $F90FLAGS because the result will be non-portable
5349 and the directories will not be searched by the dependency scanner. Note:
5350 directory names in $F90PATH will be looked-up relative to the SConscript
5351 directory when they are used in a command. To force
5353 to look-up a directory relative to the root of the source tree use #:
5354 You only need to set $F90PATH if you need to define a specific
5355 include path for Fortran 90 files.
5356 You should normally set the $FORTRANPATH variable,
5357 which specifies the include path
5358 for the default Fortran compiler
5359 for all Fortran versions.
5362 env = Environment(F90PATH='#/include')
5366 The directory look-up can also be forced using the
5371 include = Dir('include')
5372 env = Environment(F90PATH=include)
5376 The directory list will be added to command lines
5377 through the automatically-generated
5379 construction variable,
5380 which is constructed by
5381 appending the values of the
5382 $INCPREFIX and $INCSUFFIX
5383 construction variables
5384 to the beginning and end
5385 of each directory in $F90PATH.
5386 Any command lines you define that need
5387 the F90PATH directory list should
5388 include $_F90INCFLAGS:
5391 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5395 The command line used to compile a Fortran 90 source file to an object file
5396 after first running the file through the C preprocessor.
5397 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5398 are included on this command line.
5399 You only need to set $F90PPCOM if you need to use a specific
5400 C-preprocessor command line for Fortran 90 files.
5401 You should normally set the $FORTRANPPCOM variable,
5402 which specifies the default C-preprocessor command line
5403 for all Fortran versions.
5406 The Fortran 95 compiler.
5407 You should normally set the $FORTRAN variable,
5408 which specifies the default Fortran compiler
5409 for all Fortran versions.
5410 You only need to set $F95 if you need to use a specific compiler
5411 or compiler version for Fortran 95 files.
5414 The command line used to compile a Fortran 95 source file to an object file.
5415 You only need to set $F95COM if you need to use a specific
5416 command line for Fortran 95 files.
5417 You should normally set the $FORTRANCOM variable,
5418 which specifies the default command line
5419 for all Fortran versions.
5422 The string displayed when a Fortran 95 source file
5423 is compiled to an object file.
5424 If this is not set, then $F95COM or $FORTRANCOM
5425 (the command line) is displayed.
5428 General user-specified options that are passed to the Fortran 95 compiler.
5429 Note that this variable does
5433 (or similar) include search path options
5434 that scons generates automatically from $F95PATH.
5438 for the variable that expands to those options.
5439 You only need to set $F95FLAGS if you need to define specific
5440 user options for Fortran 95 files.
5441 You should normally set the $FORTRANFLAGS variable,
5442 which specifies the user-specified options
5443 passed to the default Fortran compiler
5444 for all Fortran versions.
5447 An automatically-generated construction variable
5448 containing the Fortran 95 compiler command-line options
5449 for specifying directories to be searched for include files.
5450 The value of $_F95INCFLAGS is created
5451 by appending $INCPREFIX and $INCSUFFIX
5452 to the beginning and end
5453 of each directory in $F95PATH.
5456 The list of directories that the Fortran 95 compiler will search for include
5457 directories. The implicit dependency scanner will search these
5458 directories for include files. Don't explicitly put include directory
5459 arguments in $F95FLAGS because the result will be non-portable
5460 and the directories will not be searched by the dependency scanner. Note:
5461 directory names in $F95PATH will be looked-up relative to the SConscript
5462 directory when they are used in a command. To force
5464 to look-up a directory relative to the root of the source tree use #:
5465 You only need to set $F95PATH if you need to define a specific
5466 include path for Fortran 95 files.
5467 You should normally set the $FORTRANPATH variable,
5468 which specifies the include path
5469 for the default Fortran compiler
5470 for all Fortran versions.
5473 env = Environment(F95PATH='#/include')
5477 The directory look-up can also be forced using the
5482 include = Dir('include')
5483 env = Environment(F95PATH=include)
5487 The directory list will be added to command lines
5488 through the automatically-generated
5490 construction variable,
5491 which is constructed by
5492 appending the values of the
5493 $INCPREFIX and $INCSUFFIX
5494 construction variables
5495 to the beginning and end
5496 of each directory in $F95PATH.
5497 Any command lines you define that need
5498 the F95PATH directory list should
5499 include $_F95INCFLAGS:
5502 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5506 The command line used to compile a Fortran 95 source file to an object file
5507 after first running the file through the C preprocessor.
5508 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5509 are included on this command line.
5510 You only need to set $F95PPCOM if you need to use a specific
5511 C-preprocessor command line for Fortran 95 files.
5512 You should normally set the $FORTRANPPCOM variable,
5513 which specifies the default C-preprocessor command line
5514 for all Fortran versions.
5517 The default Fortran compiler
5518 for all versions of Fortran.
5521 The command line used to compile a Fortran source file to an object file.
5522 By default, any options specified
5523 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5524 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5525 are included on this command line.
5528 The string displayed when a Fortran source file
5529 is compiled to an object file.
5530 If this is not set, then $FORTRANCOM
5531 (the command line) is displayed.
5534 General user-specified options that are passed to the Fortran compiler.
5535 Note that this variable does
5539 (or similar) include or module search path options
5540 that scons generates automatically from $FORTRANPATH.
5542 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5544 for the variables that expand those options.
5546 .IP _FORTRANINCFLAGS
5547 An automatically-generated construction variable
5548 containing the Fortran compiler command-line options
5549 for specifying directories to be searched for include
5550 files and module files.
5551 The value of $_FORTRANINCFLAGS is created
5552 by prepending/appending $INCPREFIX and $INCSUFFIX
5553 to the beginning and end
5554 of each directory in $FORTRANPATH.
5557 Directory location where the Fortran compiler should place
5558 any module files it generates. This variable is empty, by default. Some
5559 Fortran compilers will internally append this directory in the search path
5560 for module files, as well
5562 .IP FORTRANMODDIRPREFIX
5563 The prefix used to specify a module directory on the Fortran compiler command
5565 This will be appended to the beginning of the directory
5566 in the $FORTRANMODDIR construction variables
5567 when the $_FORTRANMODFLAG variables is automatically generated.
5569 .IP FORTRANMODDIRSUFFIX
5570 The suffix used to specify a module directory on the Fortran compiler command
5572 This will be appended to the beginning of the directory
5573 in the $FORTRANMODDIR construction variables
5574 when the $_FORTRANMODFLAG variables is automatically generated.
5577 An automatically-generated construction variable
5578 containing the Fortran compiler command-line option
5579 for specifying the directory location where the Fortran
5580 compiler should place any module files that happen to get
5581 generated during compilation.
5582 The value of $_FORTRANMODFLAG is created
5583 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5584 to the beginning and end of the directory in $FORTRANMODDIR.
5586 .IP FORTRANMODPREFIX
5587 The module file prefix used by the Fortran compiler. SCons assumes that
5588 the Fortran compiler follows the quasi-standard naming convention for
5590 .I <module_name>.mod.
5591 As a result, this variable is left empty, by default. For situations in
5592 which the compiler does not necessarily follow the normal convention,
5593 the user may use this variable. Its value will be appended to every
5594 module file name as scons attempts to resolve dependencies.
5596 .IP FORTRANMODSUFFIX
5597 The module file suffix used by the Fortran compiler. SCons assumes that
5598 the Fortran compiler follows the quasi-standard naming convention for
5600 .I <module_name>.mod.
5601 As a result, this variable is set to ".mod", by default. For situations
5602 in which the compiler does not necessarily follow the normal convention,
5603 the user may use this variable. Its value will be appended to every
5604 module file name as scons attempts to resolve dependencies.
5607 The list of directories that the Fortran compiler will search for
5608 include files and (for some compilers) module files. The Fortran implicit
5609 dependency scanner will search these directories for include files (but
5610 not module files since they are autogenerated and, as such, may not
5611 actually exist at the time the scan takes place). Don't explicitly put
5612 include directory arguments in FORTRANFLAGS because the result will be
5613 non-portable and the directories will not be searched by the dependency
5614 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5615 to the SConscript directory when they are used in a command. To force
5617 to look-up a directory relative to the root of the source tree use #:
5620 env = Environment(FORTRANPATH='#/include')
5624 The directory look-up can also be forced using the
5629 include = Dir('include')
5630 env = Environment(FORTRANPATH=include)
5634 The directory list will be added to command lines
5635 through the automatically-generated
5637 construction variable,
5638 which is constructed by
5639 appending the values of the
5640 $INCPREFIX and $INCSUFFIX
5641 construction variables
5642 to the beginning and end
5643 of each directory in $FORTRANPATH.
5644 Any command lines you define that need
5645 the FORTRANPATH directory list should
5646 include $_FORTRANINCFLAGS:
5649 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5653 The command line used to compile a Fortran source file to an object file
5654 after first running the file through the C preprocessor.
5655 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5656 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5657 construction variables are included on this command line.
5660 The list of suffixes of files that will be scanned
5661 for Fortran implicit dependencies
5662 (INCLUDE lines & USE statements).
5663 The default list is:
5666 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5667 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5671 A function that converts a file name into a File instance relative to the
5676 frameworks options to be added at
5677 the end of a command
5678 line building a loadable module.
5681 The Ghostscript program used to convert PostScript to PDF files.
5684 General options passed to the Ghostscript program
5685 when converting PostScript to PDF files.
5688 The Ghostscript command line used to convert PostScript to PDF files.
5691 The string displayed when
5692 Ghostscript is used to convert
5693 a PostScript file to a PDF file.
5694 If this is not set, then $GSCOM (the command line) is displayed.
5697 The list of suffixes of files that will be scanned
5698 for IDL implicit dependencies
5699 (#include or import lines).
5700 The default list is:
5707 The prefix used to specify an include directory on the C compiler command
5709 This will be appended to the beginning of each directory
5710 in the $CPPPATH and $FORTRANPATH construction variables
5711 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5712 variables are automatically generated.
5715 The suffix used to specify an include directory on the C compiler command
5717 This will be appended to the end of each directory
5718 in the $CPPPATH and $FORTRANPATH construction variables
5719 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5720 variables are automatically generated.
5723 A function to be called to install a file into a
5724 destination file name.
5725 The default function copies the file into the destination
5726 (and sets the destination file's mode and permission bits
5727 to match the source file's).
5728 The function takes the following arguments:
5731 def install(dest, source, env):
5735 is the path name of the destination file.
5737 is the path name of the source file.
5739 is the construction environment
5740 (a dictionary of construction values)
5741 in force for this file installation.
5743 .IP INTEL_C_COMPILER_VERSION
5744 Set by the "intelc" Tool
5745 to the major version number of the Intel C compiler
5749 The Java archive tool.
5752 The directory to which the Java archive tool should change
5758 The command line used to call the Java archive tool.
5761 The string displayed when the Java archive tool
5763 If this is not set, then $JARCOM (the command line) is displayed.
5766 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5770 General options passed to the Java archive tool.
5771 By default this is set to
5773 to create the necessary
5778 The suffix for Java archives:
5786 The command line used to compile a directory tree containing
5787 Java source files to
5788 corresponding Java class files.
5789 Any options specified in the $JAVACFLAGS construction variable
5790 are included on this command line.
5793 The string displayed when compiling
5794 a directory tree of Java source files to
5795 corresponding Java class files.
5796 If this is not set, then $JAVACCOM (the command line) is displayed.
5799 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5803 General options that are passed to the Java compiler.
5806 The directory in which Java class files may be found.
5807 This is stripped from the beginning of any Java .class
5808 file names supplied to the
5813 The suffix for Java class files;
5818 The Java generator for C header and stub files.
5821 The command line used to generate C header and stub files
5823 Any options specified in the $JAVAHFLAGS construction variable
5824 are included on this command line.
5827 The string displayed when C header and stub files
5828 are generated from Java classes.
5829 If this is not set, then $JAVAHCOM (the command line) is displayed.
5832 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5836 General options passed to the C header and stub file generator
5840 The suffix for Java files;
5845 The LaTeX structured formatter and typesetter.
5848 The command line used to call the LaTeX structured formatter and typesetter.
5851 The string displayed when calling
5852 the LaTeX structured formatter and typesetter.
5853 If this is not set, then $LATEXCOM (the command line) is displayed.
5856 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5860 General options passed to the LaTeX structured formatter and typesetter.
5863 The linker for building loadable modules.
5864 By default, this is the same as $SHLINK.
5867 The command line for building loadable modules.
5868 On Mac OS X, this uses the $LDMODULE,
5869 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
5870 On other systems, this is the same as $SHLINK.
5873 The string displayed when building loadable modules.
5874 If this is not set, then $LDMODULECOM (the command line) is displayed.
5877 General user options passed to the linker for building loadable modules.
5880 The prefix used for loadable module file names.
5881 On Mac OS X, this is null;
5882 on other systems, this is
5883 the same as $SHLIBPREFIX.
5886 The suffix used for loadable module file names.
5887 On Mac OS X, this is null;
5888 on other systems, this is
5889 the same as $SHLIBSUFFIX.
5892 The lexical analyzer generator.
5895 General options passed to the lexical analyzer generator.
5898 The command line used to call the lexical analyzer generator
5899 to generate a source file.
5902 The string displayed when generating a source file
5903 using the lexical analyzer generator.
5904 If this is not set, then $LEXCOM (the command line) is displayed.
5907 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5911 An automatically-generated construction variable
5912 containing the linker command-line options
5913 for specifying directories to be searched for library.
5914 The value of $_LIBDIRFLAGS is created
5915 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5916 to the beginning and end
5917 of each directory in $LIBPATH.
5920 The prefix used to specify a library directory on the linker command line.
5921 This will be appended to the beginning of each directory
5922 in the $LIBPATH construction variable
5923 when the $_LIBDIRFLAGS variable is automatically generated.
5926 The suffix used to specify a library directory on the linker command line.
5927 This will be appended to the end of each directory
5928 in the $LIBPATH construction variable
5929 when the $_LIBDIRFLAGS variable is automatically generated.
5932 An automatically-generated construction variable
5933 containing the linker command-line options
5934 for specifying libraries to be linked with the resulting target.
5935 The value of $_LIBFLAGS is created
5936 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5937 to the beginning and end
5938 of each filename in $LIBS.
5941 The prefix used to specify a library to link on the linker command line.
5942 This will be appended to the beginning of each library
5943 in the $LIBS construction variable
5944 when the $_LIBFLAGS variable is automatically generated.
5947 The suffix used to specify a library to link on the linker command line.
5948 This will be appended to the end of each library
5949 in the $LIBS construction variable
5950 when the $_LIBFLAGS variable is automatically generated.
5953 The list of directories that will be searched for libraries.
5954 The implicit dependency scanner will search these
5955 directories for include files. Don't explicitly put include directory
5956 arguments in $LINKFLAGS or $SHLINKFLAGS
5957 because the result will be non-portable
5958 and the directories will not be searched by the dependency scanner. Note:
5959 directory names in LIBPATH will be looked-up relative to the SConscript
5960 directory when they are used in a command. To force
5962 to look-up a directory relative to the root of the source tree use #:
5965 env = Environment(LIBPATH='#/libs')
5969 The directory look-up can also be forced using the
5975 env = Environment(LIBPATH=libs)
5979 The directory list will be added to command lines
5980 through the automatically-generated
5982 construction variable,
5983 which is constructed by
5984 appending the values of the
5985 $LIBDIRPREFIX and $LIBDIRSUFFIX
5986 construction variables
5987 to the beginning and end
5988 of each directory in $LIBPATH.
5989 Any command lines you define that need
5990 the LIBPATH directory list should
5991 include $_LIBDIRFLAGS:
5994 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5998 The prefix used for (static) library file names.
5999 A default value is set for each platform
6000 (posix, win32, os2, etc.),
6001 but the value is overridden by individual tools
6002 (ar, mslib, sgiar, sunar, tlib, etc.)
6003 to reflect the names of the libraries they create.
6006 An array of legal prefixes for library file names.
6009 A list of one or more libraries
6010 that will be linked with
6011 any executable programs
6012 created by this environment.
6015 The library list will be added to command lines
6016 through the automatically-generated
6018 construction variable,
6019 which is constructed by
6020 appending the values of the
6021 $LIBLINKPREFIX and $LIBLINKSUFFIX
6022 construction variables
6023 to the beginning and end
6024 of each filename in $LIBS.
6025 Any command lines you define that need
6026 the LIBS library list should
6030 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6038 list, the name of that file will be added to
6040 and thus the link line, as is, without
6046 env.Append(LIBS=File('/tmp/mylib.so'))
6050 In all cases, scons will add dependencies from the executable program to
6051 all the libraries in this list.
6054 The suffix used for (static) library file names.
6055 A default value is set for each platform
6056 (posix, win32, os2, etc.),
6057 but the value is overridden by individual tools
6058 (ar, mslib, sgiar, sunar, tlib, etc.)
6059 to reflect the names of the libraries they create.
6062 An array of legal suffixes for library file names.
6068 General user options passed to the linker.
6069 Note that this variable should
6073 (or similar) options for linking with the libraries listed in $LIBS,
6076 (or similar) library search path options
6077 that scons generates automatically from $LIBPATH.
6081 for the variable that expands to library-link options,
6085 for the variable that expands to library search path options.
6088 The command line used to link object files into an executable.
6091 The string displayed when object files
6092 are linked into an executable.
6093 If this is not set, then $LINKCOM (the command line) is displayed.
6096 env = Environment(LINKCOMSTR = "Linking $TARGET")
6100 The M4 macro preprocessor.
6103 General options passed to the M4 macro preprocessor.
6106 The command line used to pass files through the M4 macro preprocessor.
6109 The string displayed when
6110 a file is passed through the M4 macro preprocessor.
6111 If this is not set, then $M4COM (the command line) is displayed.
6114 The maximum number of characters allowed on an external command line.
6116 link lines longer than this many characters
6117 are linke via a temporary file name.
6120 When the Microsoft Visual Studio tools are initialized, they set up
6121 this dictionary with the following keys:
6124 the version of MSVS being used (can be set via
6128 the available versions of MSVS installed
6131 installed directory of Visual C++
6134 installed directory of Visual Studio
6137 installed directory of the .NET framework
6139 .B FRAMEWORKVERSIONS:
6140 list of installed versions of the .NET framework, sorted latest to oldest.
6142 .B FRAMEWORKVERSION:
6143 latest installed version of the .NET framework
6146 installed location of the .NET SDK.
6149 installed location of the Platform SDK.
6151 .B PLATFORMSDK_MODULES:
6152 dictionary of installed Platform SDK modules,
6153 where the dictionary keys are keywords for the various modules, and
6154 the values are 2-tuples where the first is the release date, and the
6155 second is the version number.
6157 If a value isn't set, it wasn't available in the registry.
6159 .IP MSVS_IGNORE_IDE_PATHS
6160 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6161 instead of the settings from the IDE.
6163 For Visual Studio, SCons will (by default) automatically determine
6164 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6165 set by the IDE. You can override this behavior by setting these
6166 variables after Environment initialization, or by setting
6167 .B MSVS_IGNORE_IDE_PATHS = 1
6168 in the Environment initialization.
6169 Specifying this will not leave these unset, but will set them to a
6170 minimal set of paths needed to run the tools successfully.
6173 For VS6, the mininimal set is:
6174 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6175 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6176 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6178 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6179 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6180 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6184 Where '<VSDir>' is the installed location of Visual Studio.
6186 .IP MSVS_USE_MFC_DIRS
6187 Tells the MS Visual Studio tool(s) to use
6188 the MFC directories in its default paths
6189 for compiling and linking.
6190 Under MSVS version 6,
6192 .B MSVS_USE_MFC_DIRS
6201 external environment variable,
6207 external environment variable.
6208 Under MSVS version 7,
6210 .B MSVS_USE_MFC_DIRS
6213 .B "atlmfc\\\\include"
6214 directory to the default
6216 external environment variable,
6219 directory to the default
6221 external environment variable.
6222 The current default value is
6224 which means these directories
6225 are added to the paths by default.
6226 This default value is likely to change
6227 in a future release,
6228 so users who want the ATL and MFC
6229 values included in their paths
6230 are encouraged to enable the
6231 .B MSVS_USE_MFC_DIRS
6233 to avoid future incompatibility.
6234 This variable has no effect if the
6238 environment variables are set explictly.
6241 Sets the preferred version of MSVS to use.
6243 SCons will (by default) select the latest version of MSVS
6244 installed on your machine. So, if you have version 6 and version 7
6245 (MSVS .NET) installed, it will prefer version 7. You can override this by
6248 variable in the Environment initialization, setting it to the
6249 appropriate version ('6.0' or '7.0', for example).
6250 If the given version isn't installed, tool initialization will fail.
6253 The action used to generate Microsoft Visual Studio
6254 project and solution files.
6256 .IP MSVSPROJECTSUFFIX
6257 The suffix used for Microsoft Visual Studio project (DSP) files.
6258 The default value is
6260 when using Visual Studio version 7.x (.NET),
6263 when using earlier versions of Visual Studio.
6265 .IP MSVSSOLUTIONSUFFIX
6266 The suffix used for Microsoft Visual Studio solution (DSW) files.
6267 The default value is
6269 when using Visual Studio version 7.x (.NET),
6272 when using earlier versions of Visual Studio.
6275 The version number of the MetroWerks CodeWarrior C compiler
6279 A list of installed versions of the MetroWerks CodeWarrior C compiler
6283 When set to non-zero,
6284 suppresses creation of a corresponding Win32 static import lib by the
6286 builder when used with
6287 MinGW or Microsoft Visual Studio.
6288 This also suppresses creation
6289 of an export (.exp) file
6290 when using Microsoft Visual Studio.
6293 The prefix used for (static) object file names.
6296 The suffix used for (static) object file names.
6299 The Perforce executable.
6302 The command line used to
6303 fetch source files from Perforce.
6306 The string displayed when
6307 fetching a source file from Perforce.
6308 If this is not set, then $P4COM (the command line) is displayed.
6311 General options that are passed to Perforce.
6314 The Microsoft Visual C++ precompiled header that will be used when compiling
6315 object files. This variable is ignored by tools other than Microsoft Visual C++.
6316 When this variable is
6317 defined SCons will add options to the compiler command line to
6318 cause it to use the precompiled header, and will also set up the
6319 dependencies for the PCH file. Example:
6322 env['PCH'] = 'StdAfx.pch'
6326 The command line used by the
6328 builder to generated a precompiled header.
6331 The string displayed when generating a precompiled header.
6332 If this is not set, then $PCHCOM (the command line) is displayed.
6335 This variable specifies how much of a source file is precompiled. This
6336 variable is ignored by tools other than Microsoft Visual C++, or when
6337 the PCH variable is not being used. When this variable is define it
6338 must be a string that is the name of the header that
6339 is included at the end of the precompiled portion of the source files, or
6340 the empty string if the "#pragma hrdstop" construct is being used:
6343 env['PCHSTOP'] = 'StdAfx.h'
6347 The Microsoft Visual C++ PDB file that will store debugging information for
6348 object files, shared libraries, and programs. This variable is ignored by
6349 tools other than Microsoft Visual C++.
6350 When this variable is
6351 defined SCons will add options to the compiler and linker command line to
6352 cause them to generate external debugging information, and will also set up the
6353 dependencies for the PDB file. Example:
6356 env['PDB'] = 'hello.pdb'
6360 A deprecated synonym for $DVIPDFCOM.
6363 The prefix used for PDF file names.
6366 The suffix used for PDF file names.
6369 The name of the platform used to create the Environment. If no platform is
6370 specified when the Environment is created,
6372 autodetects the platform.
6375 env = Environment(tools = [])
6376 if env['PLATFORM'] == 'cygwin':
6382 .IP PRINT_CMD_LINE_FUNC
6383 A Python function used to print the command lines as they are executed
6384 (assuming command printing is not disabled by the
6388 options or their equivalents).
6389 The function should take four arguments:
6391 the command being executed (a string),
6393 the target being built (file node, list, or string name(s)),
6395 the source(s) used (file node, list, or string name(s)), and
6397 the environment being used.
6399 The function must do the printing itself. The default implementation,
6400 used if this variable is not set or is None, is:
6402 def print_cmd_line(s, target, source, env):
6403 sys.stdout.write(s + "\n")
6406 Here's an example of a more interesting function:
6408 def print_cmd_line(s, target, source, env):
6409 sys.stdout.write("Building %s -> %s...\n" %
6410 (' and '.join([str(x) for x in source]),
6411 ' and '.join([str(x) for x in target])))
6412 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6413 env.Program('foo', 'foo.c')
6416 This just prints "Building <targetname> from <sourcename>..." instead
6417 of the actual commands.
6418 Such a function could also log the actual commands to a log file,
6422 The prefix used for executable file names.
6425 The suffix used for executable file names.
6428 The command line used to convert TeX DVI files into a PostScript file.
6431 The string displayed when a TeX DVI file
6432 is converted into a PostScript file.
6433 If this is not set, then $PSCOM (the command line) is displayed.
6436 The prefix used for PostScript file names.
6439 The prefix used for PostScript file names.
6442 The qt tool tries to take this from os.environ.
6443 It also initializes all QT_*
6444 construction variables listed below.
6445 (Note that all paths are constructed
6446 with python's os.path.join() method,
6447 but are listed here with the '/' separator
6448 for easier reading.)
6449 In addition, the construction environment
6450 variables CPPPATH, LIBPATH and LIBS may be modified
6452 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6453 are modified. Because the build-performance is affected when using this tool,
6454 you have to explicitly specify it at Environment creation:
6457 Environment(tools=['default','qt'])
6460 The qt tool supports the following operations:
6462 .B Automatic moc file generation from header files.
6463 You do not have to specify moc files explicitly, the tool does it for you.
6464 However, there are a few preconditions to do so: Your header file must have
6465 the same filebase as your implementation file and must stay in the same
6466 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6467 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6468 See also the corresponding builder method
6471 .B Automatic moc file generation from cxx files.
6472 As stated in the qt documentation, include the moc file at the end of
6473 the cxx file. Note that you have to include the file, which is generated
6474 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6475 <basename>.moc. A warning is generated after building the moc file, if you
6476 do not include the correct file. If you are using BuildDir, you may
6477 need to specify duplicate=1. You can turn off automatic moc file generation
6478 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6481 .B Automatic handling of .ui files.
6482 The implementation files generated from .ui files are handled much the same
6483 as yacc or lex files. Each .ui file given as a source of Program, Library or
6484 SharedLibrary will generate three files, the declaration file, the
6485 implementation file and a moc file. Because there are also generated headers,
6486 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6490 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6491 specify files to run moc on.
6494 The path where the qt binaries are installed.
6495 The default value is '$QTDIR/bin'.
6498 The path where the qt header files are installed.
6499 The default value is '$QTDIR/include'.
6500 Note: If you set this variable to None, the tool won't change the CPPPATH
6501 construction variable.
6504 Prints lots of debugging information while scanning for moc files.
6507 The path where the qt libraries are installed.
6508 The default value is '$QTDIR/lib'.
6509 Note: If you set this variable to None, the tool won't change the LIBPATH
6510 construction variable.
6513 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6514 this variable to None, the tool won't change the LIBS variable.
6517 Default value is '$QT_BINPATH/moc'.
6520 Default value is ''. Prefix for moc output files, when source is a cxx file.
6523 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6526 .IP QT_MOCFROMCPPFLAGS
6527 Default value is '-i'. These flags are passed to moc, when moccing a
6530 .IP QT_MOCFROMCXXCOM
6531 Command to generate a moc file from a cpp file.
6533 .IP QT_MOCFROMCXXCOMSTR
6534 The string displayed when generating a moc file from a cpp file.
6535 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6538 Command to generate a moc file from a header.
6540 .IP QT_MOCFROMHCOMSTR
6541 The string displayed when generating a moc file from a cpp file.
6542 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6544 .IP QT_MOCFROMHFLAGS
6545 Default value is ''. These flags are passed to moc, when moccing a header
6549 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6552 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6556 Default value is '$QT_BINPATH/uic'.
6559 Command to generate header files from .ui files.
6562 The string displayed when generating header files from .ui files.
6563 If this is not set, then $QT_UICCOM (the command line) is displayed.
6566 Default value is ''. These flags are passed to uic, when creating a a h
6567 file from a .ui file.
6569 .IP QT_UICDECLPREFIX
6570 Default value is ''. Prefix for uic generated header files.
6572 .IP QT_UICDECLSUFFIX
6573 Default value is '.h'. Suffix for uic generated header files.
6576 Default value is ''. These flags are passed to uic, when creating a cxx
6577 file from a .ui file.
6579 .IP QT_UICIMPLPREFIX
6580 Default value is 'uic_'. Prefix for uic generated implementation files.
6582 .IP QT_UICIMPLSUFFIX
6583 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6587 Default value is '.ui'. Suffix of designer input files.
6590 The archive indexer.
6593 General options passed to the archive indexer.
6596 The resource compiler used by the RES builder.
6599 The command line used by the RES builder.
6602 The string displayed when invoking the resource compiler.
6603 If this is not set, then $RCCOM (the command line) is displayed.
6606 The flags passed to the resource compiler by the RES builder.
6610 Note that this variable is not actually used
6611 for the command to fetch source files from RCS;
6614 construction variable, below.
6617 The RCS "checkout" executable,
6618 used to fetch source files from RCS.
6621 The command line used to
6622 fetch (checkout) source files from RCS.
6625 The string displayed when fetching
6626 a source file from RCS.
6627 If this is not set, then $RCS_COCOM
6628 (the command line) is displayed.
6631 Options that are passed to the $RCS_CO command.
6634 The program used to register DLLs on Windows systems.
6637 The command line used to register a newly-built DLL file
6639 Invoked when the "register=1"
6640 keyword argument is passed to the
6645 The string displayed when registering a newly-built DLL file.
6646 If this is not set, then $REGSVRCOM (the command line) is displayed.
6649 A function that converts a file name into a list of Dir instances by
6650 searching the repositories.
6653 The Java RMI stub compiler.
6656 The command line used to compile stub
6657 and skeleton class files
6658 from Java classes that contain RMI implementations.
6659 Any options specified in the $RMICFLAGS construction variable
6660 are included on this command line.
6663 The string displayed when compiling
6664 stub and skeleton class files
6665 from Java classes that contain RMI implementations.
6666 If this is not set, then $RMICCOM (the command line) is displayed.
6669 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6673 General options passed to the Java RMI stub compiler.
6676 The RPC protocol compiler.
6678 .IP RPCGENCLIENTFLAGS
6679 Options passed to the RPC protocol compiler
6680 when generating client side stubs.
6681 These are in addition to any flags specified in the
6683 construction variable.
6686 General options passed to the RPC protocol compiler.
6688 .IP RPCGENHEADERFLAGS
6689 Options passed to the RPC protocol compiler
6690 when generating a header file.
6691 These are in addition to any flags specified in the
6693 construction variable.
6695 .IP RPCGENSERVICEFLAGS
6696 Options passed to the RPC protocol compiler
6697 when generating server side stubs.
6698 These are in addition to any flags specified in the
6700 construction variable.
6703 Options passed to the RPC protocol compiler
6704 when generating XDR routines.
6705 These are in addition to any flags specified in the
6707 construction variable.
6710 A list of paths to search for shared libraries when running programs.
6711 Currently only used in the GNU (gnulink),
6712 IRIX (sgilink) and Sun (sunlink) linkers.
6713 Ignored on platforms and toolchains that don't support it.
6714 Note that the paths added to RPATH
6715 are not transformed by
6717 in any way: if you want an absolute
6718 path, you must make it absolute yourself.
6721 A list of the available implicit dependency scanners.
6722 New file scanners may be added by
6723 appending to this list,
6724 although the more flexible approach
6725 is to associate scanners
6726 with a specific Builder.
6727 See the sections "Builder Objects"
6728 and "Scanner Objects,"
6729 below, for more information.
6732 The SCCS executable.
6735 The command line used to
6736 fetch source files from SCCS.
6739 The string displayed when fetching
6740 a source file from a CVS repository.
6741 If this is not set, then $SCCSCOM
6742 (the command line) is displayed.
6745 General options that are passed to SCCS.
6748 Options that are passed specifically to the SCCS "get" subcommand.
6749 This can be set, for example, to
6751 to check out editable files from SCCS.
6754 The C compiler used for generating shared-library objects.
6757 The command line used to compile a C source file
6758 to a shared-library object file.
6759 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6760 are included on this command line.
6763 The string displayed when a C source file
6764 is compiled to a shared object file.
6765 If this is not set, then $SHCCCOM (the command line) is displayed.
6768 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6772 Options that are passed to the C compiler
6773 to generate shared-library objects.
6776 The C++ compiler used for generating shared-library objects.
6779 The command line used to compile a C++ source file
6780 to a shared-library object file.
6781 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6782 are included on this command line.
6785 The string displayed when a C++ source file
6786 is compiled to a shared object file.
6787 If this is not set, then $SHCXXCOM (the command line) is displayed.
6790 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6794 Options that are passed to the C++ compiler
6795 to generate shared-library objects.
6798 A string naming the shell program that will be passed to the
6803 construction variable for more information.
6806 The Fortran 77 compiler used for generating shared-library objects.
6807 You should normally set the $SHFORTRANC variable,
6808 which specifies the default Fortran compiler
6809 for all Fortran versions.
6810 You only need to set $SHF77 if you need to use a specific compiler
6811 or compiler version for Fortran 77 files.
6814 The command line used to compile a Fortran 77 source file
6815 to a shared-library object file.
6816 You only need to set $SHF77COM if you need to use a specific
6817 command line for Fortran 77 files.
6818 You should normally set the $SHFORTRANCOM variable,
6819 which specifies the default command line
6820 for all Fortran versions.
6823 The string displayed when a Fortran 77 source file
6824 is compiled to a shared-library object file.
6825 If this is not set, then $SHF77COM or $SHFORTRANCOM
6826 (the command line) is displayed.
6829 Options that are passed to the Fortran 77 compiler
6830 to generated shared-library objects.
6831 You only need to set $SHF77FLAGS if you need to define specific
6832 user options for Fortran 77 files.
6833 You should normally set the $SHFORTRANFLAGS variable,
6834 which specifies the user-specified options
6835 passed to the default Fortran compiler
6836 for all Fortran versions.
6839 The command line used to compile a Fortran 77 source file to a
6840 shared-library object file
6841 after first running the file through the C preprocessor.
6842 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6843 are included on this command line.
6844 You only need to set $SHF77PPCOM if you need to use a specific
6845 C-preprocessor command line for Fortran 77 files.
6846 You should normally set the $SHFORTRANPPCOM variable,
6847 which specifies the default C-preprocessor command line
6848 for all Fortran versions.
6851 The Fortran 90 compiler used for generating shared-library objects.
6852 You should normally set the $SHFORTRANC variable,
6853 which specifies the default Fortran compiler
6854 for all Fortran versions.
6855 You only need to set $SHF90 if you need to use a specific compiler
6856 or compiler version for Fortran 90 files.
6859 The command line used to compile a Fortran 90 source file
6860 to a shared-library object file.
6861 You only need to set $SHF90COM if you need to use a specific
6862 command line for Fortran 90 files.
6863 You should normally set the $SHFORTRANCOM variable,
6864 which specifies the default command line
6865 for all Fortran versions.
6868 The string displayed when a Fortran 90 source file
6869 is compiled to a shared-library object file.
6870 If this is not set, then $SHF90COM or $SHFORTRANCOM
6871 (the command line) is displayed.
6874 Options that are passed to the Fortran 90 compiler
6875 to generated shared-library objects.
6876 You only need to set $SHF90FLAGS if you need to define specific
6877 user options for Fortran 90 files.
6878 You should normally set the $SHFORTRANFLAGS variable,
6879 which specifies the user-specified options
6880 passed to the default Fortran compiler
6881 for all Fortran versions.
6884 The command line used to compile a Fortran 90 source file to a
6885 shared-library object file
6886 after first running the file through the C preprocessor.
6887 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6888 are included on this command line.
6889 You only need to set $SHF90PPCOM if you need to use a specific
6890 C-preprocessor command line for Fortran 90 files.
6891 You should normally set the $SHFORTRANPPCOM variable,
6892 which specifies the default C-preprocessor command line
6893 for all Fortran versions.
6896 The Fortran 95 compiler used for generating shared-library objects.
6897 You should normally set the $SHFORTRANC variable,
6898 which specifies the default Fortran compiler
6899 for all Fortran versions.
6900 You only need to set $SHF95 if you need to use a specific compiler
6901 or compiler version for Fortran 95 files.
6904 The command line used to compile a Fortran 95 source file
6905 to a shared-library object file.
6906 You only need to set $SHF95COM if you need to use a specific
6907 command line for Fortran 95 files.
6908 You should normally set the $SHFORTRANCOM variable,
6909 which specifies the default command line
6910 for all Fortran versions.
6913 The string displayed when a Fortran 95 source file
6914 is compiled to a shared-library object file.
6915 If this is not set, then $SHF95COM or $SHFORTRANCOM
6916 (the command line) is displayed.
6919 Options that are passed to the Fortran 95 compiler
6920 to generated shared-library objects.
6921 You only need to set $SHF95FLAGS if you need to define specific
6922 user options for Fortran 95 files.
6923 You should normally set the $SHFORTRANFLAGS variable,
6924 which specifies the user-specified options
6925 passed to the default Fortran compiler
6926 for all Fortran versions.
6929 The command line used to compile a Fortran 95 source file to a
6930 shared-library object file
6931 after first running the file through the C preprocessor.
6932 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6933 are included on this command line.
6934 You only need to set $SHF95PPCOM if you need to use a specific
6935 C-preprocessor command line for Fortran 95 files.
6936 You should normally set the $SHFORTRANPPCOM variable,
6937 which specifies the default C-preprocessor command line
6938 for all Fortran versions.
6941 The default Fortran compiler used for generating shared-library objects.
6944 The command line used to compile a Fortran source file
6945 to a shared-library object file.
6948 The string displayed when a Fortran source file
6949 is compiled to a shared-library object file.
6950 If this is not set, then $SHFORTRANCOM
6951 (the command line) is displayed.
6954 Options that are passed to the Fortran compiler
6955 to generate shared-library objects.
6958 The command line used to compile a Fortran source file to a
6959 shared-library object file
6960 after first running the file through the C preprocessor.
6961 Any options specified
6962 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6963 are included on this command line.
6966 The prefix used for shared library file names.
6969 The suffix used for shared library file names.
6972 The linker for programs that use shared libraries.
6975 The command line used to link programs using shared libaries.
6978 The string displayed when programs using shared libraries are linked.
6979 If this is not set, then $SHLINKCOM (the command line) is displayed.
6982 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6986 General user options passed to the linker for programs using shared libraries.
6987 Note that this variable should
6991 (or similar) options for linking with the libraries listed in $LIBS,
6994 (or similar) include search path options
6995 that scons generates automatically from $LIBPATH.
6999 for the variable that expands to library-link options,
7003 for the variable that expands to library search path options.
7006 The prefix used for shared object file names.
7009 The suffix used for shared object file names.
7012 A reserved variable name
7013 that may not be set or used in a construction environment.
7014 (See "Variable Substitution," below.)
7017 A reserved variable name
7018 that may not be set or used in a construction environment.
7019 (See "Variable Substitution," below.)
7022 A command interpreter function that will be called to execute command line
7023 strings. The function must expect the following arguments:
7026 def spawn(shell, escape, cmd, args, env):
7030 is a string naming the shell program to use.
7032 is a function that can be called to escape shell special characters in
7035 is the path to the command to be executed.
7037 is the arguments to the command.
7039 is a dictionary of the environment variables
7040 in which the command should be executed.
7043 '\"The Subversion executable (usually named
7047 '\"The command line used to
7048 '\"fetch source files from a Subversion repository.
7051 '\"General options that are passed to Subversion.
7054 The scripting language wrapper and interface generator.
7057 The suffix that will be used for intermediate C
7058 source files generated by
7059 the scripting language wrapper and interface generator.
7060 The default value is
7061 .BR _wrap$CFILESUFFIX .
7062 By default, this value is used whenever the
7066 specified as part of the
7068 construction variable.
7071 The command line used to call
7072 the scripting language wrapper and interface generator.
7075 The string displayed when calling
7076 the scripting language wrapper and interface generator.
7077 If this is not set, then $SWIGCOM (the command line) is displayed.
7079 .IP SWIGCXXFILESUFFIX
7080 The suffix that will be used for intermediate C++
7081 source files generated by
7082 the scripting language wrapper and interface generator.
7083 The default value is
7084 .BR _wrap$CFILESUFFIX .
7085 By default, this value is used whenever the
7087 option is specified as part of the
7089 construction variable.
7092 General options passed to
7093 the scripting language wrapper and interface generator.
7094 This is where you should set
7098 or whatever other options you want to specify to SWIG.
7101 option in this variable,
7104 generate a C++ intermediate source file
7105 with the extension that is specified as the
7113 The command line used to call the tar archiver.
7116 The string displayed when archiving files
7117 using the tar archiver.
7118 If this is not set, then $TARCOM (the command line) is displayed.
7121 env = Environment(TARCOMSTR = "Archiving $TARGET")
7125 General options passed to the tar archiver.
7128 A reserved variable name
7129 that may not be set or used in a construction environment.
7130 (See "Variable Substitution," below.)
7133 A reserved variable name
7134 that may not be set or used in a construction environment.
7135 (See "Variable Substitution," below.)
7138 The suffix used for tar file names.
7141 The TeX formatter and typesetter.
7144 The command line used to call the TeX formatter and typesetter.
7147 The string displayed when calling
7148 the TeX formatter and typesetter.
7149 If this is not set, then $TEXCOM (the command line) is displayed.
7152 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7156 General options passed to the TeX formatter and typesetter.
7159 A list of the names of the Tool specifications
7160 that are part of this construction environment.
7162 .IP WIN32_INSERT_DEF
7163 When this is set to true,
7164 a library build of a WIN32 shared library (.dll file)
7165 will also build a corresponding .def file at the same time,
7166 if a .def file is not already listed as a build target.
7167 The default is 0 (do not build a .def file).
7170 The prefix used for WIN32 .def file names.
7173 The suffix used for WIN32 .def file names.
7176 The parser generator.
7179 The command line used to call the parser generator
7180 to generate a source file.
7183 The string displayed when generating a source file
7184 using the parser generator.
7185 If this is not set, then $YACCCOM (the command line) is displayed.
7188 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7192 General options passed to the parser generator.
7193 If $YACCFLAGS contains a \-d option,
7194 SCons assumes that the call will also create a .h file
7195 (if the yacc source file ends in a .y suffix)
7197 (if the yacc source file ends in a .yy suffix)
7201 header file generated by the parser generator
7205 Note that setting this variable does not cause
7206 the parser generator to generate a header
7207 file with the specified suffix,
7208 it exists to allow you to specify
7209 what suffix the parser generator will use of its own accord.
7210 The default value is
7213 .IP YACCHXXFILESUFFIX
7214 The suffix of the C++
7215 header file generated by the parser generator
7219 Note that setting this variable does not cause
7220 the parser generator to generate a header
7221 file with the specified suffix,
7222 it exists to allow you to specify
7223 what suffix the parser generator will use of its own accord.
7224 The default value is
7228 The zip compression and file packaging utility.
7231 The command line used to call the zip utility,
7232 or the internal Python function used to create a
7236 The string displayed when archiving files
7237 using the zip utility.
7238 If this is not set, then $ZIPCOM
7239 (the command line or internal Python function) is displayed.
7242 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7251 module used by the internal Python function
7252 to control whether the zip archive
7253 is compressed or not.
7254 The default value is
7255 .BR zipfile.ZIP_DEFLATED ,
7256 which creates a compressed zip archive.
7257 This value has no effect when using Python 1.5.2
7260 module is otherwise unavailable.
7263 General options passed to the zip utility.
7266 Construction variables can be retrieved and set using the
7268 method of the construction environment:
7271 dict = env.Dictionary()
7275 or using the [] operator:
7281 Construction variables can also be passed to the construction environment
7285 env = Environment(CC="cc")
7288 or when copying a construction environment using the
7293 env2 = env.Copy(CC="cl.exe")
7296 .SS Configure Contexts
7300 .I configure contexts,
7301 an integrated mechanism similar to the
7302 various AC_CHECK macros in GNU autoconf
7303 for testing for the existence of C header
7304 files, libraries, etc.
7305 In contrast to autoconf,
7307 does not maintain an explicit cache of the tested values,
7308 but uses its normal dependency tracking to keep the checked values
7309 up to date. However, users may override this behaviour with the
7311 command line option.
7313 The following methods can be used to perform checks:
7316 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7318 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7319 This creates a configure context, which can be used to perform checks.
7321 specifies the environment for building the tests.
7322 This environment may be modified when performing checks.
7324 is a dictionary containing custom tests.
7325 See also the section about custom tests below.
7326 By default, no custom tests are added to the configure context.
7328 specifies a directory where the test cases are built.
7329 Note that this directory is not used for building
7331 The default value is the directory
7334 specifies a file which collects the output from commands
7335 that are executed to check for the existence of header files, libraries, etc.
7336 The default is the file #/config.log.
7337 If you are using the
7340 you may want to specify a subdirectory under your build directory.
7342 specifies a C header file where the results of tests
7343 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7344 The default is to not write a
7347 You can specify the same
7349 file in multiple calls to Configure,
7352 will concatenate all results in the specified file.
7354 uses its normal dependency checking
7355 to decide if it's necessary to rebuild
7359 This means that the file is not necessarily re-built each
7361 but is only rebuilt if its contents will have changed
7362 and some target that depends on the
7364 file is being built.
7369 instance has the following associated methods:
7372 .RI Configure.Finish( self )
7373 This method should be called after configuration is done.
7374 It returns the environment as modified
7375 by the configuration checks performed.
7376 After this method is called, no further checks can be performed
7377 with this configuration context.
7378 However, you can create a new
7380 context to perform additional checks.
7381 Only one context should be active at a time.
7383 The following Checks are predefined.
7384 (This list will likely grow larger as time
7385 goes by and developers contribute new useful tests.)
7388 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7391 is usable in the specified language.
7394 in which case the last item in the list
7395 is the header file to be checked,
7396 and the previous list items are
7399 lines should precede the
7400 header line being checked for.
7401 The optional argument
7404 a two character string, where the first character denotes the opening
7405 quote and the second character denotes the closing quote.
7406 By default, both characters are " (double quote).
7407 The optional argument
7413 and selects the compiler to be used for the check.
7414 Returns 1 on success and 0 on failure.
7417 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7418 This is a wrapper around
7419 .B Configure.CheckHeader
7422 is usable in the C language.
7425 in which case the last item in the list
7426 is the header file to be checked,
7427 and the previous list items are
7430 lines should precede the
7431 header line being checked for.
7432 The optional argument
7435 a two character string, where the first character denotes the opening
7436 quote and the second character denotes the closing quote (both default
7438 Returns 1 on success and 0 on failure.
7441 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7442 This is a wrapper around
7443 .B Configure.CheckHeader
7446 is usable in the C++ language.
7449 in which case the last item in the list
7450 is the header file to be checked,
7451 and the previous list items are
7454 lines should precede the
7455 header line being checked for.
7456 The optional argument
7459 a two character string, where the first character denotes the opening
7460 quote and the second character denotes the closing quote (both default
7462 Returns 1 on success and 0 on failure.
7465 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7466 Checks if the specified
7467 C or C++ function is available.
7469 is the name of the function to check for.
7472 argument is a string
7476 that will be compiled
7477 to check if the function exists;
7483 char function_name();
7491 and selects the compiler to be used for the check;
7495 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
7502 is 1 and the library provides the specified
7504 appends the library to the LIBS construction environment variable.
7506 may also be None (the default),
7509 is checked with the current LIBS variable,
7510 or a list of library names,
7511 in which case each library in the list
7518 you can link against the specified
7526 and selects the compiler to be used for the check;
7528 The default value for
7531 It is assumed, that the C-language is used.
7532 This method returns 1 on success and 0 on error.
7535 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7538 .RI Configure.CheckLib
7539 call, this call provides a more sophisticated way to check against libraries.
7542 specifies the library or a list of libraries to check.
7544 specifies a header to check for.
7547 in which case the last item in the list
7548 is the header file to be checked,
7549 and the previous list items are
7552 lines should precede the
7553 header line being checked for.
7555 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7557 can be any valid expression (with a trailing ';'). The default is 'main();'.
7559 specifies whether to add the library to the environment (only if the check
7560 succeeds). This method returns 1 on success and 0 on error.
7563 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7564 Checks for the existence of a type defined by
7567 specifies the typedef name to check for.
7569 is a string containing one or more
7571 lines that will be inserted into the program
7572 that will be run to test for the existence of the type.
7579 and selects the compiler to be used for the check;
7583 Example of a typical Configure usage:
7587 conf = Configure( env )
7588 if not conf.CheckCHeader( 'math.h' ):
7589 print 'We really need math.h!'
7591 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7592 # do stuff for qt - usage, e.g.
7593 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7598 You can define your own custom checks.
7599 in addition to the predefined checks.
7600 These are passed in a dictionary to the Configure function.
7601 This dictionary maps the names of the checks
7602 to user defined Python callables
7603 (either Python functions or class instances implementing the
7606 The first argument of the call is always a
7608 instance followed by the arguments,
7609 which must be supplied by the user of the check.
7610 These CheckContext instances define the following methods:
7613 .RI CheckContext.Message( self ", " text )
7615 Usually called before the check is started.
7617 will be displayed to the user, e.g. 'Checking for library X...'
7620 .RI CheckContext.Result( self, ", " res )
7622 Usually called after the check is done.
7624 can be either an integer or a string. In the former case, 'ok' (res != 0)
7625 or 'failed' (res == 0) is displayed to the user, in the latter case the
7626 given string is displayed.
7629 .RI CheckContext.TryCompile( self ", " text ", " extension )
7630 Checks if a file with the specified
7632 (e.g. '.c') containing
7634 can be compiled using the environment's
7636 builder. Returns 1 on success and 0 on failure.
7639 .RI CheckContext.TryLink( self ", " text ", " extension )
7640 Checks, if a file with the specified
7642 (e.g. '.c') containing
7644 can be compiled using the environment's
7646 builder. Returns 1 on success and 0 on failure.
7649 .RI CheckContext.TryRun( self ", " text ", " extension )
7650 Checks, if a file with the specified
7652 (e.g. '.c') containing
7654 can be compiled using the environment's
7656 builder. On success, the program is run. If the program
7657 executes successfully
7658 (that is, its return status is 0),
7663 is the standard output of the
7665 If the program fails execution
7666 (its return status is non-zero),
7667 then (0, '') is returned.
7670 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7671 Checks if the specified
7673 with an optional source file (contents
7680 may be anything which can be converted to a
7687 is the content of the target file.
7693 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7694 Low level implementation for testing specific builds;
7695 the methods above are based on this method.
7696 Given the Builder instance
7700 of a source file with optional
7702 this method returns 1 on success and 0 on failure. In addition,
7704 is set to the build target node, if the build was successful.
7707 Example for implementing and using custom tests:
7710 def CheckQt(context, qtdir):
7711 context.Message( 'Checking for qt ...' )
7712 lastLIBS = context.env['LIBS']
7713 lastLIBPATH = context.env['LIBPATH']
7714 lastCPPPATH= context.env['CPPPATH']
7715 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7716 ret = context.TryLink("""
7718 int main(int argc, char **argv) {
7719 QApplication qapp(argc, argv);
7724 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7725 context.Result( ret )
7729 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7730 if not conf.CheckQt('/usr/lib/qt'):
7731 print 'We really need qt!'
7736 .SS Construction Variable Options
7738 Often when building software, various options need to be specified at build
7739 time that are not known when the SConstruct/SConscript files are
7740 written. For example, libraries needed for the build may be in non-standard
7741 locations, or site-specific compiler options may need to be passed to the
7744 provides a mechanism for overridding construction variables from the
7745 command line or a text-based SConscript file through an Options
7746 object. To create an Options object, call the Options() function:
7749 .RI Options([ files "], [" args ])
7750 This creates an Options object that will read construction variables from
7751 the file or list of filenames specified in
7753 If no files are specified,
7758 then no files will be read.
7759 The optional argument
7762 values that will override anything read from the specified files;
7763 it is primarily intended to be passed the
7765 dictionary that holds variables
7766 specified on the command line.
7770 opts = Options('custom.py')
7771 opts = Options('overrides.py', ARGUMENTS)
7772 opts = Options(None, {FOO:'expansion', BAR:7})
7775 Options objects have the following methods:
7778 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7779 This adds a customizable construction variable to the Options object.
7781 is the name of the variable.
7783 is the help text for the variable.
7785 is the default value of the variable;
7786 if the default value is
7788 and there is no explicit value specified,
7789 the construction variable will
7791 be added to the construction environment.
7793 is called to validate the value of the variable, and should take three
7794 arguments: key, value, and environment
7796 is called to convert the value before putting it in the environment, and
7797 should take a single argument: value. Example:
7800 opts.Add('CC', 'The C compiler')
7804 .RI AddOptions( list )
7805 A wrapper script that adds
7806 multiple customizable construction variables
7807 to an Options object.
7809 is a list of tuple or list objects
7810 that contain the arguments
7811 for an individual call to the
7818 ('CC', 'The C compiler'),
7819 ('VALIDATE', 'An option for testing validation',
7820 'notset', validator, None),
7825 .RI Update( env ", [" args ])
7826 This updates a construction environment
7828 with the customized construction variables. Normally this method is not
7829 called directly, but is called indirectly by passing the Options object to
7830 the Environment() function:
7833 env = Environment(options=opts)
7837 The text file(s) that were specified
7838 when the Options object was created
7839 are executed as Python scripts,
7840 and the values of (global) Python variables set in the file
7841 are added to the construction environment.
7849 .RI Save( filename ", " env )
7850 This saves the currently set options into a script file named
7852 that can be used on the next invocation to automatically load the current
7853 settings. This method combined with the Options method can be used to
7854 support caching of options between runs.
7858 opts = Options(['options.cache', 'custom.py'])
7861 opts.Save('options.cache', env)
7865 .RI GenerateHelpText( env ", [" sort ])
7866 This generates help text documenting the customizable construction
7867 variables suitable to passing in to the Help() function.
7869 is the construction environment that will be used to get the actual values
7870 of customizable variables. Calling with
7874 will cause the output to be sorted
7875 by the specified argument.
7879 should take two arguments
7882 (like the standard Python
7887 Help(opts.GenerateHelpText(env))
7888 Help(opts.GenerateHelpText(env, sort=cmp))
7892 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
7893 This method returns a formatted string
7894 containing the printable help text
7896 It is normally not called directly,
7897 but is called by the
7898 .IR GenerateHelpText ()
7899 method to create the returned help text.
7900 It may be overridden with your own
7901 function that takes the arguments specified above
7902 and returns a string of help text formatted to your liking.
7904 .IR GenerateHelpText ()
7905 will not put any blank lines or extra
7906 characters in between the entries,
7907 so you must add those characters to the returned
7908 string if you want the entries separated.
7911 def my_format(env, opt, help, default, actual):
7912 fmt = "\n%s: default=%s actual=%s (%s)\n"
7913 return fmt % (opt, default. actual, help)
7914 opts.FormatOptionHelpText = my_format
7917 To make it more convenient to work with customizable Options,
7919 provides a number of functions
7920 that make it easy to set up
7921 various types of Options:
7924 .RI BoolOption( key ", " help ", " default )
7925 Return a tuple of arguments
7926 to set up a Boolean option.
7930 have a default value of
7932 and display the specified
7935 The option will interpret the values
7957 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7958 Return a tuple of arguments
7960 whose value may be one
7961 of a specified list of legal enumerated values.
7965 have a default value of
7967 and display the specified
7970 The option will only support those
7976 argument is a dictionary
7977 that can be used to convert
7978 input values into specific legal values
7987 then the values are case-sensitive.
7992 then values will be matched
7998 then values will be matched
8000 and all input values will be
8001 converted to lower case.
8004 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
8005 Return a tuple of arguments
8007 whose value may be one or more
8008 of a specified list of legal enumerated values.
8012 have a default value of
8014 and display the specified
8017 The option will only support the values
8020 or the values in the
8023 More than one value may be specified,
8024 with all values separated by commas.
8025 The default may be a string of
8026 comma-separated default values,
8027 or a list of the default values.
8030 argument is a dictionary
8031 that can be used to convert
8032 input values into specific legal values
8038 .RI PackageOption( key ", " help ", " default )
8039 Return a tuple of arguments
8041 whose value is a path name
8042 of a package that may be
8043 enabled, disabled or
8044 given an explicit path name.
8048 have a default value of
8050 and display the specified
8053 The option will support the values
8060 in which case the specified
8063 or the option may be set to an
8065 (typically the path name to a package
8066 that is being enabled).
8067 The option will also support the values
8073 to disable use of the specified option.
8076 .RI PathOption( key ", " help ", " default ", [" validator ])
8077 Return a tuple of arguments
8079 whose value is expected to be a path name.
8083 have a default value of
8085 and display the specified
8091 that will be called to
8092 verify that the specified path
8095 following ready-made validators:
8096 .BR PathOption.PathExists
8098 which verifies that the specified path exists;
8099 .BR PathOption.PathIsFile ,
8100 which verifies that the specified path is an existing file;
8101 .BR PathOption.PathIsDir ,
8102 which verifies that the specified path is an existing directory;
8104 .BR PathOption.PathIsDirCreate ,
8105 which verifies that the specified path is a directory,
8106 and will create the specified directory if the path does not exist.
8107 You may supply your own
8110 which must take three arguments
8112 the name of the options variable to be set;
8114 the specified value being checked;
8117 the construction environment)
8118 and should raise an exception
8119 if the specified value is not acceptable.
8122 These functions make it
8123 convenient to create a number
8124 of options with consistent behavior
8125 in a single call to the
8131 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
8132 EnumOption('debug', 'debug output and symbols', 'no'
8133 allowed_values=('yes', 'no', 'full'),
8134 map={}, ignorecase=0), # case sensitive
8135 ListOption('shared',
8136 'libraries to build as shared libraries',
8138 names = list_of_libs),
8139 PackageOption('x11',
8140 'use X11 installed here (yes = search some places)',
8142 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
8143 PathOption('foopath', 'where the foo library is installed', foopath,
8144 PathOption.PathIsDir),
8149 .SS File and Directory Nodes
8159 Nodes, respectively.
8160 python objects, respectively.
8161 Those objects have several user-visible attributes
8162 and methods that are often useful:
8168 This path is relative to the top-level directory
8172 The build path is the same as the source path if
8177 The absolute build path of the given file or directory.
8187 object representing the
8196 # Get the current build dir's path, relative to top.
8198 # Current dir's absolute path
8200 # Next line is always '.', because it is the top dir's path relative to itself.
8202 File('foo.c').srcnode().path # source path of the given source file.
8204 # Builders also return File objects:
8205 foo = env.Program('foo.c')
8206 print "foo will be built in %s"%foo.path
8212 can be extended to build different types of targets
8213 by adding new Builder objects
8214 to a construction environment.
8216 you should only need to add a new Builder object
8217 when you want to build a new type of file or other external target.
8218 If you just want to invoke a different compiler or other tool
8219 to build a Program, Object, Library, or any other
8220 type of output file for which
8222 already has an existing Builder,
8223 it is generally much easier to
8224 use those existing Builders
8225 in a construction environment
8226 that sets the appropriate construction variables
8229 Builder objects are created
8235 function accepts the following arguments:
8238 The command line string used to build the target from the source.
8241 a list of strings representing the command
8242 to be executed and its arguments
8243 (suitable for enclosing white space in an argument),
8245 mapping source file name suffixes to
8246 any combination of command line strings
8247 (if the builder should accept multiple source file extensions),
8250 (see the next section);
8251 or a list of any of the above.
8254 takes three arguments:
8256 - a list of source nodes,
8258 - a list of target nodes,
8260 - the construction environment.
8263 The prefix that will be prepended to the target file name.
8264 This may be specified as a:
8274 - a function or other callable that takes
8275 two arguments (a construction environment and a list of sources)
8276 and returns a prefix,
8281 - specifies a mapping from a specific source suffix (of the first
8282 source specified) to a corresponding target prefix. Both the source
8283 suffix and target prefix specifications may use environment variable
8284 substitution, and the target prefix (the 'value' entries in the
8285 dictionary) may also be a callable object. The default target prefix
8286 may be indicated by a dictionary entry with a key value of None.
8291 b = Builder("build_it < $SOURCE > $TARGET"
8294 def gen_prefix(env, sources):
8295 return "file-" + env['PLATFORM'] + '-'
8296 b = Builder("build_it < $SOURCE > $TARGET",
8297 prefix = gen_prefix)
8299 b = Builder("build_it < $SOURCE > $TARGET",
8300 suffix = { None: "file-",
8301 "$SRC_SFX_A": gen_prefix })
8305 The suffix that will be appended to the target file name.
8306 This may be specified in the same manner as the prefix above.
8307 If the suffix is a string, then
8309 will append a '.' to the beginning of the suffix if it's not already
8310 there. The string returned by callable object (or obtained from the
8311 dictionary) is untouched and must append its own '.' to the beginning
8315 b = Builder("build_it < $SOURCE > $TARGET"
8318 def gen_suffix(env, sources):
8319 return "." + env['PLATFORM'] + "-file"
8320 b = Builder("build_it < $SOURCE > $TARGET",
8321 suffix = gen_suffix)
8323 b = Builder("build_it < $SOURCE > $TARGET",
8324 suffix = { None: ".sfx1",
8325 "$SRC_SFX_A": gen_suffix })
8329 The expected source file name suffix. This may be a string or a list
8333 A Scanner object that
8334 will be invoked to find
8335 implicit dependencies for this target file.
8336 This keyword argument should be used
8337 for Scanner objects that find
8338 implicit dependencies
8339 based only on the target file
8340 and the construction environment,
8343 (See the section "Scanner Objects," below,
8344 for information about creating Scanner objects.)
8347 A Scanner object that
8349 find implicit dependences in
8351 used to build this target file.
8352 This is where you would
8353 specify a scanner to
8356 lines in source files.
8359 Scanner object may be used to
8360 indicate that this Builder
8361 should scan directory trees
8362 for on-disk changes to files
8365 does not know about from other Builder or function calls.
8366 (See the section "Scanner Objects," below,
8367 for information about creating your own Scanner objects.)
8370 A factory function that the Builder will use
8371 to turn any targets specified as strings into SCons Nodes.
8373 SCons assumes that all targets are files.
8374 Other useful target_factory
8377 for when a Builder creates a directory target,
8380 for when a Builder can create either a file
8381 or directory target.
8386 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8388 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8389 env.MakeDirectory('new_directory', [])
8392 Note that the call to the MakeDirectory Builder
8393 needs to specify an empty source list
8394 to make the string represent the builder's target;
8395 without that, it would assume the argument is the source,
8396 and would try to deduce the target name from it,
8397 which in the absence of an automatically-added prefix or suffix
8398 would lead to a matching target and source name
8399 and a circular dependency.
8402 A factory function that the Builder will use
8403 to turn any sources specified as strings into SCons Nodes.
8405 SCons assumes that all source are files.
8406 Other useful source_factory
8409 for when a Builder uses a directory as a source,
8412 for when a Builder can use files
8413 or directories (or both) as sources.
8418 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8420 env.Append(BUILDERS = {'Collect':CollectBuilder})
8421 env.Collect('archive', ['directory_name', 'file_name'])
8425 A function or list of functions to manipulate the target and source
8426 lists before dependencies are established
8427 and the target(s) are actually built.
8429 can also be a string containing a construction variable to expand
8430 to an emitter function or list of functions,
8431 or a dictionary mapping source file suffixes
8432 to emitter functions.
8433 (Only the suffix of the first source file
8434 is used to select the actual emitter function
8435 from an emitter dictionary.)
8438 takes three arguments:
8440 - a list of source nodes,
8442 - a list of target nodes,
8444 - the construction environment.
8445 An emitter must return a tuple containing two lists,
8446 the list of targets to be built by this builder,
8447 and the list of sources for this builder.
8452 def e(target, source, env):
8453 return (target + ['foo.foo'], source + ['foo.src'])
8455 # Simple association of an emitter function with a Builder.
8456 b = Builder("my_build < $TARGET > $SOURCE",
8459 def e2(target, source, env):
8460 return (target + ['bar.foo'], source + ['bar.src'])
8462 # Simple association of a list of emitter functions with a Builder.
8463 b = Builder("my_build < $TARGET > $SOURCE",
8466 # Calling an emitter function through a construction variable.
8467 env = Environment(MY_EMITTER = e)
8468 b = Builder("my_build < $TARGET > $SOURCE",
8469 emitter = '$MY_EMITTER')
8471 # Calling a list of emitter functions through a construction variable.
8472 env = Environment(EMITTER_LIST = [e, e2])
8473 b = Builder("my_build < $TARGET > $SOURCE",
8474 emitter = '$EMITTER_LIST')
8476 # Associating multiple emitters with different file
8477 # suffixes using a dictionary.
8478 def e_suf1(target, source, env):
8479 return (target + ['another_target_file'], source)
8480 def e_suf2(target, source, env):
8481 return (target, source + ['another_source_file'])
8482 b = Builder("my_build < $TARGET > $SOURCE",
8483 emitter = {'.suf1' : e_suf1,
8488 Specifies whether this builder is allowed to be called multiple times for
8489 the same target file(s). The default is 0, which means the builder
8490 can not be called multiple times for the same target file(s). Calling a
8491 builder multiple times for the same target simply adds additional source
8492 files to the target; it is not allowed to change the environment associated
8493 with the target, specify addition environment overrides, or associate a different
8494 builder with the target.
8497 A construction environment that can be used
8498 to fetch source code using this Builder.
8499 (Note that this environment is
8501 used for normal builds of normal target files,
8502 which use the environment that was
8503 used to call the Builder for the target file.)
8506 A function that returns a list of actions that will be executed to build
8507 the target(s) from the source(s).
8508 The returned action(s) may be
8509 an Action object, or anything that
8510 can be converted into an Action object
8511 (see the next section).
8513 The generator function
8514 takes four arguments:
8516 - a list of source nodes,
8518 - a list of target nodes,
8520 - the construction environment,
8522 - a Boolean value that specifies
8523 whether the generator is being called
8524 for generating a build signature
8525 (as opposed to actually executing the command).
8529 def g(source, target, env, for_signature):
8530 return [["gcc", "-c", "-o"] + target + source]
8532 b = Builder(generator=g)
8540 arguments must not both be used for the same Builder.
8543 Specifies a builder to use when a source file name suffix does not match
8544 any of the suffixes of the builder. Using this argument produces a
8545 multi-stage builder.
8548 Specifies that this builder expects exactly one source file per call. Giving
8549 more than one source files without target files results in implicitely calling
8550 the builder multiple times (once for each source given). Giving multiple
8551 source files together with target files results in a UserError exception.
8559 arguments must not both be used for the same Builder.
8562 A construction environment that can be used
8563 to fetch source code using this Builder.
8564 (Note that this environment is
8566 used for normal builds of normal target files,
8567 which use the environment that was
8568 used to call the Builder for the target file.)
8571 b = Builder(action="build < $SOURCE > $TARGET")
8572 env = Environment(BUILDERS = {'MyBuild' : b})
8573 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8577 A directory from which scons
8584 a string or a directory Node,
8585 scons will change to the specified directory.
8588 is not a string or Node
8590 then scons will change to the
8591 target file's directory.
8593 Note that scons will
8595 automatically modify
8597 construction variables like
8601 when using the chdir
8602 keyword argument--that is,
8603 the expanded file names
8604 will still be relative to
8605 the top-level SConstruct directory,
8606 and consequently incorrect
8607 relative to the chdir directory.
8608 Builders created using chdir keyword argument,
8609 will need to use construction variable
8614 to use just the filename portion of the
8618 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8620 env = Environment(BUILDERS = {'MyBuild' : b})
8621 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8625 Any additional keyword arguments supplied
8626 when a Builder object is created
8627 (that is, when the Builder() function is called)
8628 will be set in the executing construction
8629 environment when the Builder object is called.
8630 The canonical example here would be
8631 to set a construction variable to
8632 the repository of a source code system.
8634 Any additional keyword arguments supplied
8638 will only be associated with the target
8639 created by that particular Builder call
8640 (and any other files built as a
8641 result of the call).
8643 These extra keyword arguments are passed to the
8644 following functions:
8645 command generator functions,
8647 and emitter functions.
8653 function will turn its
8655 keyword argument into an appropriate
8656 internal Action object.
8657 You can also explicity create Action objects
8661 which can then be passed to the
8664 This can be used to configure
8665 an Action object more flexibly,
8666 or it may simply be more efficient
8667 than letting each separate Builder object
8668 create a separate Action
8670 Builder objects need to do the same thing.
8675 returns an appropriate object for the action
8676 represented by the type of the first argument:
8679 If the first argument is already an Action object,
8680 the object is simply returned.
8683 If the first argument is a string,
8684 a command-line Action is returned.
8685 Note that the command line string
8686 may be preceded by an
8689 to suppress printing of the
8690 specified command line,
8694 to ignore the exit status from
8695 the specified command.
8699 Action('$CC -c -o $TARGET $SOURCES')
8701 # Doesn't print the line being executed.
8702 Action('@build $TARGET $SOURCES')
8705 Action('-build $TARGET $SOURCES')
8708 .\" XXX From Gary Ruben, 23 April 2002:
8709 .\" What would be useful is a discussion of how you execute command
8710 .\" shell commands ie. what is the process used to spawn the shell, pass
8711 .\" environment variables to it etc., whether there is one shell per
8712 .\" environment or one per command etc. It might help to look at the Gnu
8713 .\" make documentation to see what they think is important to discuss about
8714 .\" a build system. I'm sure you can do a better job of organising the
8715 .\" documentation than they have :-)
8719 If the first argument is a list,
8720 then a list of Action objects is returned.
8721 An Action object is created as necessary
8722 for each element in the list.
8725 the list is itself a list,
8726 the internal list is the
8727 command and arguments to be executed via
8729 This allows white space to be enclosed
8730 in an argument by defining
8731 a command in a list within a list:
8734 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8738 If the first argument is a Python function,
8739 a function Action is returned.
8740 The Python function takes three keyword arguments,
8742 (a Node object representing the target file),
8744 (a Node object representing the source file)
8747 (the construction environment
8748 used for building the target file).
8753 arguments may be lists of Node objects if there is
8754 more than one target file or source file.
8755 The actual target and source file name(s) may
8756 be retrieved from their Node objects
8757 via the built-in Python str() function:
8760 target_file_name = str(target)
8761 source_file_names = map(lambda x: str(x), source)
8764 The function should return
8768 to indicate a successful build of the target file(s).
8769 The function may raise an exception
8770 or return a non-zero exit status
8771 to indicate an unsuccessful build.
8774 def build_it(target = None, source = None, env = None):
8775 # build the target from the source
8778 a = Action(build_it)
8781 If the action argument is not one of the above,
8784 The second, optional argument
8785 is a Python function that returns
8786 a string to be printed to describe the action being executed.
8787 Like a function to build a file,
8788 this function takes three arguments:
8790 (a Node object representing the target file),
8792 (a Node object representing the source file)
8795 (a construction environment).
8800 arguments may be lists of Node objects if there is
8801 more than one target file or source file.
8805 def build_it(target, source, env):
8806 # build the target from the source
8809 def string_it(target, source, env):
8810 return "building '%s' from '%s'" % (target[0], source[0])
8812 # Use a positional argument.
8813 a = Action(build_it, string_it)
8815 # Alternatively, use a keyword argument.
8816 a = Action(build_it, strfunction=string_it)
8819 The third, also optional argument
8820 is a list of construction variables
8821 whose values will be included
8822 in the signature of the Action
8823 when deciding whether a target should
8824 be rebuilt because the action changed.
8825 This is necessary whenever you want a target to
8826 be rebuilt when a specific
8827 construction variable changes,
8828 because the underlying Python code for a function
8829 will not change when the value of the construction variable does.
8832 def build_it(target, source, env):
8833 # build the target from the 'XXX' construction variable
8834 open(target[0], 'w').write(env['XXX'])
8837 def string_it(target, source):
8838 return "building '%s' from '%s'" % (target[0], source[0])
8840 # Use positional arguments.
8841 a = Action(build_it, string_it, ['XXX'])
8843 # Alternatively, use a keyword argument.
8844 a = Action(build_it, varlist=['XXX'])
8854 which specifies that
8855 scons will execute the action
8856 after changing to the specified directory.
8857 If the chdir argument is
8858 a string or a directory Node,
8859 scons will change to the specified directory.
8860 If the chdir argument
8861 is not a string or Node
8863 then scons will change to the
8864 target file's directory.
8866 Note that scons will
8868 automatically modify
8870 construction variables like
8874 when using the chdir
8875 keyword argument--that is,
8876 the expanded file names
8877 will still be relative to
8878 the top-level SConstruct directory,
8879 and consequently incorrect
8880 relative to the chdir directory.
8881 Builders created using chdir keyword argument,
8882 will need to use construction variable
8887 to use just the filename portion of the
8891 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8901 which specifies a function
8902 that is passed the exit status
8904 from the specified action
8905 and can return an arbitrary
8907 This can be used, for example,
8908 to specify that an Action object's
8909 return value should be ignored
8910 and SCons should, therefore,
8911 consider that the action always suceeds:
8914 def always_succeed(s):
8915 # Always return 0, which indicates success.
8917 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8918 exitstatfunc=always_succeed)
8921 .SS Miscellaneous Action Functions
8924 supplies a number of functions
8925 that arrange for various common
8926 file and directory manipulations
8928 These are similar in concept to "tasks" in the
8930 although the implementation is slightly different.
8931 These functions do not actually
8932 perform the specified action
8933 at the time the function is called,
8934 but instead return an Action object
8935 that can be executed at the
8937 (In Object-Oriented terminology,
8942 that return Action objects.)
8945 there are two natural ways
8948 are intended to be used.
8952 to perform the action
8953 at the time the SConscript
8957 global function to do so:
8959 Execute(Touch('file'))
8963 you can use these functions
8964 to supply Actions in a list
8968 This can allow you to
8969 perform more complicated
8970 sequences of file manipulation
8972 on platform-specific
8976 env = Environment(TMPBUILD = '/tmp/builddir')
8977 env.Command('foo.out', 'foo.in',
8978 [Mkdir('$TMPBUILD'),
8979 Copy('$TMPBUILD', '${SOURCE.dir}')
8980 "cd $TMPBUILD && make",
8981 Delete('$TMPBUILD')])
8985 .RI Chmod( dest ", " mode )
8986 Returns an Action object that
8987 changes the permissions on the specified
8989 file or directory to the specified
8994 Execute(Chmod('file', 0755))
8996 env.Command('foo.out', 'foo.in',
8997 [Copy('$TARGET', '$SOURCE'),
8998 Chmod('$TARGET', 0755)])
9002 .RI Copy( dest ", " src )
9003 Returns an Action object
9006 source file or directory to the
9008 destination file or directory.
9012 Execute(Copy('foo.output', 'foo.input'))
9014 env.Command('bar.out', 'bar.in',
9015 Copy('$TARGET', '$SOURCE'))
9019 .RI Delete( entry ", [" must_exist ])
9020 Returns an Action that
9021 deletes the specified
9023 which may be a file or a directory tree.
9024 If a directory is specified,
9025 the entire directory tree
9030 then a Python error will be thrown
9031 if the specified entry does not exist;
9034 that is, the Action will silently do nothing
9035 if the entry does not exist.
9039 Execute(Delete('/tmp/buildroot'))
9041 env.Command('foo.out', 'foo.in',
9042 [Delete('${TARGET.dir}'),
9045 Execute(Delete('file_that_must_exist', must_exist=1))
9051 that creates the specified
9057 Execute(Mkdir('/tmp/outputdir'))
9059 env.Command('foo.out', 'foo.in',
9060 [Mkdir('/tmp/builddir',
9061 Copy('$SOURCE', '/tmp/builddir')
9062 "cd /tmp/builddir && ])
9067 .RI Move( dest ", " src )
9069 that moves the specified
9071 file or directory to
9078 Execute(Move('file.destination', 'file.source'))
9080 env.Command('output_file', 'input_file',
9082 Move('$TARGET', 'file_created_by_MyBuildAction')])
9088 that updates the modification time
9094 Execute(Touch('file_to_be_touched'))
9096 env.Command('marker', 'input_file',
9101 .SS Variable Substitution
9103 Before executing a command,
9105 performs construction variable interpolation on the strings that make up
9106 the command line of builders.
9107 Variables are introduced by a
9110 Besides construction variables, scons provides the following
9111 variables for each command execution:
9114 The file name of the target being built, or the file name of the first
9115 target if multiple targets are being built.
9118 The file names of all targets being built.
9121 The file name of the source of the build command, or the file name of the
9122 first source if multiple sources are being built.
9125 The file names of the sources of the build command.
9127 (Note that the above variables are reserved
9128 and may not be set in a construction environment.)
9131 For example, given the construction variable CC='cc', targets=['foo'], and
9132 sources=['foo.c', 'bar.c']:
9135 action='$CC -c -o $TARGET $SOURCES'
9138 would produce the command line:
9141 cc -c -o foo foo.c bar.c
9144 Variable names may be surrounded by curly braces ({})
9145 to separate the name from the trailing characters.
9146 Within the curly braces, a variable name may have
9147 a Python slice subscript appended to select one
9148 or more items from a list.
9149 In the previous example, the string:
9161 Additionally, a variable name may
9162 have the following special
9163 modifiers appended within the enclosing curly braces
9164 to modify the interpolated string:
9167 The base path of the file name,
9168 including the directory path
9169 but excluding any suffix.
9172 The name of the directory in which the file exists.
9176 minus any directory portion.
9179 Just the basename of the file,
9181 and minus the directory.
9184 Just the file suffix.
9187 The absolute path name of the file.
9190 The POSIX form of the path,
9191 with directories separated by
9195 This is sometimes necessary on Win32 systems
9196 when a path references a file on other (POSIX) systems.
9199 The directory and file name to the source file linked to this file
9200 through BuildDir. If this file isn't linked, it just returns the
9201 directory and filename unchanged.
9204 The directory containing the source file linked to this file
9205 through BuildDir. If this file isn't linked, it just returns the
9206 directory part of the filename.
9209 The directory and file name to the source file linked to this file
9210 through BuildDir. If the file does not exist locally but exists in
9211 a Repository, the path in the Repository is returned.
9212 If this file isn't linked, it just returns the
9213 directory and filename unchanged.
9216 The Repository directory containing the source file linked to this file
9217 through BuildDir. If this file isn't linked, it just returns the
9218 directory part of the filename.
9221 For example, the specified target will
9222 expand as follows for the corresponding modifiers:
9225 $TARGET => sub/dir/file.x
9226 ${TARGET.base} => sub/dir/file
9227 ${TARGET.dir} => sub/dir
9228 ${TARGET.file} => file.x
9229 ${TARGET.filebase} => file
9230 ${TARGET.suffix} => .x
9231 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9233 SConscript('src/SConscript', build_dir='sub/dir')
9234 $SOURCE => sub/dir/file.x
9235 ${SOURCE.srcpath} => src/file.x
9236 ${SOURCE.srcdir} => src
9238 Repository('/usr/repository')
9239 $SOURCE => sub/dir/file.x
9240 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9241 ${SOURCE.rsrcdir} => /usr/repository/src
9244 Lastly, a variable name
9245 may be a callable Python function
9247 construction variable in the environment.
9249 take four arguments:
9251 - a list of target nodes,
9253 - a list of source nodes,
9255 - the construction environment,
9257 - a Boolean value that specifies
9258 whether the function is being called
9259 for generating a build signature.
9260 SCons will insert whatever
9261 the called function returns
9262 into the expanded string:
9265 def foo(target, source, env, for_signature):
9268 # Will expand $BAR to "bar baz"
9269 env=Environment(FOO=foo, BAR="$FOO baz")
9272 You can use this feature to pass arguments to a
9273 Python function by creating a callable class
9274 that stores one or more arguments in an object,
9275 and then uses them when the
9278 Note that in this case,
9279 the entire variable expansion must
9280 be enclosed by curly braces
9281 so that the arguments will
9282 be associated with the
9283 instantiation of the class:
9287 def __init__(self, arg):
9290 def __call__(self, target, source, env, for_signature):
9293 # Will expand $BAR to "my argument bar baz"
9294 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9298 The special pseudo-variables
9302 may be used to surround parts of a command line
9305 causing a rebuild--that is,
9306 which are not included in the signature
9307 of target files built with this command.
9312 will be removed from the command line
9313 before it is added to file signatures,
9318 will be removed before the command is executed.
9319 For example, the command line:
9322 echo Last build occurred $( $TODAY $). > $TARGET
9326 would execute the command:
9329 echo Last build occurred $TODAY. > $TARGET
9333 but the command signature added to any target files would be:
9336 echo Last build occurred . > $TARGET
9339 SCons uses the following rules when converting construction variables into
9343 When the value is a string it is interpreted as a space delimited list of
9344 command line arguments.
9347 When the value is a list it is interpreted as a list of command line
9348 arguments. Each element of the list is converted to a string.
9351 Anything that is not a list or string is converted to a string and
9352 interpreted as a single command line argument.
9355 Newline characters (\\n) delimit lines. The newline parsing is done after
9356 all other parsing, so it is not possible for arguments (e.g. file names) to
9357 contain embedded newline characters. This limitation will likely go away in
9358 a future version of SCons.
9366 new file types for implicit dependencies.
9367 Scanner accepts the following arguments:
9370 A Python function that will process
9372 and return a list of strings (file names)
9373 representing the implicit
9374 dependencies found in the contents.
9375 The function takes three or four arguments:
9377 def scanner_function(node, env, path):
9379 def scanner_function(node, env, path, arg):
9383 argument is the internal
9384 SCons node representing the file.
9387 to fetch the name of the file, and
9388 .B node.get_contents()
9389 to fetch contents of the file.
9393 argument is the construction environment for the scan.
9394 Fetch values from it using the
9400 argument is a tuple (or list)
9401 of directories that can be searched
9403 This will usually be the tuple returned by the
9405 argument (see below).
9409 argument is the argument supplied
9410 when the scanner was created, if any.
9413 The name of the Scanner.
9415 to identify the Scanner internally.
9418 An optional argument that, if specified,
9419 will be passed to the scanner function
9421 and the path function
9425 An optional list that can be used to
9426 determine which scanner should be used for
9428 In the usual case of scanning for file names,
9429 this argument will be a list of suffixes
9430 for the different file types that this
9431 Scanner knows how to scan.
9432 If the argument is a string,
9433 then it will be expanded
9434 into a list by the current environment.
9437 A Python function that takes
9438 two or three arguments:
9439 a construction environment, directory Node,
9440 and optional argument supplied
9441 when the scanner was created.
9444 returns a tuple of directories
9445 that can be searched for files to be returned
9446 by this Scanner object.
9449 The class of Node that should be returned
9450 by this Scanner object.
9451 Any strings or other objects returned
9452 by the scanner function
9453 that are not of this class
9454 will be run through the
9459 A Python function that will take a string
9461 and turn it into the appropriate class of Node
9462 to be returned by this Scanner object.
9465 An optional Python function that takes two arguments,
9466 a Node (file) and a construction environment,
9467 and returns whether the
9468 Node should, in fact,
9469 be scanned for dependencies.
9470 This check can be used to eliminate unnecessary
9471 calls to the scanner function when,
9472 for example, the underlying file
9473 represented by a Node does not yet exist.
9476 An optional flag that
9477 specifies whether this scanner should be re-invoked
9478 on the dependency files returned by the scanner.
9479 When this flag is not set,
9480 the Node subsystem will
9481 only invoke the scanner on the file being scanned,
9482 and not (for example) also on the files
9483 specified by the #include lines
9484 in the file being scanned.
9486 may be a callable function,
9487 in which case it will be called with a list of
9489 should return a list of Nodes
9490 that should be scanned recursively;
9491 this can be used to select a specific subset of
9492 Nodes for additional scanning.
9497 .B SourceFileScanner
9498 object that is used by
9501 .BR SharedObject (),
9505 which scanner should be used
9506 for different file extensions.
9508 .BR SourceFileScanner.add_scanner ()
9509 method to add your own Scanner object
9513 that builds target programs or
9514 libraries from a list of
9515 source files of different types:
9518 def xyz_scan(node, env, path):
9519 contents = node.get_contents()
9520 # Scan the contents and return the included files.
9522 XYZScanner = Scanner(xyz_scan)
9524 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9526 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9529 .SH SYSTEM-SPECIFIC BEHAVIOR
9530 SCons and its configuration files are very portable,
9531 due largely to its implementation in Python.
9532 There are, however, a few portability
9533 issues waiting to trap the unwary.
9535 SCons handles the upper-case
9537 file suffix differently,
9538 depending on the capabilities of
9539 the underlying system.
9540 On a case-sensitive system
9541 such as Linux or UNIX,
9542 SCons treats a file with a
9544 suffix as a C++ source file.
9545 On a case-insensitive system
9547 SCons treats a file with a
9549 suffix as a C source file.
9551 SCons handles the upper-case
9553 file suffix differently,
9554 depending on the capabilities of
9555 the underlying system.
9556 On a case-sensitive system
9557 such as Linux or UNIX,
9558 SCons treats a file with a
9560 suffix as a Fortran source file
9561 that is to be first run through
9562 the standard C preprocessor.
9563 On a case-insensitive system
9565 SCons treats a file with a
9567 suffix as a Fortran source file that should
9569 be run through the C preprocessor.
9570 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9571 Cygwin supplies a set of tools and utilities
9572 that let users work on a
9573 Windows system using a more POSIX-like environment.
9574 The Cygwin tools, including Cygwin Python,
9576 by sharing an ability to interpret UNIX-like path names.
9577 For example, the Cygwin tools
9578 will internally translate a Cygwin path name
9579 like /cygdrive/c/mydir
9580 to an equivalent Windows pathname
9581 of C:/mydir (equivalent to C:\\mydir).
9584 that are built for native Windows execution,
9585 such as the python.org and ActiveState versions,
9586 do not have the Cygwin path name semantics.
9587 This means that using a native Windows version of Python
9588 to build compiled programs using Cygwin tools
9589 (such as gcc, bison, and flex)
9590 may yield unpredictable results.
9591 "Mixing and matching" in this way
9592 can be made to work,
9593 but it requires careful attention to the use of path names
9594 in your SConscript files.
9596 In practice, users can sidestep
9597 the issue by adopting the following rules:
9599 use the Cygwin-supplied Python interpreter
9601 when using Microsoft Visual C/C++
9602 (or some other Windows compiler)
9603 use the python.org or ActiveState version of Python
9605 .SS WIN32: scons.bat file
9607 SCons is executed via a wrapper
9610 This has (at least) two ramifications:
9612 First, Windows command-line users
9613 that want to use variable assignment
9615 may have to put double quotes
9616 around the assignments:
9619 scons "FOO=BAR" "BAZ=BLEH"
9622 Second, the Cygwin shell does not
9623 recognize this file as being the same
9626 command issued at the command-line prompt.
9627 You can work around this either by
9630 from the Cygwin command line,
9631 or by creating a wrapper shell
9637 The MinGW bin directory must be in your PATH environment variable or the
9638 PATH variable under the ENV construction variable for SCons
9639 to detect and use the MinGW tools. When running under the native Windows
9640 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9641 tools, if they are both installed, regardless of the order of the bin
9642 directories in the PATH variable. If you have both MSVC and MinGW
9643 installed and you want to use MinGW instead of MSVC,
9644 then you must explictly tell SCons to use MinGW by passing
9650 to the Environment() function, because SCons will prefer the MSVC tools
9651 over the MinGW tools.
9655 To help you get started using SCons,
9656 this section contains a brief overview of some common tasks.
9658 .SS Basic Compilation From a Single Source File
9662 env.Program(target = 'foo', source = 'foo.c')
9665 Note: Build the file by specifying
9666 the target as an argument
9667 ("scons foo" or "scons foo.exe").
9668 or by specifying a dot ("scons .").
9670 .SS Basic Compilation From Multiple Source Files
9674 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9677 .SS Setting a Compilation Flag
9680 env = Environment(CCFLAGS = '-g')
9681 env.Program(target = 'foo', source = 'foo.c')
9684 .SS Search The Local Directory For .h Files
9688 need to set CCFLAGS to specify -I options by hand.
9689 SCons will construct the right -I options from CPPPATH.
9692 env = Environment(CPPPATH = ['.'])
9693 env.Program(target = 'foo', source = 'foo.c')
9696 .SS Search Multiple Directories For .h Files
9699 env = Environment(CPPPATH = ['include1', 'include2'])
9700 env.Program(target = 'foo', source = 'foo.c')
9703 .SS Building a Static Library
9707 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9708 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9711 .SS Building a Shared Library
9715 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9716 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9719 .SS Linking a Local Library Into a Program
9722 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9723 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9724 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9727 .SS Defining Your Own Builder Object
9729 Notice that when you invoke the Builder,
9730 you can leave off the target file suffix,
9731 and SCons will add it automatically.
9734 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9736 src_suffix = '.tex')
9737 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9738 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9740 # The following creates "bar.pdf" from "bar.tex"
9741 env.PDFBuilder(target = 'bar', source = 'bar')
9744 Note also that the above initialization
9745 overwrites the default Builder objects,
9746 so the Environment created above
9747 can not be used call Builders like env.Program(),
9748 env.Object(), env.StaticLibrary(), etc.
9750 .SS Adding Your Own Builder Object to an Environment
9753 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9755 src_suffix = '.tex')
9757 env.Append(BUILDERS = {'PDFBuilder' : bld})
9758 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9759 env.Program(target = 'bar', source = 'bar.c')
9762 You also can use other Pythonic techniques to add
9763 to the BUILDERS construction variable, such as:
9767 env['BUILDERS]['PDFBuilder'] = bld
9770 .SS Defining Your Own Scanner Object
9775 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9776 '\" not inappropriate doubled escape characters within the r'' raw string.
9777 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9779 def kfile_scan(node, env, path, arg):
9780 contents = node.get_contents()
9781 includes = include_re.findall(contents)
9784 kscan = Scanner(name = 'kfile',
9785 function = kfile_scan,
9788 scanners = Environment().Dictionary('SCANNERS')
9789 env = Environment(SCANNERS = scanners + [kscan])
9791 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9793 bar_in = File('bar.in')
9794 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9795 bar_in.target_scanner = kscan
9798 .SS Creating a Hierarchical Build
9800 Notice that the file names specified in a subdirectory's
9802 file are relative to that subdirectory.
9808 env.Program(target = 'foo', source = 'foo.c')
9810 SConscript('sub/SConscript')
9815 # Builds sub/foo from sub/foo.c
9816 env.Program(target = 'foo', source = 'foo.c')
9818 SConscript('dir/SConscript')
9823 # Builds sub/dir/foo from sub/dir/foo.c
9824 env.Program(target = 'foo', source = 'foo.c')
9827 .SS Sharing Variables Between SConscript Files
9829 You must explicitly Export() and Import() variables that
9830 you want to share between SConscript files.
9836 env.Program(target = 'foo', source = 'foo.c')
9839 SConscript('subdirectory/SConscript')
9841 subdirectory/SConscript:
9844 env.Program(target = 'foo', source = 'foo.c')
9847 .SS Building Multiple Variants From the Same Source
9849 Use the build_dir keyword argument to
9850 the SConscript function to establish
9851 one or more separate build directories for
9852 a given source directory:
9857 cppdefines = ['FOO']
9858 Export("cppdefines")
9859 SConscript('src/SConscript', build_dir='foo')
9861 cppdefines = ['BAR']
9862 Export("cppdefines")
9863 SConscript('src/SConscript', build_dir='bar')
9867 Import("cppdefines")
9868 env = Environment(CPPDEFINES = cppdefines)
9869 env.Program(target = 'src', source = 'src.c')
9872 Note the use of the Export() method
9873 to set the "cppdefines" variable to a different
9874 value each time we call the SConscript function.
9876 .SS Hierarchical Build of Two Libraries Linked With a Program
9881 env = Environment(LIBPATH = ['#libA', '#libB'])
9883 SConscript('libA/SConscript')
9884 SConscript('libB/SConscript')
9885 SConscript('Main/SConscript')
9890 env.Library('a', Split('a1.c a2.c a3.c'))
9895 env.Library('b', Split('b1.c b2.c b3.c'))
9900 e = env.Copy(LIBS = ['a', 'b'])
9901 e.Program('foo', Split('m1.c m2.c m3.c'))
9904 The '#' in the LIBPATH directories specify that they're relative to the
9905 top-level directory, so they don't turn into "Main/libA" when they're
9906 used in Main/SConscript.
9908 Specifying only 'a' and 'b' for the library names
9909 allows SCons to append the appropriate library
9910 prefix and suffix for the current platform
9911 (for example, 'liba.a' on POSIX systems,
9912 'a.lib' on Windows).
9914 .SS Customizing contruction variables from the command line.
9916 The following would allow the C compiler to be specified on the command
9917 line or in the file custom.py.
9920 opts = Options('custom.py')
9921 opts.Add('CC', 'The C compiler.')
9922 env = Environment(options=opts)
9923 Help(opts.GenerateHelpText(env))
9926 The user could specify the C compiler on the command line:
9932 or in the custom.py file:
9938 or get documentation on the options:
9949 .SS Using Microsoft Visual C++ precompiled headers
9951 Since windows.h includes everything and the kitchen sink, it can take quite
9952 some time to compile it over and over again for a bunch of object files, so
9953 Microsoft provides a mechanism to compile a set of headers once and then
9954 include the previously compiled headers in any object file. This
9955 technology is called precompiled headers. The general recipe is to create a
9956 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9957 then include every header you want to precompile in "StdAfx.h", and finally
9958 include "StdAfx.h" as the first header in all the source files you are
9959 compiling to object files. For example:
9963 #include <windows.h>
9964 #include <my_big_header.h>
9983 /* do some other stuff */
9989 env['PCHSTOP'] = 'StdAfx.h'
9990 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9991 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9994 For more information see the document for the PCH builder, and the PCH and
9995 PCHSTOP construction variables. To learn about the details of precompiled
9996 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9998 .SS Using Microsoft Visual C++ external debugging information
10000 Since including debugging information in programs and shared libraries can
10001 cause their size to increase significantly, Microsoft provides a mechanism
10002 for including the debugging information in an external file called a PDB
10003 file. SCons supports PDB files through the PDB construction
10009 env['PDB'] = 'MyApp.pdb'
10010 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10013 For more information see the document for the PDB construction variable.
10018 Specifies the directory that contains the SCons Python module directory
10019 (e.g. /home/aroach/scons-src-0.01/src/engine).
10022 A string of options that will be used by scons in addition to those passed
10023 on the command line.
10034 Steven Knight <knight@baldmt.com>
10036 Anthony Roach <aroach@electriceyeball.com>