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 "November 2003"
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')
318 requires Python version 1.5.2 or later.
319 There should be no other dependencies or requirements to run
322 .\" The following paragraph reflects the default tool search orders
323 .\" currently in SCons/Tool/__init__.py. If any of those search orders
324 .\" change, this documentation should change, too.
327 knows how to search for available programming tools
331 searches in order for the
332 Microsoft Visual C++ tools,
333 the MinGW tool chain,
334 the Intel compiler tools,
335 and the PharLap ETS compiler.
338 searches in order for the
341 and the Microsoft Visual C++ tools,
342 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
344 searches for the native compiler tools
345 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
346 and the GCC tool chain.
347 On all other platforms,
348 including POSIX (Linux and UNIX) platforms,
351 for the GCC tool chain,
352 the Microsoft Visual C++ tools,
353 and the Intel compiler tools.
354 You may, of course, override these default values
355 by appropriate configuration of
356 Environment construction variables.
361 supports the same command-line options as GNU
363 and many of those supported by
368 Ignored for compatibility with non-GNU versions of
372 -c, --clean, --remove
373 Clean up by removing all target files for which a construction
374 command is specified.
375 Also remove any files or directories associated to the construction command
376 using the Clean() function.
379 --cache-disable, --no-cache
380 Disable the derived-file caching specified by
383 will neither retrieve files from the cache
384 nor copy files to the cache.
387 --cache-force, --cache-populate
390 populate a cache by copying any already-existing, up-to-date
391 derived files to the cache,
392 in addition to files built by this invocation.
393 This is useful to populate a new cache with
394 all the current derived files,
395 or to add to the cache any derived files
396 recently built with caching disabled via the
404 and retrieving a derived file from the cache,
406 that would have been executed to build the file,
407 instead of the usual report,
408 "Retrieved `file' from cache."
409 This will produce consistent output for build logs,
410 regardless of whether a target
411 file was rebuilt or retrieved from the cache.
414 .RI "-C" " directory" ", --directory=" directory
415 Change to the specified
417 before searching for the
422 file, or doing anything
425 options are interpreted
426 relative to the previous one, and the right-most
428 option wins. (This option is nearly
430 .BR "-f directory/SConstruct" ,
431 except that it will search for
436 in the specified directory.)
440 .\" Display dependencies while building target files. Useful for
441 .\" figuring out why a specific file is being rebuilt, as well as
442 .\" general debugging of the build process.
446 Works exactly the same way as the
448 option except for the way default targets are handled.
449 When this option is used and no targets are specified on the command line,
450 all default targets are built, whether or not they are below the current
455 Debug the build process.
457 specifies what type of debugging:
461 Print a count of how many objects are created
462 of the various classes used internally by SCons.
463 This only works when run under Python 2.1 or later.
467 Print the dependency tree
468 after each top-level target is built. This prints out only derived files.
472 Print the include tree after each top-level target is built.
473 This is generally used to find out what files are included by the sources
474 of a given derived file:
477 $ scons --debug=includes foo.o
482 Prints how much memory SCons uses
483 before and after reading the SConscript files
484 and before and after building.
488 Prints a list of the various objects
489 of the various classes used internally by SCons.
490 This only works when run under Python 2.1 or later.
494 Re-run SCons under the control of the
501 Print the raw command line used to build each target
502 before the construction environment variables are substituted.
503 Also shows which targets are being built by this command.
504 Output looks something like this:
506 $ scons --debug=presub
507 Building myprog.o with action(s):
508 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
514 Prints various time profiling information: the time spent
515 executing each build command, the total build time, the total time spent
516 executing build commands, the total time spent executing SConstruct and
517 SConscript files, and the total time spent executing SCons itself.
521 Print the dependency tree
522 after each top-level target is built. This prints out the complete
523 dependency tree including implicit dependencies and ignored
527 .\" -e, --environment-overrides
528 .\" Variables from the execution environment override construction
529 .\" variables from the SConscript files.
532 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
535 as the initial SConscript file.
539 Print a local help message for this build, if one is defined in
540 the SConscript file(s), plus a line that describes the
542 option for command-line option help. If no local help message
543 is defined, prints the standard help message about command-line
544 options. Exits after displaying the appropriate message.
548 Print the standard help message about command-line options and
553 Ignore all errors from commands executed to rebuild files.
556 .RI -I " directory" ", --include-dir=" directory
560 imported Python modules. If several
563 are used, the directories are searched in the order specified.
567 Cache implicit dependencies. This can cause
569 to miss changes in the implicit dependencies in cases where a new implicit
570 dependency is added earlier in the implicit dependency search path
571 (e.g. CPPPATH) than a current implicit dependency with the same name.
574 --implicit-deps-changed
575 Force SCons to ignore the cached implicit dependencies. This causes the
576 implicit dependencies to be rescanned and recached. This implies
577 .BR --implicit-cache .
580 --implicit-deps-unchanged
581 Force SCons to ignore changes in the implicit dependencies.
582 This causes cached implicit dependencies to always be used.
584 .BR --implicit-cache .
587 .RI -j " N" ", --jobs=" N
588 Specifies the number of jobs (commands) to run simultaneously.
589 If there is more than one
591 option, the last one is effective.
595 .\" is specified without an argument,
597 .\" will not limit the number of
598 .\" simultaneous jobs.
602 Continue as much as possible after an error. The target that
603 failed and those that depend on it will not be remade, but other
604 targets specified on the command line will still be processed.
607 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
608 .\" No new jobs (commands) will be started if
609 .\" there are other jobs running and the system load
610 .\" average is at least
612 .\" (a floating-point number).
615 .RI --duplicate= ORDER
616 There are three ways to duplicate files in a build tree: hard links,
617 soft (symbolic) links and copies. The default behaviour of SCons is to
618 prefer hard links to soft links to copies. You can specify different
619 behaviours with this option.
629 SCons will attempt to duplicate files using
630 the mechanisms in the specified order.
635 .\" List derived files (targets, dependencies) that would be built,
636 .\" but do not build them.
637 .\" [XXX This can probably go away with the right
638 .\" combination of other options. Revisit this issue.]
642 .\" List derived files that would be built, with the actions
643 .\" (commands) that build them. Does not build the files.
644 .\" [XXX This can probably go away with the right
645 .\" combination of other options. Revisit this issue.]
649 .\" List derived files that would be built, plus where the file is
650 .\" defined (file name and line number). Does not build the files.
651 .\" [XXX This can probably go away with the right
652 .\" combination of other options. Revisit this issue.]
656 Ignored for compatibility with non-GNU versions of
660 .RI --max-drift= SECONDS
661 Set the maximum expected drift in the modification time of files to
663 This value determines how old a file must be before its content signature
664 is cached. The default value is 2 days, which means a file must have a
665 modification time of at least two days ago in order to have its content
666 signature cached. A negative value means to never cache the content
667 signature and to ignore the cached value if there already is one. A value
668 of 0 means to always cache the signature, no matter how old the file is.
671 -n, --just-print, --dry-run, --recon
672 No execute. Print the commands that would be executed to build
673 any out-of-date target files, but do not execute the commands.
676 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
680 .\" not rebuild anything due to changes in the contents of
683 .\" .RI --override " file"
684 .\" Read values to override specific build environment variables
685 .\" from the specified
689 .\" Print the data base (construction environments,
690 .\" Builder and Scanner objects) that are defined
691 .\" after reading the SConscript files.
692 .\" After printing, a normal build is performed
693 .\" as usual, as specified by other command-line options.
694 .\" This also prints version information
699 .\" To print the database without performing a build do:
707 Run SCons under the Python profiler
708 and save the results in the specified
710 The results may be analyzed using the Python
714 Do not run any commands, or print anything. Just return an exit
715 status that is zero if the specified targets are already up to
716 date, non-zero otherwise.
719 Quiets SCons status messages about
720 reading SConscript files,
722 and entering directories.
723 Commands that are executed
724 to rebuild target files are still printed.
727 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
728 .\" Clear the default construction variables. Construction
729 .\" environments that are created will be completely empty.
733 Build dependencies in a random order. This is useful when
734 building multiple trees simultaneously with caching enabled,
735 to prevent multiple builds from simultaneously trying to build
736 or retrieve the same target files.
739 -s, --silent, --quiet
740 Silent. Do not print commands that are executed to rebuild
742 Also suppresses SCons status messages.
745 -S, --no-keep-going, --stop
746 Ignored for compatibility with GNU
751 Ignored for compatibility with GNU
753 (Touching a file to make it
754 appear up-to-date is unnecessary when using
758 -u, --up, --search-up
759 Walks up the directory structure until an
764 file is found, and uses that
765 as the top of the directory tree.
766 If no targets are specified on the command line,
767 only targets at or below the
768 current directory will be built.
772 Works exactly the same way as the
774 option except for the way default targets are handled.
775 When this option is used and no targets are specified on the command line,
776 all default targets that are defined in the SConscript(s) in the current
777 directory are built, regardless of what directory the resultant targets end
784 version, copyright information,
785 list of authors, and any other relevant information.
789 -w, --print-directory
790 Print a message containing the working directory before and
791 after other processing.
794 .RI --warn= type ", --warn=no-" type
795 Enable or disable warnings.
797 specifies the type of warnings to be enabled or disabled:
800 --warn=all, --warn=no-all
801 Enables or disables all warnings.
804 --warn=dependency, --warn=no-dependency
805 Enables or disables warnings about dependencies.
806 These warnings are disabled by default.
809 --warn=deprecated, --warn=no-deprecated
810 Enables or disables warnings about use of deprecated features.
811 These warnings are enabled by default.
814 --warn=missing-sconscript, --warn=no-missing-sconscript
815 Enables or disables warnings about missing SConscript files.
816 These warnings are enabled by default.
820 Turn off -w, even if it was turned on implicitly.
823 .\" .RI --write-filenames= file
824 .\" Write all filenames considered into
828 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
829 .\" Pretend that the target
832 .\" modified. When used with the
835 .\" show you what would be rebuilt if you were to modify that file.
841 .\" --warn-undefined-variables
842 .\" Warn when an undefined variable is referenced.
845 .RI -Y " repository" ", --repository=" repository
846 Search the specified repository for any input and target
847 files not found in the local directory hierarchy. Multiple
849 options may specified, in which case the
850 repositories are searched in the order specified.
852 .SH CONFIGURATION FILE REFERENCE
853 .\" .SS Python Basics
854 .\" XXX Adding this in the future would be a help.
855 .SS Construction Environments
856 A construction environment is the basic means by which the SConscript
857 files communicate build information to
859 A new construction environment is created using the
867 By default, a new construction environment is
868 initialized with a set of builder methods
869 and construction variables that are appropriate
870 for the current platform.
871 An optional platform keyword argument may be
872 used to specify that an environment should
873 be initialized for a different platform:
876 env = Environment(platform = 'cygwin')
877 env = Environment(platform = 'os2')
878 env = Environment(platform = 'posix')
879 env = Environment(platform = 'win32')
882 Specifying a platform initializes the appropriate
883 construction variables in the environment
884 to use and generate file names with prefixes
885 and suffixes appropriate for the platform.
891 variable from the user's external environment
892 to the construction environment's
895 This is so that any executed commands
896 that use sockets to connect with other systems
897 (such as fetching source files from
898 external CVS repository specifications like
899 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
900 will work on Win32 systems.
902 The platform argument may be function or callable object,
903 in which case the Environment() method
904 will call the specified argument to update
905 the new construction environment:
908 def my_platform(env):
911 env = Environment(platform = my_platform)
914 Additionally, a specific set of tools
915 with which to initialize the environment
916 may specified as an optional keyword argument:
919 env = Environment(tools = ['msvc', 'lex'])
922 Non-built-in tools may be specified using the toolpath argument:
925 env = Environment(tools = ['foo'], toolpath = ['tools'])
928 This looks for a tool specification in tools/foo.py. foo.py should
929 have two functions: generate(env) and exists(env). generate()
930 modifies the passed in environment and exists() should return a true
931 value if the tool is available. Tools in the toolpath are used before
932 any of the built-in ones. For example, adding gcc.py to the toolpath
933 would override the built-in gcc tool.
935 The elements of the tools list may also
936 be functions or callable objects,
937 in which case the Environment() method
938 will call the specified elements
939 to update the new construction environment:
943 env['XYZZY'] = 'xyzzy'
945 env = Environment(tools = [my_tool])
948 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
949 the environment it receives to customize the tool for different platforms.
951 If no tool list is specified, then SCons will auto-detect the installed
952 tools using the PATH variable in the ENV construction variable and the
953 platform name when the Environment is constructed. Changing the PATH
954 variable after the Environment is constructed will not cause the tools to
957 SCons supports the following tool specifications out of the box:
1024 Additionally, there is a "tool" named
1026 which configures the
1027 environment with a default set of tools for the current platform.
1029 On posix and cygwin platforms
1030 the GNU tools (e.g. gcc) are preferred by SCons,
1031 on win32 the Microsoft tools (e.g. msvc)
1032 followed by MinGW are preferred by SCons,
1033 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1037 Build rules are specified by calling a construction
1038 environment's builder methods.
1039 The arguments to the builder methods are
1041 (a list of target files)
1044 (a list of source files).
1046 Because long lists of file names
1047 can lead to a lot of quoting,
1052 and a same-named environment method
1053 that split a single string
1054 into a list, separated on
1055 strings of white-space characters.
1056 (These are similar to the
1057 string.split() method
1058 from the standard Python library,
1059 but work even if the input isn't a string.)
1061 Like all Python arguments,
1062 the target and source arguments to a builder method
1063 can be specified either with or without
1064 the "target" and "source" keywords.
1065 When the keywords are omitted,
1066 the target is first,
1067 followed by the source.
1068 The following are equivalent examples of calling the Program builder method:
1071 env.Program('bar', ['bar.c', 'foo.c'])
1072 env.Program('bar', Split('bar.c foo.c'))
1073 env.Program('bar', env.Split('bar.c foo.c'))
1074 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1075 env.Program(target = 'bar', Split('bar.c foo.c'))
1076 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1077 env.Program('bar', source = string.split('bar.c foo.c'))
1080 When the target shares the same base name
1081 as the source and only the suffix varies,
1082 and if the builder method has a suffix defined for the target file type,
1083 then the target argument may be omitted completely,
1086 will deduce the target file name from
1087 the source file name.
1088 The following examples all build the
1094 (on Windows systems)
1095 from the bar.c source file:
1098 env.Program(target = 'bar', source = 'bar.c')
1099 env.Program('bar', source = 'bar.c')
1100 env.Program(source = 'bar.c')
1101 env.Program('bar.c')
1104 It is possible to override or add construction variables when calling a
1105 builder method by passing additional keyword arguments.
1106 These overridden or added
1107 variables will only be in effect when building the target, so they will not
1108 affect other parts of the build. For example, if you want to add additional
1109 libraries for just one program:
1112 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1115 or generate a shared library with a nonstandard suffix:
1118 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1121 Although the builder methods defined by
1124 methods of a construction environment object,
1125 they may also be called without an explicit environment:
1128 Program('hello', 'hello.c')
1129 SharedLibrary('word', 'word.cpp')
1133 the methods are called internally using a default construction
1134 environment that consists of the tools and values that
1136 has determined are appropriate for the local system.
1138 All builder methods return a Node or a list of Nodes,
1139 representing the target or targets that will be built.
1140 A list of Nodes is returned if there is more than one target,
1141 and a single Node is returned if there is only one target.
1144 is an internal SCons object
1146 build targets or sources.
1148 The returned Node(s)
1149 can be passed to other builder methods as source(s)
1150 or passed to any SCons function or method
1151 where a filename would normally be accepted.
1152 For example, if it were necessary
1155 flag when compiling one specific object file:
1158 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1159 env.Program(source = ['foo.c', bar_obj, 'main.c'])
1162 Using a Node in this way
1163 makes for a more portable build
1164 by avoiding having to specify
1165 a platform-specific object suffix
1166 when calling the Program() builder method.
1168 The path name for a Node's file may be used
1169 by passing the Node to the Python-builtin
1174 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1175 print "The path to bar_obj is:", str(bar_obj)
1179 provides the following builder methods:
1181 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1184 Builds a C source file given a lex (.l) or yacc (.y) input file.
1185 The suffix specified by the $CFILESUFFIX construction variable
1187 is automatically added to the target
1188 if it is not already present. Example:
1192 env.CFile(target = 'foo.c', source = 'foo.l')
1194 env.CFile(target = 'bar', source = 'bar.y')
1197 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1200 Builds a C++ source file given a lex (.ll), yacc (.yy)
1201 or uic (.ui) input file.
1202 The suffix specified by the $CXXFILESUFFIX construction variable
1204 is automatically added to the target
1205 if it is not already present. Example:
1209 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1211 env.CXXFile(target = 'bar', source = 'bar.yy')
1214 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1217 Builds a .dvi file from a .tex, .ltx or .latex input file.
1218 If the source file suffix is .tex,
1220 will examine the contents of the file;
1225 is found, the file is assumed to be a LaTeX file and
1226 the target is built by invoking the $LATEXCOM command line;
1227 otherwise, the $TEXCOM command line is used.
1228 If the file is a LaTeX file,
1231 builder method will also examine the contents
1234 and invoke the $BIBTEX command line
1238 and will examine the contents
1240 file and re-run the $LATEXCOM command
1241 if the log file says it is necessary.
1244 (hard-coded within TeX itself)
1245 is automatically added to the target
1246 if it is not already present. Examples:
1249 # builds from aaa.tex
1250 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1252 env.DVI(target = 'bbb', source = 'bbb.ltx')
1253 # builds from ccc.latex
1254 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1257 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1260 Builds a Java archive (.jar) file
1261 from a source tree of .class files.
1262 If the $JARCHDIR value is set, the
1264 command will change to the specified directory using the
1267 If the contents any of the source files begin with the string
1268 .BR Manifest-Version ,
1269 the file is assumed to be a manifest
1270 and is passed to the
1277 env.Jar(target = 'foo.jar', source = 'classes')
1280 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1283 Builds one or more Java class files
1284 from one or more source trees of .java files.
1285 The class files will be placed underneath
1286 the specified target directory.
1287 SCons will parse each source .java file
1289 (including inner classes)
1290 defined within that file,
1291 and from that figure out the
1292 target .class files that will be created.
1293 SCons will also search each Java file
1294 for the Java package name,
1295 which it assumes can be found on a line
1296 beginning with the string
1298 in the first column;
1299 the resulting .class files
1300 will be placed in a directory reflecting
1301 the specified package name.
1305 defining a single public
1308 containing a package name of
1310 will generate a corresponding
1311 .IR sub/dir/Foo.class
1317 env.Java(target = 'classes', source = 'src')
1318 env.Java(target = 'classes', source = ['src1', 'src2'])
1321 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1324 Builds C header and source files for
1325 implementing Java native methods.
1326 The target can be either a directory
1327 in which the header files will be written,
1328 or a header file name which
1329 will contain all of the definitions.
1330 The source can be either the names of .class files,
1331 or the objects returned from the
1335 If the construction variable
1337 is set, either in the environment
1338 or in the call to the
1340 builder method itself,
1341 then the value of the variable
1342 will be stripped from the
1343 beginning of any .class file names.
1348 # builds java_native.h
1349 classes = env.Java(target = 'classdir', source = 'src')
1350 env.JavaH(target = 'java_native.h', source = classes)
1352 # builds include/package_foo.h and include/package_bar.h
1353 env.JavaH(target = 'include',
1354 source = ['package/foo.class', 'package/bar.class'])
1356 # builds export/foo.h and export/bar.h
1357 env.JavaH(target = 'export',
1358 source = ['classes/foo.class', 'classes/bar.class'],
1359 JAVACLASSDIR = 'classes')
1362 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1369 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1372 Builds an output file from an M4 input file.
1373 This uses a default $M4FLAGS value of
1375 which considers all warnings to be fatal
1376 and stops on the first warning
1377 when using the GNU version of m4.
1381 env.M4(target = 'foo.c', source = 'foo.c.m4')
1384 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1386 .IP env.MSVSProject()
1387 Builds Microsoft Visual Studio project files.
1388 This builds a Visual Studio project file, based on the version of
1389 Visual Studio that is configured (either the latest installed version,
1390 or the version set by
1392 in the Environment constructor).
1393 For VS 6, it will generate
1397 files, for VS 7, it will
1404 It takes several lists of filenames to be placed into the project
1405 file, currently these are limited to
1406 .B srcs, incs, localincs, resources,
1409 These are pretty self explanatory, but it
1410 should be noted that the 'srcs' list is NOT added to the $SOURCES
1411 environment variable. This is because it represents a list of files
1412 to be added to the project file, not the source used to build the
1413 project file (in this case, the 'source' is the SConscript file used
1414 to call MSVSProject).
1416 In addition to these values (which are all optional, although not
1417 specifying any of them results in an empty project file), the
1418 following values must be specified:
1420 target: The name of the target .dsp or .vcproj file. The correct
1421 suffix for the version of Visual Studio must be used, but the value
1423 env['MSVSPROJECTSUFFIX']
1425 will be defined to the correct value (see example below).
1427 variant: The name of this particular variant. These are typically
1428 things like "Debug" or "Release", but really can be anything you want.
1429 Multiple calls to MSVSProject with different variants are allowed: all
1430 variants will be added to the project file with their appropriate
1431 build targets and sources.
1433 buildtarget: A list of SCons.Node.FS objects which is returned from
1434 the command which builds the target. This is used to tell SCons what
1435 to build when the 'build' button is pressed inside of the IDE.
1440 barsrcs = ['bar.cpp'],
1441 barincs = ['bar.h'],
1442 barlocalincs = ['StdAfx.h']
1443 barresources = ['bar.rc','resource.h']
1444 barmisc = ['bar_readme.txt']
1446 dll = local.SharedLibrary(target = 'bar.dll',
1449 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1452 localincs = barlocalincs,
1453 resources = barresources,
1456 variant = 'Release')
1459 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1469 Builds a Microsoft Visual C++ precompiled header.
1470 Calling this builder method
1471 returns a list of two targets: the PCH as the first element, and the object
1472 file as the second element. Normally the object file is ignored.
1473 This builder method is only
1474 provided when Microsoft Visual C++ is being used as the compiler.
1475 The PCH builder method is generally used in
1476 conjuction with the PCH construction variable to force object files to use
1477 the precompiled header:
1480 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1483 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1486 Builds a .pdf file from a .dvi input file
1487 (or, by extension, a .tex, .ltx, or .latex input file).
1488 The suffix specified by the $PDFSUFFIX construction variable
1490 is added automatically to the target
1491 if it is not already present. Example:
1494 # builds from aaa.tex
1495 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1496 # builds bbb.pdf from bbb.dvi
1497 env.PDF(target = 'bbb', source = 'bbb.dvi')
1500 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1502 .IP env.PostScript()
1503 Builds a .ps file from a .dvi input file
1504 (or, by extension, a .tex, .ltx, or .latex input file).
1505 The suffix specified by the $PSSUFFIX construction variable
1507 is added automatically to the target
1508 if it is not already present. Example:
1511 # builds from aaa.tex
1512 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1513 # builds bbb.ps from bbb.dvi
1514 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1517 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1520 Builds an executable given one or more object files
1521 or C, C++, D, or Fortran source files.
1522 If any C, C++, D or Fortran source files are specified,
1523 then they will be automatically
1524 compiled to object files using the
1527 see that builder method's description for
1528 a list of legal source file suffixes
1529 and how they are interpreted.
1530 The target executable file prefix
1531 (specified by the $PROGPREFIX construction variable; nothing by default)
1533 (specified by the $PROGSUFFIX construction variable;
1534 by default, .exe on Windows systems, nothing on POSIX systems)
1535 are automatically added to the target if not already present.
1539 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1542 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1545 Builds a Microsoft Visual C++ resource file.
1546 This builder method is only provided
1547 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1551 for MinGW) suffix is added to the target name if no other suffix is given. The source
1552 file is scanned for implicit dependencies as though it were a C file. Example:
1555 env.RES('resource.rc')
1558 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1561 Builds stub and skeleton class files
1563 from Java .class files.
1564 The target is a directory
1565 relative to which the stub
1566 and skeleton class files will be written.
1567 The source can be the names of .class files,
1568 or the objects return from the
1572 If the construction variable
1574 is set, either in the environment
1575 or in the call to the
1577 builder method itself,
1578 then the value of the variable
1579 will be stripped from the
1580 beginning of any .class file names.
1583 classes = env.Java(target = 'classdir', source = 'src')
1584 env.RMIC(target = 'outdir1', source = classes)
1586 env.RMIC(target = 'outdir2',
1587 source = ['package/foo.class', 'package/bar.class'])
1589 env.RMIC(target = 'outdir3',
1590 source = ['classes/foo.class', 'classes/bar.class'],
1591 JAVACLASSDIR = 'classes')
1594 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1596 .IP env.SharedLibrary()
1597 Builds a shared library
1598 (.so on a POSIX system, .dll on WIN32)
1599 given one or more object files
1600 or C, C++, D or Fortran source files.
1601 If any source files are given,
1602 then they will be automatically
1603 compiled to object files.
1604 The static library prefix and suffix (if any)
1605 are automatically added to the target.
1606 The target library file prefix
1607 (specified by the $SHLIBPREFIX construction variable;
1608 by default, lib on POSIX systems, nothing on Windows systems)
1610 (specified by the $SHLIBSUFFIX construction variable;
1611 by default, .dll on Windows systems, .so on POSIX systems)
1612 are automatically added to the target if not already present.
1616 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1619 On WIN32 systems, the
1621 builder method will always build an import (.lib) library
1622 in addition to the shared (.dll) library,
1623 adding a .lib library with the same basename
1624 if there is not already a .lib file explicitly
1625 listed in the targets.
1627 Any object files listed in the
1629 must have been built for a shared library
1634 will raise an error if there is any mismatch.
1636 On WIN32 systems, specifying "register=1" will cause the dll to be
1637 registered after it is built using REGSVR32. The command that is run
1638 ("regsvr32" by default) is determined by $REGSVR construction
1639 variable, and the flags passed are determined by $REGSVRFLAGS. By
1640 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1641 up and requiring user attention when it is run. If you change
1642 $REGSVRFLAGS, be sure to include "/s". For example,
1645 env.SharedLibrary(target = 'bar',
1646 source = ['bar.cxx', 'foo.obj'],
1651 will register "bar.dll" as a COM object when it is done linking it.
1653 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1655 .IP env.SharedObject()
1656 Builds an object file for
1657 inclusion in a shared library.
1658 Source files must have one of the same set of extensions
1659 specified above for the
1662 On some platforms building a shared object requires additional
1663 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1664 normal (static) object, but on some platforms there is no difference between a
1665 shared object and a normal (static) one. When there is a difference, SCons
1666 will only allow shared objects to be linked into a shared library, and will
1667 use a different suffix for shared objects. On platforms where there is no
1668 difference, SCons will allow both normal (static)
1669 and shared objects to be linked into a
1670 shared library, and will use the same suffix for shared and normal
1672 The target object file prefix
1673 (specified by the $SHOBJPREFIX construction variable;
1674 by default, the same as $OBJPREFIX)
1676 (specified by the $SHOBJSUFFIX construction variable)
1677 are automatically added to the target if not already present.
1681 env.SharedObject(target = 'ddd', source = 'ddd.c')
1682 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1683 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1686 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1688 .IP env.StaticLibrary()
1689 Builds a static library given one or more object files
1690 or C, C++, D or Fortran source files.
1691 If any source files are given,
1692 then they will be automatically
1693 compiled to object files.
1694 The static library prefix and suffix (if any)
1695 are automatically added to the target.
1696 The target library file prefix
1697 (specified by the $LIBPREFIX construction variable;
1698 by default, lib on POSIX systems, nothing on Windows systems)
1700 (specified by the $LIBSUFFIX construction variable;
1701 by default, .lib on Windows systems, .a on POSIX systems)
1702 are automatically added to the target if not already present.
1706 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1710 Any object files listed in the
1712 must have been built for a static library
1717 will raise an error if there is any mismatch.
1719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1721 .IP env.StaticObject()
1722 Builds a static object file
1723 from one or more C, C++, D, or Fortran source files.
1724 Source files must have one of the following extensions:
1727 .asm assembly language file
1728 .ASM assembly language file
1740 .F WIN32: Fortran file
1741 POSIX: Fortran file + C pre-processor
1744 .fpp Fortran file + C pre-processor
1745 .FPP Fortran file + C pre-processor
1746 .s assembly language file
1747 .S WIN32: assembly language file
1748 POSIX: assembly language file + C pre-processor
1749 .spp assembly language file + C pre-processor
1750 .SPP assembly language file + C pre-processor
1753 The target object file prefix
1754 (specified by the $OBJPREFIX construction variable; nothing by default)
1756 (specified by the $OBJSUFFIX construction variable;
1757 \.obj on Windows systems, .o on POSIX systems)
1758 are automatically added to the target if not already present.
1762 env.StaticObject(target = 'aaa', source = 'aaa.c')
1763 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1764 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1767 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1770 Builds a tar archive of the specified files
1772 Unlike most builder methods,
1775 builder method may be called multiple times
1777 each additional call
1778 adds to the list of entries
1779 that will be built into the archive.
1782 env.Tar('src.tar', 'src')
1784 # Create the stuff.tar file.
1785 env.Tar('stuff', ['subdir1', 'subdir2'])
1786 # Also add "another" to the stuff.tar file.
1787 env.Tar('stuff', 'another')
1789 # Set TARFLAGS to create a gzip-filtered archive.
1790 env = Environment(TARFLAGS = '-c -z')
1791 env.Tar('foo.tar.gz', 'foo')
1793 # Also set the suffix to .tgz.
1794 env = Environment(TARFLAGS = '-c -z',
1799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1801 .IP env.TypeLibrary()
1802 Builds a Windows type library (.tlb) file from and input IDL file
1803 (.idl). In addition, it will build the associated inteface stub and
1804 proxy source files. It names them according to the base name of the .idl file.
1809 env.TypeLibrary(source="foo.idl")
1812 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1817 Builds a zip archive of the specified files
1819 Unlike most builder methods,
1822 builder method may be called multiple times
1824 each additional call
1825 adds to the list of entries
1826 that will be built into the archive.
1829 env.Zip('src.zip', 'src')
1831 # Create the stuff.zip file.
1832 env.Zip('stuff', ['subdir1', 'subdir2'])
1833 # Also add "another" to the stuff.tar file.
1834 env.Zip('stuff', 'another')
1839 C source files, C++ source files,
1840 Fortran source files with
1842 (POSIX systems only),
1847 and assembly language files with
1849 (POSIX systems only),
1854 for C preprocessor dependencies,
1855 so the dependencies do not need to be specified explicitly.
1857 targets of builder methods automatically depend on their sources.
1858 An explicit dependency can
1859 be specified using the
1861 method of a construction environment (see below).
1863 .SS Methods and Functions to Do Things
1864 In addition to Builder methods,
1866 provides a number of other construction environment methods
1867 and global functions to
1868 manipulate the build configuration.
1870 Usually, a construction environment method
1871 and global function with the same name both exist
1872 so that you don't have to remember whether
1873 to a specific bit of functionality
1874 must be called with or without a construction environment.
1875 In the following list,
1876 if you call something as a global function
1879 .RI Function( arguments )
1881 and if you call something through a construction
1882 environment it looks like:
1884 .RI env.Function( arguments )
1886 If you can call the functionality in both ways,
1887 then both forms are listed.
1889 Except where otherwise noted,
1891 construction environment method
1893 provide the exact same functionality.
1894 The only difference is that,
1896 calling the functionality through a construction environment will
1897 substitute construction variables into
1898 any supplied strings.
1901 env = Environment(FOO = 'foo')
1905 the first call to the global
1907 function will actually add a target named
1909 to the list of default targets,
1910 while the second call to the
1912 construction environment method
1913 will expand the value
1914 and add a target named
1916 to the list of default targets.
1917 For more on construction variable expansion,
1918 see the next section on
1919 construction variables.
1921 Construction environment methods
1922 and global functions supported by
1926 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1928 .RI Action( action ", [" strfunction ", " varlist ])
1930 .RI env.Action( action ", [" strfunction ", " varlist ])
1931 Creates an Action object for
1934 See the section "Action Objects,"
1935 below, for a complete explanation of the arguments and behavior.
1937 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1939 .RI AddPostAction( target ", " action )
1941 .RI env.AddPostAction( target ", " action )
1942 Arranges for the specified
1948 The specified action(s) may be
1949 an Action object, or anything that
1950 can be converted into an Action object
1953 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1955 .RI AddPreAction( target ", " action )
1957 .RI env.AddPreAction( target ", " action )
1958 Arranges for the specified
1961 before the specified
1964 The specified action(s) may be
1965 an Action object, or anything that
1966 can be converted into an Action object
1969 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1971 .RI Alias( alias ", [" targets ])
1973 .RI env.Alias( alias ", [" targets ])
1974 Creates one or more phony targets that
1975 expand to one or more other targets.
1976 Returns the Node object representing the alias,
1977 which exists outside of any file system.
1978 This Node object, or the alias name,
1979 may be used as a dependency of any other target,
1980 including another alias.
1982 can be called multiple times for the same
1983 alias to add additional targets to the alias.
1987 Alias('install', '/usr/bin')
1988 Alias(['install', 'install-lib'], '/usr/local/lib')
1990 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
1991 env.Alias('install', ['/usr/local/man'])
1994 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1996 .RI AlwaysBuild( target ", ...)"
1998 .RI env.AlwaysBuild( target ", ...)"
2001 so that it is always assumed to be out of date,
2002 and will always be rebuilt if needed.
2005 does not add its target(s) to the default target list,
2006 so the targets will only be built
2007 if they are specified on the command line,
2008 or are a dependent of a target specified on the command line--but
2011 be built if so specified.
2012 Multiple targets can be passed in to a single call to
2015 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2017 .RI env.Append( key = val ", [...])"
2018 Appends the specified keyword arguments
2019 to the end of construction variables in the environment.
2020 If the Environment does not have
2021 the specified construction variable,
2022 it is simply added to the environment.
2023 If the values of the construction variable
2024 and the keyword argument are the same type,
2025 then the two values will be simply added together.
2026 Otherwise, the construction variable
2027 and the value of the keyword argument
2028 are both coerced to lists,
2029 and the lists are added together.
2030 (See also the Prepend method, below.)
2033 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2036 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2038 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2039 This appends new path elements to the given path in the
2040 specified external environment
2044 any particular path once (leaving the last one it encounters and
2045 ignoring the rest, to preserve path order),
2046 and to help assure this,
2047 will normalize all paths (using
2050 .BR os.path.normcase ).
2051 This can also handle the
2052 case where the given old path variable is a list instead of a
2053 string, in which case a list will be returned instead of a string.
2057 print 'before:',env['ENV']['INCLUDE']
2058 include_path = '/foo/bar:/foo'
2059 env.PrependENVPath('INCLUDE', include_path)
2060 print 'after:',env['ENV']['INCLUDE']
2064 after: /biz:/foo/bar:/foo
2067 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2069 .RI env.AppendUnique( key = val ", [...])"
2070 Appends the specified keyword arguments
2071 to the end of construction variables in the environment.
2072 If the Environment does not have
2073 the specified construction variable,
2074 it is simply added to the environment.
2075 If the construction variable being appended to is a list,
2076 then any value(s) that already exist in the
2077 construction variable will
2079 be added again to the list.
2082 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2085 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2088 A factory function that
2089 returns a Builder object
2090 to be used to fetch source files
2092 The returned Builder
2093 is intended to be passed to the
2098 env.SourceCode('.', env.BitKeeper())
2101 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2103 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2105 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2106 This specifies a build directory
2108 in which to build all derived files
2109 that would normally be built under
2111 Multiple build directories can be set up for multiple build variants, for
2114 must be underneath the SConstruct file's directory,
2117 may not be underneath the
2120 The default behavior is for
2122 to duplicate all of the files in the tree underneath
2126 and then build the derived files within the copied tree.
2127 (The duplication is performed by
2129 depending on the platform; see also the
2132 This guarantees correct builds
2133 regardless of whether intermediate source files
2134 are generated during the build,
2135 where preprocessors or other scanners search
2137 or whether individual compilers or other invoked tools
2138 are hard-coded to put derived files in the same directory as source files.
2140 This behavior of making a complete copy of the source tree
2141 may be disabled by setting
2146 to invoke Builders using the
2147 path names of source files in
2149 and the path names of derived files within
2151 This is always more efficient than
2153 and is usually safe for most builds.
2157 may cause build problems
2158 if source files are generated during the build,
2159 if any invoked tools are hard-coded to
2160 put derived files in the same directory as the source files.
2162 Note that specifying a
2164 works most naturally
2165 with a subsidiary SConscript file
2166 in the source directory.
2168 you would then call the subsidiary SConscript file
2169 not in the source directory,
2174 had made a virtual copy of the source tree
2175 regardless of the value of
2177 This is how you tell
2179 which variant of a source tree to build.
2183 BuildDir('build-variant1', 'src')
2184 SConscript('build-variant1/SConscript')
2185 BuildDir('build-variant2', 'src')
2186 SConscript('build-variant2/SConscript')
2192 function, described below,
2194 specify a build directory
2195 in conjunction with calling a subsidiary
2198 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2200 .RI Builder( action ", [" multi ", " prefix ", " suffix ", " src_suffix ", " src_builder ", " emitter ])
2202 .RI env.Builder( action ", [" multi ", " prefix ", " suffix ", " src_suffix ", " src_builder ", " emitter ])
2203 Creates a Builder object for
2206 See the section "Builder Objects,"
2207 below, for a complete explanation of the arguments and behavior.
2209 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2211 .RI CacheDir( cache_dir )
2213 .RI env.CacheDir( cache_dir )
2216 will maintain a cache of derived files in
2218 The derived files in the cache will be shared
2219 among all the builds using the same
2227 finds a derived file that needs to be rebuilt,
2228 it will first look in the cache to see if a
2229 derived file has already been built
2230 from identical input files and an identical build action
2231 (as incorporated into the MD5 build signature).
2234 will retrieve the file from the cache.
2235 If the derived file is not present in the cache,
2238 then place a copy of the built file in the cache
2239 (identified by its MD5 build signature),
2240 so that it may be retrieved by other
2241 builds that need to build the same derived file
2242 from identical inputs.
2246 may be disabled for any invocation
2255 will place a copy of
2257 derived files in the cache,
2258 even if they already existed
2259 and were not built by this invocation.
2260 This is useful to populate a cache
2263 is added to a build,
2272 "Retrieved `file' from cache,"
2275 option is being used.
2280 will print the action that
2282 have been used to build the file,
2283 without any indication that
2284 the file was actually retrieved from the cache.
2285 This is useful to generate build logs
2286 that are equivalent regardless of whether
2287 a given derived file has been built in-place
2288 or retrieved from the cache.
2290 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2292 .RI Clean( target ", " files_or_dirs )
2294 .RI env.Clean( target ", " files_or_dirs )
2295 This specifies a list of files or directories which should be removed
2296 whenever the target is specified with the
2298 command line option.
2302 and create a new target or add files and directories to the
2303 clean list for the specified target.
2305 Multiple files or directories should be specified
2306 either as separate arguments to the
2308 method, or as a list.
2310 will also accept the return value of any of the construction environment
2315 Clean('foo', ['bar', 'baz'])
2316 Clean('dist', env.Program('hello', 'hello.c'))
2319 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2321 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2323 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2324 Executes a specific action
2325 (or list of actions)
2326 to build a target file or files.
2327 This is more convenient
2328 than defining a separate Builder object
2329 for a single special-case build.
2330 Any keyword arguments specified override any
2331 same-named existing construction variables.
2333 Note that an action can be an external command,
2334 specified as a string,
2335 or a callable Python object;
2336 see "Action Objects," below.
2340 env.Command('foo.out', 'foo.in',
2341 "$FOO_BUILD < $SOURCES > $TARGET")
2343 env.Command('bar.out', 'bar.in',
2345 "$BAR_BUILD < $SOURCES > $TARGET"],
2346 ENV = {'PATH' : '/usr/local/bin/'})
2348 def rename(env, target, source):
2350 os.rename('.tmp', str(target[0]))
2352 env.Command('baz.out', 'baz.in',
2353 ["$BAZ_BUILD < $SOURCES > .tmp",
2357 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2359 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
2361 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
2362 Creates a Configure object for integrated
2363 functionality similar to GNU autoconf.
2364 See the section "Configure Contexts,"
2365 below, for a complete explanation of the arguments and behavior.
2367 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2369 .RI env.Copy([ key = val ", ...])"
2370 Return a separate copy of a construction environment.
2371 If there are any keyword arguments specified,
2372 they are added to the returned copy,
2373 overwriting any existing values
2378 env3 = env.Copy(CCFLAGS = '-g')
2381 Additionally, a list of tools and a toolpath may be specified, as in
2382 the Environment constructor:
2385 def MyTool(env): env['FOO'] = 'bar'
2386 env4 = env.Copy(tools = ['msvc', MyTool])
2389 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2391 .RI env.CVS( repository ", " module )
2392 A factory function that
2393 returns a Builder object
2394 to be used to fetch source files
2398 The returned Builder
2399 is intended to be passed to the
2403 The optional specified
2405 will be added to the beginning
2406 of all repository path names;
2407 this can be used, in essence,
2408 to strip initial directory names
2409 from the repository path names,
2410 so that you only have to
2411 replicate part of the repository
2412 directory hierarchy in your
2413 local build directory:
2416 # Will fetch foo/bar/src.c
2417 # from /usr/local/CVSROOT/foo/bar/src.c.
2418 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2420 # Will fetch bar/src.c
2421 # from /usr/local/CVSROOT/foo/bar/src.c.
2422 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2425 # from /usr/local/CVSROOT/foo/bar/src.c.
2426 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2429 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2431 .RI Default( targets )
2433 .RI env.Default( targets )
2434 This specifies a list of default targets,
2435 which will be built by
2437 if no explicit targets are given on the command line.
2441 and add to the list of default targets.
2443 Multiple targets should be specified as
2444 separate arguments to the
2446 method, or as a list.
2448 will also accept the Node returned by any
2449 of a construction environment's
2454 Default('foo', 'bar', 'baz')
2455 env.Default(['a', 'b', 'c'])
2456 hello = env.Program('hello', 'hello.c')
2464 will clear all default targets.
2467 will add to the (now empty) default-target list
2470 The current list of targets added using the
2472 function or method is available in the
2477 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2479 .RI DefaultEnvironment([ args ])
2480 Creates and returns a default construction environment object.
2481 This construction environment is used internally by SCons
2482 in order to execute many of the global functions in this list,
2483 and to fetch source files transparently
2484 from source code management systems.
2486 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2488 .RI Depends( target ", " dependency )
2490 .RI env.Depends( target ", " dependency )
2491 Specifies an explicit dependency;
2492 the target file(s) will be rebuilt
2493 whenever the dependency file(s) has changed.
2494 This should only be necessary
2495 for cases where the dependency
2496 is not caught by a Scanner
2500 env.Depends('foo', 'other-input-file-for-foo')
2503 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2505 .RI env.Dictionary([ vars ])
2506 Returns a dictionary object
2507 containing copies of all of the
2508 construction variables in the environment.
2509 If there are any variable names specified,
2510 only the specified construction
2511 variables are returned in the dictionary.
2514 dict = env.Dictionary()
2515 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2518 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2520 .RI Dir( name ", [" directory ])
2522 .RI env.Dir( name ", [" directory ])
2523 This returns an object that represents a given directory
2526 can be a relative or absolute path.
2528 is an optional directory that will be used as the parent directory.
2530 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2532 .RI EnsurePythonVersion( major ", " minor )
2534 .RI env.EnsurePythonVersion( major ", " minor )
2535 Ensure that the Python version is at least
2538 print out an error message and exit SCons with a non-zero exit code if the
2539 actual Python version is not late enough.
2542 EnsurePythonVersion(2,2)
2545 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2547 .RI EnsureSConsVersion( major ", " minor )
2549 .RI env.EnsureSConsVersion( major ", " minor )
2550 Ensure that the SCons version is at least
2553 print out an error message and exit SCons with a non-zero exit code if the
2554 actual SCons version is not late enough.
2557 EnsureSConsVersion(0,9)
2560 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2562 .RI Environment([ key = value ", ...])"
2564 .RI env.Environment([ key = value ", ...])"
2565 Return a new construction environment
2566 initialized with the specified
2570 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2572 .RI Execute( action ", [" strfunction ", " varlist ])
2574 .RI env.Execute( action ", [" strfunction ", " varlist ])
2575 Executes an Action object.
2578 may be an Action object
2579 (see the section "Action Objects,"
2580 below, for a complete explanation of the arguments and behavior),
2581 or it may be a command-line string,
2583 or executable Python function,
2584 each of which will be converted
2585 into an Action object
2587 The exit value of the command
2588 or return value of the Python function
2591 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2595 .RI env.Exit([ value ])
2601 A default exit value of
2604 is used if no value is specified.
2606 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2610 .RI env.Export( vars )
2613 to export a list of variables from the current
2614 SConscript file to all other SConscript files.
2615 The exported variables are kept in a global collection,
2616 so subsequent calls to
2618 will over-write previous exports that have the same name.
2619 Multiple variable names can be passed to
2621 as separate arguments or as a list. A dictionary can be used to map
2622 variables to a different name when exported. Both local variables and
2623 global variables can be exported.
2628 # Make env available for all SConscript files to Import().
2632 # Make env and package available for all SConscript files:.
2633 Export("env", "package")
2635 # Make env and package available for all SConscript files:
2636 Export(["env", "package"])
2638 # Make env available using the name debug:.
2639 Export({"debug":env})
2645 function supports an
2647 argument that makes it easier to to export a variable or
2648 set of variables to a single SConscript file.
2649 See the description of the
2653 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2655 .RI File( name ", [" directory ])
2657 .RI env.File( name ", [" directory ])
2658 This returns an object that represents a given file
2661 can be a relative or absolute path.
2663 is an optional directory that will be used as the parent directory.
2665 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2667 .RI FindFile( file ", " dirs )
2669 .RI env.FindFile( file ", " dirs )
2672 in the path specified by
2675 may be a list of file names or a single file name. In addition to searching
2676 for files that exist in the filesytem, this function also searches for
2677 derived files that have not yet been built.
2680 foo = env.FindFile('foo', ['dir1', 'dir2'])
2683 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2685 .RI GetBuildPath( file ", [" ... ])
2687 .RI env.GetBuildPath( file ", [" ... ])
2690 path name (or names) for the specified
2698 Nodes or strings representing path names.
2700 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2704 .RI env.GetLaunchDir()
2705 Returns the absolute path name of the directory from which
2708 was initially invoked.
2709 This can be useful when using the
2714 options, which internally
2715 change to the directory in which the
2719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2721 .RI GetOption( name )
2723 .RI env.GetOption( name )
2724 This function provides a way to query a select subset of the scons command line
2725 options from a SConscript file. See
2727 for a description of the options available.
2729 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2731 '\".RI GlobalBuilders( flag )
2735 '\"adds the names of the default builders
2736 '\"(Program, Library, etc.)
2737 '\"to the global name space
2738 '\"so they can be called without an explicit construction environment.
2739 '\"(This is the default.)
2743 '\"the names of the default builders are removed
2744 '\"from the global name space
2745 '\"so that an explicit construction environment is required
2746 '\"to call all builders.
2748 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2752 .RI env.Help( text )
2753 This specifies help text to be printed if the
2755 argument is given to
2758 will exit after printing out the help text.
2760 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2762 .RI Ignore( target ", " dependency )
2764 .RI env.Ignore( target ", " dependency )
2765 The specified dependency file(s)
2766 will be ignored when deciding if
2767 the target file(s) need to be rebuilt.
2770 env.Ignore('foo', 'foo.c')
2771 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2774 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2778 .RI env.Import( vars )
2781 to import a list of variables into the current SConscript file. This
2782 will import variables that were exported with
2788 Variables exported by
2791 Multiple variable names can be passed to
2793 as separate arguments or as a list. The variable "*" can be used
2794 to import all variables.
2799 Import("env", "variable")
2800 Import(["env", "variable"])
2804 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2806 .RI Install( dir ", " source )
2808 .RI env.Install( dir ", " source )
2809 Installs one or more files in a destination directory.
2810 The file names remain the same.
2813 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2816 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2818 .RI InstallAs( target ", " source )
2820 .RI env.InstallAs( target ", " source )
2821 Installs one or more files as specific file names,
2822 allowing changing a file name as part of the
2824 It is an error if the target and source
2825 list different numbers of files.
2828 env.InstallAs(target = '/usr/local/bin/foo',
2829 source = 'foo_debug')
2830 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2831 source = ['libFOO.a', 'libBAR.a'])
2834 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2836 .RI Literal( string )
2838 .RI env.Literal( string )
2841 will be preserved as-is
2842 and not have construction variables expanded.
2844 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2846 .RI Local( targets )
2848 .RI env.Local( targets )
2851 will have copies made in the local tree,
2852 even if an already up-to-date copy
2853 exists in a repository.
2854 Returns a list of the target Node or Nodes.
2856 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2858 .RI env.ParseConfig( command ", [" function ])
2861 to modify the environment as specified by the output of
2865 expects the output of a typical
2869 and parses the returned
2883 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2886 A factory function that
2887 returns a Builder object
2888 to be used to fetch source files
2889 from the Perforce source code management system.
2890 The returned Builder
2891 is intended to be passed to the
2896 env.SourceCode('.', env.Perforce())
2899 Perforce uses a number of external
2900 environment variables for its operation.
2901 Consequently, this function adds the
2902 following variables from the user's external environment
2903 to the construction environment's
2916 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2918 .RI Platform( string )
2919 Returns a callable object
2920 that can be used to initialize
2921 a construction environment using the
2922 platform keyword of the Environment() method:
2925 env = Environment(platform = Platform('win32'))
2928 .RI env.Platform( string )
2929 Applies the callable object for the specified platform
2931 to the environment through which the method was called.
2934 env.Platform('posix')
2941 variable from the user's external environment
2942 to the construction environment's
2945 This is so that any executed commands
2946 that use sockets to connect with other systems
2947 (such as fetching source files from
2948 external CVS repository specifications like
2949 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
2950 will work on Win32 systems.
2952 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2954 .RI Precious( target ", ...)"
2956 .RI env.Precious( target ", ...)"
2959 as precious so it is not deleted before it is rebuilt. Normally
2961 deletes a target before building it.
2962 Multiple targets can be passed in to a single call to
2965 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2967 .RI env.Prepend( key = val ", [...])"
2968 Appends the specified keyword arguments
2969 to the beginning of construction variables in the environment.
2970 If the Environment does not have
2971 the specified construction variable,
2972 it is simply added to the environment.
2973 If the values of the construction variable
2974 and the keyword argument are the same type,
2975 then the two values will be simply added together.
2976 Otherwise, the construction variable
2977 and the value of the keyword argument
2978 are both coerced to lists,
2979 and the lists are added together.
2980 (See also the Append method, above.)
2983 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
2986 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2988 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
2989 This appends new path elements to the given path in the
2990 specified external environment
2994 any particular path once (leaving the first one it encounters and
2995 ignoring the rest, to preserve path order),
2996 and to help assure this,
2997 will normalize all paths (using
3000 .BR os.path.normcase ).
3001 This can also handle the
3002 case where the given old path variable is a list instead of a
3003 string, in which case a list will be returned instead of a string.
3007 print 'before:',env['ENV']['INCLUDE']
3008 include_path = '/foo/bar:/foo'
3009 env.PrependENVPath('INCLUDE', include_path)
3010 print 'after:',env['ENV']['INCLUDE']
3014 after: /foo/bar:/foo:/biz
3017 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3019 .RI env.AppendUnique( key = val ", [...])"
3020 Appends the specified keyword arguments
3021 to the beginning of construction variables in the environment.
3022 If the Environment does not have
3023 the specified construction variable,
3024 it is simply added to the environment.
3025 If the construction variable being appended to is a list,
3026 then any value(s) that already exist in the
3027 construction variable will
3029 be added again to the list.
3032 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3035 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3038 A factory function that
3039 returns a Builder object
3040 to be used to fetch source files
3042 The returned Builder
3043 is intended to be passed to the
3048 env.SourceCode('.', env.RCS())
3053 will fetch source files
3054 from RCS subdirectories automatically,
3056 as demonstrated in the above example
3057 should only be necessary if
3058 you are fetching from
3061 directory as the source files,
3062 or if you need to explicitly specify RCS
3063 for a specific subdirectory.
3065 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3067 .RI env.Replace( key = val ", [...])"
3068 Replaces construction variables in the Environment
3069 with the specified keyword arguments.
3072 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3075 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3077 .RI Repository( directory )
3079 .RI env.Repository( directory )
3082 is a repository to be searched for files.
3086 and each one adds to the list of
3087 repositories that will be searched.
3091 a repository is a copy of the source tree,
3092 from the top-level directory on down,
3094 both source files and derived files
3095 that can be used to build targets in
3096 the local source tree.
3097 The canonical example would be an
3098 official source tree maintained by an integrator.
3099 If the repository contains derived files,
3100 then the derived files should have been built using
3102 so that the repository contains the necessary
3103 signature information to allow
3105 to figure out when it is appropriate to
3106 use the repository copy of a derived file,
3107 instead of building one locally.
3109 Note that if an up-to-date derived file
3110 already exists in a repository,
3114 make a copy in the local directory tree.
3115 In order to guarantee that a local copy
3121 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3126 what variable(s) to use as the return value(s) of the current SConscript
3127 file. These variables will be returned to the "calling" SConscript file
3128 as the return value(s) of
3130 Multiple variable names should be passed to
3136 Return(["foo", "bar"])
3139 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3141 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3143 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3144 Creates a Scanner object for
3147 See the section "Scanner Objects,"
3148 below, for a complete explanation of the arguments and behavior.
3150 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3153 A factory function that
3154 returns a Builder object
3155 to be used to fetch source files
3157 The returned Builder
3158 is intended to be passed to the
3163 env.SourceCode('.', env.SCCS())
3168 will fetch source files
3169 from SCCS subdirectories automatically,
3171 as demonstrated in the above example
3172 should only be necessary if
3173 you are fetching from
3176 directory as the source files,
3177 or if you need to explicitly specify SCCS
3178 for a specific subdirectory.
3180 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3182 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3184 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3186 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3188 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3192 one or more subsidiary SConscript (configuration) files.
3193 There are two ways to call the
3197 The first way you can call
3199 is to explicitly specify one or more
3201 as the first argument.
3202 A single script may be specified as a string;
3203 multiple scripts must be specified as a list
3204 (either explicitly or as created by
3208 The second way you can call
3210 is to specify a list of (sub)directory names
3217 execute a subsidiary configuration file named
3219 in each of the specified directories.
3220 You may specify a name other than
3222 by supplying an optional
3228 argument provides a list of variable names or a dictionary of
3229 named values to export to the
3231 These variables are locally exported only to the specified
3233 and do not affect the
3234 global pool of variables used by
3238 '\"If multiple dirs are provided,
3239 '\"each script gets a fresh export.
3244 function to import the variables.
3248 argument specifies that all of the target files
3249 (for example, object files and executables)
3250 that would normally be built in the subdirectory in which
3252 resides should actually
3258 argument specifies that the
3259 source files from which
3260 the target files should be built
3266 will link or copy (depending on the platform)
3267 all the source files into the build directory.
3268 This behavior may be disabled by
3269 setting the optional
3272 (it is set to 1 by default),
3275 will refer directly to
3276 the source files in their source directory
3277 when building target files.
3280 is usually safe, and always more efficient
3283 but it may cause build problems in certain end-cases,
3284 such as compiling from source files that
3285 are generated by the build.)
3287 Any variables returned by
3291 will be returned by the call to
3297 SConscript('subdir/SConscript')
3298 foo = SConscript('sub/SConscript', exports='env')
3299 SConscript('dir/SConscript', exports=['env', 'variable'])
3300 SConscript('src/SConscript', build_dir='build', duplicate=0)
3301 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3302 SConscript(dirs=['sub1', 'sub2'])
3303 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3306 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3308 .RI SConscriptChdir( value )
3310 .RI env.SConscriptChdir( value )
3313 changes its working directory
3314 to the directory in which each
3315 subsidiary SConscript file lives.
3316 This behavior may be disabled
3317 by specifying either:
3321 env.SConscriptChdir(0)
3326 will stay in the top-level directory
3327 while reading all SConscript files.
3328 (This may be necessary when building from repositories,
3329 when all the directories in which SConscript files may be found
3330 don't necessarily exist locally.)
3332 You may enable and disable
3333 this ability by calling
3340 SConscript('foo/SConscript') # will not chdir to foo
3341 env.SConscriptChdir(1)
3342 SConscript('bar/SConscript') # will chdir to bar
3345 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3347 .RI SConsignFile([ file , dbm_module ])
3349 .RI env.SConsignFile([ file , dbm_module ])
3352 to store all file signatures
3362 is not an absolute path name,
3363 the file is placed in the same directory as the top-level
3369 argument can be used to specify
3370 which Python database module
3371 The default is to use a custom
3373 module that uses pickled
3374 Python data structures,
3375 and which works on all Python versions from 1.5.2 on.
3380 # Stores signatures in ".sconsign.dbm"
3381 # in the top-level SConstruct directory.
3384 # Stores signatures in the file "etc/scons-signatures"
3385 # relative to the top-level SConstruct directory.
3386 SConsignFile("etc/scons-signatures")
3388 # Stores signatures in the specified absolute file name.
3389 SConsignFile("/home/me/SCons/signatures")
3392 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3394 .RI SetOption( name ", " value )
3396 .RI env.SetOption( name ", " value )
3397 This function provides a way to set a select subset of the scons command
3398 line options from a SConscript file. The options supported are:
3400 which corresponds to -c, --clean, and --remove;
3403 corresponds to --duplicate;
3405 which corresponds to --implicit-cache;
3407 which corresponds to --max-drift;
3409 which corresponds to -j and --jobs.
3410 See the documentation for the
3411 corresponding command line object for information about each specific
3415 SetOption('max_drift', 1)
3418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3420 .RI SideEffect( side_effect ", " target )
3422 .RI env.SideEffect( side_effect ", " target )
3425 as a side effect of building
3431 can be a list, a file name, or a node.
3432 A side effect is a target that is created
3433 as a side effect of building other targets.
3434 For example, a Windows PDB
3435 file is created as a side effect of building the .obj
3436 files for a static library.
3437 If a target is a side effect of multiple build commands,
3439 will ensure that only one set of commands
3440 is executed at a time.
3441 Consequently, you only need to use this method
3442 for side-effect targets that are built as a result of
3443 multiple build commands.
3445 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3447 .RI SourceCode( entries ", " builder )
3449 .RI env.SourceCode( entries ", " builder )
3450 Arrange for non-existent source files to
3451 be fetched from a source code management system
3456 may be a Node, string or list of both,
3457 and may represent either individual
3458 source files or directories in which
3459 source files can be found.
3461 For any non-existent source files,
3463 will search up the directory tree
3473 will not use a builder to fetch
3474 source files for the specified
3478 builder has been specified
3479 for a directory higher up the tree.
3483 fetch files from SCCS or RCS subdirectories
3484 without explicit configuration.
3485 This takes some extra processing time
3486 to search for the necessary
3487 source code management files on disk.
3488 You can avoid these extra searches
3489 and speed up your build a little
3490 by disabling these searches as follows:
3493 env.SourceCode('.', None)
3497 Note that if the specified
3499 is one you create by hand,
3500 it must have an associated
3501 construction environment to use
3502 when fetching a source file.
3505 provides a set of canned factory
3506 functions that return appropriate
3507 Builders for various popular
3508 source code management systems.
3509 Canonical examples of invocation include:
3512 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3513 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3514 env.SourceCode('/', env.RCS())
3515 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3516 env.SourceCode('no_source.c', None)
3518 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3520 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3522 '\".RI Subversion( repository ", " module )
3523 '\"A factory function that
3524 '\"returns a Builder object
3525 '\"to be used to fetch source files
3526 '\"from the specified Subversion
3528 '\"The returned Builder
3529 '\"is intended to be passed to the
3533 '\"The optional specified
3535 '\"will be added to the beginning
3536 '\"of all repository path names;
3537 '\"this can be used, in essence,
3538 '\"to strip initial directory names
3539 '\"from the repository path names,
3540 '\"so that you only have to
3541 '\"replicate part of the repository
3542 '\"directory hierarchy in your
3543 '\"local build directory:
3546 '\"# Will fetch foo/bar/src.c
3547 '\"# from /usr/local/Subversion/foo/bar/src.c.
3548 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3550 '\"# Will fetch bar/src.c
3551 '\"# from /usr/local/Subversion/foo/bar/src.c.
3552 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3554 '\"# Will fetch src.c
3555 '\"# from /usr/local/Subversion/foo/bar/src.c.
3556 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3561 .RI SourceSignatures( type )
3563 .RI env.SourceSignatures( type )
3564 This function tells SCons what type of signature to use for source files:
3568 If the environment method is used,
3569 the specified type of source signature
3570 is only used when deciding whether targets
3571 built with that environment are up-to-date or must be rebuilt.
3572 If the global function is used,
3573 the specified type of source signature becomes the default
3574 used for all decisions
3575 about whether targets are up-to-date.
3577 "MD5" means the signature of a source file
3578 is the MD5 checksum of its contents.
3579 "timestamp" means the signature of a source file
3580 is its timestamp (modification time).
3581 When using "timestamp" signatures,
3582 changes in the command line will not cause files to be rebuilt.
3583 "MD5" signatures take longer to compute,
3584 but are more accurate than "timestamp" signatures.
3585 The default is "MD5".
3587 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3591 .RI env.Split( arg )
3592 Returns a list of file names or other objects.
3594 it will be split on strings of white-space characters
3596 making it easier to write long lists of file names.
3597 If arg is already a list,
3598 the list will be returned untouched.
3599 If arg is any other type of object,
3600 it will be returned as a list
3601 containing just the object.
3604 files = Split("f1.c f2.c f3.c")
3605 files = env.Split("f4.c f5.c f6.c")
3613 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3615 .RI TargetSignatures( type )
3617 .RI env.TargetSignatures( type )
3618 This function tells SCons what type of signatures to use
3623 If the environment method is used,
3624 the specified type of signature is only used
3625 for targets built with that environment.
3626 If the global function is used,
3627 the specified type of signature becomes the default
3628 used for all target files that
3629 don't have an explicit target signature type
3630 specified for their environments.
3632 "build" means the signature of a target file
3633 is made by concatenating all of the
3634 signatures of all its source files.
3635 "content" means the signature of a target
3636 file is an MD5 checksum of its contents.
3637 "build" signatures are usually faster to compute,
3638 but "content" signatures can prevent unnecessary rebuilds
3639 when a target file is rebuilt to the exact same contents
3640 as the previous build.
3641 The default is "build".
3643 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3645 .RI Tool( string, toolpath=[] )
3646 Returns a callable object
3647 that can be used to initialize
3648 a construction environment using the
3649 tools keyword of the Environment() method.
3650 The object may be called with a construction
3651 environment as an argument,
3652 in which case the object will be
3653 add the necessary variables
3654 to the construction environment
3655 and the name of the tool will be added to the
3657 construction variable.
3660 env = Environment(tools = [ Tool('msvc') ])
3664 t(env) # adds 'msvc' to the TOOLS variable
3665 u = Tool('opengl', toolpath = ['tools'])
3666 u(env) # adds 'opengl' to the TOOLS variable
3669 .RI env.Tool( string [, toolpath] )
3670 Applies the callable object for the specified tool
3672 to the environment through which the method was called.
3676 env.Tool('opengl', toolpath = ['build/tools'])
3679 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3683 .RI env.Value( value )
3684 Returns a Node object representing the specified Python value. Value
3685 nodes can be used as dependencies of targets. If the result of
3688 changes between SCons runs, any targets depending on
3690 will be rebuilt. When using timestamp source signatures, Value nodes'
3691 timestamps are equal to the system time when the node is created.
3694 def create(target, source, env):
3695 f = open(str(target[0]), 'wb')
3696 f.write('prefix=' + source[0].get_contents())
3698 prefix = ARGUMENTS.get('prefix', '/usr/local')
3700 env['BUILDERS']['Config'] = Builder(action = create)
3701 env.Config(target = 'package-config', source = Value(prefix))
3704 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3706 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
3708 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
3710 Searches for the specified executable
3712 returning the full path name to the program
3714 and returning None if not.
3715 Searches the specified
3717 the value of the calling environment's PATH
3718 (env['ENV']['PATH']),
3719 or the user's current external PATH
3720 (os.environ['PATH'])
3722 On Win32 systems, searches for executable
3723 programs with any of the file extensions
3724 listed in the specified
3726 the calling environment's PATHEXT
3727 (env['ENV']['PATHEXT'])
3728 or the user's current PATHEXT
3729 (os.environ['PATHEXT'])
3737 .SS SConscript Variables
3738 In addition to the global functions and methods,
3740 supports a number of Python variables
3741 that can be used in SConscript files
3742 to affect how you want the build to be performed.
3744 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3747 A dictionary of all the
3749 arguments specified on the command line.
3750 The dictionary is not in order,
3751 and if a given keyword has
3752 more than one value assigned to it
3753 on the command line,
3754 the last (right-most) value is
3760 if ARGUMENTS.get('debug', 0):
3761 env = Environment(CCFLAGS = '-g')
3766 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3769 A list of the targets which
3771 will actually try to build,
3772 regardless of whether they were specified on
3773 the command line or via the
3776 The elements of this list may be strings
3778 nodes, so you should run the list through the Python
3780 function to make sure any Node path names
3781 are converted to strings.
3783 Because this list may be taken from the
3784 list of targets specified using the
3787 the contents of the list may change
3788 on each successive call to
3793 for additional information.
3796 if 'foo' in BUILD_TARGETS:
3797 print "Don't forget to test the `foo' program!"
3798 if 'special/program' in BUILD_TARGETS:
3799 SConscript('special')
3804 list only contains targets expected listed
3805 on the command line or via calls to the
3810 contain all dependent targets that will be built as
3811 a result of making the sure the explicitly-specified
3812 targets are up to date.
3814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3816 COMMAND_LINE_TARGETS
3817 A list of the targets explicitly specified on
3819 If there are no targets specified on the command line,
3821 This can be used, for example,
3822 to take specific actions only
3823 when a certain target or targets
3824 is explicitly being built:
3827 if 'foo' in COMMAND_LINE_TARGETS:
3828 print "Don't forget to test the `foo' program!"
3829 if 'special/program' in COMMAND_LINE_TARGETS:
3830 SConscript('special')
3833 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3836 A list of the target
3838 that have been specified using the
3841 The elements of the list are nodes,
3842 so you need to run them through the Python
3844 function to get at the path name for each Node.
3847 print str(DEFAULT_TARGETS[0])
3848 if 'foo' in map(str, DEFAULT_TARGETS):
3849 print "Don't forget to test the `foo' program!"
3854 list change on on each successive call to the
3859 print map(str, DEFAULT_TARGETS) # originally []
3861 print map(str, DEFAULT_TARGETS) # now a node ['foo']
3863 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
3865 print map(str, DEFAULT_TARGETS) # back to []
3868 Consequently, be sure to use
3870 only after you've made all of your
3873 or else simply be careful of the order
3874 of these statements in your SConscript files
3875 so that you don't look for a specific
3876 default target before it's actually been added to the list.
3878 .SS Construction Variables
3879 .\" XXX From Gary Ruben, 23 April 2002:
3880 .\" I think it would be good to have an example with each construction
3881 .\" variable description in the documentation.
3883 .\" CC The C compiler
3884 .\" Example: env["CC"] = "c68x"
3885 .\" Default: env["CC"] = "cc"
3887 .\" CCCOM The command line ...
3889 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
3890 .\" env["CC"] = "c68x"
3891 .\" env["CFLAGS"] = "-ps -qq -mr"
3892 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
3894 .\" (I dunno what this is ;-)
3895 A construction environment has an associated dictionary of
3896 .I construction variables
3897 that are used by built-in or user-supplied build rules.
3898 Construction variables must follow the same rules for
3900 the initial character must be an underscore or letter,
3901 followed by any number of underscores, letters, or digits.
3903 A number of useful construction variables are automatically defined by
3904 scons for each supported platform, and additional construction variables
3905 can be defined by the user. The following is a list of the automatically
3906 defined construction variables:
3909 The static library archiver.
3912 The command line used to generate a static library from object files.
3915 General options passed to the static library archiver.
3921 The command line used to generate an object file
3922 from an assembly-language source file.
3925 General options passed to the assembler.
3928 The command line used to assemble an assembly-language
3929 source file into an object file
3930 after first running the file through the C preprocessor.
3931 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
3932 are included on this command line.
3935 The bibliography generator for the TeX formatter and typesetter and the
3936 LaTeX structured formatter and typesetter.
3939 The command line used to call the bibliography generator for the
3940 TeX formatter and typesetter and the LaTeX structured formatter and
3944 General options passed to the bibliography generator for the TeX formatter
3945 and typesetter and the LaTeX structured formatter and typesetter.
3948 The BitKeeper executable.
3951 The command line for
3952 fetching source files using BitKEeper.
3955 The command ($BITKEEPER) and subcommand
3956 for fetching source files using BitKeeper.
3958 .IP BITKEEPERGETFLAGS
3959 Options that are passed to the BitKeeper
3964 A dictionary mapping the names of the builders
3965 available through this environment
3966 to underlying Builder objects.
3968 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
3969 are available by default.
3970 If you initialize this variable when an
3971 Environment is created:
3974 env = Environment(BUILDERS = {'NewBuilder' : foo})
3977 the default Builders will no longer be available.
3978 To use a new Builder object in addition to the default Builders,
3979 add your new Builder object like this:
3983 env.Append(BUILDERS = {'NewBuilder' : foo})
3990 env['BUILDERS]['NewBuilder'] = foo
3997 The command line used to compile a C source file to a (static) object file.
3998 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
3999 are included on this command line.
4002 General options that are passed to the C compiler.
4005 The suffix for C source files.
4006 This is used by the internal CFile builder
4007 when generating C files from Lex (.l) or YACC (.y) input files.
4008 The default suffix, of course, is
4011 On case-insensitive systems (like Win32),
4018 The version number of the C compiler.
4019 This may or may not be set,
4020 depending on the specific C compiler being used.
4023 A function used to produce variables like $_CPPINCFLAGS. It takes
4025 arguments: a prefix to concatenate onto each element, a list of
4026 elements, a suffix to concatenate onto each element, an environment
4027 for variable interpolation, and an optional function that will be
4028 called to transform the list before concatenation.
4031 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4035 A platform independent specification of C preprocessor definitions.
4036 The definitions will be added to command lines
4037 through the automatically-generated
4038 $_CPPDEFFLAGS construction variable (see below),
4039 which is constructed according to
4040 the type of value of $CPPDEFINES:
4043 If $CPPDEFINES is a string,
4045 $CPPDEFPREFIX and $CPPDEFSUFFIX
4046 construction variables
4047 will be added to the beginning and end.
4050 # Will add -Dxyz to POSIX compiler command lines,
4051 # and /Dxyz to Microsoft Visual C++ command lines.
4052 env = Environment(CPPDEFINES='xyz')
4056 If $CPPDEFINES is a list,
4058 $CPPDEFPREFIX and $CPPDEFSUFFIX
4059 construction variables
4060 will be appended to the beginning and end
4061 of each element in the list.
4062 If any element is a list or tuple,
4063 then the first item is the name being
4064 defined and the second item is its value:
4067 # Will add -DB=2 -DA to POSIX compiler command lines,
4068 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4069 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4073 If $CPPDEFINES is a dictionary,
4075 $CPPDEFPREFIX and $CPPDEFSUFFIX
4076 construction variables
4077 will be appended to the beginning and end
4078 of each item from the dictionary.
4079 The key of each dictionary item
4080 is a name being defined
4081 to the dictionary item's corresponding value;
4084 then the name is defined without an explicit value.
4085 Note that the resulting flags are sorted by keyword
4086 to ensure that the order of the options on the
4087 command line is consistent each time
4092 # Will add -DA -DB=2 to POSIX compiler command lines,
4093 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4094 env = Environment(CPPDEFINES={'B':2, 'A':None})
4098 An automatically-generated construction variable
4099 containing the C preprocessor command-line options
4101 The value of $_CPPDEFFLAGS is created
4102 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4103 to the beginning and end
4104 of each directory in $CPPDEFINES.
4107 The prefix used to specify preprocessor definitions
4108 on the C compiler command line.
4109 This will be appended to the beginning of each definition
4110 in the $CPPDEFINES construction variable
4111 when the $_CPPDEFFLAGS variable is automatically generated.
4114 The suffix used to specify preprocessor definitions
4115 on the C compiler command line.
4116 This will be appended to the end of each definition
4117 in the $CPPDEFINES construction variable
4118 when the $_CPPDEFFLAGS variable is automatically generated.
4121 User-specified C preprocessor options.
4122 These will be included in any command that uses the C preprocessor,
4123 including not just compilation of C and C++ source files
4124 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4125 but also the $F77PPCOM and $SHF77PPCOM command lines
4126 used to compile a Fortran source file,
4127 and the $ASPPCOM command line
4128 used to assemble an assembly language source file,
4129 after first running each file through the C preprocessor.
4130 Note that this variable does
4134 (or similar) include search path options
4135 that scons generates automatically from $CPPPATH.
4139 for the variable that expands to those options.
4142 An automatically-generated construction variable
4143 containing the C preprocessor command-line options
4144 for specifying directories to be searched for include files.
4145 The value of $_CPPINCFLAGS is created
4146 by appending $INCPREFIX and $INCSUFFIX
4147 to the beginning and end
4148 of each directory in $CPPPATH.
4151 The list of directories that the C preprocessor will search for include
4152 directories. The C/C++ implicit dependency scanner will search these
4153 directories for include files. Don't explicitly put include directory
4154 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4155 and the directories will not be searched by the dependency scanner. Note:
4156 directory names in CPPPATH will be looked-up relative to the SConscript
4157 directory when they are used in a command. To force
4159 to look-up a directory relative to the root of the source tree use #:
4162 env = Environment(CPPPATH='#/include')
4166 The directory look-up can also be forced using the
4171 include = Dir('include')
4172 env = Environment(CPPPATH=include)
4176 The directory list will be added to command lines
4177 through the automatically-generated
4179 construction variable,
4180 which is constructed by
4181 appending the values of the
4182 $INCPREFIX and $INCSUFFIX
4183 construction variables
4184 to the beginning and end
4185 of each directory in $CPPPATH.
4186 Any command lines you define that need
4187 the CPPPATH directory list should
4188 include $_CPPINCFLAGS:
4191 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4195 The list of suffixes of files that will be scanned
4196 for C preprocessor implicit dependencies
4198 The default list is:
4201 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4202 ".h", ".H", ".hxx", ".hpp", ".hh",
4203 ".F", ".fpp", ".FPP",
4204 ".S", ".spp", ".SPP"]
4211 Options that are passed to the CVS checkout subcommand.
4214 The command line used to
4215 fetch source files from a CVS repository.
4218 General options that are passed to CVS.
4219 By default, this is set to
4221 to specify from where the files must be fetched.
4224 The path to the CVS repository.
4225 This is referenced in the default
4232 The suffix for C++ source files.
4233 This is used by the internal CXXFile builder
4234 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4235 The default suffix is
4237 SCons also treats files with the suffixes
4244 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4251 The command line used to compile a C++ source file to an object file.
4252 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4253 are included on this command line.
4256 General options that are passed to the C++ compiler.
4259 The version number of the C++ compiler.
4260 This may or may not be set,
4261 depending on the specific C++ compiler being used.
4264 A function that converts a file name into a Dir instance relative to the
4268 The list of suffixes of files that will be scanned
4269 for imported D package files.
4270 The default list is:
4277 The TeX DVI file to PDF file converter.
4280 General options passed to the TeX DVI file to PDF file converter.
4283 The command line used to convert TeX DVI files into a PDF file.
4286 The TeX DVI file to PostScript converter.
4289 General options passed to the TeX DVI file to PostScript converter.
4292 A dictionary of environment variables
4293 to use when invoking commands. When ENV is used in a command all list
4294 values will be joined using the path separator and any other non-string
4295 values will simply be coerced to a string.
4296 Note that, by default,
4300 propagate the environment in force when you
4303 to the commands used to build target files.
4304 This is so that builds will be guaranteed
4305 repeatable regardless of the environment
4306 variables set at the time
4310 If you want to propagate your
4311 environment variables
4312 to the commands executed
4313 to build target files,
4314 you must do so explicitly:
4318 env = Environment(ENV = os.environ)
4322 Note that you can choose only to propagate
4323 certain environment variables.
4327 environment variable,
4330 uses the same utilities
4331 as the invoking shell (or other process):
4336 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4340 A function that will be called to escape shell special characters in
4341 command lines. The function should take one argument: the command line
4342 string to escape; and should return the escaped command line.
4345 The Fortran compiler.
4348 The command line used to compile a Fortran source file to an object file.
4351 General user-specified options that are passed to the Fortran compiler.
4352 Note that this variable does
4356 (or similar) include search path options
4357 that scons generates automatically from $F77PATH.
4361 for the variable that expands to those options.
4364 An automatically-generated construction variable
4365 containing the Fortran compiler command-line options
4366 for specifying directories to be searched for include files.
4367 The value of $_F77INCFLAGS is created
4368 by appending $INCPREFIX and $INCSUFFIX
4369 to the beginning and end
4370 of each directory in $F77PATH.
4373 The list of directories that the Fortran compiler will search for include
4374 directories. The Fortran implicit dependency scanner will search these
4375 directories for include files. Don't explicitly put include directory
4376 arguments in F77FLAGS because the result will be non-portable
4377 and the directories will not be searched by the dependency scanner. Note:
4378 directory names in F77PATH will be looked-up relative to the SConscript
4379 directory when they are used in a command. To force
4381 to look-up a directory relative to the root of the source tree use #:
4384 env = Environment(F77PATH='#/include')
4388 The directory look-up can also be forced using the
4393 include = Dir('include')
4394 env = Environment(F77PATH=include)
4398 The directory list will be added to command lines
4399 through the automatically-generated
4401 construction variable,
4402 which is constructed by
4403 appending the values of the
4404 $INCPREFIX and $INCSUFFIX
4405 construction variables
4406 to the beginning and end
4407 of each directory in $F77PATH.
4408 Any command lines you define that need
4409 the F77PATH directory list should
4410 include $_F77INCFLAGS:
4413 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4417 The command line used to compile a Fortran source file to an object file
4418 after first running the file through the C preprocessor.
4419 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4420 are included on this command line.
4423 The list of suffixes of files that will be scanned
4424 for Fortran implicit dependencies
4426 The default list is:
4429 [".f", ".F", ".for", ".FOR"]
4433 A function that converts a file name into a File instance relative to the
4437 The Ghostscript program used to convert PostScript to PDF files.
4440 General options passed to the Ghostscript program
4441 when converting PostScript to PDF files.
4444 The Ghostscript command line used to convert PostScript to PDF files.
4447 The list of suffixes of files that will be scanned
4448 for IDL implicit dependencies
4449 (#include or import lines).
4450 The default list is:
4457 The prefix used to specify an include directory on the C compiler command
4459 This will be appended to the beginning of each directory
4460 in the $CPPPATH and $F77PATH construction variables
4461 when the $_CPPINCFLAGS and $_F77INCFLAGS
4462 variables are automatically generated.
4465 The suffix used to specify an include directory on the C compiler command
4467 This will be appended to the end of each directory
4468 in the $CPPPATH and $F77PATH construction variables
4469 when the $_CPPINCFLAGS and $_F77INCFLAGS
4470 variables are automatically generated.
4473 A function to be called to install a file into a
4474 destination file name.
4475 The default function copies the file into the destination
4476 (and sets the destination file's mode and permission bits
4477 to match the source file's).
4478 The function takes the following arguments:
4481 def install(dest, source, env):
4485 is the path name of the destination file.
4487 is the path name of the source file.
4489 is the construction environment
4490 (a dictionary of construction values)
4491 in force for this file installation.
4494 The Java archive tool.
4497 The directory to which the Java archive tool should change
4503 The command line used to call the Java archive tool.
4506 General options passed to the Java archive tool.
4507 By default this is set to
4509 to create the necessary
4514 The suffix for Java archives:
4522 The command line used to compile a directory tree containing
4523 Java source files to
4524 corresponding Java class files.
4525 Any options specified in the $JAVACFLAGS construction variable
4526 are included on this command line.
4529 General options that are passed to the Java compiler.
4532 The directory in which Java class files may be found.
4533 This is stripped from the beginning of any Java .class
4534 file names supplied to the
4539 The suffix for Java class files;
4544 The Java generator for C header and stub files.
4547 The command line used to generate C header and stub files
4549 Any options specified in the $JAVAHFLAGS construction variable
4550 are included on this command line.
4553 General options passed to the C header and stub file generator
4557 The suffix for Java files;
4562 The LaTeX structured formatter and typesetter.
4565 The command line used to call the LaTeX structured formatter and typesetter.
4568 General options passed to the LaTeX structured formatter and typesetter.
4571 The lexical analyzer generator.
4574 General options passed to the lexical analyzer generator.
4577 The command line used to call the lexical analyzer generator
4578 to generate a source file.
4581 An automatically-generated construction variable
4582 containing the linker command-line options
4583 for specifying directories to be searched for library.
4584 The value of $_LIBDIRFLAGS is created
4585 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
4586 to the beginning and end
4587 of each directory in $LIBPATH.
4590 The prefix used to specify a library directory on the linker command line.
4591 This will be appended to the beginning of each directory
4592 in the $LIBPATH construction variable
4593 when the $_LIBDIRFLAGS variable is automatically generated.
4596 The suffix used to specify a library directory on the linker command line.
4597 This will be appended to the end of each directory
4598 in the $LIBPATH construction variable
4599 when the $_LIBDIRFLAGS variable is automatically generated.
4602 An automatically-generated construction variable
4603 containing the linker command-line options
4604 for specifying libraries to be linked with the resulting target.
4605 The value of $_LIBFLAGS is created
4606 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
4607 to the beginning and end
4608 of each directory in $LIBS.
4611 The prefix used to specify a library to link on the linker command line.
4612 This will be appended to the beginning of each library
4613 in the $LIBS construction variable
4614 when the $_LIBFLAGS variable is automatically generated.
4617 The suffix used to specify a library to link on the linker command line.
4618 This will be appended to the end of each library
4619 in the $LIBS construction variable
4620 when the $_LIBFLAGS variable is automatically generated.
4623 The list of directories that will be searched for libraries.
4624 The implicit dependency scanner will search these
4625 directories for include files. Don't explicitly put include directory
4626 arguments in $LINKFLAGS or $SHLINKFLAGS
4627 because the result will be non-portable
4628 and the directories will not be searched by the dependency scanner. Note:
4629 directory names in LIBPATH will be looked-up relative to the SConscript
4630 directory when they are used in a command. To force
4632 to look-up a directory relative to the root of the source tree use #:
4635 env = Environment(LIBPATH='#/libs')
4639 The directory look-up can also be forced using the
4645 env = Environment(LIBPATH=libs)
4649 The directory list will be added to command lines
4650 through the automatically-generated
4652 construction variable,
4653 which is constructed by
4654 appending the values of the
4655 $LIBDIRPREFIX and $LIBDIRSUFFIX
4656 construction variables
4657 to the beginning and end
4658 of each directory in $LIBPATH.
4659 Any command lines you define that need
4660 the LIBPATH directory list should
4661 include $_LIBDIRFLAGS:
4664 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
4668 The prefix used for (static) library file names.
4671 An array of legal prefixes for library file names.
4674 A list of one or more libraries
4675 that will be linked with
4676 any executable programs
4677 created by this environment.
4680 The library list will be added to command lines
4681 through the automatically-generated
4683 construction variable,
4684 which is constructed by
4685 appending the values of the
4686 $LIBLINKPREFIX and $LIBLINKSUFFIX
4687 construction variables
4688 to the beginning and end
4689 of each directory in $LIBS.
4690 Any command lines you define that need
4691 the LIBS library list should
4695 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
4699 The suffix used for (static) library file names.
4702 An array of legal suffixes for library file names.
4708 General user options passed to the linker.
4709 Note that this variable should
4713 (or similar) options for linking with the libraries listed in $LIBS,
4716 (or similar) library search path options
4717 that scons generates automatically from $LIBPATH.
4721 for the variable that expands to library-link options,
4725 for the variable that expands to library search path options.
4728 The command line used to link object files into an executable.
4731 The M4 macro preprocessor.
4734 General options passed to the M4 macro preprocessor.
4737 The command line used to pass files through the macro preprocessor.
4740 The maximum number of characters allowed on an external command line.
4742 link lines longer than this many characters
4743 are linke via a temporary file name.
4746 When the Microsoft Visual Studio tools are initialized, they set up
4747 this dictionary with the following keys:
4750 the version of MSVS being used (can be set via
4754 the available versions of MSVS installed
4757 installed directory of Visual C++
4760 installed directory of Visual Studio
4763 installed directory of the .NET framework
4765 .B FRAMEWORKVERSIONS:
4766 list of installed versions of the .NET framework, sorted latest to oldest.
4768 .B FRAMEWORKVERSION:
4769 latest installed version of the .NET framework
4772 installed location of the .NET SDK.
4775 installed location of the Platform SDK.
4777 .B PLATFORMSDK_MODULES:
4778 dictionary of installed Platform SDK modules,
4779 where the dictionary keys are keywords for the various modules, and
4780 the values are 2-tuples where the first is the release date, and the
4781 second is the version number.
4783 If a value isn't set, it wasn't available in the registry.
4785 .IP MSVS_IGNORE_IDE_PATHS
4786 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
4787 instead of the settings from the IDE.
4789 For Visual Studio, SCons will (by default) automatically determine
4790 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
4791 set by the IDE. You can override this behavior by setting these
4792 variables after Environment initialization, or by setting
4793 .B MSVS_IGNORE_IDE_PATHS = 1
4794 in the Environment initialization.
4795 Specifying this will not leave these unset, but will set them to a
4796 minimal set of paths needed to run the tools successfully.
4799 For VS6, the mininimal set is:
4800 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
4801 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
4802 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
4804 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
4805 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
4806 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
4810 Where '<VSDir>' is the installed location of Visual Studio.
4812 .IP MSVS_USE_MFC_DIRS
4813 Tells the MS Visual Studio tool(s) to use
4814 the MFC directories in its default paths
4815 for compiling and linking.
4816 Under MSVS version 6,
4818 .B MSVS_USE_MFC_DIRS
4827 external environment variable,
4833 external environment variable.
4834 Under MSVS version 7,
4836 .B MSVS_USE_MFC_DIRS
4840 directory to the default
4842 external environment variable,
4845 directory to the default
4847 external environment variable.
4848 The current default value is
4850 which means these directories
4851 are added to the paths by default.
4852 This default value is likely to change
4853 in a future release,
4854 so users who want the ATL and MFC
4855 values included in their paths
4856 are encouraged to enable the
4857 .B MSVS_USE_MFC_DIRS
4859 to avoid future incompatibility.
4860 This variable has no effect if the
4864 environment variables are set explictly.
4867 Sets the preferred version of MSVS to use.
4869 SCons will (by default) select the latest version of MSVS
4870 installed on your machine. So, if you have version 6 and version 7
4871 (MSVS .NET) installed, it will prefer version 7. You can override this by
4874 variable in the Environment initialization, setting it to the
4875 appropriate version ('6.0' or '7.0', for example).
4876 If the given version isn't installed, tool initialization will fail.
4879 The action used to generate Microsoft Visual Studio
4880 project and solution files.
4882 .IP MSVSPROJECTSUFFIX
4883 The suffix used for Microsoft Visual Studio project (DSP) files.
4884 The default value is
4886 when using Visual Studio version 7.x (.NET),
4889 when using earlier versions of Visual Studio.
4891 .IP MSVSSOLUTIONSUFFIX
4892 The suffix used for Microsoft Visual Studio solution (DSW) files.
4893 The default value is
4895 when using Visual Studio version 7.x (.NET),
4898 when using earlier versions of Visual Studio.
4901 When set to non-zero,
4902 suppresses creation of a corresponding Win32 static import lib by the
4904 builder when used with
4905 MinGW or Microsoft Visual Studio.
4906 This also suppresses creation
4907 of an export (.exp) file
4908 when using Microsoft Visual Studio.
4911 The prefix used for (static) object file names.
4914 The suffix used for (static) object file names.
4917 The Perforce executable.
4920 The command line used to
4921 fetch source files from Perforce.
4924 General options that are passed to Perforce.
4927 The Microsoft Visual C++ precompiled header that will be used when compiling
4928 object files. This variable is ignored by tools other than Microsoft Visual C++.
4929 When this variable is
4930 defined SCons will add options to the compiler command line to
4931 cause it to use the precompiled header, and will also set up the
4932 dependencies for the PCH file. Example:
4935 env['PCH'] = 'StdAfx.pch'
4939 This variable specifies how much of a source file is precompiled. This
4940 variable is ignored by tools other than Microsoft Visual C++, or when
4941 the PCH variable is not being used. When this variable is define it
4942 must be a string that is the name of the header that
4943 is included at the end of the precompiled portion of the source files, or
4944 the empty string if the "#pragma hrdstop" construct is being used:
4947 env['PCHSTOP'] = 'StdAfx.h'
4951 The Microsoft Visual C++ PDB file that will store debugging information for
4952 object files, shared libraries, and programs. This variable is ignored by
4953 tools other than Microsoft Visual C++.
4954 When this variable is
4955 defined SCons will add options to the compiler and linker command line to
4956 cause them to generate external debugging information, and will also set up the
4957 dependencies for the PDB file. Example:
4960 env['PDB'] = 'hello.pdb'
4964 A deprecated synonym for $DVIPDFCOM.
4967 The prefix used for PDF file names.
4970 The suffix used for PDF file names.
4973 The name of the platform used to create the Environment. If no platform is
4974 specified when the Environment is created,
4976 autodetects the platform.
4979 env = Environment(tools = [])
4980 if env['PLATFORM'] == 'cygwin':
4987 The prefix used for executable file names.
4990 The suffix used for executable file names.
4993 The command line used to convert TeX DVI files into a PostScript file.
4996 The prefix used for PostScript file names.
4999 The prefix used for PostScript file names.
5002 The qt tool tries to take this from os.environ.
5003 It also initializes all QT_*
5004 construction variables listed below.
5005 (Note that all paths are constructed
5006 with python's os.path.join() method,
5007 but are listed here with the '/' separator
5008 for easier reading.)
5009 In addition, the construction environment
5010 variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5011 are modified. Because the build-performance is affected when using this tool,
5012 you have to explicitly specify it at Environment creation:
5015 Environment(tools=['default','qt']).
5020 to verify that the qt support really works.
5021 The qt tool supports the following operations:
5023 .B Automatic moc file generation from header files.
5024 You do not have to specify moc files explicitly, the tool does it for you.
5025 However, there are a few preconditions to do so: Your header file must have
5026 the same filebase as your implementation file and must stay in the same
5027 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh.
5029 .B Automatic moc file generation from cxx files.
5030 As stated in the qt documentation,
5031 include the moc file at the end of the cxx file.
5032 Note that you have to include the file, which is generated by the
5033 QT_MOCNAMEGENERATOR function. If you are using BuildDir, you may need to
5034 specify duplicate=1.
5036 .B Automatic handling of .ui files.
5037 The implementation files generated from .ui files are handled much the same
5038 as yacc or lex files. Because there are also generated headers, you may
5039 need to specify duplicate=1 in calls to BuildDir.
5041 .IP QT_AUTOBUILD_MOC_SOURCES
5042 If true, moc-generated sources are automatically compiled into the
5043 program or library that uses them. Defaults to 1.
5046 Default value is 'qt'. You may want to set this to 'qt-mt'
5049 Default value is '$QTDIR/bin/moc'.
5052 Default value is '$QTDIR/bin/uic'.
5055 Default value is ''. These flags are passed to uic, when creating a cxx
5056 file from a .ui file.
5059 Default value is ''. These flags are passed to uic, when creating a a h
5060 file from a .ui file.
5062 .IP QT_MOCFROMHFLAGS
5063 Default value is ''. These flags are passed to moc, when moccing a header
5066 .IP QT_MOCFROMCPPFLAGS
5067 Default value is '-i'. These flags are passed to moc, when moccing a
5071 Default value is '.h'. Suffix of headers generated with uic.
5074 Default value is '.ui'. Suffix of designer files.
5077 Default value is '.ui.h'.
5079 .IP QT_MOCNAMEGENERATOR
5080 Three-argument function, which generates names of moc output files.
5081 This is the most flexible way to support the huge number of conventions
5082 for this type of files. The arguments are the
5084 , which is the file to be moc'd without path and extension, the
5086 , which is the extension of the file to be moc'd and the environment
5088 The default value maps 'myfile.myext' to 'moc_myfile.$CXXFILESUFFIX':
5091 lambda filebase, src_suffix, env: 'moc_' + filebase + env['CXXFILESUFFIX']
5095 Command to generate cxx files from .ui files.
5098 Command to generate header files from .ui files.
5101 Command to generate a moc file from a header.
5103 .IP QT_MOCFROMCXXCOM
5104 Command to generate a moc file from a cpp file.
5107 The archive indexer.
5110 General options passed to the archive indexer.
5113 The resource compiler used by the RES builder.
5116 The command line used by the RES builder.
5119 The flags passed to the resource compiler by the RES builder.
5123 Note that this variable is not actually used
5124 for the command to fetch source files from RCS;
5127 construction variable, below.
5130 The RCS "checkout" executable,
5131 used to fetch source files from RCS.
5134 The command line used to
5135 fetch (checkout) source files from RCS.
5138 Options that are passed to the $RCS_CO command.
5141 A function that converts a file name into a list of Dir instances by
5142 searching the repositories.
5145 The Java RMI stub compiler.
5148 The command line used to compile stub
5149 and skeleton class files
5150 from Java classes that contain RMI implementations.
5151 Any options specified in the $RMICFLAGS construction variable
5152 are included on this command line.
5155 General options passed to the Java RMI stub compiler.
5158 A list of paths to search for shared libraries when running programs.
5159 Currently only used in the GNU linker. Ignored on platforms and
5160 toolchains that don't support it. Note that the paths added to RPATH
5161 are not transformed by
5163 in any way: if you want an absolute
5164 path, you must make it absolute yourself.
5167 A list of the available implicit dependency scanners.
5170 The SCCS executable.
5173 The command line used to
5174 fetch source files from SCCS.
5177 General options that are passed to SCCS.
5180 Options that are passed specifically to the SCCS "get" subcommand.
5181 This can be set, for example, to
5183 to check out editable files from SCCS.
5186 The C compiler used for generating shared-library objects.
5189 The command line used to compile a C source file
5190 to a shared-library object file.
5191 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
5192 are included on this command line.
5195 Options that are passed to the C compiler
5196 to generate shared-library objects.
5199 The C++ compiler used for generating shared-library objects.
5202 The command line used to compile a C++ source file
5203 to a shared-library object file.
5204 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
5205 are included on this command line.
5208 Options that are passed to the C++ compiler
5209 to generate shared-library objects.
5212 A string naming the shell program that will be passed to the
5217 construction variable for more information.
5220 The Fortran compiler used for generating shared-library objects.
5223 The command line used to compile a Fortran source file
5224 to a shared-library object file.
5227 Options that are passed to the Fortran compiler
5228 to generated shared-library objects.
5231 The command line used to compile a Fortran source file to a
5232 shared-library object file
5233 after first running the file through the C preprocessor.
5234 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
5235 are included on this command line.
5238 The prefix used for shared library file names.
5241 The suffix used for shared library file names.
5244 The linker for programs that use shared libraries.
5247 General user options passed to the linker for programs using shared libraries.
5248 Note that this variable should
5252 (or similar) options for linking with the libraries listed in $LIBS,
5255 (or similar) include search path options
5256 that scons generates automatically from $LIBPATH.
5260 for the variable that expands to library-link options,
5264 for the variable that expands to library search path options.
5267 The prefix used for shared object file names.
5270 The suffix used for shared object file names.
5273 A reserved variable name
5274 that may not be set or used in a construction environment.
5275 (See "Variable Substitution," below.)
5278 A reserved variable name
5279 that may not be set or used in a construction environment.
5280 (See "Variable Substitution," below.)
5283 A command interpreter function that will be called to execute command line
5284 strings. The function must expect 4 arguments:
5287 def spawn(shell, escape, cmd, args, env):
5291 is a string naming the shell program to use.
5293 is a function that can be called to escape shell special characters in
5296 is the path to the command to be executed.
5298 is that arguments to the command.
5300 is a dictionary of the environment variables
5301 in which the command should be executed.
5304 '\"The Subversion executable (usually named
5308 '\"The command line used to
5309 '\"fetch source files from a Subversion repository.
5312 '\"General options that are passed to Subversion.
5315 The scripting language wrapper and interface generator.
5318 The suffix that will be used for intermediate C
5319 source files generated by
5320 the scripting language wrapper and interface generator.
5321 The default value is
5322 .BR _wrap$CFILESUFFIX .
5323 By default, this value is used whenever the
5327 specified as part of the
5329 construction variable.
5332 The command line used to call
5333 the scripting language wrapper and interface generator.
5335 .IP SWIGCXXFILESUFFIX
5336 The suffix that will be used for intermediate C++
5337 source files generated by
5338 the scripting language wrapper and interface generator.
5339 The default value is
5340 .BR _wrap$CFILESUFFIX .
5341 By default, this value is used whenever the
5343 option is specified as part of the
5345 construction variable.
5348 General options passed to
5349 the scripting language wrapper and interface generator.
5350 This is where you should set
5354 or whatever other options you want to specify to SWIG.
5357 option in this variable,
5360 generate a C++ intermediate source file
5361 with the extension that is specified as the
5369 The command line used to call the tar archiver.
5372 General options passed to the tar archiver.
5375 A reserved variable name
5376 that may not be set or used in a construction environment.
5377 (See "Variable Substitution," below.)
5380 A reserved variable name
5381 that may not be set or used in a construction environment.
5382 (See "Variable Substitution," below.)
5385 The suffix used for tar file names.
5388 The TeX formatter and typesetter.
5391 The command line used to call the TeX formatter and typesetter.
5394 General options passed to the TeX formatter and typesetter.
5397 A list of the names of the Tool specifications
5398 that are part of this construction environment.
5400 .IP WIN32_INSERT_DEF
5401 When this is set to true,
5402 a library build of a WIN32 shared library (.dll file)
5403 will also build a corresponding .def file at the same time,
5404 if a .def file is not already listed as a build target.
5405 The default is 0 (do not build a .def file).
5408 The prefix used for WIN32 .def file names.
5411 The suffix used for WIN32 .def file names.
5414 The parser generator.
5417 The command line used to call the parser generator
5418 to generate a source file.
5421 General options passed to the parser generator.
5422 If $YACCFLAGS contains a \-d option,
5423 SCons assumes that the call will also create a .h file
5424 (if the yacc source file ends in a .y suffix)
5426 (if the yacc source file ends in a .yy suffix)
5429 The zip compression and file packaging utility.
5432 The command line used to call the zip utility,
5433 or the internal Python function used to create a
5442 module used by the internal Python function
5443 to control whether the zip archive
5444 is compressed or not.
5445 The default value is
5446 .BR zipfile.ZIP_DEFLATED ,
5447 which creates a compressed zip archive.
5448 This value has no effect when using Python 1.5.2
5451 module is otherwise unavailable.
5454 General options passed to the zip utility.
5457 Construction variables can be retrieved and set using the
5459 method of the construction environment:
5462 dict = env.Dictionary()
5466 or using the [] operator:
5472 Construction variables can also be passed to the construction environment
5476 env = Environment(CC="cc")
5479 or when copying a construction environment using the
5484 env2 = env.Copy(CC="cl.exe")
5487 .SS Configure Contexts
5491 .I configure contexts,
5492 an integrated mechanism similar to the
5493 various AC_CHECK macros in GNU autoconf
5494 for testing for the existence of C header
5495 files, libraries, etc.
5496 In contrast to autoconf,
5498 does not maintain an explicit cache of the tested values,
5499 but uses its normal dependency tracking to keep the checked values
5501 The following methods can be used to perform checks:
5504 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
5506 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
5507 This creates a configure context, which can be used to perform checks.
5509 specifies the environment for building the tests.
5510 This environment may be modified when performing checks.
5512 is a dictionary containing custom tests.
5513 See also the section about custom tests below.
5514 By default, no custom tests are added to the configure context.
5516 specifies a directory where the test cases are built.
5517 Note that this directory is not used for building
5519 The default value is the directory
5522 specifies a file which collects the output from commands
5523 that are executed to check for the existence of header files, libraries, etc.
5524 The default is the file #/config.log.
5525 If you are using the
5528 you may want to specify a subdirectory under your build directory.
5533 instance has the following associated methods:
5536 .RI Configure.Finish( self )
5537 This method should be called after configuration is done.
5538 It returns the environment as modified
5539 by the configuration checks performed.
5540 After this method is called, no further checks can be performed
5541 with this configuration context.
5542 However, you can create a new
5544 context to perform additional checks.
5545 Only one context should be active at a time.
5547 The following Checks are predefined.
5548 (This list will likely grow larger as time
5549 goes by and developers contribute new useful tests.)
5552 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
5555 is usable in the specified language.
5558 in which case the last item in the list
5559 is the header file to be checked,
5560 and the previous list items are
5563 lines should precede the
5564 header line being checked for.
5565 The optional argument
5568 a two character string, where the first character denotes the opening
5569 quote and the second character denotes the closing quote.
5570 By default, both characters are " (double quote).
5571 The optional argument
5577 and selects the compiler to be used for the check.
5578 Returns 1 on success and 0 on failure.
5581 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
5582 This is a wrapper around
5583 .B Configure.CheckHeader
5586 is usable in the C language.
5589 in which case the last item in the list
5590 is the header file to be checked,
5591 and the previous list items are
5594 lines should precede the
5595 header line being checked for.
5596 The optional argument
5599 a two character string, where the first character denotes the opening
5600 quote and the second character denotes the closing quote (both default
5602 Returns 1 on success and 0 on failure.
5605 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
5606 This is a wrapper around
5607 .B Configure.CheckHeader
5610 is usable in the C++ language.
5613 in which case the last item in the list
5614 is the header file to be checked,
5615 and the previous list items are
5618 lines should precede the
5619 header line being checked for.
5620 The optional argument
5623 a two character string, where the first character denotes the opening
5624 quote and the second character denotes the closing quote (both default
5626 Returns 1 on success and 0 on failure.
5629 .RI Configure.CheckFunc( self ", " function_name ", [" language ])
5630 Checks if the specified
5631 C or C+++ function is available.
5633 is the name of the function to check for.
5640 and selects the compiler to be used for the check;
5644 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
5651 is 1 and the library provides the specified
5653 appends the library to the LIBS construction environment variable.
5655 may also be None (the default),
5658 is checked with the current LIBS variable,
5659 or a list of library names,
5660 in which case each library in the list
5667 you can link against the specified
5675 and selects the compiler to be used for the check;
5677 The default value for
5680 It is assumed, that the C-language is used.
5681 This method returns 1 on success and 0 on error.
5684 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
5687 .RI Configure.CheckLib
5688 call, this call provides a more sophisticated way to check against libraries.
5691 specifies the library or a list of libraries to check.
5693 specifies a header to check for.
5696 in which case the last item in the list
5697 is the header file to be checked,
5698 and the previous list items are
5701 lines should precede the
5702 header line being checked for.
5704 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
5706 can be any valid expression (with a trailing ';'). The default is 'main();'.
5708 specifies whether to add the library to the environment (only if the check
5709 succeeds). This method returns 1 on success and 0 on error.
5712 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
5713 Checks for the existence of a type defined by
5716 specifies the typedef name to check for.
5718 is a string containing one or more
5720 lines that will be inserted into the program
5721 that will be run to test for the existence of the type.
5728 and selects the compiler to be used for the check;
5732 Example of a typical Configure usage:
5736 conf = Configure( env )
5737 if not conf.CheckCHeader( 'math.h' ):
5738 print 'We really need math.h!'
5740 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
5741 # do stuff for qt - usage, e.g.
5742 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
5747 You can define your own custom checks.
5748 in addition to the predefined checks.
5749 These are passed in a dictionary to the Configure function.
5750 This dictionary maps the names of the checks
5751 to user defined Python callables
5752 (either Python functions or class instances implementing the
5755 The first argument of the call is always a
5757 instance followed by the arguments,
5758 which must be supplied by the user of the check.
5759 These CheckContext instances define the following methods:
5762 .RI CheckContext.Message( self ", " text )
5764 Usually called before the check is started.
5766 will be displayed to the user, e.g. 'Checking for library X...'
5769 .RI CheckContext.Result( self, ", " res )
5771 Usually called after the check is done.
5773 can be either an integer or a string. In the former case, 'ok' (res != 0)
5774 or 'failed' (res == 0) is displayed to the user, in the latter case the
5775 given string is displayed.
5778 .RI CheckContext.TryCompile( self ", " text ", " extension )
5779 Checks if a file with the specified
5781 (e.g. '.c') containing
5783 can be compiled using the environment's
5785 builder. Returns 1 on success and 0 on failure.
5788 .RI CheckContext.TryLink( self ", " text ", " extension )
5789 Checks, if a file with the specified
5791 (e.g. '.c') containing
5793 can be compiled using the environment's
5795 builder. Returns 1 on success and 0 on failure.
5798 .RI CheckContext.TryRun( self ", " text ", " extension )
5799 Checks, if a file with the specified
5801 (e.g. '.c') containing
5803 can be compiled using the environment's
5805 builder. On success, the program is run. If the program
5806 executes successfully
5807 (that is, its return status is 0),
5812 is the standard output of the
5814 If the program fails execution
5815 (its return status is non-zero),
5816 then (0, '') is returned.
5819 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
5820 Checks if the specified
5822 with an optional source file (contents
5829 may be anything which can be converted to a
5836 is the content of the target file.
5842 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
5843 Low level implementation for testing specific builds;
5844 the methods above are based on this method.
5845 Given the Builder instance
5849 of a source file with optional
5851 this method returns 1 on success and 0 on failure. In addition,
5853 is set to the build target node, if the build was successful.
5856 Example for implementing and using custom tests:
5859 def CheckQt(context, qtdir):
5860 context.Message( 'Checking for qt ...' )
5861 lastLIBS = context.env['LIBS']
5862 lastLIBPATH = context.env['LIBPATH']
5863 lastCPPPATH= context.env['CPPPATH']
5864 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
5865 ret = context.TryLink("""
5867 int main(int argc, char **argv) {
5868 QApplication qapp(argc, argv);
5873 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
5874 context.Result( ret )
5878 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
5879 if not conf.CheckQt('/usr/lib/qt'):
5880 print 'We really need qt!'
5885 .SS Construction Variable Options
5887 Often when building software, various options need to be specified at build
5888 time that are not known when the SConstruct/SConscript files are
5889 written. For example, libraries needed for the build may be in non-standard
5890 locations, or site-specific compiler options may need to be passed to the
5893 provides a mechanism for overridding construction variables from the
5894 command line or a text-based SConscript file through an Options
5895 object. To create an Options object, call the Options() function:
5898 .RI Options([ files "], [" args ])
5899 This creates an Options object that will read construction variables from
5900 the file or list of filenames specified in
5902 If no files are specified,
5907 then no files will be read.
5908 The optional argument
5911 values that will override anything read from the specified files;
5912 it is primarily intended to be passed the
5914 dictionary that holds variables
5915 specified on the command line.
5919 opts = Options('custom.py')
5920 opts = Options('overrides.py', ARGUMENTS)
5921 opts = Options(None, {FOO:'expansion', BAR:7})
5924 Options objects have the following methods:
5927 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
5928 This adds a customizable construction variable to the Options object.
5930 is the name of the variable.
5932 is the help text for the variable.
5934 is the default value of the variable.
5936 is called to validate the value of the variable, and should take three
5937 arguments: key, value, and environment
5939 is called to convert the value before putting it in the environment, and
5940 should take a single argument: value. Example:
5943 opts.Add('CC', 'The C compiler')
5947 .RI AddOptions( list )
5948 A wrapper script that adds
5949 multiple customizable construction variables
5950 to an Options object.
5952 is a list of tuple or list objects
5953 that contain the arguments
5954 for an individual call to the
5961 ('CC', 'The C compiler'),
5962 ('VALIDATE', 'An option for testing validation',
5963 'notset', validator, None),
5968 .RI Update( env ", [" args ])
5969 This updates a construction environment
5971 with the customized construction variables. Normally this method is not
5972 called directly, but is called indirectly by passing the Options object to
5973 the Environment() function:
5976 env = Environment(options=opts)
5980 .RI Save( filename ", " env )
5981 This saves the currently set options into a script file named
5983 that can be used on the next invocation to automatically load the current
5984 settings. This method combined with the Options method can be used to
5985 support caching of options between runs.
5989 opts = Options(['options.cache', 'custom.py'])
5992 opts.Save('options.cache', env)
5996 .RI GenerateHelpText( env ", [" sort ])
5997 This generates help text documenting the customizable construction
5998 variables suitable to passing in to the Help() function.
6000 is the construction environment that will be used to get the actual values
6001 of customizable variables. Calling with
6005 will cause the output to be sorted
6006 by the specified argument.
6010 should take two arguments
6013 (like the standard Python
6018 Help(opts.GenerateHelpText(env))
6019 Help(opts.GenerateHelpText(env, sort=cmp))
6022 The text based SConscript file is executed as a Python script, and the
6023 global variables are queried for customizable construction
6030 To make it more convenient to work with customizable Options,
6032 provides a number of functions
6033 that make it easy to set up
6034 various types of Options:
6037 .RI BoolOption( key ", " help ", " default )
6038 Return a tuple of arguments
6039 to set up a Boolean option.
6043 have a default value of
6045 and display the specified
6048 The option will interpret the values
6070 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
6071 Return a tuple of arguments
6073 whose value may be one
6074 of a specified list of legal enumerated values.
6078 have a default value of
6080 and display the specified
6083 The option will only support those
6089 argument is a dictionary
6090 that can be used to convert
6091 input values into specific legal values
6100 then the values are case-sensitive.
6105 then values will be matched
6111 then values will be matched
6113 and all input values will be
6114 converted to lower case.
6117 .RI ListOption( key ", " help ", " default ", " names )
6118 Return a tuple of arguments
6120 whose value may be one or more
6121 of a specified list of legal enumerated values.
6125 have a default value of
6127 and display the specified
6130 The option will only support the values
6133 or the values in the
6136 More than one value may be specified,
6137 with all values separated by commas.
6140 .RI PackageOption( key ", " help ", " default )
6141 Return a tuple of arguments
6143 whose value is a path name
6144 of a package that may be
6145 enabled, disabled or
6146 given an explicit path name.
6150 have a default value of
6152 and display the specified
6155 The option will support the values
6162 in which case the specified
6165 or the option may be set to an
6167 (typically the path name to a package
6168 that is being enabled).
6169 The option will also support the values
6175 to disable use of the specified option.
6178 .RI PathOption( key ", " help ", " default )
6179 Return a tuple of arguments
6181 whose value is expected to be a path name.
6185 have a default value of
6187 and display the specified
6192 These functions make it
6193 convenient to create a number
6194 of options with consistent behavior
6195 in a single call to the
6201 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
6202 EnumOption('debug', 'debug output and symbols', 'no'
6203 allowed_values=('yes', 'no', 'full'),
6204 map={}, ignorecase=0), # case sensitive
6205 ListOption('shared',
6206 'libraries to build as shared libraries',
6208 names = list_of_libs),
6209 PackageOption('x11',
6210 'use X11 installed here (yes = search some places)',
6212 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
6219 can be extended by adding new builders to a construction
6220 environment using the
6225 function accepts the following arguments:
6228 The command line string used to build the target from the source.
6231 a list of strings representing the command
6232 to be executed and its arguments
6233 (suitable for enclosing white space in an argument),
6235 mapping source file name suffixes to
6236 any combination of command line strings
6237 (if the builder should accept multiple source file extensions),
6240 (see the next section);
6241 or a list of any of the above.
6244 takes three arguments:
6246 - a list of source nodes,
6248 - a list of target nodes,
6250 - the construction environment.
6253 Specifies whether this builder is allowed to be called multiple times for
6254 the same target file(s). The default is 0, which means the builder
6255 can not be called multiple times for the same target file(s). Calling a
6256 builder multiple times for the same target simply adds additional source
6257 files to the target; it is not allowed to change the environment associated
6258 with the target, specify addition environment overrides, or associate a different
6259 builder with the target.
6262 The prefix that will be prepended to the target file name.
6263 This may be a simple string, or a callable object that takes
6264 two arguments, a construction environment and a list of sources,
6265 and returns a prefix.
6268 b = Builder("build_it < $SOURCE > $TARGET"
6271 def gen_prefix(env, sources):
6272 return "file-" + env['PLATFORM'] + '-'
6273 b = Builder("build_it < $SOURCE > $TARGET"
6274 prefix = gen_prefix)
6278 The suffix that will be appended to the target file name.
6279 This may be a simple string, or a callable object that takes
6280 two arguments, a construction environment and a list of sources,
6281 and returns a suffix.
6282 If the suffix is a string, then
6284 will append a '.' to the beginning of the
6285 suffix if it's not already there.
6286 The string returned by callable object
6287 is untouched and must append its own '.'
6288 to the beginning if one is desired.
6291 b = Builder("build_it < $SOURCE > $TARGET"
6294 def gen_suffix(env, sources):
6295 return "." + env['PLATFORM'] + "-file"
6296 b = Builder("build_it < $SOURCE > $TARGET"
6297 suffix = gen_suffix)
6301 The expected source file name suffix.
6304 Specifies a builder to use when a source file name suffix does not match
6305 any of the suffixes of the builder. Using this argument produces a
6306 multi-stage builder.
6309 A function or list of functions to manipulate the target and source
6310 lists before dependencies are established
6311 and the target(s) are actually built.
6313 can also be string containing a construction variable to expand
6314 to an emitter function or list of functions,
6315 or a dictionary mapping source file suffixes
6316 to emitter functions.
6317 (Only the suffix of the first source file
6318 is used to select the actual emitter function
6319 from an emitter dictionary.)
6322 takes three arguments:
6324 - a list of source nodes,
6326 - a list of target nodes,
6328 - the construction environment.
6329 An emitter must return a tuple containing two lists,
6330 the list of targets to be built by this builder,
6331 and the list of sources for this builder.
6336 def e(target, source, env):
6337 return (target + ['foo.foo'], source + ['foo.src'])
6339 # Simple association of an emitter function with a Builder.
6340 b = Builder("my_build < $TARGET > $SOURCE",
6343 def e2(target, source, env):
6344 return (target + ['bar.foo'], source + ['bar.src'])
6346 # Simple association of a list of emitter functions with a Builder.
6347 b = Builder("my_build < $TARGET > $SOURCE",
6350 # Calling an emitter function through a construction variable.
6351 env = Environment(MY_EMITTER = e)
6352 b = Builder("my_build < $TARGET > $SOURCE",
6353 emitter = '$MY_EMITTER')
6355 # Calling a list of emitter functions through a construction variable.
6356 env = Environment(EMITTER_LIST = [e, e2])
6357 b = Builder("my_build < $TARGET > $SOURCE",
6358 emitter = '$EMITTER_LIST')
6360 # Associating multiple emitters with different file
6361 # suffixes using a dictionary.
6362 def e_suf1(target, source, env):
6363 return (target + ['another_target_file'], source)
6364 def e_suf2(target, source, env):
6365 return (target, source + ['another_source_file'])
6366 b = Builder("my_build < $TARGET > $SOURCE",
6367 emitter = {'.suf1' : e_suf1,
6372 A function that returns a list of actions that will be executed to build
6373 the target(s) from the source(s).
6374 The returned action(s) may be
6375 an Action object, or anything that
6376 can be converted into an Action object
6377 (see the next section).
6379 The generator function
6380 takes four arguments:
6382 - a list of source nodes,
6384 - a list of target nodes,
6386 - the construction environment,
6388 - a Boolean value that specifies
6389 whether the generator is being called
6390 for generating a build signature
6391 (as opposed to actually executing the command).
6395 def g(source, target, env, for_signature):
6396 return [["gcc", "-c", "-o"] + target + source]
6398 b = Builder(generator=g)
6405 arguments must not both be used for the same Builder.
6408 A construction environment that can be used
6409 to fetch source code using this Builder.
6410 (Note that this environment is
6412 used for normal builds of normal target files,
6413 which use the environment that was
6414 used to call the Builder for the target file.)
6416 Any additional keyword arguments supplied
6417 when a Builder object is created
6418 (that is, when the Builder() function is called)
6419 will be set in the executing construction
6420 environment when the Builder object is called.
6421 The canonical example here would be
6422 to set a construction variable to
6423 the repository of a source code system.
6425 Any additional keyword arguments supplied
6429 will only be associated with the target
6430 created by that particular Builder call
6431 (and any other files built as a
6432 result of the call).
6435 b = Builder(action="build < $SOURCE > $TARGET")
6436 env = Environment(BUILDERS = {'MyBuild' : b})
6437 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
6440 These extra keyword arguments are passed to the
6441 following functions:
6442 command generator functions,
6444 and emitter functions.
6450 function will turn its
6452 keyword argument into an appropriate
6453 internal Action object.
6454 You can also explicity create Action objects
6458 which can then be passed to the
6461 This can be used to configure
6462 an Action object more flexibly,
6463 or it may simply be more efficient
6464 than letting each separate Builder object
6465 create a separate Action
6467 Builder objects need to do the same thing.
6472 returns an appropriate object for the action
6473 represented by the type of the first argument:
6476 If the first argument is already an Action object,
6477 the object is simply returned.
6480 If the first argument is a string,
6481 a command-line Action is returned.
6484 Action('$CC -c -o $TARGET $SOURCES')
6487 .\" XXX From Gary Ruben, 23 April 2002:
6488 .\" What would be useful is a discussion of how you execute command
6489 .\" shell commands ie. what is the process used to spawn the shell, pass
6490 .\" environment variables to it etc., whether there is one shell per
6491 .\" environment or one per command etc. It might help to look at the Gnu
6492 .\" make documentation to see what they think is important to discuss about
6493 .\" a build system. I'm sure you can do a better job of organising the
6494 .\" documentation than they have :-)
6498 If the first argument is a list,
6499 then a list of Action objects is returned.
6500 An Action object is created as necessary
6501 for each element in the list.
6504 the list is itself a list,
6505 the internal list is the
6506 command and arguments to be executed via
6508 This allows white space to be enclosed
6509 in an argument by defining
6510 a command in a list within a list:
6513 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
6517 If the first argument is a Python function,
6518 a function Action is returned.
6519 The Python function takes three keyword arguments,
6521 (a Node object representing the target file),
6523 (a Node object representing the source file)
6526 (the construction environment
6527 used for building the target file).
6532 arguments may be lists of Node objects if there is
6533 more than one target file or source file.
6534 The actual target and source file name(s) may
6535 be retrieved from their Node objects
6536 via the built-in Python str() function:
6539 target_file_name = str(target)
6540 source_file_names = map(lambda x: str(x), source)
6543 The function should return
6547 to indicate a successful build of the target file(s).
6548 The function may raise an exception
6549 or return a non-zero exit status
6550 to indicate an unsuccessful build.
6553 def build_it(target = None, source = None, env = None):
6554 # build the target from the source
6557 a = Action(build_it)
6560 The second, optional argument
6561 is a Python function that returns
6562 a string to be printed to describe the action being executed.
6563 Like a function to build a file,
6564 this function takes three arguments:
6566 (a Node object representing the target file),
6568 (a Node object representing the source file)
6571 (a construction environment).
6576 arguments may be lists of Node objects if there is
6577 more than one target file or source file.
6581 def build_it(target, source, env):
6582 # build the target from the source
6585 def string_it(target, source, env):
6586 return "building '%s' from '%s'" % (target[0], source[0])
6588 # Use a positional argument.
6589 a = Action(build_it, string_it)
6591 # Alternatively, use a keyword argument.
6592 a = Action(build_it, strfunction=string_it)
6595 The third, also optional argument
6596 is a list of construction variables
6597 whose values will be included
6598 in the signature of the Action
6599 when deciding whether a target should
6600 be rebuilt because the action changed.
6601 This is necessary whenever you want a target to
6602 be rebuilt when a specific
6603 construction variable changes,
6604 because the underlying Python code for a function
6605 will not change when the value of the construction variable does.
6608 def build_it(target, source, env):
6609 # build the target from the 'XXX' construction variable
6610 open(target[0], 'w').write(env['XXX'])
6613 def string_it(target, source):
6614 return "building '%s' from '%s'" % (target[0], source[0])
6616 # Use positional arguments.
6617 a = Action(build_it, string_it, ['XXX'])
6619 # Alternatively, use a keyword argument.
6620 a = Action(build_it, varlist=['XXX'])
6623 If the action argument is not one of the above,
6626 .SS Miscellaneous Action Functions
6629 supplies a number of functions
6630 that arrange for various common
6631 file and directory manipulations
6633 These are similar in concept to "tasks" in the
6635 although the implementation is slightly different.
6636 These functions do not actually
6637 perform the specified action
6638 at the time the function is called,
6639 but instead return an Action object
6640 that can be executed at the
6642 (In Object-Oriented terminology,
6647 that return Action objects.)
6650 there are two natural ways
6653 are intended to be used.
6657 to perform the action
6658 at the time the SConscript
6662 global function to do so:
6664 Execute(Touch('file'))
6668 you can use these functions
6669 to supply Actions in a list
6673 This can allow you to
6674 perform more complicated
6675 sequences of file manipulation
6677 on platform-specific
6681 env = Environment(TMPBUILD = '/tmp/builddir')
6682 env.Command('foo.out', 'foo.in',
6683 [Mkdir('$TMPBUILD'),
6684 Copy('${SOURCE.dir}', '$TMPBUILD')
6685 "cd $TMPBUILD && make",
6686 Delete('$TMPBUILD')])
6690 .RI Chmod( dest ", " mode )
6691 Returns an Action object that
6692 changes the permissions on the specified
6694 file or directory to the specified
6699 Execute(Chmod('file', 0755))
6701 env.Command('foo.out', 'foo.in',
6702 [Copy('$TARGET', '$SOURCE'),
6703 Chmod('$TARGET', 0755)])
6707 .RI Copy( dest ", " src )
6708 Returns an Action object
6711 source file or directory to the
6713 destination file or directory.
6717 Execute(Copy('foo.output', 'foo.input'))
6719 env.Command('bar.out', 'bar.in',
6720 Copy('$TARGET', '$SOURCE'))
6725 Returns an Action that
6726 deletes the specified
6728 which may be a file or a directory tree.
6729 If a directory is specified,
6730 the entire directory tree
6735 Execute(Delete('/tmp/buildroot'))
6737 env.Command('foo.out', 'foo.in',
6738 [Delete('${TARGET.dir}'),
6745 that creates the specified
6751 Execute(Mkdir('/tmp/outputdir'))
6753 env.Command('foo.out', 'foo.in',
6754 [Mkdir('/tmp/builddir',
6755 Copy('$SOURCE', '/tmp/builddir')
6756 "cd /tmp/builddir && ])
6761 .RI Move( dest ", " src )
6763 that moves the specified
6765 file or directory to
6772 Execute(Move('file.destination', 'file.source'))
6774 env.Command('output_file', 'input_file',
6776 Move('$TARGET', 'file_created_by_MyBuildAction')])
6782 that updates the modification time
6788 Execute(Touch('file_to_be_touched'))
6790 env.Command('marker', 'input_file',
6795 .SS Variable Substitution
6797 Before executing a command,
6799 performs construction variable interpolation on the strings that make up
6800 the command line of builders.
6801 Variables are introduced by a
6804 Besides construction variables, scons provides the following
6805 variables for each command execution:
6808 The file name of the target being built, or the file name of the first
6809 target if multiple targets are being built.
6812 The file names of all targets being built.
6815 The file name of the source of the build command, or the file name of the
6816 first source if multiple sources are being built.
6819 The file names of the sources of the build command.
6821 (Note that the above variables are reserved
6822 and may not be set in a construction environment.)
6825 For example, given the construction variable CC='cc', targets=['foo'], and
6826 sources=['foo.c', 'bar.c']:
6829 action='$CC -c -o $TARGET $SOURCES'
6832 would produce the command line:
6835 cc -c -o foo foo.c bar.c
6838 Variable names may be surrounded by curly braces ({})
6839 to separate the name from the trailing characters.
6840 Within the curly braces, a variable name may have
6841 a Python slice subscript appended to select one
6842 or more items from a list.
6843 In the previous example, the string:
6855 Additionally, a variable name may
6856 have the following special
6857 modifiers appended within the enclosing curly braces
6858 to modify the interpolated string:
6861 The base path of the file name,
6862 including the directory path
6863 but excluding any suffix.
6866 The name of the directory in which the file exists.
6870 minus any directory portion.
6873 Just the basename of the file,
6875 and minus the directory.
6878 Just the file suffix.
6881 The absolute path name of the file.
6884 The POSIX form of the path,
6885 with directories separated by
6889 This is sometimes necessary on Win32 systems
6890 when a path references a file on other (POSIX) systems.
6893 The directory and file name to the source file linked to this file
6894 through BuildDir. If this file isn't linked, it just returns the
6895 directory and filename unchanged.
6898 The directory containing the source file linked to this file
6899 through BuildDir. If this file isn't linked, it just returns the
6900 directory part of the filename.
6903 The directory and file name to the source file linked to this file
6904 through BuildDir. If the file does not exist locally but exists in
6905 a Repository, the path in the Repository is returned.
6906 If this file isn't linked, it just returns the
6907 directory and filename unchanged.
6910 The Repository directory containing the source file linked to this file
6911 through BuildDir. If this file isn't linked, it just returns the
6912 directory part of the filename.
6915 For example, the specified target will
6916 expand as follows for the corresponding modifiers:
6919 $TARGET => sub/dir/file.x
6920 ${TARGET.base} => sub/dir/file
6921 ${TARGET.dir} => sub/dir
6922 ${TARGET.file} => file.x
6923 ${TARGET.filebase} => file
6924 ${TARGET.suffix} => .x
6925 ${TARGET.abspath} => /top/dir/sub/dir/file.x
6927 BuildDir('sub/dir','src')
6928 $SOURCE => sub/dir/file.x
6929 ${SOURCE.srcpath} => src/file.x
6930 ${SOURCE.srcdir} => src
6932 Repository('/usr/repository')
6933 $SOURCE => sub/dir/file.x
6934 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
6935 ${SOURCE.rsrcdir} => /usr/repository/src
6938 Lastly, a variable name
6939 may be a callable Python function
6941 construction variable in the environment.
6943 take four arguments:
6945 - a list of target nodes,
6947 - a list of source nodes,
6949 - the construction environment,
6951 - a Boolean value that specifies
6952 whether the function is being called
6953 for generating a build signature.
6954 SCons will insert whatever
6955 the called function returns
6956 into the expanded string:
6959 def foo(target, source, env, for_signature):
6962 # Will expand $BAR to "bar baz"
6963 env=Environment(FOO=foo, BAR="$FOO baz")
6966 You can use this feature to pass arguments to a
6967 Python function by creating a callable class
6968 that stores one or more arguments in an object,
6969 and then uses them when the
6972 Note that in this case,
6973 the entire variable expansion must
6974 be enclosed by curly braces
6975 so that the arguments will
6976 be associated with the
6977 instantiation of the class:
6981 def __init__(self, arg):
6984 def __call__(self, target, source, env, for_signature):
6987 # Will expand $BAR to "my argument bar baz"
6988 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
6992 The special pseudo-variables
6996 may be used to surround parts of a command line
6999 causing a rebuild--that is,
7000 which are not included in the signature
7001 of target files built with this command.
7006 will be removed from the command line
7007 before it is added to file signatures,
7012 will be removed before the command is executed.
7013 For example, the command line:
7016 echo Last build occurred $( $TODAY $). > $TARGET
7020 would execute the command:
7023 echo Last build occurred $TODAY. > $TARGET
7027 but the command signature added to any target files would be:
7030 echo Last build occurred . > $TARGET
7033 SCons uses the following rules when converting construction variables into
7037 When the value is a string it is interpreted as a space delimited list of
7038 command line arguments.
7041 When the value is a list it is interpreted as a list of command line
7042 arguments. Each element of the list is converted to a string.
7045 Anything that is not a list or string is converted to a string and
7046 interpreted as a single command line argument.
7049 Newline characters (\\n) delimit lines. The newline parsing is done after
7050 all other parsing, so it is not possible for arguments (e.g. file names) to
7051 contain embedded newline characters. This limitation will likely go away in
7052 a future version of SCons.
7060 new file types for implicit dependencies.
7061 Scanner accepts the following arguments:
7064 A Python function that will process
7066 and return a list of strings (file names)
7067 representing the implicit
7068 dependencies found in the contents.
7069 The function takes three or four arguments:
7071 def scanner_function(node, env, path):
7073 def scanner_function(node, env, path, arg):
7077 argument is the internal
7078 SCons node representing the file.
7081 to fetch the name of the file, and
7082 .B node.get_contents()
7083 to fetch contents of the file.
7087 argument is the construction environment for the scan.
7088 Fetch values from it using the
7094 argument is a tuple (or list)
7095 of directories that can be searched
7097 This will usually be the tuple returned by the
7099 argument (see below).
7103 argument is the argument supplied
7104 when the scanner was created, if any.
7107 The name of the Scanner.
7109 to identify the Scanner internally.
7112 An optional argument that, if specified,
7113 will be passed to the scanner function
7115 and the path function
7119 An optional list that can be used to
7120 determine which scanner should be used for
7122 In the usual case of scanning for file names,
7123 this argument will be a list of suffixes
7124 for the different file types that this
7125 Scanner knows how to scan.
7126 If the argument is a string,
7127 then it will be expanded
7128 into a list by the current environment.
7131 A Python function that takes
7132 two or three arguments:
7133 a construction environment, directory Node,
7134 and optional argument supplied
7135 when the scanner was created.
7138 returns a tuple of directories
7139 that can be searched for files to be returned
7140 by this Scanner object.
7143 The class of Node that should be returned
7144 by this Scanner object.
7145 Any strings or other objects returned
7146 by the scanner function
7147 that are not of this class
7148 will be run through the
7153 A Python function that will take a string
7155 and turn it into the appropriate class of Node
7156 to be returned by this Scanner object.
7159 An optional Python function that takes a Node (file)
7160 as an argument and returns whether the
7161 Node should, in fact,
7162 be scanned for dependencies.
7163 This check can be used to eliminate unnecessary
7164 calls to the scanner function when,
7165 for example, the underlying file
7166 represented by a Node does not yet exist.
7169 An optional flag that
7170 specifies whether this scanner should be re-invoked
7171 on the dependency files returned by the scanner.
7172 When this flag is not set,
7173 the Node subsystem will
7174 only invoke the scanner on the file being scanned,
7175 and not (for example) also on the files
7176 specified by the #include lines
7177 in the file being scanned.
7179 .SH SYSTEM-SPECIFIC BEHAVIOR
7180 SCons and its configuration files are very portable,
7181 due largely to its implementation in Python.
7182 There are, however, a few portability
7183 issues waiting to trap the unwary.
7185 SCons handles the upper-case
7187 file suffix differently,
7188 depending on the capabilities of
7189 the underlying system.
7190 On a case-sensitive system
7191 such as Linux or UNIX,
7192 SCons treats a file with a
7194 suffix as a C++ source file.
7195 On a case-insensitive system
7197 SCons treats a file with a
7199 suffix as a C source file.
7201 SCons handles the upper-case
7203 file suffix differently,
7204 depending on the capabilities of
7205 the underlying system.
7206 On a case-sensitive system
7207 such as Linux or UNIX,
7208 SCons treats a file with a
7210 suffix as a Fortran source file
7211 that is to be first run through
7212 the standard C preprocessor.
7213 On a case-insensitive system
7215 SCons treats a file with a
7217 suffix as a Fortran source file that should
7219 be run through the C preprocessor.
7220 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
7221 Cygwin supplies a set of tools and utilities
7222 that let users work on a
7223 Windows system using a more POSIX-like environment.
7224 The Cygwin tools, including Cygwin Python,
7226 by sharing an ability to interpret UNIX-like path names.
7227 For example, the Cygwin tools
7228 will internally translate a Cygwin path name
7229 like /cygdrive/c/mydir
7230 to an equivalent Windows pathname
7231 of C:/mydir (equivalent to C:\\mydir).
7234 that are built for native Windows execution,
7235 such as the python.org and ActiveState versions,
7236 do not have the Cygwin path name semantics.
7237 This means that using a native Windows version of Python
7238 to build compiled programs using Cygwin tools
7239 (such as gcc, bison, and flex)
7240 may yield unpredictable results.
7241 "Mixing and matching" in this way
7242 can be made to work,
7243 but it requires careful attention to the use of path names
7244 in your SConscript files.
7246 In practice, users can sidestep
7247 the issue by adopting the following rules:
7249 use the Cygwin-supplied Python interpreter
7251 when using Microsoft Visual C/C++
7252 (or some other Windows compiler)
7253 use the python.org or ActiveState version of Python
7255 .SS WIN32: scons.bat file
7257 SCons is executed via a wrapper
7260 This has (at least) two ramifications:
7262 First, Windows command-line users
7263 that want to use variable assignment
7265 may have to put double quotes
7266 around the assignments:
7269 scons "FOO=BAR" "BAZ=BLEH"
7272 Second, the Cygwin shell does not
7273 recognize this file as being the same
7276 command issued at the command-line prompt.
7277 You can work around this either by
7280 from the Cygwin command line,
7281 or by creating a wrapper shell
7287 The MinGW bin directory must be in your PATH environment variable or the
7288 PATH variable under the ENV construction variable for SCons
7289 to detect and use the MinGW tools. When running under the native Windows
7290 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
7291 tools, if they are both installed, regardless of the order of the bin
7292 directories in the PATH variable. If you have both MSVC and MinGW
7293 installed and you want to use MinGW instead of MSVC,
7294 then you must explictly tell SCons to use MinGW by passing
7300 to the Environment() function, because SCons will prefer the MSVC tools
7301 over the MinGW tools.
7305 To help you get started using SCons,
7306 this section contains a brief overview of some common tasks.
7308 .SS Basic Compilation From a Single Source File
7312 env.Program(target = 'foo', source = 'foo.c')
7315 Note: Build the file by specifying
7316 the target as an argument
7317 ("scons foo" or "scons foo.exe").
7318 or by specifying a dot ("scons .").
7320 .SS Basic Compilation From Multiple Source Files
7324 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
7327 .SS Setting a Compilation Flag
7330 env = Environment(CCFLAGS = '-g')
7331 env.Program(target = 'foo', source = 'foo.c')
7334 .SS Search The Local Directory For .h Files
7338 need to set CCFLAGS to specify -I options by hand.
7339 SCons will construct the right -I options from CPPPATH.
7342 env = Environment(CPPPATH = ['.'])
7343 env.Program(target = 'foo', source = 'foo.c')
7346 .SS Search Multiple Directories For .h Files
7349 env = Environment(CPPPATH = ['include1', 'include2'])
7350 env.Program(target = 'foo', source = 'foo.c')
7353 .SS Building a Static Library
7357 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
7358 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
7361 .SS Building a Shared Library
7365 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
7366 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
7369 .SS Linking a Local Library Into a Program
7372 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
7373 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
7374 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
7377 .SS Defining Your Own Builder Object
7379 Notice that when you invoke the Builder,
7380 you can leave off the target file suffix,
7381 and SCons will add it automatically.
7384 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
7386 src_suffix = '.tex')
7387 env = Environment(BUILDERS = {'PDFBuilder' : bld})
7388 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
7390 # The following creates "bar.pdf" from "bar.tex"
7391 env.PDFBuilder(target = 'bar', source = 'bar')
7394 Note also that the above initialization
7395 overwrites the default Builder objects,
7396 so the Environment created above
7397 can not be used call Builders like env.Program(),
7398 env.Object(), env.StaticLibrary(), etc.
7400 .SS Adding Your Own Builder Object to an Environment
7403 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
7405 src_suffix = '.tex')
7407 env.Append(BUILDERS = {'PDFBuilder' : bld})
7408 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
7409 env.Program(target = 'bar', source = 'bar.c')
7412 You also can use other Pythonic techniques to add
7413 to the BUILDERS construction variable, such as:
7417 env['BUILDERS]['PDFBuilder'] = bld
7420 .SS Defining Your Own Scanner Object
7425 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
7427 def kfile_scan(node, env, path, arg):
7428 contents = node.get_contents()
7429 includes = include_re.findall(contents)
7432 kscan = Scanner(name = 'kfile',
7433 function = kfile_scan,
7436 scanners = Environment().Dictionary('SCANNERS')
7437 env = Environment(SCANNERS = scanners + [kscan])
7439 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
7441 bar_in = File('bar.in')
7442 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
7443 bar_in.target_scanner = kscan
7446 .SS Creating a Hierarchical Build
7448 Notice that the file names specified in a subdirectory's
7450 file are relative to that subdirectory.
7456 env.Program(target = 'foo', source = 'foo.c')
7458 SConscript('sub/SConscript')
7463 # Builds sub/foo from sub/foo.c
7464 env.Program(target = 'foo', source = 'foo.c')
7466 SConscript('dir/SConscript')
7471 # Builds sub/dir/foo from sub/dir/foo.c
7472 env.Program(target = 'foo', source = 'foo.c')
7475 .SS Sharing Variables Between SConscript Files
7477 You must explicitly Export() and Import() variables that
7478 you want to share between SConscript files.
7484 env.Program(target = 'foo', source = 'foo.c')
7487 SConscript('subdirectory/SConscript')
7489 subdirectory/SConscript:
7492 env.Program(target = 'foo', source = 'foo.c')
7495 .SS Building Multiple Variants From the Same Source
7497 Use the BuildDir() method to establish
7498 one or more separate build directories for
7499 a given source directory,
7500 then use the SConscript() method
7501 to specify the SConscript files
7502 in the build directories:
7509 BuildDir('foo', 'src')
7510 SConscript('foo/SConscript')
7514 BuildDir('bar', 'src')
7515 SConscript('bar/SConscript')
7520 env = Environment(CCFLAGS = ccflags)
7521 env.Program(target = 'src', source = 'src.c')
7524 Note the use of the Export() method
7525 to set the "ccflags" variable to a different
7526 value for each variant build.
7528 .SS Hierarchical Build of Two Libraries Linked With a Program
7533 env = Environment(LIBPATH = ['#libA', '#libB'])
7535 SConscript('libA/SConscript')
7536 SConscript('libB/SConscript')
7537 SConscript('Main/SConscript')
7542 env.Library('a', Split('a1.c a2.c a3.c'))
7547 env.Library('b', Split('b1.c b2.c b3.c'))
7552 e = env.Copy(LIBS = ['a', ','b'])
7553 e.Program('foo', Split('m1.c m2.c m3.c'))
7556 The '#' in the LIBPATH directories specify that they're relative to the
7557 top-level directory, so they don't turn into "Main/libA" when they're
7558 used in Main/SConscript.
7560 Specifying only 'a' and 'b' for the library names
7561 allows SCons to append the appropriate library
7562 prefix and suffix for the current platform
7563 (for example, 'liba.a' on POSIX systems,
7564 'a.lib' on Windows).
7566 .SS Customizing contruction variables from the command line.
7568 The following would allow the C compiler to be specified on the command
7569 line or in the file custom.py.
7572 opts = Options('custom.py')
7573 opts.Add('CC', 'The C compiler.')
7574 env = Environment(options=opts)
7575 Help(opts.GenerateHelpText(env))
7578 The user could specify the C compiler on the command line:
7584 or in the custom.py file:
7590 or get documentation on the options:
7601 .SS Using Microsoft Visual C++ precompiled headers
7603 Since windows.h includes everything and the kitchen sink, it can take quite
7604 some time to compile it over and over again for a bunch of object files, so
7605 Microsoft provides a mechanism to compile a set of headers once and then
7606 include the previously compiled headers in any object file. This
7607 technology is called precompiled headers. The general recipe is to create a
7608 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
7609 then include every header you want to precompile in "StdAfx.h", and finally
7610 include "StdAfx.h" as the first header in all the source files you are
7611 compiling to object files. For example:
7615 #include <windows.h>
7616 #include <my_big_header.h>
7635 /* do some other stuff */
7641 env['PCHSTOP'] = 'StdAfx.h'
7642 env['PCH'] = env.PCH('StdAfx.cpp')[0]
7643 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7646 For more information see the document for the PCH builder, and the PCH and
7647 PCHSTOP construction variables. To learn about the details of precompiled
7648 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
7650 .SS Using Microsoft Visual C++ external debugging information
7652 Since including debugging information in programs and shared libraries can
7653 cause their size to increase significantly, Microsoft provides a mechanism
7654 for including the debugging information in an external file called a PDB
7655 file. SCons supports PDB files through the PDB construction
7661 env['PDB'] = 'MyApp.pdb'
7662 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
7665 For more information see the document for the PDB construction variable.
7670 Specifies the directory that contains the SCons Python module directory
7671 (e.g. /home/aroach/scons-src-0.01/src/engine).
7674 A string of options that will be used by scons in addition to those passed
7675 on the command line.
7686 Steven Knight <knight@baldmt.com>
7688 Anthony Roach <aroach@electriceyeball.com>