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 "August 2004"
36 scons \- a software construction tool
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found.
65 An alternate file name may be
72 file can specify subsidiary
73 configuration files using the
77 these subsidiary files are named
79 although any name may be used.
80 (Because of this naming convention,
81 the term "SConscript files"
82 is sometimes used to refer
86 regardless of actual file name.)
88 The configuration files
89 specify the target files to be built, and
90 (optionally) the rules to build those targets. Reasonable default
91 rules exist for building common software components (executable
92 programs, object files, libraries), so that for most software
93 projects, only the target and input files need be specified.
96 reads and executes the SConscript files as Python scripts,
97 so you may use normal Python scripting capabilities
98 (such as flow control, data manipulation, and imported Python libraries)
99 to handle complicated build situations.
101 however, reads and executes all of the SConscript files
103 it begins building any targets.
104 To make this obvious,
106 prints the following messages about what it is doing:
110 scons: Reading SConscript files ...
111 scons: done reading SConscript files.
112 scons: Building targets ...
114 scons: done building targets.
119 (everything except the line that reads "cp foo.in foo.out")
120 may be suppressed using the
125 does not automatically propagate
126 the external environment used to execute
128 to the commands used to build target files.
129 This is so that builds will be guaranteed
130 repeatable regardless of the environment
131 variables set at the time
134 This also means that if the compiler or other commands
135 that you want to use to build your target files
136 are not in standard system locations,
138 will not find them unless
139 you explicitly set the PATH
140 to include those locations.
141 Whenever you create an
143 construction environment,
144 you can propagate the value of PATH
145 from your external environment as follows:
149 env = Environment(ENV = {'PATH' : os.environ['PATH']})
153 can scan known input files automatically for dependency
154 information (for example, #include statements
155 in C or C++ files) and will rebuild dependent files appropriately
156 whenever any "included" input file changes.
159 ability to define new scanners for unknown input file types.
162 knows how to fetch files automatically from
163 SCCS or RCS subdirectories
164 using SCCS, RCS or BitKeeper.
167 is normally executed in a top-level directory containing a
169 file, optionally specifying
170 as command-line arguments
171 the target file or files to be built.
173 By default, the command
179 will build all target files in or below the current directory.
180 Explicit default targets
181 (to be built when no targets are specified on the command line)
182 may be defined the SConscript file(s)
185 function, described below.
189 targets are specified in the SConscript file(s),
190 all target files in or below the current directory
191 may be built by explicitly specifying
192 the current directory (.)
193 as a command-line target:
199 Building all target files,
200 including any files outside of the current directory,
201 may be specified by supplying a command-line target
202 of the root directory (on POSIX systems):
208 or the path name(s) of the volume(s) in which all the targets
209 should be built (on Windows systems):
215 To build only specific targets,
216 supply them as command-line arguments:
222 in which case only the specified targets will be built
223 (along with any derived files on which they depend).
225 Specifying "cleanup" targets in SConscript files is not
228 flag removes all files
229 necessary to build the specified target:
235 to remove all target files, or:
238 scons -c build export
241 to remove target files under build and export.
242 Additional files or directories to remove can be specified using the
245 A subset of a hierarchical tree may be built by
246 remaining at the top-level directory (where the
248 file lives) and specifying the subdirectory as the target to be
255 or by changing directory and invoking scons with the
257 option, which traverses up the directory
258 hierarchy until it finds the
260 file, and then builds
261 targets relatively to the current subdirectory:
269 supports building multiple targets in parallel via a
271 option that takes, as its argument, the number
272 of simultaneous tasks that may be spawned:
278 builds four targets in parallel, for example.
281 can maintain a cache of target (derived) files that can
282 be shared between multiple builds. When caching is enabled in a
283 SConscript file, any target files built by
286 to the cache. If an up-to-date target file is found in the cache, it
287 will be retrieved from the cache instead of being rebuilt locally.
288 Caching behavior may be disabled and controlled in other ways by the
290 .BR --cache-disable ,
293 command-line options. The
295 option is useful to prevent multiple builds
296 from trying to update the cache simultaneously.
298 Values of variables to be passed to the SConscript file(s)
299 may be specified on the command line:
305 These variables are available in SConscript files
306 through the ARGUMENTS dictionary,
307 and can be used in the SConscript file(s) to modify
308 the build in any way:
311 if ARGUMENTS.get('debug', 0):
312 env = Environment(CCFLAGS = '-g')
317 The command-line variable arguments are also available
319 indexed by their order on the command line.
320 This allows you to process them in order rather than by name,
322 ARGLIST[0] returns a tuple
323 containing (argname, argvalue).
324 A Python exception is thrown if you
325 try to access a list member that
329 requires Python version 1.5.2 or later.
330 There should be no other dependencies or requirements to run
333 .\" The following paragraph reflects the default tool search orders
334 .\" currently in SCons/Tool/__init__.py. If any of those search orders
335 .\" change, this documentation should change, too.
338 knows how to search for available programming tools
342 searches in order for the
343 Microsoft Visual C++ tools,
344 the MinGW tool chain,
345 the Intel compiler tools,
346 and the PharLap ETS compiler.
349 searches in order for the
352 and the Microsoft Visual C++ tools,
353 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
355 searches for the native compiler tools
356 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
357 and the GCC tool chain.
358 On all other platforms,
359 including POSIX (Linux and UNIX) platforms,
362 for the GCC tool chain,
363 the Microsoft Visual C++ tools,
364 and the Intel compiler tools.
365 You may, of course, override these default values
366 by appropriate configuration of
367 Environment construction variables.
372 supports the same command-line options as GNU
374 and many of those supported by
379 Ignored for compatibility with non-GNU versions of
383 -c, --clean, --remove
384 Clean up by removing all target files for which a construction
385 command is specified.
386 Also remove any files or directories associated to the construction command
387 using the Clean() function.
390 --cache-disable, --no-cache
391 Disable the derived-file caching specified by
394 will neither retrieve files from the cache
395 nor copy files to the cache.
398 --cache-force, --cache-populate
401 populate a cache by copying any already-existing, up-to-date
402 derived files to the cache,
403 in addition to files built by this invocation.
404 This is useful to populate a new cache with
405 all the current derived files,
406 or to add to the cache any derived files
407 recently built with caching disabled via the
415 and retrieving a derived file from the cache,
417 that would have been executed to build the file,
418 instead of the usual report,
419 "Retrieved `file' from cache."
420 This will produce consistent output for build logs,
421 regardless of whether a target
422 file was rebuilt or retrieved from the cache.
425 .RI "-C" " directory" ", --directory=" directory
426 Change to the specified
428 before searching for the
433 file, or doing anything
436 options are interpreted
437 relative to the previous one, and the right-most
439 option wins. (This option is nearly
441 .BR "-f directory/SConstruct" ,
442 except that it will search for
447 in the specified directory.)
451 .\" Display dependencies while building target files. Useful for
452 .\" figuring out why a specific file is being rebuilt, as well as
453 .\" general debugging of the build process.
457 Works exactly the same way as the
459 option except for the way default targets are handled.
460 When this option is used and no targets are specified on the command line,
461 all default targets are built, whether or not they are below the current
466 Debug the build process.
468 specifies what type of debugging:
472 Print a count of how many objects are created
473 of the various classes used internally by SCons.
474 This only works when run under Python 2.1 or later.
478 Print the dependency tree
479 after each top-level target is built. This prints out only derived files.
483 Print the include tree after each top-level target is built.
484 This is generally used to find out what files are included by the sources
485 of a given derived file:
488 $ scons --debug=includes foo.o
493 Prints how much memory SCons uses
494 before and after reading the SConscript files
495 and before and after building.
499 Prints a list of the various objects
500 of the various classes used internally by SCons.
501 This only works when run under Python 2.1 or later.
505 Re-run SCons under the control of the
512 Print the raw command line used to build each target
513 before the construction environment variables are substituted.
514 Also shows which targets are being built by this command.
515 Output looks something like this:
517 $ scons --debug=presub
518 Building myprog.o with action(s):
519 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
525 Prints various time profiling information: the time spent
526 executing each build command, the total build time, the total time spent
527 executing build commands, the total time spent executing SConstruct and
528 SConscript files, and the total time spent executing SCons itself.
532 Print the dependency tree
533 after each top-level target is built. This prints out the complete
534 dependency tree including implicit dependencies and ignored
538 .\" -e, --environment-overrides
539 .\" Variables from the execution environment override construction
540 .\" variables from the SConscript files.
543 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
546 as the initial SConscript file.
550 Print a local help message for this build, if one is defined in
551 the SConscript file(s), plus a line that describes the
553 option for command-line option help. If no local help message
554 is defined, prints the standard help message about command-line
555 options. Exits after displaying the appropriate message.
559 Print the standard help message about command-line options and
564 Ignore all errors from commands executed to rebuild files.
567 .RI -I " directory" ", --include-dir=" directory
571 imported Python modules. If several
574 are used, the directories are searched in the order specified.
578 Cache implicit dependencies. This can cause
580 to miss changes in the implicit dependencies in cases where a new implicit
581 dependency is added earlier in the implicit dependency search path
582 (e.g. CPPPATH) than a current implicit dependency with the same name.
585 --implicit-deps-changed
586 Force SCons to ignore the cached implicit dependencies. This causes the
587 implicit dependencies to be rescanned and recached. This implies
588 .BR --implicit-cache .
591 --implicit-deps-unchanged
592 Force SCons to ignore changes in the implicit dependencies.
593 This causes cached implicit dependencies to always be used.
595 .BR --implicit-cache .
598 .RI -j " N" ", --jobs=" N
599 Specifies the number of jobs (commands) to run simultaneously.
600 If there is more than one
602 option, the last one is effective.
606 .\" is specified without an argument,
608 .\" will not limit the number of
609 .\" simultaneous jobs.
613 Continue as much as possible after an error. The target that
614 failed and those that depend on it will not be remade, but other
615 targets specified on the command line will still be processed.
618 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
619 .\" No new jobs (commands) will be started if
620 .\" there are other jobs running and the system load
621 .\" average is at least
623 .\" (a floating-point number).
626 .RI --duplicate= ORDER
627 There are three ways to duplicate files in a build tree: hard links,
628 soft (symbolic) links and copies. The default behaviour of SCons is to
629 prefer hard links to soft links to copies. You can specify different
630 behaviours with this option.
640 SCons will attempt to duplicate files using
641 the mechanisms in the specified order.
646 .\" List derived files (targets, dependencies) that would be built,
647 .\" but do not build them.
648 .\" [XXX This can probably go away with the right
649 .\" combination of other options. Revisit this issue.]
653 .\" List derived files that would be built, with the actions
654 .\" (commands) that build them. Does not build the files.
655 .\" [XXX This can probably go away with the right
656 .\" combination of other options. Revisit this issue.]
660 .\" List derived files that would be built, plus where the file is
661 .\" defined (file name and line number). Does not build the files.
662 .\" [XXX This can probably go away with the right
663 .\" combination of other options. Revisit this issue.]
667 Ignored for compatibility with non-GNU versions of
671 .RI --max-drift= SECONDS
672 Set the maximum expected drift in the modification time of files to
674 This value determines how old a file must be before its content signature
675 is cached. The default value is 2 days, which means a file must have a
676 modification time of at least two days ago in order to have its content
677 signature cached. A negative value means to never cache the content
678 signature and to ignore the cached value if there already is one. A value
679 of 0 means to always cache the signature, no matter how old the file is.
682 -n, --just-print, --dry-run, --recon
683 No execute. Print the commands that would be executed to build
684 any out-of-date target files, but do not execute the commands.
687 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
691 .\" not rebuild anything due to changes in the contents of
694 .\" .RI --override " file"
695 .\" Read values to override specific build environment variables
696 .\" from the specified
700 .\" Print the data base (construction environments,
701 .\" Builder and Scanner objects) that are defined
702 .\" after reading the SConscript files.
703 .\" After printing, a normal build is performed
704 .\" as usual, as specified by other command-line options.
705 .\" This also prints version information
710 .\" To print the database without performing a build do:
718 Run SCons under the Python profiler
719 and save the results in the specified
721 The results may be analyzed using the Python
725 Do not run any commands, or print anything. Just return an exit
726 status that is zero if the specified targets are already up to
727 date, non-zero otherwise.
730 Quiets SCons status messages about
731 reading SConscript files,
733 and entering directories.
734 Commands that are executed
735 to rebuild target files are still printed.
738 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
739 .\" Clear the default construction variables. Construction
740 .\" environments that are created will be completely empty.
744 Build dependencies in a random order. This is useful when
745 building multiple trees simultaneously with caching enabled,
746 to prevent multiple builds from simultaneously trying to build
747 or retrieve the same target files.
750 -s, --silent, --quiet
751 Silent. Do not print commands that are executed to rebuild
753 Also suppresses SCons status messages.
756 -S, --no-keep-going, --stop
757 Ignored for compatibility with GNU
761 .RI --save-explain-info= 0|1
763 scons will save additional information about the build
768 .B --save-explain-info=0
769 will tell scons to speed up the build
770 by not saving this information.
774 Ignored for compatibility with GNU
776 (Touching a file to make it
777 appear up-to-date is unnecessary when using
781 -u, --up, --search-up
782 Walks up the directory structure until an
787 file is found, and uses that
788 as the top of the directory tree.
789 If no targets are specified on the command line,
790 only targets at or below the
791 current directory will be built.
795 Works exactly the same way as the
797 option except for the way default targets are handled.
798 When this option is used and no targets are specified on the command line,
799 all default targets that are defined in the SConscript(s) in the current
800 directory are built, regardless of what directory the resultant targets end
807 version, copyright information,
808 list of authors, and any other relevant information.
812 -w, --print-directory
813 Print a message containing the working directory before and
814 after other processing.
817 .RI --warn= type ", --warn=no-" type
818 Enable or disable warnings.
820 specifies the type of warnings to be enabled or disabled:
823 --warn=all, --warn=no-all
824 Enables or disables all warnings.
827 --warn=dependency, --warn=no-dependency
828 Enables or disables warnings about dependencies.
829 These warnings are disabled by default.
832 --warn=deprecated, --warn=no-deprecated
833 Enables or disables warnings about use of deprecated features.
834 These warnings are enabled by default.
837 --warn=missing-sconscript, --warn=no-missing-sconscript
838 Enables or disables warnings about missing SConscript files.
839 These warnings are enabled by default.
843 Turn off -w, even if it was turned on implicitly.
846 .\" .RI --write-filenames= file
847 .\" Write all filenames considered into
851 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
852 .\" Pretend that the target
855 .\" modified. When used with the
858 .\" show you what would be rebuilt if you were to modify that file.
864 .\" --warn-undefined-variables
865 .\" Warn when an undefined variable is referenced.
868 .RI -Y " repository" ", --repository=" repository
869 Search the specified repository for any input and target
870 files not found in the local directory hierarchy. Multiple
872 options may specified, in which case the
873 repositories are searched in the order specified.
875 .SH CONFIGURATION FILE REFERENCE
876 .\" .SS Python Basics
877 .\" XXX Adding this in the future would be a help.
878 .SS Construction Environments
879 A construction environment is the basic means by which the SConscript
880 files communicate build information to
882 A new construction environment is created using the
890 By default, a new construction environment is
891 initialized with a set of builder methods
892 and construction variables that are appropriate
893 for the current platform.
894 An optional platform keyword argument may be
895 used to specify that an environment should
896 be initialized for a different platform:
899 env = Environment(platform = 'cygwin')
900 env = Environment(platform = 'os2')
901 env = Environment(platform = 'posix')
902 env = Environment(platform = 'win32')
905 Specifying a platform initializes the appropriate
906 construction variables in the environment
907 to use and generate file names with prefixes
908 and suffixes appropriate for the platform.
914 variable from the user's external environment
915 to the construction environment's
918 This is so that any executed commands
919 that use sockets to connect with other systems
920 (such as fetching source files from
921 external CVS repository specifications like
922 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
923 will work on Win32 systems.
925 The platform argument may be function or callable object,
926 in which case the Environment() method
927 will call the specified argument to update
928 the new construction environment:
931 def my_platform(env):
934 env = Environment(platform = my_platform)
937 Additionally, a specific set of tools
938 with which to initialize the environment
939 may specified as an optional keyword argument:
942 env = Environment(tools = ['msvc', 'lex'])
945 Non-built-in tools may be specified using the toolpath argument:
948 env = Environment(tools = ['foo'], toolpath = ['tools'])
951 This looks for a tool specification in tools/foo.py. foo.py should
952 have two functions: generate(env) and exists(env). generate()
953 modifies the passed in environment and exists() should return a true
954 value if the tool is available. Tools in the toolpath are used before
955 any of the built-in ones. For example, adding gcc.py to the toolpath
956 would override the built-in gcc tool.
958 The elements of the tools list may also
959 be functions or callable objects,
960 in which case the Environment() method
961 will call the specified elements
962 to update the new construction environment:
966 env['XYZZY'] = 'xyzzy'
968 env = Environment(tools = [my_tool])
971 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
972 the environment it receives to customize the tool for different platforms.
974 If no tool list is specified, then SCons will auto-detect the installed
975 tools using the PATH variable in the ENV construction variable and the
976 platform name when the Environment is constructed. Changing the PATH
977 variable after the Environment is constructed will not cause the tools to
980 SCons supports the following tool specifications out of the box:
1052 Additionally, there is a "tool" named
1054 which configures the
1055 environment with a default set of tools for the current platform.
1057 On posix and cygwin platforms
1058 the GNU tools (e.g. gcc) are preferred by SCons,
1059 on win32 the Microsoft tools (e.g. msvc)
1060 followed by MinGW are preferred by SCons,
1061 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1065 Build rules are specified by calling a construction
1066 environment's builder methods.
1067 The arguments to the builder methods are
1069 (a list of target files)
1072 (a list of source files).
1074 Because long lists of file names
1075 can lead to a lot of quoting,
1080 and a same-named environment method
1081 that split a single string
1082 into a list, separated on
1083 strings of white-space characters.
1084 (These are similar to the
1085 string.split() method
1086 from the standard Python library,
1087 but work even if the input isn't a string.)
1089 Like all Python arguments,
1090 the target and source arguments to a builder method
1091 can be specified either with or without
1092 the "target" and "source" keywords.
1093 When the keywords are omitted,
1094 the target is first,
1095 followed by the source.
1096 The following are equivalent examples of calling the Program builder method:
1099 env.Program('bar', ['bar.c', 'foo.c'])
1100 env.Program('bar', Split('bar.c foo.c'))
1101 env.Program('bar', env.Split('bar.c foo.c'))
1102 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1103 env.Program(target = 'bar', Split('bar.c foo.c'))
1104 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1105 env.Program('bar', source = string.split('bar.c foo.c'))
1108 When the target shares the same base name
1109 as the source and only the suffix varies,
1110 and if the builder method has a suffix defined for the target file type,
1111 then the target argument may be omitted completely,
1114 will deduce the target file name from
1115 the source file name.
1116 The following examples all build the
1122 (on Windows systems)
1123 from the bar.c source file:
1126 env.Program(target = 'bar', source = 'bar.c')
1127 env.Program('bar', source = 'bar.c')
1128 env.Program(source = 'bar.c')
1129 env.Program('bar.c')
1132 It is possible to override or add construction variables when calling a
1133 builder method by passing additional keyword arguments.
1134 These overridden or added
1135 variables will only be in effect when building the target, so they will not
1136 affect other parts of the build. For example, if you want to add additional
1137 libraries for just one program:
1140 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1143 or generate a shared library with a nonstandard suffix:
1146 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1149 Although the builder methods defined by
1152 methods of a construction environment object,
1153 they may also be called without an explicit environment:
1156 Program('hello', 'hello.c')
1157 SharedLibrary('word', 'word.cpp')
1161 the methods are called internally using a default construction
1162 environment that consists of the tools and values that
1164 has determined are appropriate for the local system.
1166 All builder methods return a Node or a list of Nodes,
1167 representing the target or targets that will be built.
1168 A list of Nodes is returned if there is more than one target,
1169 and a single Node is returned if there is only one target.
1172 is an internal SCons object
1174 build targets or sources.
1176 The returned Node(s)
1177 can be passed to other builder methods as source(s)
1178 or passed to any SCons function or method
1179 where a filename would normally be accepted.
1180 For example, if it were necessary
1183 flag when compiling one specific object file:
1186 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1187 env.Program(source = ['foo.c', bar_obj, 'main.c'])
1190 Using a Node in this way
1191 makes for a more portable build
1192 by avoiding having to specify
1193 a platform-specific object suffix
1194 when calling the Program() builder method.
1196 The path name for a Node's file may be used
1197 by passing the Node to the Python-builtin
1202 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1203 print "The path to bar_obj is:", str(bar_obj)
1207 provides the following builder methods:
1209 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1212 Builds a C source file given a lex (.l) or yacc (.y) input file.
1213 The suffix specified by the $CFILESUFFIX construction variable
1215 is automatically added to the target
1216 if it is not already present. Example:
1220 env.CFile(target = 'foo.c', source = 'foo.l')
1222 env.CFile(target = 'bar', source = 'bar.y')
1225 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1228 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1230 The suffix specified by the $CXXFILESUFFIX construction variable
1232 is automatically added to the target
1233 if it is not already present. Example:
1237 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1239 env.CXXFile(target = 'bar', source = 'bar.yy')
1242 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1245 Builds a .dvi file from a .tex, .ltx or .latex input file.
1246 If the source file suffix is .tex,
1248 will examine the contents of the file;
1253 is found, the file is assumed to be a LaTeX file and
1254 the target is built by invoking the $LATEXCOM command line;
1255 otherwise, the $TEXCOM command line is used.
1256 If the file is a LaTeX file,
1259 builder method will also examine the contents
1262 and invoke the $BIBTEX command line
1266 and will examine the contents
1268 file and re-run the $LATEXCOM command
1269 if the log file says it is necessary.
1272 (hard-coded within TeX itself)
1273 is automatically added to the target
1274 if it is not already present. Examples:
1277 # builds from aaa.tex
1278 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1280 env.DVI(target = 'bbb', source = 'bbb.ltx')
1281 # builds from ccc.latex
1282 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1285 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1288 Builds a Java archive (.jar) file
1289 from a source tree of .class files.
1290 If the $JARCHDIR value is set, the
1292 command will change to the specified directory using the
1295 If the contents any of the source files begin with the string
1296 .BR Manifest-Version ,
1297 the file is assumed to be a manifest
1298 and is passed to the
1305 env.Jar(target = 'foo.jar', source = 'classes')
1308 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1311 Builds one or more Java class files
1312 from one or more source trees of .java files.
1313 The class files will be placed underneath
1314 the specified target directory.
1315 SCons will parse each source .java file
1317 (including inner classes)
1318 defined within that file,
1319 and from that figure out the
1320 target .class files that will be created.
1321 SCons will also search each Java file
1322 for the Java package name,
1323 which it assumes can be found on a line
1324 beginning with the string
1326 in the first column;
1327 the resulting .class files
1328 will be placed in a directory reflecting
1329 the specified package name.
1333 defining a single public
1336 containing a package name of
1338 will generate a corresponding
1339 .IR sub/dir/Foo.class
1345 env.Java(target = 'classes', source = 'src')
1346 env.Java(target = 'classes', source = ['src1', 'src2'])
1349 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1352 Builds C header and source files for
1353 implementing Java native methods.
1354 The target can be either a directory
1355 in which the header files will be written,
1356 or a header file name which
1357 will contain all of the definitions.
1358 The source can be either the names of .class files,
1359 or the objects returned from the
1363 If the construction variable
1365 is set, either in the environment
1366 or in the call to the
1368 builder method itself,
1369 then the value of the variable
1370 will be stripped from the
1371 beginning of any .class file names.
1376 # builds java_native.h
1377 classes = env.Java(target = 'classdir', source = 'src')
1378 env.JavaH(target = 'java_native.h', source = classes)
1380 # builds include/package_foo.h and include/package_bar.h
1381 env.JavaH(target = 'include',
1382 source = ['package/foo.class', 'package/bar.class'])
1384 # builds export/foo.h and export/bar.h
1385 env.JavaH(target = 'export',
1386 source = ['classes/foo.class', 'classes/bar.class'],
1387 JAVACLASSDIR = 'classes')
1390 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1397 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1400 Builds an output file from an M4 input file.
1401 This uses a default $M4FLAGS value of
1403 which considers all warnings to be fatal
1404 and stops on the first warning
1405 when using the GNU version of m4.
1409 env.M4(target = 'foo.c', source = 'foo.c.m4')
1412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1415 Builds an output file from a moc input file. Moc input files are either
1416 header files or cxx files. This builder is only available after using the
1417 tool 'qt'. See the QTDIR variable for more information.
1421 env.Moc('foo.h') # generates moc_foo.cc
1422 env.Moc('foo.cpp') # generates foo.moc
1425 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1427 .IP env.MSVSProject()
1428 Builds Microsoft Visual Studio project files.
1429 This builds a Visual Studio project file, based on the version of
1430 Visual Studio that is configured (either the latest installed version,
1431 or the version set by
1433 in the Environment constructor).
1434 For VS 6, it will generate
1438 files, for VS 7, it will
1445 It takes several lists of filenames to be placed into the project
1446 file, currently these are limited to
1447 .B srcs, incs, localincs, resources,
1450 These are pretty self explanatory, but it
1451 should be noted that the 'srcs' list is NOT added to the $SOURCES
1452 environment variable. This is because it represents a list of files
1453 to be added to the project file, not the source used to build the
1454 project file (in this case, the 'source' is the SConscript file used
1455 to call MSVSProject).
1457 In addition to these values (which are all optional, although not
1458 specifying any of them results in an empty project file), the
1459 following values must be specified:
1461 target: The name of the target .dsp or .vcproj file. The correct
1462 suffix for the version of Visual Studio must be used, but the value
1464 env['MSVSPROJECTSUFFIX']
1466 will be defined to the correct value (see example below).
1468 variant: The name of this particular variant. These are typically
1469 things like "Debug" or "Release", but really can be anything you want.
1470 Multiple calls to MSVSProject with different variants are allowed: all
1471 variants will be added to the project file with their appropriate
1472 build targets and sources.
1474 buildtarget: A list of SCons.Node.FS objects which is returned from
1475 the command which builds the target. This is used to tell SCons what
1476 to build when the 'build' button is pressed inside of the IDE.
1481 barsrcs = ['bar.cpp'],
1482 barincs = ['bar.h'],
1483 barlocalincs = ['StdAfx.h']
1484 barresources = ['bar.rc','resource.h']
1485 barmisc = ['bar_readme.txt']
1487 dll = local.SharedLibrary(target = 'bar.dll',
1490 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1493 localincs = barlocalincs,
1494 resources = barresources,
1497 variant = 'Release')
1500 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1507 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1510 Builds a Microsoft Visual C++ precompiled header.
1511 Calling this builder method
1512 returns a list of two targets: the PCH as the first element, and the object
1513 file as the second element. Normally the object file is ignored.
1514 This builder method is only
1515 provided when Microsoft Visual C++ is being used as the compiler.
1516 The PCH builder method is generally used in
1517 conjuction with the PCH construction variable to force object files to use
1518 the precompiled header:
1521 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1524 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1527 Builds a .pdf file from a .dvi input file
1528 (or, by extension, a .tex, .ltx, or .latex input file).
1529 The suffix specified by the $PDFSUFFIX construction variable
1531 is added automatically to the target
1532 if it is not already present. Example:
1535 # builds from aaa.tex
1536 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1537 # builds bbb.pdf from bbb.dvi
1538 env.PDF(target = 'bbb', source = 'bbb.dvi')
1541 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1543 .IP env.PostScript()
1544 Builds a .ps file from a .dvi input file
1545 (or, by extension, a .tex, .ltx, or .latex input file).
1546 The suffix specified by the $PSSUFFIX construction variable
1548 is added automatically to the target
1549 if it is not already present. Example:
1552 # builds from aaa.tex
1553 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1554 # builds bbb.ps from bbb.dvi
1555 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1558 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1561 Builds an executable given one or more object files
1562 or C, C++, D, or Fortran source files.
1563 If any C, C++, D or Fortran source files are specified,
1564 then they will be automatically
1565 compiled to object files using the
1568 see that builder method's description for
1569 a list of legal source file suffixes
1570 and how they are interpreted.
1571 The target executable file prefix
1572 (specified by the $PROGPREFIX construction variable; nothing by default)
1574 (specified by the $PROGSUFFIX construction variable;
1575 by default, .exe on Windows systems, nothing on POSIX systems)
1576 are automatically added to the target if not already present.
1580 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1586 Builds a Microsoft Visual C++ resource file.
1587 This builder method is only provided
1588 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1592 for MinGW) suffix is added to the target name if no other suffix is given. The source
1593 file is scanned for implicit dependencies as though it were a C file. Example:
1596 env.RES('resource.rc')
1599 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1602 Builds stub and skeleton class files
1604 from Java .class files.
1605 The target is a directory
1606 relative to which the stub
1607 and skeleton class files will be written.
1608 The source can be the names of .class files,
1609 or the objects return from the
1613 If the construction variable
1615 is set, either in the environment
1616 or in the call to the
1618 builder method itself,
1619 then the value of the variable
1620 will be stripped from the
1621 beginning of any .class file names.
1624 classes = env.Java(target = 'classdir', source = 'src')
1625 env.RMIC(target = 'outdir1', source = classes)
1627 env.RMIC(target = 'outdir2',
1628 source = ['package/foo.class', 'package/bar.class'])
1630 env.RMIC(target = 'outdir3',
1631 source = ['classes/foo.class', 'classes/bar.class'],
1632 JAVACLASSDIR = 'classes')
1635 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1637 .IP env.SharedLibrary()
1638 Builds a shared library
1639 (.so on a POSIX system, .dll on WIN32)
1640 given one or more object files
1641 or C, C++, D or Fortran source files.
1642 If any source files are given,
1643 then they will be automatically
1644 compiled to object files.
1645 The static library prefix and suffix (if any)
1646 are automatically added to the target.
1647 The target library file prefix
1648 (specified by the $SHLIBPREFIX construction variable;
1649 by default, lib on POSIX systems, nothing on Windows systems)
1651 (specified by the $SHLIBSUFFIX construction variable;
1652 by default, .dll on Windows systems, .so on POSIX systems)
1653 are automatically added to the target if not already present.
1657 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1660 On WIN32 systems, the
1662 builder method will always build an import (.lib) library
1663 in addition to the shared (.dll) library,
1664 adding a .lib library with the same basename
1665 if there is not already a .lib file explicitly
1666 listed in the targets.
1668 Any object files listed in the
1670 must have been built for a shared library
1675 will raise an error if there is any mismatch.
1677 On WIN32 systems, specifying "register=1" will cause the dll to be
1678 registered after it is built using REGSVR32. The command that is run
1679 ("regsvr32" by default) is determined by $REGSVR construction
1680 variable, and the flags passed are determined by $REGSVRFLAGS. By
1681 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1682 up and requiring user attention when it is run. If you change
1683 $REGSVRFLAGS, be sure to include "/s". For example,
1686 env.SharedLibrary(target = 'bar',
1687 source = ['bar.cxx', 'foo.obj'],
1692 will register "bar.dll" as a COM object when it is done linking it.
1694 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1696 .IP env.SharedObject()
1697 Builds an object file for
1698 inclusion in a shared library.
1699 Source files must have one of the same set of extensions
1700 specified above for the
1703 On some platforms building a shared object requires additional
1704 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1705 normal (static) object, but on some platforms there is no difference between a
1706 shared object and a normal (static) one. When there is a difference, SCons
1707 will only allow shared objects to be linked into a shared library, and will
1708 use a different suffix for shared objects. On platforms where there is no
1709 difference, SCons will allow both normal (static)
1710 and shared objects to be linked into a
1711 shared library, and will use the same suffix for shared and normal
1713 The target object file prefix
1714 (specified by the $SHOBJPREFIX construction variable;
1715 by default, the same as $OBJPREFIX)
1717 (specified by the $SHOBJSUFFIX construction variable)
1718 are automatically added to the target if not already present.
1722 env.SharedObject(target = 'ddd', source = 'ddd.c')
1723 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1724 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1727 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1729 .IP env.StaticLibrary()
1730 Builds a static library given one or more object files
1731 or C, C++, D or Fortran source files.
1732 If any source files are given,
1733 then they will be automatically
1734 compiled to object files.
1735 The static library prefix and suffix (if any)
1736 are automatically added to the target.
1737 The target library file prefix
1738 (specified by the $LIBPREFIX construction variable;
1739 by default, lib on POSIX systems, nothing on Windows systems)
1741 (specified by the $LIBSUFFIX construction variable;
1742 by default, .lib on Windows systems, .a on POSIX systems)
1743 are automatically added to the target if not already present.
1747 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1751 Any object files listed in the
1753 must have been built for a static library
1758 will raise an error if there is any mismatch.
1760 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1762 .IP env.StaticObject()
1763 Builds a static object file
1764 from one or more C, C++, D, or Fortran source files.
1765 Source files must have one of the following extensions:
1768 .asm assembly language file
1769 .ASM assembly language file
1781 .F WIN32: Fortran file
1782 POSIX: Fortran file + C pre-processor
1785 .fpp Fortran file + C pre-processor
1786 .FPP Fortran file + C pre-processor
1787 .s assembly language file
1788 .S WIN32: assembly language file
1789 POSIX: assembly language file + C pre-processor
1790 .spp assembly language file + C pre-processor
1791 .SPP assembly language file + C pre-processor
1794 The target object file prefix
1795 (specified by the $OBJPREFIX construction variable; nothing by default)
1797 (specified by the $OBJSUFFIX construction variable;
1798 \.obj on Windows systems, .o on POSIX systems)
1799 are automatically added to the target if not already present.
1803 env.StaticObject(target = 'aaa', source = 'aaa.c')
1804 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1805 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1808 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1811 Builds a tar archive of the specified files
1813 Unlike most builder methods,
1816 builder method may be called multiple times
1818 each additional call
1819 adds to the list of entries
1820 that will be built into the archive.
1823 env.Tar('src.tar', 'src')
1825 # Create the stuff.tar file.
1826 env.Tar('stuff', ['subdir1', 'subdir2'])
1827 # Also add "another" to the stuff.tar file.
1828 env.Tar('stuff', 'another')
1830 # Set TARFLAGS to create a gzip-filtered archive.
1831 env = Environment(TARFLAGS = '-c -z')
1832 env.Tar('foo.tar.gz', 'foo')
1834 # Also set the suffix to .tgz.
1835 env = Environment(TARFLAGS = '-c -z',
1840 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1842 .IP env.TypeLibrary()
1843 Builds a Windows type library (.tlb) file from and input IDL file
1844 (.idl). In addition, it will build the associated inteface stub and
1845 proxy source files. It names them according to the base name of the .idl file.
1850 env.TypeLibrary(source="foo.idl")
1853 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1855 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1858 Builds a header file, an implementation file and a moc file from an ui file.
1859 and returns the corresponding nodes in the above order.
1860 This builder is only available after using the tool 'qt'. Note: you can
1861 specify .ui files directly as inputs for Program, Library and SharedLibrary
1862 without using this builder. Using the builder lets you override the standard
1863 naming conventions (be careful: prefixes are always prepended to names of
1864 built files; if you don't want prefixes, you may set them to ``).
1865 See the QTDIR variable for more information.
1869 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
1870 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
1871 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
1874 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1877 Builds a zip archive of the specified files
1879 Unlike most builder methods,
1882 builder method may be called multiple times
1884 each additional call
1885 adds to the list of entries
1886 that will be built into the archive.
1889 env.Zip('src.zip', 'src')
1891 # Create the stuff.zip file.
1892 env.Zip('stuff', ['subdir1', 'subdir2'])
1893 # Also add "another" to the stuff.tar file.
1894 env.Zip('stuff', 'another')
1899 C source files, C++ source files,
1900 Fortran source files with
1902 (POSIX systems only),
1907 and assembly language files with
1909 (POSIX systems only),
1914 for C preprocessor dependencies,
1915 so the dependencies do not need to be specified explicitly.
1917 targets of builder methods automatically depend on their sources.
1918 An explicit dependency can
1919 be specified using the
1921 method of a construction environment (see below).
1923 .SS Methods and Functions to Do Things
1924 In addition to Builder methods,
1926 provides a number of other construction environment methods
1927 and global functions to
1928 manipulate the build configuration.
1930 Usually, a construction environment method
1931 and global function with the same name both exist
1932 so that you don't have to remember whether
1933 to a specific bit of functionality
1934 must be called with or without a construction environment.
1935 In the following list,
1936 if you call something as a global function
1939 .RI Function( arguments )
1941 and if you call something through a construction
1942 environment it looks like:
1944 .RI env.Function( arguments )
1946 If you can call the functionality in both ways,
1947 then both forms are listed.
1949 Except where otherwise noted,
1951 construction environment method
1953 provide the exact same functionality.
1954 The only difference is that,
1956 calling the functionality through a construction environment will
1957 substitute construction variables into
1958 any supplied strings.
1961 env = Environment(FOO = 'foo')
1965 the first call to the global
1967 function will actually add a target named
1969 to the list of default targets,
1970 while the second call to the
1972 construction environment method
1973 will expand the value
1974 and add a target named
1976 to the list of default targets.
1977 For more on construction variable expansion,
1978 see the next section on
1979 construction variables.
1981 Construction environment methods
1982 and global functions supported by
1986 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1988 .RI Action( action ", [" strfunction ", " varlist ])
1990 .RI env.Action( action ", [" strfunction ", " varlist ])
1991 Creates an Action object for
1994 See the section "Action Objects,"
1995 below, for a complete explanation of the arguments and behavior.
1997 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1999 .RI AddPostAction( target ", " action )
2001 .RI env.AddPostAction( target ", " action )
2002 Arranges for the specified
2008 The specified action(s) may be
2009 an Action object, or anything that
2010 can be converted into an Action object
2013 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2015 .RI AddPreAction( target ", " action )
2017 .RI env.AddPreAction( target ", " action )
2018 Arranges for the specified
2021 before the specified
2024 The specified action(s) may be
2025 an Action object, or anything that
2026 can be converted into an Action object
2029 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2031 .RI Alias( alias ", [" targets ])
2033 .RI env.Alias( alias ", [" targets ])
2034 Creates one or more phony targets that
2035 expand to one or more other targets.
2036 Returns the Node object representing the alias,
2037 which exists outside of any file system.
2038 This Node object, or the alias name,
2039 may be used as a dependency of any other target,
2040 including another alias.
2042 can be called multiple times for the same
2043 alias to add additional targets to the alias.
2047 Alias('install', '/usr/bin')
2048 Alias(['install', 'install-lib'], '/usr/local/lib')
2050 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2051 env.Alias('install', ['/usr/local/man'])
2054 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2056 .RI AlwaysBuild( target ", ...)"
2058 .RI env.AlwaysBuild( target ", ...)"
2061 so that it is always assumed to be out of date,
2062 and will always be rebuilt if needed.
2065 does not add its target(s) to the default target list,
2066 so the targets will only be built
2067 if they are specified on the command line,
2068 or are a dependent of a target specified on the command line--but
2071 be built if so specified.
2072 Multiple targets can be passed in to a single call to
2075 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2077 .RI env.Append( key = val ", [...])"
2078 Appends the specified keyword arguments
2079 to the end of construction variables in the environment.
2080 If the Environment does not have
2081 the specified construction variable,
2082 it is simply added to the environment.
2083 If the values of the construction variable
2084 and the keyword argument are the same type,
2085 then the two values will be simply added together.
2086 Otherwise, the construction variable
2087 and the value of the keyword argument
2088 are both coerced to lists,
2089 and the lists are added together.
2090 (See also the Prepend method, below.)
2093 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2098 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2099 This appends new path elements to the given path in the
2100 specified external environment
2104 any particular path once (leaving the last one it encounters and
2105 ignoring the rest, to preserve path order),
2106 and to help assure this,
2107 will normalize all paths (using
2110 .BR os.path.normcase ).
2111 This can also handle the
2112 case where the given old path variable is a list instead of a
2113 string, in which case a list will be returned instead of a string.
2117 print 'before:',env['ENV']['INCLUDE']
2118 include_path = '/foo/bar:/foo'
2119 env.PrependENVPath('INCLUDE', include_path)
2120 print 'after:',env['ENV']['INCLUDE']
2124 after: /biz:/foo/bar:/foo
2127 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2129 .RI env.AppendUnique( key = val ", [...])"
2130 Appends the specified keyword arguments
2131 to the end of construction variables in the environment.
2132 If the Environment does not have
2133 the specified construction variable,
2134 it is simply added to the environment.
2135 If the construction variable being appended to is a list,
2136 then any value(s) that already exist in the
2137 construction variable will
2139 be added again to the list.
2142 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2145 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2148 A factory function that
2149 returns a Builder object
2150 to be used to fetch source files
2152 The returned Builder
2153 is intended to be passed to the
2158 env.SourceCode('.', env.BitKeeper())
2161 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2163 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2165 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2166 This specifies a build directory
2168 in which to build all derived files
2169 that would normally be built under
2171 Multiple build directories can be set up for multiple build variants, for
2174 must be underneath the SConstruct file's directory,
2177 may not be underneath the
2180 The default behavior is for
2182 to duplicate all of the files in the tree underneath
2186 and then build the derived files within the copied tree.
2187 (The duplication is performed by
2189 depending on the platform; see also the
2192 This guarantees correct builds
2193 regardless of whether intermediate source files
2194 are generated during the build,
2195 where preprocessors or other scanners search
2197 or whether individual compilers or other invoked tools
2198 are hard-coded to put derived files in the same directory as source files.
2200 This behavior of making a complete copy of the source tree
2201 may be disabled by setting
2206 to invoke Builders using the
2207 path names of source files in
2209 and the path names of derived files within
2211 This is always more efficient than
2213 and is usually safe for most builds.
2217 may cause build problems
2218 if source files are generated during the build,
2219 if any invoked tools are hard-coded to
2220 put derived files in the same directory as the source files.
2222 Note that specifying a
2224 works most naturally
2225 with a subsidiary SConscript file
2226 in the source directory.
2228 you would then call the subsidiary SConscript file
2229 not in the source directory,
2234 had made a virtual copy of the source tree
2235 regardless of the value of
2237 This is how you tell
2239 which variant of a source tree to build.
2243 BuildDir('build-variant1', 'src')
2244 SConscript('build-variant1/SConscript')
2245 BuildDir('build-variant2', 'src')
2246 SConscript('build-variant2/SConscript')
2252 function, described below,
2254 specify a build directory
2255 in conjunction with calling a subsidiary
2258 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2260 .RI Builder( action ", [" arguments ])
2262 .RI env.Builder( action ", [" arguments ])
2263 Creates a Builder object for
2266 See the section "Builder Objects,"
2267 below, for a complete explanation of the arguments and behavior.
2269 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2271 .RI CacheDir( cache_dir )
2273 .RI env.CacheDir( cache_dir )
2276 will maintain a cache of derived files in
2278 The derived files in the cache will be shared
2279 among all the builds using the same
2287 finds a derived file that needs to be rebuilt,
2288 it will first look in the cache to see if a
2289 derived file has already been built
2290 from identical input files and an identical build action
2291 (as incorporated into the MD5 build signature).
2294 will retrieve the file from the cache.
2295 If the derived file is not present in the cache,
2298 then place a copy of the built file in the cache
2299 (identified by its MD5 build signature),
2300 so that it may be retrieved by other
2301 builds that need to build the same derived file
2302 from identical inputs.
2306 may be disabled for any invocation
2315 will place a copy of
2317 derived files in the cache,
2318 even if they already existed
2319 and were not built by this invocation.
2320 This is useful to populate a cache
2323 is added to a build,
2332 "Retrieved `file' from cache,"
2335 option is being used.
2340 will print the action that
2342 have been used to build the file,
2343 without any indication that
2344 the file was actually retrieved from the cache.
2345 This is useful to generate build logs
2346 that are equivalent regardless of whether
2347 a given derived file has been built in-place
2348 or retrieved from the cache.
2350 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2352 .RI Clean( target ", " files_or_dirs )
2354 .RI env.Clean( target ", " files_or_dirs )
2355 This specifies a list of files or directories which should be removed
2356 whenever the target is specified with the
2358 command line option.
2362 and create a new target or add files and directories to the
2363 clean list for the specified target.
2365 Multiple files or directories should be specified
2366 either as separate arguments to the
2368 method, or as a list.
2370 will also accept the return value of any of the construction environment
2375 Clean('foo', ['bar', 'baz'])
2376 Clean('dist', env.Program('hello', 'hello.c'))
2379 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2381 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2383 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2384 Executes a specific action
2385 (or list of actions)
2386 to build a target file or files.
2387 This is more convenient
2388 than defining a separate Builder object
2389 for a single special-case build.
2390 Any keyword arguments specified override any
2391 same-named existing construction variables.
2393 Note that an action can be an external command,
2394 specified as a string,
2395 or a callable Python object;
2396 see "Action Objects," below.
2400 env.Command('foo.out', 'foo.in',
2401 "$FOO_BUILD < $SOURCES > $TARGET")
2403 env.Command('bar.out', 'bar.in',
2405 "$BAR_BUILD < $SOURCES > $TARGET"],
2406 ENV = {'PATH' : '/usr/local/bin/'})
2408 def rename(env, target, source):
2410 os.rename('.tmp', str(target[0]))
2412 env.Command('baz.out', 'baz.in',
2413 ["$BAZ_BUILD < $SOURCES > .tmp",
2417 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2419 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
2421 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
2422 Creates a Configure object for integrated
2423 functionality similar to GNU autoconf.
2424 See the section "Configure Contexts,"
2425 below, for a complete explanation of the arguments and behavior.
2427 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2429 .RI env.Copy([ key = val ", ...])"
2430 Return a separate copy of a construction environment.
2431 If there are any keyword arguments specified,
2432 they are added to the returned copy,
2433 overwriting any existing values
2438 env3 = env.Copy(CCFLAGS = '-g')
2441 Additionally, a list of tools and a toolpath may be specified, as in
2442 the Environment constructor:
2445 def MyTool(env): env['FOO'] = 'bar'
2446 env4 = env.Copy(tools = ['msvc', MyTool])
2449 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2451 .RI env.CVS( repository ", " module )
2452 A factory function that
2453 returns a Builder object
2454 to be used to fetch source files
2458 The returned Builder
2459 is intended to be passed to the
2463 The optional specified
2465 will be added to the beginning
2466 of all repository path names;
2467 this can be used, in essence,
2468 to strip initial directory names
2469 from the repository path names,
2470 so that you only have to
2471 replicate part of the repository
2472 directory hierarchy in your
2473 local build directory:
2476 # Will fetch foo/bar/src.c
2477 # from /usr/local/CVSROOT/foo/bar/src.c.
2478 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2480 # Will fetch bar/src.c
2481 # from /usr/local/CVSROOT/foo/bar/src.c.
2482 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2485 # from /usr/local/CVSROOT/foo/bar/src.c.
2486 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2489 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2491 .RI Default( targets )
2493 .RI env.Default( targets )
2494 This specifies a list of default targets,
2495 which will be built by
2497 if no explicit targets are given on the command line.
2501 and add to the list of default targets.
2503 Multiple targets should be specified as
2504 separate arguments to the
2506 method, or as a list.
2508 will also accept the Node returned by any
2509 of a construction environment's
2514 Default('foo', 'bar', 'baz')
2515 env.Default(['a', 'b', 'c'])
2516 hello = env.Program('hello', 'hello.c')
2524 will clear all default targets.
2527 will add to the (now empty) default-target list
2530 The current list of targets added using the
2532 function or method is available in the
2537 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2539 .RI DefaultEnvironment([ args ])
2540 Creates and returns a default construction environment object.
2541 This construction environment is used internally by SCons
2542 in order to execute many of the global functions in this list,
2543 and to fetch source files transparently
2544 from source code management systems.
2546 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2548 .RI Depends( target ", " dependency )
2550 .RI env.Depends( target ", " dependency )
2551 Specifies an explicit dependency;
2552 the target file(s) will be rebuilt
2553 whenever the dependency file(s) has changed.
2554 This should only be necessary
2555 for cases where the dependency
2556 is not caught by a Scanner
2560 env.Depends('foo', 'other-input-file-for-foo')
2563 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2565 .RI env.Dictionary([ vars ])
2566 Returns a dictionary object
2567 containing copies of all of the
2568 construction variables in the environment.
2569 If there are any variable names specified,
2570 only the specified construction
2571 variables are returned in the dictionary.
2574 dict = env.Dictionary()
2575 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2578 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2580 .RI Dir( name ", [" directory ])
2582 .RI env.Dir( name ", [" directory ])
2583 This returns an object that represents a given directory
2586 can be a relative or absolute path.
2588 is an optional directory that will be used as the parent directory.
2590 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2592 .RI EnsurePythonVersion( major ", " minor )
2594 .RI env.EnsurePythonVersion( major ", " minor )
2595 Ensure that the Python version is at least
2598 print out an error message and exit SCons with a non-zero exit code if the
2599 actual Python version is not late enough.
2602 EnsurePythonVersion(2,2)
2605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2607 .RI EnsureSConsVersion( major ", " minor )
2609 .RI env.EnsureSConsVersion( major ", " minor )
2610 Ensure that the SCons version is at least
2613 print out an error message and exit SCons with a non-zero exit code if the
2614 actual SCons version is not late enough.
2617 EnsureSConsVersion(0,9)
2620 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2622 .RI Environment([ key = value ", ...])"
2624 .RI env.Environment([ key = value ", ...])"
2625 Return a new construction environment
2626 initialized with the specified
2630 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2632 .RI Execute( action ", [" strfunction ", " varlist ])
2634 .RI env.Execute( action ", [" strfunction ", " varlist ])
2635 Executes an Action object.
2638 may be an Action object
2639 (see the section "Action Objects,"
2640 below, for a complete explanation of the arguments and behavior),
2641 or it may be a command-line string,
2643 or executable Python function,
2644 each of which will be converted
2645 into an Action object
2647 The exit value of the command
2648 or return value of the Python function
2651 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2655 .RI env.Exit([ value ])
2661 A default exit value of
2664 is used if no value is specified.
2666 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2670 .RI env.Export( vars )
2673 to export a list of variables from the current
2674 SConscript file to all other SConscript files.
2675 The exported variables are kept in a global collection,
2676 so subsequent calls to
2678 will over-write previous exports that have the same name.
2679 Multiple variable names can be passed to
2681 as separate arguments or as a list. A dictionary can be used to map
2682 variables to a different name when exported. Both local variables and
2683 global variables can be exported.
2688 # Make env available for all SConscript files to Import().
2692 # Make env and package available for all SConscript files:.
2693 Export("env", "package")
2695 # Make env and package available for all SConscript files:
2696 Export(["env", "package"])
2698 # Make env available using the name debug:.
2699 Export({"debug":env})
2705 function supports an
2707 argument that makes it easier to to export a variable or
2708 set of variables to a single SConscript file.
2709 See the description of the
2713 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2715 .RI File( name ", [" directory ])
2717 .RI env.File( name ", [" directory ])
2718 This returns an object that represents a given file
2721 can be a relative or absolute path.
2723 is an optional directory that will be used as the parent directory.
2725 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2727 .RI FindFile( file ", " dirs )
2729 .RI env.FindFile( file ", " dirs )
2732 in the path specified by
2735 may be a list of file names or a single file name. In addition to searching
2736 for files that exist in the filesytem, this function also searches for
2737 derived files that have not yet been built.
2740 foo = env.FindFile('foo', ['dir1', 'dir2'])
2743 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2745 .RI GetBuildPath( file ", [" ... ])
2747 .RI env.GetBuildPath( file ", [" ... ])
2750 path name (or names) for the specified
2758 Nodes or strings representing path names.
2760 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2764 .RI env.GetLaunchDir()
2765 Returns the absolute path name of the directory from which
2768 was initially invoked.
2769 This can be useful when using the
2774 options, which internally
2775 change to the directory in which the
2779 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2781 .RI GetOption( name )
2783 .RI env.GetOption( name )
2784 This function provides a way to query a select subset of the scons command line
2785 options from a SConscript file. See
2787 for a description of the options available.
2789 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2791 '\".RI GlobalBuilders( flag )
2795 '\"adds the names of the default builders
2796 '\"(Program, Library, etc.)
2797 '\"to the global name space
2798 '\"so they can be called without an explicit construction environment.
2799 '\"(This is the default.)
2803 '\"the names of the default builders are removed
2804 '\"from the global name space
2805 '\"so that an explicit construction environment is required
2806 '\"to call all builders.
2808 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2812 .RI env.Help( text )
2813 This specifies help text to be printed if the
2815 argument is given to
2818 will exit after printing out the help text.
2820 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2822 .RI Ignore( target ", " dependency )
2824 .RI env.Ignore( target ", " dependency )
2825 The specified dependency file(s)
2826 will be ignored when deciding if
2827 the target file(s) need to be rebuilt.
2830 env.Ignore('foo', 'foo.c')
2831 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2834 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2838 .RI env.Import( vars )
2841 to import a list of variables into the current SConscript file. This
2842 will import variables that were exported with
2848 Variables exported by
2851 Multiple variable names can be passed to
2853 as separate arguments or as a list. The variable "*" can be used
2854 to import all variables.
2859 Import("env", "variable")
2860 Import(["env", "variable"])
2864 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2866 .RI Install( dir ", " source )
2868 .RI env.Install( dir ", " source )
2869 Installs one or more files in a destination directory.
2870 The file names remain the same.
2873 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2876 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2878 .RI InstallAs( target ", " source )
2880 .RI env.InstallAs( target ", " source )
2881 Installs one or more files as specific file names,
2882 allowing changing a file name as part of the
2884 It is an error if the target and source
2885 list different numbers of files.
2888 env.InstallAs(target = '/usr/local/bin/foo',
2889 source = 'foo_debug')
2890 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2891 source = ['libFOO.a', 'libBAR.a'])
2894 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2896 .RI Literal( string )
2898 .RI env.Literal( string )
2901 will be preserved as-is
2902 and not have construction variables expanded.
2904 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2906 .RI Local( targets )
2908 .RI env.Local( targets )
2911 will have copies made in the local tree,
2912 even if an already up-to-date copy
2913 exists in a repository.
2914 Returns a list of the target Node or Nodes.
2916 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2918 .RI env.ParseConfig( command ", [" function ])
2921 to modify the environment as specified by the output of
2925 expects the output of a typical
2929 and parses the returned
2949 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2952 A factory function that
2953 returns a Builder object
2954 to be used to fetch source files
2955 from the Perforce source code management system.
2956 The returned Builder
2957 is intended to be passed to the
2962 env.SourceCode('.', env.Perforce())
2965 Perforce uses a number of external
2966 environment variables for its operation.
2967 Consequently, this function adds the
2968 following variables from the user's external environment
2969 to the construction environment's
2982 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2984 .RI Platform( string )
2985 Returns a callable object
2986 that can be used to initialize
2987 a construction environment using the
2988 platform keyword of the Environment() method:
2991 env = Environment(platform = Platform('win32'))
2994 .RI env.Platform( string )
2995 Applies the callable object for the specified platform
2997 to the environment through which the method was called.
3000 env.Platform('posix')
3007 variable from the user's external environment
3008 to the construction environment's
3011 This is so that any executed commands
3012 that use sockets to connect with other systems
3013 (such as fetching source files from
3014 external CVS repository specifications like
3015 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3016 will work on Win32 systems.
3018 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3020 .RI Precious( target ", ...)"
3022 .RI env.Precious( target ", ...)"
3025 as precious so it is not deleted before it is rebuilt. Normally
3027 deletes a target before building it.
3028 Multiple targets can be passed in to a single call to
3031 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3033 .RI env.Prepend( key = val ", [...])"
3034 Appends the specified keyword arguments
3035 to the beginning of construction variables in the environment.
3036 If the Environment does not have
3037 the specified construction variable,
3038 it is simply added to the environment.
3039 If the values of the construction variable
3040 and the keyword argument are the same type,
3041 then the two values will be simply added together.
3042 Otherwise, the construction variable
3043 and the value of the keyword argument
3044 are both coerced to lists,
3045 and the lists are added together.
3046 (See also the Append method, above.)
3049 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3052 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3054 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3055 This appends new path elements to the given path in the
3056 specified external environment
3060 any particular path once (leaving the first one it encounters and
3061 ignoring the rest, to preserve path order),
3062 and to help assure this,
3063 will normalize all paths (using
3066 .BR os.path.normcase ).
3067 This can also handle the
3068 case where the given old path variable is a list instead of a
3069 string, in which case a list will be returned instead of a string.
3073 print 'before:',env['ENV']['INCLUDE']
3074 include_path = '/foo/bar:/foo'
3075 env.PrependENVPath('INCLUDE', include_path)
3076 print 'after:',env['ENV']['INCLUDE']
3080 after: /foo/bar:/foo:/biz
3083 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3085 .RI env.AppendUnique( key = val ", [...])"
3086 Appends the specified keyword arguments
3087 to the beginning of construction variables in the environment.
3088 If the Environment does not have
3089 the specified construction variable,
3090 it is simply added to the environment.
3091 If the construction variable being appended to is a list,
3092 then any value(s) that already exist in the
3093 construction variable will
3095 be added again to the list.
3098 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3101 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3104 A factory function that
3105 returns a Builder object
3106 to be used to fetch source files
3108 The returned Builder
3109 is intended to be passed to the
3114 env.SourceCode('.', env.RCS())
3119 will fetch source files
3120 from RCS subdirectories automatically,
3122 as demonstrated in the above example
3123 should only be necessary if
3124 you are fetching from
3127 directory as the source files,
3128 or if you need to explicitly specify RCS
3129 for a specific subdirectory.
3131 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3133 .RI env.Replace( key = val ", [...])"
3134 Replaces construction variables in the Environment
3135 with the specified keyword arguments.
3138 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3141 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3143 .RI Repository( directory )
3145 .RI env.Repository( directory )
3148 is a repository to be searched for files.
3152 and each one adds to the list of
3153 repositories that will be searched.
3157 a repository is a copy of the source tree,
3158 from the top-level directory on down,
3160 both source files and derived files
3161 that can be used to build targets in
3162 the local source tree.
3163 The canonical example would be an
3164 official source tree maintained by an integrator.
3165 If the repository contains derived files,
3166 then the derived files should have been built using
3168 so that the repository contains the necessary
3169 signature information to allow
3171 to figure out when it is appropriate to
3172 use the repository copy of a derived file,
3173 instead of building one locally.
3175 Note that if an up-to-date derived file
3176 already exists in a repository,
3180 make a copy in the local directory tree.
3181 In order to guarantee that a local copy
3187 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3192 what variable(s) to use as the return value(s) of the current SConscript
3193 file. These variables will be returned to the "calling" SConscript file
3194 as the return value(s) of
3196 Multiple variable names should be passed to
3202 Return(["foo", "bar"])
3205 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3207 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3209 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3210 Creates a Scanner object for
3213 See the section "Scanner Objects,"
3214 below, for a complete explanation of the arguments and behavior.
3216 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3219 A factory function that
3220 returns a Builder object
3221 to be used to fetch source files
3223 The returned Builder
3224 is intended to be passed to the
3229 env.SourceCode('.', env.SCCS())
3234 will fetch source files
3235 from SCCS subdirectories automatically,
3237 as demonstrated in the above example
3238 should only be necessary if
3239 you are fetching from
3242 directory as the source files,
3243 or if you need to explicitly specify SCCS
3244 for a specific subdirectory.
3246 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3248 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3250 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3252 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3254 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3258 one or more subsidiary SConscript (configuration) files.
3259 There are two ways to call the
3263 The first way you can call
3265 is to explicitly specify one or more
3267 as the first argument.
3268 A single script may be specified as a string;
3269 multiple scripts must be specified as a list
3270 (either explicitly or as created by
3274 The second way you can call
3276 is to specify a list of (sub)directory names
3283 execute a subsidiary configuration file named
3285 in each of the specified directories.
3286 You may specify a name other than
3288 by supplying an optional
3294 argument provides a list of variable names or a dictionary of
3295 named values to export to the
3297 These variables are locally exported only to the specified
3299 and do not affect the
3300 global pool of variables used by
3304 '\"If multiple dirs are provided,
3305 '\"each script gets a fresh export.
3310 function to import the variables.
3314 argument specifies that all of the target files
3315 (for example, object files and executables)
3316 that would normally be built in the subdirectory in which
3318 resides should actually
3324 argument specifies that the
3325 source files from which
3326 the target files should be built
3332 will link or copy (depending on the platform)
3333 all the source files into the build directory.
3334 This behavior may be disabled by
3335 setting the optional
3338 (it is set to 1 by default),
3341 will refer directly to
3342 the source files in their source directory
3343 when building target files.
3346 is usually safe, and always more efficient
3349 but it may cause build problems in certain end-cases,
3350 such as compiling from source files that
3351 are generated by the build.)
3353 Any variables returned by
3357 will be returned by the call to
3363 SConscript('subdir/SConscript')
3364 foo = SConscript('sub/SConscript', exports='env')
3365 SConscript('dir/SConscript', exports=['env', 'variable'])
3366 SConscript('src/SConscript', build_dir='build', duplicate=0)
3367 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3368 SConscript(dirs=['sub1', 'sub2'])
3369 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3372 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3374 .RI SConscriptChdir( value )
3376 .RI env.SConscriptChdir( value )
3379 changes its working directory
3380 to the directory in which each
3381 subsidiary SConscript file lives.
3382 This behavior may be disabled
3383 by specifying either:
3387 env.SConscriptChdir(0)
3392 will stay in the top-level directory
3393 while reading all SConscript files.
3394 (This may be necessary when building from repositories,
3395 when all the directories in which SConscript files may be found
3396 don't necessarily exist locally.)
3398 You may enable and disable
3399 this ability by calling
3406 SConscript('foo/SConscript') # will not chdir to foo
3407 env.SConscriptChdir(1)
3408 SConscript('bar/SConscript') # will chdir to bar
3411 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3413 .RI SConsignFile([ file , dbm_module ])
3415 .RI env.SConsignFile([ file , dbm_module ])
3418 to store all file signatures
3428 is not an absolute path name,
3429 the file is placed in the same directory as the top-level
3435 argument can be used to specify
3436 which Python database module
3437 The default is to use a custom
3439 module that uses pickled
3440 Python data structures,
3441 and which works on all Python versions from 1.5.2 on.
3446 # Stores signatures in ".sconsign.dbm"
3447 # in the top-level SConstruct directory.
3450 # Stores signatures in the file "etc/scons-signatures"
3451 # relative to the top-level SConstruct directory.
3452 SConsignFile("etc/scons-signatures")
3454 # Stores signatures in the specified absolute file name.
3455 SConsignFile("/home/me/SCons/signatures")
3458 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3460 .RI SetOption( name ", " value )
3462 .RI env.SetOption( name ", " value )
3463 This function provides a way to set a select subset of the scons command
3464 line options from a SConscript file. The options supported are:
3466 which corresponds to -c, --clean, and --remove;
3469 corresponds to --duplicate;
3471 which corresponds to --implicit-cache;
3473 which corresponds to --max-drift;
3475 which corresponds to -j and --jobs;
3476 .B save_explain_info
3477 which corresponds to --save-explain-info.
3478 See the documentation for the
3479 corresponding command line object for information about each specific
3483 SetOption('max_drift', 1)
3486 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3488 .RI SideEffect( side_effect ", " target )
3490 .RI env.SideEffect( side_effect ", " target )
3493 as a side effect of building
3499 can be a list, a file name, or a node.
3500 A side effect is a target that is created
3501 as a side effect of building other targets.
3502 For example, a Windows PDB
3503 file is created as a side effect of building the .obj
3504 files for a static library.
3505 If a target is a side effect of multiple build commands,
3507 will ensure that only one set of commands
3508 is executed at a time.
3509 Consequently, you only need to use this method
3510 for side-effect targets that are built as a result of
3511 multiple build commands.
3513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3515 .RI SourceCode( entries ", " builder )
3517 .RI env.SourceCode( entries ", " builder )
3518 Arrange for non-existent source files to
3519 be fetched from a source code management system
3524 may be a Node, string or list of both,
3525 and may represent either individual
3526 source files or directories in which
3527 source files can be found.
3529 For any non-existent source files,
3531 will search up the directory tree
3541 will not use a builder to fetch
3542 source files for the specified
3546 builder has been specified
3547 for a directory higher up the tree.
3551 fetch files from SCCS or RCS subdirectories
3552 without explicit configuration.
3553 This takes some extra processing time
3554 to search for the necessary
3555 source code management files on disk.
3556 You can avoid these extra searches
3557 and speed up your build a little
3558 by disabling these searches as follows:
3561 env.SourceCode('.', None)
3565 Note that if the specified
3567 is one you create by hand,
3568 it must have an associated
3569 construction environment to use
3570 when fetching a source file.
3573 provides a set of canned factory
3574 functions that return appropriate
3575 Builders for various popular
3576 source code management systems.
3577 Canonical examples of invocation include:
3580 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3581 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3582 env.SourceCode('/', env.RCS())
3583 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3584 env.SourceCode('no_source.c', None)
3586 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3588 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3590 '\".RI Subversion( repository ", " module )
3591 '\"A factory function that
3592 '\"returns a Builder object
3593 '\"to be used to fetch source files
3594 '\"from the specified Subversion
3596 '\"The returned Builder
3597 '\"is intended to be passed to the
3601 '\"The optional specified
3603 '\"will be added to the beginning
3604 '\"of all repository path names;
3605 '\"this can be used, in essence,
3606 '\"to strip initial directory names
3607 '\"from the repository path names,
3608 '\"so that you only have to
3609 '\"replicate part of the repository
3610 '\"directory hierarchy in your
3611 '\"local build directory:
3614 '\"# Will fetch foo/bar/src.c
3615 '\"# from /usr/local/Subversion/foo/bar/src.c.
3616 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3618 '\"# Will fetch bar/src.c
3619 '\"# from /usr/local/Subversion/foo/bar/src.c.
3620 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3622 '\"# Will fetch src.c
3623 '\"# from /usr/local/Subversion/foo/bar/src.c.
3624 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3627 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3629 .RI SourceSignatures( type )
3631 .RI env.SourceSignatures( type )
3632 This function tells SCons what type of signature to use for source files:
3636 If the environment method is used,
3637 the specified type of source signature
3638 is only used when deciding whether targets
3639 built with that environment are up-to-date or must be rebuilt.
3640 If the global function is used,
3641 the specified type of source signature becomes the default
3642 used for all decisions
3643 about whether targets are up-to-date.
3645 "MD5" means the signature of a source file
3646 is the MD5 checksum of its contents.
3647 "timestamp" means the signature of a source file
3648 is its timestamp (modification time).
3649 There is no different between the two behaviors
3653 "MD5" signatures take longer to compute,
3654 but are more accurate than "timestamp" signatures.
3655 The default is "MD5".
3657 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3661 .RI env.Split( arg )
3662 Returns a list of file names or other objects.
3664 it will be split on strings of white-space characters
3666 making it easier to write long lists of file names.
3667 If arg is already a list,
3668 the list will be returned untouched.
3669 If arg is any other type of object,
3670 it will be returned as a list
3671 containing just the object.
3674 files = Split("f1.c f2.c f3.c")
3675 files = env.Split("f4.c f5.c f6.c")
3683 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3685 .RI TargetSignatures( type )
3687 .RI env.TargetSignatures( type )
3688 This function tells SCons what type of signatures to use
3693 If the environment method is used,
3694 the specified type of signature is only used
3695 for targets built with that environment.
3696 If the global function is used,
3697 the specified type of signature becomes the default
3698 used for all target files that
3699 don't have an explicit target signature type
3700 specified for their environments.
3702 "build" means the signature of a target file
3703 is made by concatenating all of the
3704 signatures of all its source files.
3705 "content" means the signature of a target
3706 file is an MD5 checksum of its contents.
3707 "build" signatures are usually faster to compute,
3708 but "content" signatures can prevent unnecessary rebuilds
3709 when a target file is rebuilt to the exact same contents
3710 as the previous build.
3711 The default is "build".
3713 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3715 .RI Tool( string, toolpath=[] )
3716 Returns a callable object
3717 that can be used to initialize
3718 a construction environment using the
3719 tools keyword of the Environment() method.
3720 The object may be called with a construction
3721 environment as an argument,
3722 in which case the object will be
3723 add the necessary variables
3724 to the construction environment
3725 and the name of the tool will be added to the
3727 construction variable.
3730 env = Environment(tools = [ Tool('msvc') ])
3734 t(env) # adds 'msvc' to the TOOLS variable
3735 u = Tool('opengl', toolpath = ['tools'])
3736 u(env) # adds 'opengl' to the TOOLS variable
3739 .RI env.Tool( string [, toolpath] )
3740 Applies the callable object for the specified tool
3742 to the environment through which the method was called.
3746 env.Tool('opengl', toolpath = ['build/tools'])
3749 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3753 .RI env.Value( value )
3754 Returns a Node object representing the specified Python value. Value
3755 nodes can be used as dependencies of targets. If the result of
3758 changes between SCons runs, any targets depending on
3760 will be rebuilt. When using timestamp source signatures, Value nodes'
3761 timestamps are equal to the system time when the node is created.
3764 def create(target, source, env):
3765 f = open(str(target[0]), 'wb')
3766 f.write('prefix=' + source[0].get_contents())
3768 prefix = ARGUMENTS.get('prefix', '/usr/local')
3770 env['BUILDERS']['Config'] = Builder(action = create)
3771 env.Config(target = 'package-config', source = Value(prefix))
3774 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3776 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
3778 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
3780 Searches for the specified executable
3782 returning the full path name to the program
3784 and returning None if not.
3785 Searches the specified
3787 the value of the calling environment's PATH
3788 (env['ENV']['PATH']),
3789 or the user's current external PATH
3790 (os.environ['PATH'])
3792 On Win32 systems, searches for executable
3793 programs with any of the file extensions
3794 listed in the specified
3796 the calling environment's PATHEXT
3797 (env['ENV']['PATHEXT'])
3798 or the user's current PATHEXT
3799 (os.environ['PATHEXT'])
3807 .SS SConscript Variables
3808 In addition to the global functions and methods,
3810 supports a number of Python variables
3811 that can be used in SConscript files
3812 to affect how you want the build to be performed.
3814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3819 arguments specified on the command line.
3820 Each element in the list is a tuple
3822 .RI ( keyword , value )
3828 elements of the tuple
3830 subscripting for element
3834 of the tuple, respectively.
3837 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
3838 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
3839 third_tuple = ARGLIST[2]
3840 print "third keyword, value =", third_tuple[0], third_tuple[1]
3841 for key, value in ARGLIST:
3842 # process key and value
3845 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3848 A dictionary of all the
3850 arguments specified on the command line.
3851 The dictionary is not in order,
3852 and if a given keyword has
3853 more than one value assigned to it
3854 on the command line,
3855 the last (right-most) value is
3861 if ARGUMENTS.get('debug', 0):
3862 env = Environment(CCFLAGS = '-g')
3867 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3870 A list of the targets which
3872 will actually try to build,
3873 regardless of whether they were specified on
3874 the command line or via the
3877 The elements of this list may be strings
3879 nodes, so you should run the list through the Python
3881 function to make sure any Node path names
3882 are converted to strings.
3884 Because this list may be taken from the
3885 list of targets specified using the
3888 the contents of the list may change
3889 on each successive call to
3894 for additional information.
3897 if 'foo' in BUILD_TARGETS:
3898 print "Don't forget to test the `foo' program!"
3899 if 'special/program' in BUILD_TARGETS:
3900 SConscript('special')
3905 list only contains targets expected listed
3906 on the command line or via calls to the
3911 contain all dependent targets that will be built as
3912 a result of making the sure the explicitly-specified
3913 targets are up to date.
3915 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3917 COMMAND_LINE_TARGETS
3918 A list of the targets explicitly specified on
3920 If there are no targets specified on the command line,
3922 This can be used, for example,
3923 to take specific actions only
3924 when a certain target or targets
3925 is explicitly being built:
3928 if 'foo' in COMMAND_LINE_TARGETS:
3929 print "Don't forget to test the `foo' program!"
3930 if 'special/program' in COMMAND_LINE_TARGETS:
3931 SConscript('special')
3934 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3937 A list of the target
3939 that have been specified using the
3942 The elements of the list are nodes,
3943 so you need to run them through the Python
3945 function to get at the path name for each Node.
3948 print str(DEFAULT_TARGETS[0])
3949 if 'foo' in map(str, DEFAULT_TARGETS):
3950 print "Don't forget to test the `foo' program!"
3955 list change on on each successive call to the
3960 print map(str, DEFAULT_TARGETS) # originally []
3962 print map(str, DEFAULT_TARGETS) # now a node ['foo']
3964 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
3966 print map(str, DEFAULT_TARGETS) # back to []
3969 Consequently, be sure to use
3971 only after you've made all of your
3974 or else simply be careful of the order
3975 of these statements in your SConscript files
3976 so that you don't look for a specific
3977 default target before it's actually been added to the list.
3979 .SS Construction Variables
3980 .\" XXX From Gary Ruben, 23 April 2002:
3981 .\" I think it would be good to have an example with each construction
3982 .\" variable description in the documentation.
3984 .\" CC The C compiler
3985 .\" Example: env["CC"] = "c68x"
3986 .\" Default: env["CC"] = "cc"
3988 .\" CCCOM The command line ...
3990 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
3991 .\" env["CC"] = "c68x"
3992 .\" env["CFLAGS"] = "-ps -qq -mr"
3993 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
3995 .\" (I dunno what this is ;-)
3996 A construction environment has an associated dictionary of
3997 .I construction variables
3998 that are used by built-in or user-supplied build rules.
3999 Construction variables must follow the same rules for
4001 the initial character must be an underscore or letter,
4002 followed by any number of underscores, letters, or digits.
4004 A number of useful construction variables are automatically defined by
4005 scons for each supported platform, and additional construction variables
4006 can be defined by the user. The following is a list of the automatically
4007 defined construction variables:
4010 The static library archiver.
4013 The command line used to generate a static library from object files.
4016 General options passed to the static library archiver.
4022 The command line used to generate an object file
4023 from an assembly-language source file.
4026 General options passed to the assembler.
4029 The command line used to assemble an assembly-language
4030 source file into an object file
4031 after first running the file through the C preprocessor.
4032 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4033 are included on this command line.
4036 The bibliography generator for the TeX formatter and typesetter and the
4037 LaTeX structured formatter and typesetter.
4040 The command line used to call the bibliography generator for the
4041 TeX formatter and typesetter and the LaTeX structured formatter and
4045 General options passed to the bibliography generator for the TeX formatter
4046 and typesetter and the LaTeX structured formatter and typesetter.
4049 The BitKeeper executable.
4052 The command line for
4053 fetching source files using BitKEeper.
4056 The command ($BITKEEPER) and subcommand
4057 for fetching source files using BitKeeper.
4059 .IP BITKEEPERGETFLAGS
4060 Options that are passed to the BitKeeper
4065 A dictionary mapping the names of the builders
4066 available through this environment
4067 to underlying Builder objects.
4069 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4070 are available by default.
4071 If you initialize this variable when an
4072 Environment is created:
4075 env = Environment(BUILDERS = {'NewBuilder' : foo})
4078 the default Builders will no longer be available.
4079 To use a new Builder object in addition to the default Builders,
4080 add your new Builder object like this:
4084 env.Append(BUILDERS = {'NewBuilder' : foo})
4091 env['BUILDERS]['NewBuilder'] = foo
4098 The command line used to compile a C source file to a (static) object file.
4099 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4100 are included on this command line.
4103 General options that are passed to the C compiler.
4106 The suffix for C source files.
4107 This is used by the internal CFile builder
4108 when generating C files from Lex (.l) or YACC (.y) input files.
4109 The default suffix, of course, is
4112 On case-insensitive systems (like Win32),
4119 The version number of the C compiler.
4120 This may or may not be set,
4121 depending on the specific C compiler being used.
4124 A function used to produce variables like $_CPPINCFLAGS. It takes
4126 arguments: a prefix to concatenate onto each element, a list of
4127 elements, a suffix to concatenate onto each element, an environment
4128 for variable interpolation, and an optional function that will be
4129 called to transform the list before concatenation.
4132 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4136 A platform independent specification of C preprocessor definitions.
4137 The definitions will be added to command lines
4138 through the automatically-generated
4139 $_CPPDEFFLAGS construction variable (see below),
4140 which is constructed according to
4141 the type of value of $CPPDEFINES:
4144 If $CPPDEFINES is a string,
4146 $CPPDEFPREFIX and $CPPDEFSUFFIX
4147 construction variables
4148 will be added to the beginning and end.
4151 # Will add -Dxyz to POSIX compiler command lines,
4152 # and /Dxyz to Microsoft Visual C++ command lines.
4153 env = Environment(CPPDEFINES='xyz')
4157 If $CPPDEFINES is a list,
4159 $CPPDEFPREFIX and $CPPDEFSUFFIX
4160 construction variables
4161 will be appended to the beginning and end
4162 of each element in the list.
4163 If any element is a list or tuple,
4164 then the first item is the name being
4165 defined and the second item is its value:
4168 # Will add -DB=2 -DA to POSIX compiler command lines,
4169 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4170 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4174 If $CPPDEFINES is a dictionary,
4176 $CPPDEFPREFIX and $CPPDEFSUFFIX
4177 construction variables
4178 will be appended to the beginning and end
4179 of each item from the dictionary.
4180 The key of each dictionary item
4181 is a name being defined
4182 to the dictionary item's corresponding value;
4185 then the name is defined without an explicit value.
4186 Note that the resulting flags are sorted by keyword
4187 to ensure that the order of the options on the
4188 command line is consistent each time
4193 # Will add -DA -DB=2 to POSIX compiler command lines,
4194 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4195 env = Environment(CPPDEFINES={'B':2, 'A':None})
4199 An automatically-generated construction variable
4200 containing the C preprocessor command-line options
4202 The value of $_CPPDEFFLAGS is created
4203 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4204 to the beginning and end
4205 of each directory in $CPPDEFINES.
4208 The prefix used to specify preprocessor definitions
4209 on the C compiler command line.
4210 This will be appended to the beginning of each definition
4211 in the $CPPDEFINES construction variable
4212 when the $_CPPDEFFLAGS variable is automatically generated.
4215 The suffix used to specify preprocessor definitions
4216 on the C compiler command line.
4217 This will be appended to the end of each definition
4218 in the $CPPDEFINES construction variable
4219 when the $_CPPDEFFLAGS variable is automatically generated.
4222 User-specified C preprocessor options.
4223 These will be included in any command that uses the C preprocessor,
4224 including not just compilation of C and C++ source files
4225 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4226 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4227 $F77PPCOM and $SHF77PPCOM command lines
4228 used to compile a Fortran source file,
4229 and the $ASPPCOM command line
4230 used to assemble an assembly language source file,
4231 after first running each file through the C preprocessor.
4232 Note that this variable does
4236 (or similar) include search path options
4237 that scons generates automatically from $CPPPATH.
4241 for the variable that expands to those options.
4244 An automatically-generated construction variable
4245 containing the C preprocessor command-line options
4246 for specifying directories to be searched for include files.
4247 The value of $_CPPINCFLAGS is created
4248 by appending $INCPREFIX and $INCSUFFIX
4249 to the beginning and end
4250 of each directory in $CPPPATH.
4253 The list of directories that the C preprocessor will search for include
4254 directories. The C/C++ implicit dependency scanner will search these
4255 directories for include files. Don't explicitly put include directory
4256 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4257 and the directories will not be searched by the dependency scanner. Note:
4258 directory names in CPPPATH will be looked-up relative to the SConscript
4259 directory when they are used in a command. To force
4261 to look-up a directory relative to the root of the source tree use #:
4264 env = Environment(CPPPATH='#/include')
4268 The directory look-up can also be forced using the
4273 include = Dir('include')
4274 env = Environment(CPPPATH=include)
4278 The directory list will be added to command lines
4279 through the automatically-generated
4281 construction variable,
4282 which is constructed by
4283 appending the values of the
4284 $INCPREFIX and $INCSUFFIX
4285 construction variables
4286 to the beginning and end
4287 of each directory in $CPPPATH.
4288 Any command lines you define that need
4289 the CPPPATH directory list should
4290 include $_CPPINCFLAGS:
4293 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4297 The list of suffixes of files that will be scanned
4298 for C preprocessor implicit dependencies
4300 The default list is:
4303 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4304 ".h", ".H", ".hxx", ".hpp", ".hh",
4305 ".F", ".fpp", ".FPP",
4306 ".S", ".spp", ".SPP"]
4313 Options that are passed to the CVS checkout subcommand.
4316 The command line used to
4317 fetch source files from a CVS repository.
4320 General options that are passed to CVS.
4321 By default, this is set to
4323 to specify from where the files must be fetched.
4326 The path to the CVS repository.
4327 This is referenced in the default
4334 The suffix for C++ source files.
4335 This is used by the internal CXXFile builder
4336 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4337 The default suffix is
4339 SCons also treats files with the suffixes
4346 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4353 The command line used to compile a C++ source file to an object file.
4354 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4355 are included on this command line.
4358 General options that are passed to the C++ compiler.
4361 The version number of the C++ compiler.
4362 This may or may not be set,
4363 depending on the specific C++ compiler being used.
4366 A function that converts a file name into a Dir instance relative to the
4370 The list of suffixes of files that will be scanned
4371 for imported D package files.
4372 The default list is:
4379 The TeX DVI file to PDF file converter.
4382 General options passed to the TeX DVI file to PDF file converter.
4385 The command line used to convert TeX DVI files into a PDF file.
4388 The TeX DVI file to PostScript converter.
4391 General options passed to the TeX DVI file to PostScript converter.
4394 A dictionary of environment variables
4395 to use when invoking commands. When ENV is used in a command all list
4396 values will be joined using the path separator and any other non-string
4397 values will simply be coerced to a string.
4398 Note that, by default,
4402 propagate the environment in force when you
4405 to the commands used to build target files.
4406 This is so that builds will be guaranteed
4407 repeatable regardless of the environment
4408 variables set at the time
4412 If you want to propagate your
4413 environment variables
4414 to the commands executed
4415 to build target files,
4416 you must do so explicitly:
4420 env = Environment(ENV = os.environ)
4424 Note that you can choose only to propagate
4425 certain environment variables.
4429 environment variable,
4432 uses the same utilities
4433 as the invoking shell (or other process):
4438 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4442 A function that will be called to escape shell special characters in
4443 command lines. The function should take one argument: the command line
4444 string to escape; and should return the escaped command line.
4447 The Fortran 77 compiler.
4448 You should normally set the $FORTRAN variable,
4449 which specifies the default Fortran compiler
4450 for all Fortran versions.
4451 You only need to set $F77 if you need to use a specific compiler
4452 or compiler version for Fortran 77 files.
4455 The command line used to compile a Fortran 77 source file to an object file.
4456 You only need to set $F77COM if you need to use a specific
4457 command line for Fortran 77 files.
4458 You should normally set the $FORTRANCOM variable,
4459 which specifies the default command line
4460 for all Fortran versions.
4463 General user-specified options that are passed to the Fortran 77 compiler.
4464 Note that this variable does
4468 (or similar) include search path options
4469 that scons generates automatically from $F77PATH.
4473 for the variable that expands to those options.
4474 You only need to set $F77FLAGS if you need to define specific
4475 user options for Fortran 77 files.
4476 You should normally set the $FORTRANFLAGS variable,
4477 which specifies the user-specified options
4478 passed to the default Fortran compiler
4479 for all Fortran versions.
4482 An automatically-generated construction variable
4483 containing the Fortran 77 compiler command-line options
4484 for specifying directories to be searched for include files.
4485 The value of $_F77INCFLAGS is created
4486 by appending $INCPREFIX and $INCSUFFIX
4487 to the beginning and end
4488 of each directory in $F77PATH.
4491 The list of directories that the Fortran 77 compiler will search for include
4492 directories. The implicit dependency scanner will search these
4493 directories for include files. Don't explicitly put include directory
4494 arguments in $F77FLAGS because the result will be non-portable
4495 and the directories will not be searched by the dependency scanner. Note:
4496 directory names in $F77PATH will be looked-up relative to the SConscript
4497 directory when they are used in a command. To force
4499 to look-up a directory relative to the root of the source tree use #:
4500 You only need to set $F77PATH if you need to define a specific
4501 include path for Fortran 77 files.
4502 You should normally set the $FORTRANPATH variable,
4503 which specifies the include path
4504 for the default Fortran compiler
4505 for all Fortran versions.
4508 env = Environment(F77PATH='#/include')
4512 The directory look-up can also be forced using the
4517 include = Dir('include')
4518 env = Environment(F77PATH=include)
4522 The directory list will be added to command lines
4523 through the automatically-generated
4525 construction variable,
4526 which is constructed by
4527 appending the values of the
4528 $INCPREFIX and $INCSUFFIX
4529 construction variables
4530 to the beginning and end
4531 of each directory in $F77PATH.
4532 Any command lines you define that need
4533 the F77PATH directory list should
4534 include $_F77INCFLAGS:
4537 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4541 The command line used to compile a Fortran 77 source file to an object file
4542 after first running the file through the C preprocessor.
4543 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4544 are included on this command line.
4545 You only need to set $F77PPCOM if you need to use a specific
4546 C-preprocessor command line for Fortran 77 files.
4547 You should normally set the $FORTRANPPCOM variable,
4548 which specifies the default C-preprocessor command line
4549 for all Fortran versions.
4552 The Fortran 90 compiler.
4553 You should normally set the $FORTRAN variable,
4554 which specifies the default Fortran compiler
4555 for all Fortran versions.
4556 You only need to set $F90 if you need to use a specific compiler
4557 or compiler version for Fortran 90 files.
4560 The command line used to compile a Fortran 90 source file to an object file.
4561 You only need to set $F90COM if you need to use a specific
4562 command line for Fortran 90 files.
4563 You should normally set the $FORTRANCOM variable,
4564 which specifies the default command line
4565 for all Fortran versions.
4568 General user-specified options that are passed to the Fortran 90 compiler.
4569 Note that this variable does
4573 (or similar) include search path options
4574 that scons generates automatically from $F90PATH.
4578 for the variable that expands to those options.
4579 You only need to set $F90FLAGS if you need to define specific
4580 user options for Fortran 90 files.
4581 You should normally set the $FORTRANFLAGS variable,
4582 which specifies the user-specified options
4583 passed to the default Fortran compiler
4584 for all Fortran versions.
4587 An automatically-generated construction variable
4588 containing the Fortran 90 compiler command-line options
4589 for specifying directories to be searched for include files.
4590 The value of $_F90INCFLAGS is created
4591 by appending $INCPREFIX and $INCSUFFIX
4592 to the beginning and end
4593 of each directory in $F90PATH.
4596 The list of directories that the Fortran 90 compiler will search for include
4597 directories. The implicit dependency scanner will search these
4598 directories for include files. Don't explicitly put include directory
4599 arguments in $F90FLAGS because the result will be non-portable
4600 and the directories will not be searched by the dependency scanner. Note:
4601 directory names in $F90PATH will be looked-up relative to the SConscript
4602 directory when they are used in a command. To force
4604 to look-up a directory relative to the root of the source tree use #:
4605 You only need to set $F90PATH if you need to define a specific
4606 include path for Fortran 90 files.
4607 You should normally set the $FORTRANPATH variable,
4608 which specifies the include path
4609 for the default Fortran compiler
4610 for all Fortran versions.
4613 env = Environment(F90PATH='#/include')
4617 The directory look-up can also be forced using the
4622 include = Dir('include')
4623 env = Environment(F90PATH=include)
4627 The directory list will be added to command lines
4628 through the automatically-generated
4630 construction variable,
4631 which is constructed by
4632 appending the values of the
4633 $INCPREFIX and $INCSUFFIX
4634 construction variables
4635 to the beginning and end
4636 of each directory in $F90PATH.
4637 Any command lines you define that need
4638 the F90PATH directory list should
4639 include $_F90INCFLAGS:
4642 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
4646 The command line used to compile a Fortran 90 source file to an object file
4647 after first running the file through the C preprocessor.
4648 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
4649 are included on this command line.
4650 You only need to set $F90PPCOM if you need to use a specific
4651 C-preprocessor command line for Fortran 90 files.
4652 You should normally set the $FORTRANPPCOM variable,
4653 which specifies the default C-preprocessor command line
4654 for all Fortran versions.
4657 The Fortran 95 compiler.
4658 You should normally set the $FORTRAN variable,
4659 which specifies the default Fortran compiler
4660 for all Fortran versions.
4661 You only need to set $F95 if you need to use a specific compiler
4662 or compiler version for Fortran 95 files.
4665 The command line used to compile a Fortran 95 source file to an object file.
4666 You only need to set $F95COM if you need to use a specific
4667 command line for Fortran 95 files.
4668 You should normally set the $FORTRANCOM variable,
4669 which specifies the default command line
4670 for all Fortran versions.
4673 General user-specified options that are passed to the Fortran 95 compiler.
4674 Note that this variable does
4678 (or similar) include search path options
4679 that scons generates automatically from $F95PATH.
4683 for the variable that expands to those options.
4684 You only need to set $F95FLAGS if you need to define specific
4685 user options for Fortran 95 files.
4686 You should normally set the $FORTRANFLAGS variable,
4687 which specifies the user-specified options
4688 passed to the default Fortran compiler
4689 for all Fortran versions.
4692 An automatically-generated construction variable
4693 containing the Fortran 95 compiler command-line options
4694 for specifying directories to be searched for include files.
4695 The value of $_F95INCFLAGS is created
4696 by appending $INCPREFIX and $INCSUFFIX
4697 to the beginning and end
4698 of each directory in $F95PATH.
4701 The list of directories that the Fortran 95 compiler will search for include
4702 directories. The implicit dependency scanner will search these
4703 directories for include files. Don't explicitly put include directory
4704 arguments in $F95FLAGS because the result will be non-portable
4705 and the directories will not be searched by the dependency scanner. Note:
4706 directory names in $F95PATH will be looked-up relative to the SConscript
4707 directory when they are used in a command. To force
4709 to look-up a directory relative to the root of the source tree use #:
4710 You only need to set $F95PATH if you need to define a specific
4711 include path for Fortran 95 files.
4712 You should normally set the $FORTRANPATH variable,
4713 which specifies the include path
4714 for the default Fortran compiler
4715 for all Fortran versions.
4718 env = Environment(F95PATH='#/include')
4722 The directory look-up can also be forced using the
4727 include = Dir('include')
4728 env = Environment(F95PATH=include)
4732 The directory list will be added to command lines
4733 through the automatically-generated
4735 construction variable,
4736 which is constructed by
4737 appending the values of the
4738 $INCPREFIX and $INCSUFFIX
4739 construction variables
4740 to the beginning and end
4741 of each directory in $F95PATH.
4742 Any command lines you define that need
4743 the F95PATH directory list should
4744 include $_F95INCFLAGS:
4747 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
4751 The command line used to compile a Fortran 95 source file to an object file
4752 after first running the file through the C preprocessor.
4753 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
4754 are included on this command line.
4755 You only need to set $F95PPCOM if you need to use a specific
4756 C-preprocessor command line for Fortran 95 files.
4757 You should normally set the $FORTRANPPCOM variable,
4758 which specifies the default C-preprocessor command line
4759 for all Fortran versions.
4762 The default Fortran compiler
4763 for all versions of Fortran.
4766 The command line used to compile a Fortran source file to an object file.
4767 By default, any options specified
4768 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
4769 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
4770 are included on this command line.
4773 General user-specified options that are passed to the Fortran compiler.
4774 Note that this variable does
4778 (or similar) include or module search path options
4779 that scons generates automatically from $FORTRANPATH.
4781 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
4783 for the variables that expand those options.
4785 .IP _FORTRANINCFLAGS
4786 An automatically-generated construction variable
4787 containing the Fortran compiler command-line options
4788 for specifying directories to be searched for include
4789 files and module files.
4790 The value of $_FORTRANINCFLAGS is created
4791 by prepending/appending $INCPREFIX and $INCSUFFIX
4792 to the beginning and end
4793 of each directory in $FORTRANPATH.
4796 Directory location where the Fortran compiler should place
4797 any module files it generates. This variable is empty, by default. Some
4798 Fortran compilers will internally append this directory in the search path
4799 for module files, as well
4801 .IP FORTRANMODDIRPREFIX
4802 The prefix used to specify a module directory on the Fortran compiler command
4804 This will be appended to the beginning of the directory
4805 in the $FORTRANMODDIR construction variables
4806 when the $_FORTRANMODFLAG variables is automatically generated.
4808 .IP FORTRANMODDIRSUFFIX
4809 The suffix used to specify a module directory on the Fortran compiler command
4811 This will be appended to the beginning of the directory
4812 in the $FORTRANMODDIR construction variables
4813 when the $_FORTRANMODFLAG variables is automatically generated.
4816 An automatically-generated construction variable
4817 containing the Fortran compiler command-line option
4818 for specifying the directory location where the Fortran
4819 compiler should place any module files that happen to get
4820 generated during compilation.
4821 The value of $_FORTRANMODFLAG is created
4822 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
4823 to the beginning and end of the directory in $FORTRANMODDIR.
4825 .IP FORTRANMODPREFIX
4826 The module file prefix used by the Fortran compiler. SCons assumes that
4827 the Fortran compiler follows the quasi-standard naming convention for
4829 .I <module_name>.mod.
4830 As a result, this variable is left empty, by default. For situations in
4831 which the compiler does not necessarily follow the normal convention,
4832 the user may use this variable. Its value will be appended to every
4833 module file name as scons attempts to resolve dependencies.
4835 .IP FORTRANMODSUFFIX
4836 The module file suffix used by the Fortran compiler. SCons assumes that
4837 the Fortran compiler follows the quasi-standard naming convention for
4839 .I <module_name>.mod.
4840 As a result, this variable is set to ".mod", by default. For situations
4841 in which the compiler does not necessarily follow the normal convention,
4842 the user may use this variable. Its value will be appended to every
4843 module file name as scons attempts to resolve dependencies.
4846 The list of directories that the Fortran compiler will search for
4847 include files and (for some compilers) module files. The Fortran implicit
4848 dependency scanner will search these directories for include files (but
4849 not module files since they are autogenerated and, as such, may not
4850 actually exist at the time the scan takes place). Don't explicitly put
4851 include directory arguments in FORTRANFLAGS because the result will be
4852 non-portable and the directories will not be searched by the dependency
4853 scanner. Note: directory names in FORTRANPATH will be looked-up relative
4854 to the SConscript directory when they are used in a command. To force
4856 to look-up a directory relative to the root of the source tree use #:
4859 env = Environment(FORTRANPATH='#/include')
4863 The directory look-up can also be forced using the
4868 include = Dir('include')
4869 env = Environment(FORTRANPATH=include)
4873 The directory list will be added to command lines
4874 through the automatically-generated
4876 construction variable,
4877 which is constructed by
4878 appending the values of the
4879 $INCPREFIX and $INCSUFFIX
4880 construction variables
4881 to the beginning and end
4882 of each directory in $FORTRANPATH.
4883 Any command lines you define that need
4884 the FORTRANPATH directory list should
4885 include $_FORTRANINCFLAGS:
4888 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
4892 The command line used to compile a Fortran source file to an object file
4893 after first running the file through the C preprocessor.
4894 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
4895 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
4896 construction variables are included on this command line.
4899 The list of suffixes of files that will be scanned
4900 for Fortran implicit dependencies
4901 (INCLUDE lines & USE statements).
4902 The default list is:
4905 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
4906 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
4910 A function that converts a file name into a File instance relative to the
4914 The Ghostscript program used to convert PostScript to PDF files.
4917 General options passed to the Ghostscript program
4918 when converting PostScript to PDF files.
4921 The Ghostscript command line used to convert PostScript to PDF files.
4924 The list of suffixes of files that will be scanned
4925 for IDL implicit dependencies
4926 (#include or import lines).
4927 The default list is:
4934 The prefix used to specify an include directory on the C compiler command
4936 This will be appended to the beginning of each directory
4937 in the $CPPPATH and $FORTRANPATH construction variables
4938 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
4939 variables are automatically generated.
4942 The suffix used to specify an include directory on the C compiler command
4944 This will be appended to the end of each directory
4945 in the $CPPPATH and $FORTRANPATH construction variables
4946 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
4947 variables are automatically generated.
4950 A function to be called to install a file into a
4951 destination file name.
4952 The default function copies the file into the destination
4953 (and sets the destination file's mode and permission bits
4954 to match the source file's).
4955 The function takes the following arguments:
4958 def install(dest, source, env):
4962 is the path name of the destination file.
4964 is the path name of the source file.
4966 is the construction environment
4967 (a dictionary of construction values)
4968 in force for this file installation.
4971 The Java archive tool.
4974 The directory to which the Java archive tool should change
4980 The command line used to call the Java archive tool.
4983 General options passed to the Java archive tool.
4984 By default this is set to
4986 to create the necessary
4991 The suffix for Java archives:
4999 The command line used to compile a directory tree containing
5000 Java source files to
5001 corresponding Java class files.
5002 Any options specified in the $JAVACFLAGS construction variable
5003 are included on this command line.
5006 General options that are passed to the Java compiler.
5009 The directory in which Java class files may be found.
5010 This is stripped from the beginning of any Java .class
5011 file names supplied to the
5016 The suffix for Java class files;
5021 The Java generator for C header and stub files.
5024 The command line used to generate C header and stub files
5026 Any options specified in the $JAVAHFLAGS construction variable
5027 are included on this command line.
5030 General options passed to the C header and stub file generator
5034 The suffix for Java files;
5039 The LaTeX structured formatter and typesetter.
5042 The command line used to call the LaTeX structured formatter and typesetter.
5045 General options passed to the LaTeX structured formatter and typesetter.
5048 The lexical analyzer generator.
5051 General options passed to the lexical analyzer generator.
5054 The command line used to call the lexical analyzer generator
5055 to generate a source file.
5058 An automatically-generated construction variable
5059 containing the linker command-line options
5060 for specifying directories to be searched for library.
5061 The value of $_LIBDIRFLAGS is created
5062 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5063 to the beginning and end
5064 of each directory in $LIBPATH.
5067 The prefix used to specify a library directory on the linker command line.
5068 This will be appended to the beginning of each directory
5069 in the $LIBPATH construction variable
5070 when the $_LIBDIRFLAGS variable is automatically generated.
5073 The suffix used to specify a library directory on the linker command line.
5074 This will be appended to the end of each directory
5075 in the $LIBPATH construction variable
5076 when the $_LIBDIRFLAGS variable is automatically generated.
5079 An automatically-generated construction variable
5080 containing the linker command-line options
5081 for specifying libraries to be linked with the resulting target.
5082 The value of $_LIBFLAGS is created
5083 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5084 to the beginning and end
5085 of each directory in $LIBS.
5088 The prefix used to specify a library to link on the linker command line.
5089 This will be appended to the beginning of each library
5090 in the $LIBS construction variable
5091 when the $_LIBFLAGS variable is automatically generated.
5094 The suffix used to specify a library to link on the linker command line.
5095 This will be appended to the end of each library
5096 in the $LIBS construction variable
5097 when the $_LIBFLAGS variable is automatically generated.
5100 The list of directories that will be searched for libraries.
5101 The implicit dependency scanner will search these
5102 directories for include files. Don't explicitly put include directory
5103 arguments in $LINKFLAGS or $SHLINKFLAGS
5104 because the result will be non-portable
5105 and the directories will not be searched by the dependency scanner. Note:
5106 directory names in LIBPATH will be looked-up relative to the SConscript
5107 directory when they are used in a command. To force
5109 to look-up a directory relative to the root of the source tree use #:
5112 env = Environment(LIBPATH='#/libs')
5116 The directory look-up can also be forced using the
5122 env = Environment(LIBPATH=libs)
5126 The directory list will be added to command lines
5127 through the automatically-generated
5129 construction variable,
5130 which is constructed by
5131 appending the values of the
5132 $LIBDIRPREFIX and $LIBDIRSUFFIX
5133 construction variables
5134 to the beginning and end
5135 of each directory in $LIBPATH.
5136 Any command lines you define that need
5137 the LIBPATH directory list should
5138 include $_LIBDIRFLAGS:
5141 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5145 The prefix used for (static) library file names.
5146 A default value is set for each platform
5147 (posix, win32, os2, etc.),
5148 but the value is overridden by individual tools
5149 (ar, mslib, sgiar, sunar, tlib, etc.)
5150 to reflect the names of the libraries they create.
5153 An array of legal prefixes for library file names.
5156 A list of one or more libraries
5157 that will be linked with
5158 any executable programs
5159 created by this environment.
5162 The library list will be added to command lines
5163 through the automatically-generated
5165 construction variable,
5166 which is constructed by
5167 appending the values of the
5168 $LIBLINKPREFIX and $LIBLINKSUFFIX
5169 construction variables
5170 to the beginning and end
5171 of each directory in $LIBS.
5172 Any command lines you define that need
5173 the LIBS library list should
5177 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5181 The suffix used for (static) library file names.
5182 A default value is set for each platform
5183 (posix, win32, os2, etc.),
5184 but the value is overridden by individual tools
5185 (ar, mslib, sgiar, sunar, tlib, etc.)
5186 to reflect the names of the libraries they create.
5189 An array of legal suffixes for library file names.
5195 General user options passed to the linker.
5196 Note that this variable should
5200 (or similar) options for linking with the libraries listed in $LIBS,
5203 (or similar) library search path options
5204 that scons generates automatically from $LIBPATH.
5208 for the variable that expands to library-link options,
5212 for the variable that expands to library search path options.
5215 The command line used to link object files into an executable.
5218 The M4 macro preprocessor.
5221 General options passed to the M4 macro preprocessor.
5224 The command line used to pass files through the macro preprocessor.
5227 The maximum number of characters allowed on an external command line.
5229 link lines longer than this many characters
5230 are linke via a temporary file name.
5233 When the Microsoft Visual Studio tools are initialized, they set up
5234 this dictionary with the following keys:
5237 the version of MSVS being used (can be set via
5241 the available versions of MSVS installed
5244 installed directory of Visual C++
5247 installed directory of Visual Studio
5250 installed directory of the .NET framework
5252 .B FRAMEWORKVERSIONS:
5253 list of installed versions of the .NET framework, sorted latest to oldest.
5255 .B FRAMEWORKVERSION:
5256 latest installed version of the .NET framework
5259 installed location of the .NET SDK.
5262 installed location of the Platform SDK.
5264 .B PLATFORMSDK_MODULES:
5265 dictionary of installed Platform SDK modules,
5266 where the dictionary keys are keywords for the various modules, and
5267 the values are 2-tuples where the first is the release date, and the
5268 second is the version number.
5270 If a value isn't set, it wasn't available in the registry.
5272 .IP MSVS_IGNORE_IDE_PATHS
5273 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5274 instead of the settings from the IDE.
5276 For Visual Studio, SCons will (by default) automatically determine
5277 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5278 set by the IDE. You can override this behavior by setting these
5279 variables after Environment initialization, or by setting
5280 .B MSVS_IGNORE_IDE_PATHS = 1
5281 in the Environment initialization.
5282 Specifying this will not leave these unset, but will set them to a
5283 minimal set of paths needed to run the tools successfully.
5286 For VS6, the mininimal set is:
5287 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5288 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5289 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5291 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5292 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5293 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5297 Where '<VSDir>' is the installed location of Visual Studio.
5299 .IP MSVS_USE_MFC_DIRS
5300 Tells the MS Visual Studio tool(s) to use
5301 the MFC directories in its default paths
5302 for compiling and linking.
5303 Under MSVS version 6,
5305 .B MSVS_USE_MFC_DIRS
5314 external environment variable,
5320 external environment variable.
5321 Under MSVS version 7,
5323 .B MSVS_USE_MFC_DIRS
5327 directory to the default
5329 external environment variable,
5332 directory to the default
5334 external environment variable.
5335 The current default value is
5337 which means these directories
5338 are added to the paths by default.
5339 This default value is likely to change
5340 in a future release,
5341 so users who want the ATL and MFC
5342 values included in their paths
5343 are encouraged to enable the
5344 .B MSVS_USE_MFC_DIRS
5346 to avoid future incompatibility.
5347 This variable has no effect if the
5351 environment variables are set explictly.
5354 Sets the preferred version of MSVS to use.
5356 SCons will (by default) select the latest version of MSVS
5357 installed on your machine. So, if you have version 6 and version 7
5358 (MSVS .NET) installed, it will prefer version 7. You can override this by
5361 variable in the Environment initialization, setting it to the
5362 appropriate version ('6.0' or '7.0', for example).
5363 If the given version isn't installed, tool initialization will fail.
5366 The action used to generate Microsoft Visual Studio
5367 project and solution files.
5369 .IP MSVSPROJECTSUFFIX
5370 The suffix used for Microsoft Visual Studio project (DSP) files.
5371 The default value is
5373 when using Visual Studio version 7.x (.NET),
5376 when using earlier versions of Visual Studio.
5378 .IP MSVSSOLUTIONSUFFIX
5379 The suffix used for Microsoft Visual Studio solution (DSW) files.
5380 The default value is
5382 when using Visual Studio version 7.x (.NET),
5385 when using earlier versions of Visual Studio.
5388 When set to non-zero,
5389 suppresses creation of a corresponding Win32 static import lib by the
5391 builder when used with
5392 MinGW or Microsoft Visual Studio.
5393 This also suppresses creation
5394 of an export (.exp) file
5395 when using Microsoft Visual Studio.
5398 The prefix used for (static) object file names.
5401 The suffix used for (static) object file names.
5404 The Perforce executable.
5407 The command line used to
5408 fetch source files from Perforce.
5411 General options that are passed to Perforce.
5414 The Microsoft Visual C++ precompiled header that will be used when compiling
5415 object files. This variable is ignored by tools other than Microsoft Visual C++.
5416 When this variable is
5417 defined SCons will add options to the compiler command line to
5418 cause it to use the precompiled header, and will also set up the
5419 dependencies for the PCH file. Example:
5422 env['PCH'] = 'StdAfx.pch'
5426 This variable specifies how much of a source file is precompiled. This
5427 variable is ignored by tools other than Microsoft Visual C++, or when
5428 the PCH variable is not being used. When this variable is define it
5429 must be a string that is the name of the header that
5430 is included at the end of the precompiled portion of the source files, or
5431 the empty string if the "#pragma hrdstop" construct is being used:
5434 env['PCHSTOP'] = 'StdAfx.h'
5438 The Microsoft Visual C++ PDB file that will store debugging information for
5439 object files, shared libraries, and programs. This variable is ignored by
5440 tools other than Microsoft Visual C++.
5441 When this variable is
5442 defined SCons will add options to the compiler and linker command line to
5443 cause them to generate external debugging information, and will also set up the
5444 dependencies for the PDB file. Example:
5447 env['PDB'] = 'hello.pdb'
5451 A deprecated synonym for $DVIPDFCOM.
5454 The prefix used for PDF file names.
5457 The suffix used for PDF file names.
5460 The name of the platform used to create the Environment. If no platform is
5461 specified when the Environment is created,
5463 autodetects the platform.
5466 env = Environment(tools = [])
5467 if env['PLATFORM'] == 'cygwin':
5474 The prefix used for executable file names.
5477 The suffix used for executable file names.
5480 The command line used to convert TeX DVI files into a PostScript file.
5483 The prefix used for PostScript file names.
5486 The prefix used for PostScript file names.
5489 The qt tool tries to take this from os.environ.
5490 It also initializes all QT_*
5491 construction variables listed below.
5492 (Note that all paths are constructed
5493 with python's os.path.join() method,
5494 but are listed here with the '/' separator
5495 for easier reading.)
5496 In addition, the construction environment
5497 variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5498 are modified. Because the build-performance is affected when using this tool,
5499 you have to explicitly specify it at Environment creation:
5502 Environment(tools=['default','qt'])
5505 The qt tool supports the following operations:
5507 .B Automatic moc file generation from header files.
5508 You do not have to specify moc files explicitly, the tool does it for you.
5509 However, there are a few preconditions to do so: Your header file must have
5510 the same filebase as your implementation file and must stay in the same
5511 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
5512 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
5513 See also the corresponding builder method
5516 .B Automatic moc file generation from cxx files.
5517 As stated in the qt documentation, include the moc file at the end of
5518 the cxx file. Note that you have to include the file, which is generated
5519 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
5520 <basename>.moc. A warning is generated after building the moc file, if you
5521 do not include the correct file. If you are using BuildDir, you may
5522 need to specify duplicate=1. You can turn off automatic moc file generation
5523 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
5526 .B Automatic handling of .ui files.
5527 The implementation files generated from .ui files are handled much the same
5528 as yacc or lex files. Each .ui file given as a source of Program, Library or
5529 SharedLibrary will generate three files, the declaration file, the
5530 implementation file and a moc file. Because there are also generated headers,
5531 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
5535 Turn off scanning for mocable files. Use the Moc Builder to explicitely
5536 specify files to run moc on.
5539 Prints lots of debugging information while scanning for moc files.
5542 Default value is 'qt'. You may want to set this to 'qt-mt'.
5545 Default value is '$QTDIR/bin/moc'.
5548 Default value is ''. Prefix for moc output files, when source is a cxx file.
5551 Default value is '.moc'. Suffix for moc output files, when source is a cxx
5554 .IP QT_MOCFROMCPPFLAGS
5555 Default value is '-i'. These flags are passed to moc, when moccing a
5558 .IP QT_MOCFROMCXXCOM
5559 Command to generate a moc file from a cpp file.
5562 Command to generate a moc file from a header.
5564 .IP QT_MOCFROMHFLAGS
5565 Default value is ''. These flags are passed to moc, when moccing a header
5569 Default value is 'moc_'. Prefix for moc output files, when source is a header.
5572 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
5576 Default value is '$QTDIR/bin/uic'.
5579 Command to generate header files from .ui files.
5582 Default value is ''. These flags are passed to uic, when creating a a h
5583 file from a .ui file.
5585 .IP QT_UICDECLPREFIX
5586 Default value is ''. Prefix for uic generated header files.
5588 .IP QT_UICDECLSUFFIX
5589 Default value is '.h'. Suffix for uic generated header files.
5592 Command to generate cxx files from .ui files.
5595 Default value is ''. These flags are passed to uic, when creating a cxx
5596 file from a .ui file.
5598 .IP QT_UICIMPLPREFIX
5599 Default value is 'uic_'. Prefix for uic generated implementation files.
5601 .IP QT_UICIMPLSUFFIX
5602 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
5606 Default value is '.ui'. Suffix of designer input files.
5609 The archive indexer.
5612 General options passed to the archive indexer.
5615 The resource compiler used by the RES builder.
5618 The command line used by the RES builder.
5621 The flags passed to the resource compiler by the RES builder.
5625 Note that this variable is not actually used
5626 for the command to fetch source files from RCS;
5629 construction variable, below.
5632 The RCS "checkout" executable,
5633 used to fetch source files from RCS.
5636 The command line used to
5637 fetch (checkout) source files from RCS.
5640 Options that are passed to the $RCS_CO command.
5643 A function that converts a file name into a list of Dir instances by
5644 searching the repositories.
5647 The Java RMI stub compiler.
5650 The command line used to compile stub
5651 and skeleton class files
5652 from Java classes that contain RMI implementations.
5653 Any options specified in the $RMICFLAGS construction variable
5654 are included on this command line.
5657 General options passed to the Java RMI stub compiler.
5660 A list of paths to search for shared libraries when running programs.
5661 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
5662 Ignored on platforms and toolchains that don't support it.
5663 Note that the paths added to RPATH
5664 are not transformed by
5666 in any way: if you want an absolute
5667 path, you must make it absolute yourself.
5670 A list of the available implicit dependency scanners.
5671 New file scanners may be added by
5672 appending to this list,
5673 although the more flexible approach
5674 is to associate scanners
5675 with a specific Builder.
5676 See the sections "Builder Objects"
5677 and "Scanner Objects,"
5678 below, for more information.
5681 The SCCS executable.
5684 The command line used to
5685 fetch source files from SCCS.
5688 General options that are passed to SCCS.
5691 Options that are passed specifically to the SCCS "get" subcommand.
5692 This can be set, for example, to
5694 to check out editable files from SCCS.
5697 The C compiler used for generating shared-library objects.
5700 The command line used to compile a C source file
5701 to a shared-library object file.
5702 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
5703 are included on this command line.
5706 Options that are passed to the C compiler
5707 to generate shared-library objects.
5710 The C++ compiler used for generating shared-library objects.
5713 The command line used to compile a C++ source file
5714 to a shared-library object file.
5715 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
5716 are included on this command line.
5719 Options that are passed to the C++ compiler
5720 to generate shared-library objects.
5723 A string naming the shell program that will be passed to the
5728 construction variable for more information.
5731 The Fortran 77 compiler used for generating shared-library objects.
5732 You should normally set the $SHFORTRANC variable,
5733 which specifies the default Fortran compiler
5734 for all Fortran versions.
5735 You only need to set $SHF77 if you need to use a specific compiler
5736 or compiler version for Fortran 77 files.
5739 The command line used to compile a Fortran 77 source file
5740 to a shared-library object file.
5741 You only need to set $SHF77COM if you need to use a specific
5742 command line for Fortran 77 files.
5743 You should normally set the $SHFORTRANCOM variable,
5744 which specifies the default command line
5745 for all Fortran versions.
5748 Options that are passed to the Fortran 77 compiler
5749 to generated shared-library objects.
5750 You only need to set $SHF77FLAGS if you need to define specific
5751 user options for Fortran 77 files.
5752 You should normally set the $SHFORTRANFLAGS variable,
5753 which specifies the user-specified options
5754 passed to the default Fortran compiler
5755 for all Fortran versions.
5758 The command line used to compile a Fortran 77 source file to a
5759 shared-library object file
5760 after first running the file through the C preprocessor.
5761 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
5762 are included on this command line.
5763 You only need to set $SHF77PPCOM if you need to use a specific
5764 C-preprocessor command line for Fortran 77 files.
5765 You should normally set the $SHFORTRANPPCOM variable,
5766 which specifies the default C-preprocessor command line
5767 for all Fortran versions.
5770 The Fortran 90 compiler used for generating shared-library objects.
5771 You should normally set the $SHFORTRANC variable,
5772 which specifies the default Fortran compiler
5773 for all Fortran versions.
5774 You only need to set $SHF90 if you need to use a specific compiler
5775 or compiler version for Fortran 90 files.
5778 The command line used to compile a Fortran 90 source file
5779 to a shared-library object file.
5780 You only need to set $SHF90COM if you need to use a specific
5781 command line for Fortran 90 files.
5782 You should normally set the $SHFORTRANCOM variable,
5783 which specifies the default command line
5784 for all Fortran versions.
5787 Options that are passed to the Fortran 90 compiler
5788 to generated shared-library objects.
5789 You only need to set $SHF90FLAGS if you need to define specific
5790 user options for Fortran 90 files.
5791 You should normally set the $SHFORTRANFLAGS variable,
5792 which specifies the user-specified options
5793 passed to the default Fortran compiler
5794 for all Fortran versions.
5797 The command line used to compile a Fortran 90 source file to a
5798 shared-library object file
5799 after first running the file through the C preprocessor.
5800 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
5801 are included on this command line.
5802 You only need to set $SHF90PPCOM if you need to use a specific
5803 C-preprocessor command line for Fortran 90 files.
5804 You should normally set the $SHFORTRANPPCOM variable,
5805 which specifies the default C-preprocessor command line
5806 for all Fortran versions.
5809 The Fortran 95 compiler used for generating shared-library objects.
5810 You should normally set the $SHFORTRANC variable,
5811 which specifies the default Fortran compiler
5812 for all Fortran versions.
5813 You only need to set $SHF95 if you need to use a specific compiler
5814 or compiler version for Fortran 95 files.
5817 The command line used to compile a Fortran 95 source file
5818 to a shared-library object file.
5819 You only need to set $SHF95COM if you need to use a specific
5820 command line for Fortran 95 files.
5821 You should normally set the $SHFORTRANCOM variable,
5822 which specifies the default command line
5823 for all Fortran versions.
5826 Options that are passed to the Fortran 95 compiler
5827 to generated shared-library objects.
5828 You only need to set $SHF95FLAGS if you need to define specific
5829 user options for Fortran 95 files.
5830 You should normally set the $SHFORTRANFLAGS variable,
5831 which specifies the user-specified options
5832 passed to the default Fortran compiler
5833 for all Fortran versions.
5836 The command line used to compile a Fortran 95 source file to a
5837 shared-library object file
5838 after first running the file through the C preprocessor.
5839 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
5840 are included on this command line.
5841 You only need to set $SHF95PPCOM if you need to use a specific
5842 C-preprocessor command line for Fortran 95 files.
5843 You should normally set the $SHFORTRANPPCOM variable,
5844 which specifies the default C-preprocessor command line
5845 for all Fortran versions.
5848 The default Fortran compiler used for generating shared-library objects.
5851 The command line used to compile a Fortran source file
5852 to a shared-library object file.
5855 Options that are passed to the Fortran compiler
5856 to generate shared-library objects.
5859 The command line used to compile a Fortran source file to a
5860 shared-library object file
5861 after first running the file through the C preprocessor.
5862 Any options specified
5863 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
5864 are included on this command line.
5867 The prefix used for shared library file names.
5870 The suffix used for shared library file names.
5873 The linker for programs that use shared libraries.
5876 General user options passed to the linker for programs using shared libraries.
5877 Note that this variable should
5881 (or similar) options for linking with the libraries listed in $LIBS,
5884 (or similar) include search path options
5885 that scons generates automatically from $LIBPATH.
5889 for the variable that expands to library-link options,
5893 for the variable that expands to library search path options.
5896 The prefix used for shared object file names.
5899 The suffix used for shared object file names.
5902 A reserved variable name
5903 that may not be set or used in a construction environment.
5904 (See "Variable Substitution," below.)
5907 A reserved variable name
5908 that may not be set or used in a construction environment.
5909 (See "Variable Substitution," below.)
5912 A command interpreter function that will be called to execute command line
5913 strings. The function must expect 4 arguments:
5916 def spawn(shell, escape, cmd, args, env):
5920 is a string naming the shell program to use.
5922 is a function that can be called to escape shell special characters in
5925 is the path to the command to be executed.
5927 is that arguments to the command.
5929 is a dictionary of the environment variables
5930 in which the command should be executed.
5933 '\"The Subversion executable (usually named
5937 '\"The command line used to
5938 '\"fetch source files from a Subversion repository.
5941 '\"General options that are passed to Subversion.
5944 The scripting language wrapper and interface generator.
5947 The suffix that will be used for intermediate C
5948 source files generated by
5949 the scripting language wrapper and interface generator.
5950 The default value is
5951 .BR _wrap$CFILESUFFIX .
5952 By default, this value is used whenever the
5956 specified as part of the
5958 construction variable.
5961 The command line used to call
5962 the scripting language wrapper and interface generator.
5964 .IP SWIGCXXFILESUFFIX
5965 The suffix that will be used for intermediate C++
5966 source files generated by
5967 the scripting language wrapper and interface generator.
5968 The default value is
5969 .BR _wrap$CFILESUFFIX .
5970 By default, this value is used whenever the
5972 option is specified as part of the
5974 construction variable.
5977 General options passed to
5978 the scripting language wrapper and interface generator.
5979 This is where you should set
5983 or whatever other options you want to specify to SWIG.
5986 option in this variable,
5989 generate a C++ intermediate source file
5990 with the extension that is specified as the
5998 The command line used to call the tar archiver.
6001 General options passed to the tar archiver.
6004 A reserved variable name
6005 that may not be set or used in a construction environment.
6006 (See "Variable Substitution," below.)
6009 A reserved variable name
6010 that may not be set or used in a construction environment.
6011 (See "Variable Substitution," below.)
6014 The suffix used for tar file names.
6017 The TeX formatter and typesetter.
6020 The command line used to call the TeX formatter and typesetter.
6023 General options passed to the TeX formatter and typesetter.
6026 A list of the names of the Tool specifications
6027 that are part of this construction environment.
6029 .IP WIN32_INSERT_DEF
6030 When this is set to true,
6031 a library build of a WIN32 shared library (.dll file)
6032 will also build a corresponding .def file at the same time,
6033 if a .def file is not already listed as a build target.
6034 The default is 0 (do not build a .def file).
6037 The prefix used for WIN32 .def file names.
6040 The suffix used for WIN32 .def file names.
6043 The parser generator.
6046 The command line used to call the parser generator
6047 to generate a source file.
6050 General options passed to the parser generator.
6051 If $YACCFLAGS contains a \-d option,
6052 SCons assumes that the call will also create a .h file
6053 (if the yacc source file ends in a .y suffix)
6055 (if the yacc source file ends in a .yy suffix)
6058 The zip compression and file packaging utility.
6061 The command line used to call the zip utility,
6062 or the internal Python function used to create a
6071 module used by the internal Python function
6072 to control whether the zip archive
6073 is compressed or not.
6074 The default value is
6075 .BR zipfile.ZIP_DEFLATED ,
6076 which creates a compressed zip archive.
6077 This value has no effect when using Python 1.5.2
6080 module is otherwise unavailable.
6083 General options passed to the zip utility.
6086 Construction variables can be retrieved and set using the
6088 method of the construction environment:
6091 dict = env.Dictionary()
6095 or using the [] operator:
6101 Construction variables can also be passed to the construction environment
6105 env = Environment(CC="cc")
6108 or when copying a construction environment using the
6113 env2 = env.Copy(CC="cl.exe")
6116 .SS Configure Contexts
6120 .I configure contexts,
6121 an integrated mechanism similar to the
6122 various AC_CHECK macros in GNU autoconf
6123 for testing for the existence of C header
6124 files, libraries, etc.
6125 In contrast to autoconf,
6127 does not maintain an explicit cache of the tested values,
6128 but uses its normal dependency tracking to keep the checked values
6130 The following methods can be used to perform checks:
6133 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
6135 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
6136 This creates a configure context, which can be used to perform checks.
6138 specifies the environment for building the tests.
6139 This environment may be modified when performing checks.
6141 is a dictionary containing custom tests.
6142 See also the section about custom tests below.
6143 By default, no custom tests are added to the configure context.
6145 specifies a directory where the test cases are built.
6146 Note that this directory is not used for building
6148 The default value is the directory
6151 specifies a file which collects the output from commands
6152 that are executed to check for the existence of header files, libraries, etc.
6153 The default is the file #/config.log.
6154 If you are using the
6157 you may want to specify a subdirectory under your build directory.
6162 instance has the following associated methods:
6165 .RI Configure.Finish( self )
6166 This method should be called after configuration is done.
6167 It returns the environment as modified
6168 by the configuration checks performed.
6169 After this method is called, no further checks can be performed
6170 with this configuration context.
6171 However, you can create a new
6173 context to perform additional checks.
6174 Only one context should be active at a time.
6176 The following Checks are predefined.
6177 (This list will likely grow larger as time
6178 goes by and developers contribute new useful tests.)
6181 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6184 is usable in the specified language.
6187 in which case the last item in the list
6188 is the header file to be checked,
6189 and the previous list items are
6192 lines should precede the
6193 header line being checked for.
6194 The optional argument
6197 a two character string, where the first character denotes the opening
6198 quote and the second character denotes the closing quote.
6199 By default, both characters are " (double quote).
6200 The optional argument
6206 and selects the compiler to be used for the check.
6207 Returns 1 on success and 0 on failure.
6210 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6211 This is a wrapper around
6212 .B Configure.CheckHeader
6215 is usable in the C language.
6218 in which case the last item in the list
6219 is the header file to be checked,
6220 and the previous list items are
6223 lines should precede the
6224 header line being checked for.
6225 The optional argument
6228 a two character string, where the first character denotes the opening
6229 quote and the second character denotes the closing quote (both default
6231 Returns 1 on success and 0 on failure.
6234 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6235 This is a wrapper around
6236 .B Configure.CheckHeader
6239 is usable in the C++ language.
6242 in which case the last item in the list
6243 is the header file to be checked,
6244 and the previous list items are
6247 lines should precede the
6248 header line being checked for.
6249 The optional argument
6252 a two character string, where the first character denotes the opening
6253 quote and the second character denotes the closing quote (both default
6255 Returns 1 on success and 0 on failure.
6258 .RI Configure.CheckFunc( self ", " function_name ", [" language ])
6259 Checks if the specified
6260 C or C+++ function is available.
6262 is the name of the function to check for.
6269 and selects the compiler to be used for the check;
6273 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
6280 is 1 and the library provides the specified
6282 appends the library to the LIBS construction environment variable.
6284 may also be None (the default),
6287 is checked with the current LIBS variable,
6288 or a list of library names,
6289 in which case each library in the list
6296 you can link against the specified
6304 and selects the compiler to be used for the check;
6306 The default value for
6309 It is assumed, that the C-language is used.
6310 This method returns 1 on success and 0 on error.
6313 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
6316 .RI Configure.CheckLib
6317 call, this call provides a more sophisticated way to check against libraries.
6320 specifies the library or a list of libraries to check.
6322 specifies a header to check for.
6325 in which case the last item in the list
6326 is the header file to be checked,
6327 and the previous list items are
6330 lines should precede the
6331 header line being checked for.
6333 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6335 can be any valid expression (with a trailing ';'). The default is 'main();'.
6337 specifies whether to add the library to the environment (only if the check
6338 succeeds). This method returns 1 on success and 0 on error.
6341 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
6342 Checks for the existence of a type defined by
6345 specifies the typedef name to check for.
6347 is a string containing one or more
6349 lines that will be inserted into the program
6350 that will be run to test for the existence of the type.
6357 and selects the compiler to be used for the check;
6361 Example of a typical Configure usage:
6365 conf = Configure( env )
6366 if not conf.CheckCHeader( 'math.h' ):
6367 print 'We really need math.h!'
6369 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6370 # do stuff for qt - usage, e.g.
6371 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6376 You can define your own custom checks.
6377 in addition to the predefined checks.
6378 These are passed in a dictionary to the Configure function.
6379 This dictionary maps the names of the checks
6380 to user defined Python callables
6381 (either Python functions or class instances implementing the
6384 The first argument of the call is always a
6386 instance followed by the arguments,
6387 which must be supplied by the user of the check.
6388 These CheckContext instances define the following methods:
6391 .RI CheckContext.Message( self ", " text )
6393 Usually called before the check is started.
6395 will be displayed to the user, e.g. 'Checking for library X...'
6398 .RI CheckContext.Result( self, ", " res )
6400 Usually called after the check is done.
6402 can be either an integer or a string. In the former case, 'ok' (res != 0)
6403 or 'failed' (res == 0) is displayed to the user, in the latter case the
6404 given string is displayed.
6407 .RI CheckContext.TryCompile( self ", " text ", " extension )
6408 Checks if a file with the specified
6410 (e.g. '.c') containing
6412 can be compiled using the environment's
6414 builder. Returns 1 on success and 0 on failure.
6417 .RI CheckContext.TryLink( self ", " text ", " extension )
6418 Checks, if a file with the specified
6420 (e.g. '.c') containing
6422 can be compiled using the environment's
6424 builder. Returns 1 on success and 0 on failure.
6427 .RI CheckContext.TryRun( self ", " text ", " extension )
6428 Checks, if a file with the specified
6430 (e.g. '.c') containing
6432 can be compiled using the environment's
6434 builder. On success, the program is run. If the program
6435 executes successfully
6436 (that is, its return status is 0),
6441 is the standard output of the
6443 If the program fails execution
6444 (its return status is non-zero),
6445 then (0, '') is returned.
6448 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
6449 Checks if the specified
6451 with an optional source file (contents
6458 may be anything which can be converted to a
6465 is the content of the target file.
6471 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
6472 Low level implementation for testing specific builds;
6473 the methods above are based on this method.
6474 Given the Builder instance
6478 of a source file with optional
6480 this method returns 1 on success and 0 on failure. In addition,
6482 is set to the build target node, if the build was successful.
6485 Example for implementing and using custom tests:
6488 def CheckQt(context, qtdir):
6489 context.Message( 'Checking for qt ...' )
6490 lastLIBS = context.env['LIBS']
6491 lastLIBPATH = context.env['LIBPATH']
6492 lastCPPPATH= context.env['CPPPATH']
6493 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
6494 ret = context.TryLink("""
6496 int main(int argc, char **argv) {
6497 QApplication qapp(argc, argv);
6502 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
6503 context.Result( ret )
6507 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
6508 if not conf.CheckQt('/usr/lib/qt'):
6509 print 'We really need qt!'
6514 .SS Construction Variable Options
6516 Often when building software, various options need to be specified at build
6517 time that are not known when the SConstruct/SConscript files are
6518 written. For example, libraries needed for the build may be in non-standard
6519 locations, or site-specific compiler options may need to be passed to the
6522 provides a mechanism for overridding construction variables from the
6523 command line or a text-based SConscript file through an Options
6524 object. To create an Options object, call the Options() function:
6527 .RI Options([ files "], [" args ])
6528 This creates an Options object that will read construction variables from
6529 the file or list of filenames specified in
6531 If no files are specified,
6536 then no files will be read.
6537 The optional argument
6540 values that will override anything read from the specified files;
6541 it is primarily intended to be passed the
6543 dictionary that holds variables
6544 specified on the command line.
6548 opts = Options('custom.py')
6549 opts = Options('overrides.py', ARGUMENTS)
6550 opts = Options(None, {FOO:'expansion', BAR:7})
6553 Options objects have the following methods:
6556 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
6557 This adds a customizable construction variable to the Options object.
6559 is the name of the variable.
6561 is the help text for the variable.
6563 is the default value of the variable.
6565 is called to validate the value of the variable, and should take three
6566 arguments: key, value, and environment
6568 is called to convert the value before putting it in the environment, and
6569 should take a single argument: value. Example:
6572 opts.Add('CC', 'The C compiler')
6576 .RI AddOptions( list )
6577 A wrapper script that adds
6578 multiple customizable construction variables
6579 to an Options object.
6581 is a list of tuple or list objects
6582 that contain the arguments
6583 for an individual call to the
6590 ('CC', 'The C compiler'),
6591 ('VALIDATE', 'An option for testing validation',
6592 'notset', validator, None),
6597 .RI Update( env ", [" args ])
6598 This updates a construction environment
6600 with the customized construction variables. Normally this method is not
6601 called directly, but is called indirectly by passing the Options object to
6602 the Environment() function:
6605 env = Environment(options=opts)
6609 .RI Save( filename ", " env )
6610 This saves the currently set options into a script file named
6612 that can be used on the next invocation to automatically load the current
6613 settings. This method combined with the Options method can be used to
6614 support caching of options between runs.
6618 opts = Options(['options.cache', 'custom.py'])
6621 opts.Save('options.cache', env)
6625 .RI GenerateHelpText( env ", [" sort ])
6626 This generates help text documenting the customizable construction
6627 variables suitable to passing in to the Help() function.
6629 is the construction environment that will be used to get the actual values
6630 of customizable variables. Calling with
6634 will cause the output to be sorted
6635 by the specified argument.
6639 should take two arguments
6642 (like the standard Python
6647 Help(opts.GenerateHelpText(env))
6648 Help(opts.GenerateHelpText(env, sort=cmp))
6651 The text based SConscript file is executed as a Python script, and the
6652 global variables are queried for customizable construction
6659 To make it more convenient to work with customizable Options,
6661 provides a number of functions
6662 that make it easy to set up
6663 various types of Options:
6666 .RI BoolOption( key ", " help ", " default )
6667 Return a tuple of arguments
6668 to set up a Boolean option.
6672 have a default value of
6674 and display the specified
6677 The option will interpret the values
6699 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
6700 Return a tuple of arguments
6702 whose value may be one
6703 of a specified list of legal enumerated values.
6707 have a default value of
6709 and display the specified
6712 The option will only support those
6718 argument is a dictionary
6719 that can be used to convert
6720 input values into specific legal values
6729 then the values are case-sensitive.
6734 then values will be matched
6740 then values will be matched
6742 and all input values will be
6743 converted to lower case.
6746 .RI ListOption( key ", " help ", " default ", " names )
6747 Return a tuple of arguments
6749 whose value may be one or more
6750 of a specified list of legal enumerated values.
6754 have a default value of
6756 and display the specified
6759 The option will only support the values
6762 or the values in the
6765 More than one value may be specified,
6766 with all values separated by commas.
6769 .RI PackageOption( key ", " help ", " default )
6770 Return a tuple of arguments
6772 whose value is a path name
6773 of a package that may be
6774 enabled, disabled or
6775 given an explicit path name.
6779 have a default value of
6781 and display the specified
6784 The option will support the values
6791 in which case the specified
6794 or the option may be set to an
6796 (typically the path name to a package
6797 that is being enabled).
6798 The option will also support the values
6804 to disable use of the specified option.
6807 .RI PathOption( key ", " help ", " default )
6808 Return a tuple of arguments
6810 whose value is expected to be a path name.
6814 have a default value of
6816 and display the specified
6821 These functions make it
6822 convenient to create a number
6823 of options with consistent behavior
6824 in a single call to the
6830 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
6831 EnumOption('debug', 'debug output and symbols', 'no'
6832 allowed_values=('yes', 'no', 'full'),
6833 map={}, ignorecase=0), # case sensitive
6834 ListOption('shared',
6835 'libraries to build as shared libraries',
6837 names = list_of_libs),
6838 PackageOption('x11',
6839 'use X11 installed here (yes = search some places)',
6841 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
6848 can be extended to build different types of targets
6849 by adding new Builder objects
6850 to a construction environment.
6852 you should only need to add a new Builder object
6853 when you want to build a new type of file or other external target.
6854 If you just want to invoke a different compiler or other tool
6855 to build a Program, Object, Library, or any other
6856 type of output file for which
6858 already has an existing Builder,
6859 it is generally much easier to
6860 use those existing Builders
6861 in a construction environment
6862 that sets the appropriate construction variables
6865 Builder objects are created
6871 function accepts the following arguments:
6874 The command line string used to build the target from the source.
6877 a list of strings representing the command
6878 to be executed and its arguments
6879 (suitable for enclosing white space in an argument),
6881 mapping source file name suffixes to
6882 any combination of command line strings
6883 (if the builder should accept multiple source file extensions),
6886 (see the next section);
6887 or a list of any of the above.
6890 takes three arguments:
6892 - a list of source nodes,
6894 - a list of target nodes,
6896 - the construction environment.
6899 The prefix that will be prepended to the target file name.
6900 This may be a simple string, or a callable object that takes
6901 two arguments, a construction environment and a list of sources,
6902 and returns a prefix.
6905 b = Builder("build_it < $SOURCE > $TARGET"
6908 def gen_prefix(env, sources):
6909 return "file-" + env['PLATFORM'] + '-'
6910 b = Builder("build_it < $SOURCE > $TARGET"
6911 prefix = gen_prefix)
6915 The suffix that will be appended to the target file name.
6916 This may be a simple string, or a callable object that takes
6917 two arguments, a construction environment and a list of sources,
6918 and returns a suffix.
6919 If the suffix is a string, then
6921 will append a '.' to the beginning of the
6922 suffix if it's not already there.
6923 The string returned by callable object
6924 is untouched and must append its own '.'
6925 to the beginning if one is desired.
6928 b = Builder("build_it < $SOURCE > $TARGET"
6931 def gen_suffix(env, sources):
6932 return "." + env['PLATFORM'] + "-file"
6933 b = Builder("build_it < $SOURCE > $TARGET"
6934 suffix = gen_suffix)
6938 The expected source file name suffix.
6941 A Scanner object that
6942 will be invoked to find
6943 implicit dependencies for this target file.
6944 This keyword argument should be used
6945 for Scanner objects that find
6946 implicit dependencies
6947 based only on the target file
6948 and the construction environment,
6951 (See the section "Scanner Objects," below,
6952 for information about creating Scanner objects.)
6955 A Scanner object that
6957 find implicit dependences in
6959 used to build this target file.
6960 This is where you would
6961 specify a scanner to
6964 lines in source files.
6965 (See the section "Scanner Objects," below,
6966 for information about creating Scanner objects.)
6969 A factory function that the Builder will use
6970 to turn any targets specified as strings into SCons Nodes.
6972 SCons assumes that all targets are files.
6973 Other useful target_factory
6976 for when a Builder creates a directory target,
6979 for when a Builder can create either a file
6980 or directory target.
6985 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
6987 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
6988 env.MakeDirectory('new_directory')
6992 A factory function that the Builder will use
6993 to turn any sources specified as strings into SCons Nodes.
6995 SCons assumes that all source are files.
6996 Other useful source_factory
6999 for when a Builder uses a directory as a source,
7002 for when a Builder can use files
7003 or directories (or both) as sources.
7008 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7010 env.Append(BUILDERS = {'Collect':CollectBuilder})
7011 env.Collect('archive', ['directory_name', 'file_name'])
7015 A function or list of functions to manipulate the target and source
7016 lists before dependencies are established
7017 and the target(s) are actually built.
7019 can also be a string containing a construction variable to expand
7020 to an emitter function or list of functions,
7021 or a dictionary mapping source file suffixes
7022 to emitter functions.
7023 (Only the suffix of the first source file
7024 is used to select the actual emitter function
7025 from an emitter dictionary.)
7028 takes three arguments:
7030 - a list of source nodes,
7032 - a list of target nodes,
7034 - the construction environment.
7035 An emitter must return a tuple containing two lists,
7036 the list of targets to be built by this builder,
7037 and the list of sources for this builder.
7042 def e(target, source, env):
7043 return (target + ['foo.foo'], source + ['foo.src'])
7045 # Simple association of an emitter function with a Builder.
7046 b = Builder("my_build < $TARGET > $SOURCE",
7049 def e2(target, source, env):
7050 return (target + ['bar.foo'], source + ['bar.src'])
7052 # Simple association of a list of emitter functions with a Builder.
7053 b = Builder("my_build < $TARGET > $SOURCE",
7056 # Calling an emitter function through a construction variable.
7057 env = Environment(MY_EMITTER = e)
7058 b = Builder("my_build < $TARGET > $SOURCE",
7059 emitter = '$MY_EMITTER')
7061 # Calling a list of emitter functions through a construction variable.
7062 env = Environment(EMITTER_LIST = [e, e2])
7063 b = Builder("my_build < $TARGET > $SOURCE",
7064 emitter = '$EMITTER_LIST')
7066 # Associating multiple emitters with different file
7067 # suffixes using a dictionary.
7068 def e_suf1(target, source, env):
7069 return (target + ['another_target_file'], source)
7070 def e_suf2(target, source, env):
7071 return (target, source + ['another_source_file'])
7072 b = Builder("my_build < $TARGET > $SOURCE",
7073 emitter = {'.suf1' : e_suf1,
7081 arguments must not both be used for the same Builder.
7084 Specifies whether this builder is allowed to be called multiple times for
7085 the same target file(s). The default is 0, which means the builder
7086 can not be called multiple times for the same target file(s). Calling a
7087 builder multiple times for the same target simply adds additional source
7088 files to the target; it is not allowed to change the environment associated
7089 with the target, specify addition environment overrides, or associate a different
7090 builder with the target.
7093 A construction environment that can be used
7094 to fetch source code using this Builder.
7095 (Note that this environment is
7097 used for normal builds of normal target files,
7098 which use the environment that was
7099 used to call the Builder for the target file.)
7102 A function that returns a list of actions that will be executed to build
7103 the target(s) from the source(s).
7104 The returned action(s) may be
7105 an Action object, or anything that
7106 can be converted into an Action object
7107 (see the next section).
7109 The generator function
7110 takes four arguments:
7112 - a list of source nodes,
7114 - a list of target nodes,
7116 - the construction environment,
7118 - a Boolean value that specifies
7119 whether the generator is being called
7120 for generating a build signature
7121 (as opposed to actually executing the command).
7125 def g(source, target, env, for_signature):
7126 return [["gcc", "-c", "-o"] + target + source]
7128 b = Builder(generator=g)
7132 Specifies a builder to use when a source file name suffix does not match
7133 any of the suffixes of the builder. Using this argument produces a
7134 multi-stage builder.
7137 Specifies that this builder expects exactly one source file per call. Giving
7138 more than one source files without target files results in implicitely calling
7139 the builder multiple times (once for each source given). Giving multiple
7140 source files together with target files results in a UserError exception.
7148 arguments must not both be used for the same Builder.
7151 A construction environment that can be used
7152 to fetch source code using this Builder.
7153 (Note that this environment is
7155 used for normal builds of normal target files,
7156 which use the environment that was
7157 used to call the Builder for the target file.)
7160 b = Builder(action="build < $SOURCE > $TARGET")
7161 env = Environment(BUILDERS = {'MyBuild' : b})
7162 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
7166 Any additional keyword arguments supplied
7167 when a Builder object is created
7168 (that is, when the Builder() function is called)
7169 will be set in the executing construction
7170 environment when the Builder object is called.
7171 The canonical example here would be
7172 to set a construction variable to
7173 the repository of a source code system.
7175 Any additional keyword arguments supplied
7179 will only be associated with the target
7180 created by that particular Builder call
7181 (and any other files built as a
7182 result of the call).
7184 These extra keyword arguments are passed to the
7185 following functions:
7186 command generator functions,
7188 and emitter functions.
7194 function will turn its
7196 keyword argument into an appropriate
7197 internal Action object.
7198 You can also explicity create Action objects
7202 which can then be passed to the
7205 This can be used to configure
7206 an Action object more flexibly,
7207 or it may simply be more efficient
7208 than letting each separate Builder object
7209 create a separate Action
7211 Builder objects need to do the same thing.
7216 returns an appropriate object for the action
7217 represented by the type of the first argument:
7220 If the first argument is already an Action object,
7221 the object is simply returned.
7224 If the first argument is a string,
7225 a command-line Action is returned.
7228 Action('$CC -c -o $TARGET $SOURCES')
7231 .\" XXX From Gary Ruben, 23 April 2002:
7232 .\" What would be useful is a discussion of how you execute command
7233 .\" shell commands ie. what is the process used to spawn the shell, pass
7234 .\" environment variables to it etc., whether there is one shell per
7235 .\" environment or one per command etc. It might help to look at the Gnu
7236 .\" make documentation to see what they think is important to discuss about
7237 .\" a build system. I'm sure you can do a better job of organising the
7238 .\" documentation than they have :-)
7242 If the first argument is a list,
7243 then a list of Action objects is returned.
7244 An Action object is created as necessary
7245 for each element in the list.
7248 the list is itself a list,
7249 the internal list is the
7250 command and arguments to be executed via
7252 This allows white space to be enclosed
7253 in an argument by defining
7254 a command in a list within a list:
7257 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7261 If the first argument is a Python function,
7262 a function Action is returned.
7263 The Python function takes three keyword arguments,
7265 (a Node object representing the target file),
7267 (a Node object representing the source file)
7270 (the construction environment
7271 used for building the target file).
7276 arguments may be lists of Node objects if there is
7277 more than one target file or source file.
7278 The actual target and source file name(s) may
7279 be retrieved from their Node objects
7280 via the built-in Python str() function:
7283 target_file_name = str(target)
7284 source_file_names = map(lambda x: str(x), source)
7287 The function should return
7291 to indicate a successful build of the target file(s).
7292 The function may raise an exception
7293 or return a non-zero exit status
7294 to indicate an unsuccessful build.
7297 def build_it(target = None, source = None, env = None):
7298 # build the target from the source
7301 a = Action(build_it)
7304 The second, optional argument
7305 is a Python function that returns
7306 a string to be printed to describe the action being executed.
7307 Like a function to build a file,
7308 this function takes three arguments:
7310 (a Node object representing the target file),
7312 (a Node object representing the source file)
7315 (a construction environment).
7320 arguments may be lists of Node objects if there is
7321 more than one target file or source file.
7325 def build_it(target, source, env):
7326 # build the target from the source
7329 def string_it(target, source, env):
7330 return "building '%s' from '%s'" % (target[0], source[0])
7332 # Use a positional argument.
7333 a = Action(build_it, string_it)
7335 # Alternatively, use a keyword argument.
7336 a = Action(build_it, strfunction=string_it)
7339 The third, also optional argument
7340 is a list of construction variables
7341 whose values will be included
7342 in the signature of the Action
7343 when deciding whether a target should
7344 be rebuilt because the action changed.
7345 This is necessary whenever you want a target to
7346 be rebuilt when a specific
7347 construction variable changes,
7348 because the underlying Python code for a function
7349 will not change when the value of the construction variable does.
7352 def build_it(target, source, env):
7353 # build the target from the 'XXX' construction variable
7354 open(target[0], 'w').write(env['XXX'])
7357 def string_it(target, source):
7358 return "building '%s' from '%s'" % (target[0], source[0])
7360 # Use positional arguments.
7361 a = Action(build_it, string_it, ['XXX'])
7363 # Alternatively, use a keyword argument.
7364 a = Action(build_it, varlist=['XXX'])
7367 If the action argument is not one of the above,
7370 .SS Miscellaneous Action Functions
7373 supplies a number of functions
7374 that arrange for various common
7375 file and directory manipulations
7377 These are similar in concept to "tasks" in the
7379 although the implementation is slightly different.
7380 These functions do not actually
7381 perform the specified action
7382 at the time the function is called,
7383 but instead return an Action object
7384 that can be executed at the
7386 (In Object-Oriented terminology,
7391 that return Action objects.)
7394 there are two natural ways
7397 are intended to be used.
7401 to perform the action
7402 at the time the SConscript
7406 global function to do so:
7408 Execute(Touch('file'))
7412 you can use these functions
7413 to supply Actions in a list
7417 This can allow you to
7418 perform more complicated
7419 sequences of file manipulation
7421 on platform-specific
7425 env = Environment(TMPBUILD = '/tmp/builddir')
7426 env.Command('foo.out', 'foo.in',
7427 [Mkdir('$TMPBUILD'),
7428 Copy('${SOURCE.dir}', '$TMPBUILD')
7429 "cd $TMPBUILD && make",
7430 Delete('$TMPBUILD')])
7434 .RI Chmod( dest ", " mode )
7435 Returns an Action object that
7436 changes the permissions on the specified
7438 file or directory to the specified
7443 Execute(Chmod('file', 0755))
7445 env.Command('foo.out', 'foo.in',
7446 [Copy('$TARGET', '$SOURCE'),
7447 Chmod('$TARGET', 0755)])
7451 .RI Copy( dest ", " src )
7452 Returns an Action object
7455 source file or directory to the
7457 destination file or directory.
7461 Execute(Copy('foo.output', 'foo.input'))
7463 env.Command('bar.out', 'bar.in',
7464 Copy('$TARGET', '$SOURCE'))
7469 Returns an Action that
7470 deletes the specified
7472 which may be a file or a directory tree.
7473 If a directory is specified,
7474 the entire directory tree
7479 Execute(Delete('/tmp/buildroot'))
7481 env.Command('foo.out', 'foo.in',
7482 [Delete('${TARGET.dir}'),
7489 that creates the specified
7495 Execute(Mkdir('/tmp/outputdir'))
7497 env.Command('foo.out', 'foo.in',
7498 [Mkdir('/tmp/builddir',
7499 Copy('$SOURCE', '/tmp/builddir')
7500 "cd /tmp/builddir && ])
7505 .RI Move( dest ", " src )
7507 that moves the specified
7509 file or directory to
7516 Execute(Move('file.destination', 'file.source'))
7518 env.Command('output_file', 'input_file',
7520 Move('$TARGET', 'file_created_by_MyBuildAction')])
7526 that updates the modification time
7532 Execute(Touch('file_to_be_touched'))
7534 env.Command('marker', 'input_file',
7539 .SS Variable Substitution
7541 Before executing a command,
7543 performs construction variable interpolation on the strings that make up
7544 the command line of builders.
7545 Variables are introduced by a
7548 Besides construction variables, scons provides the following
7549 variables for each command execution:
7552 The file name of the target being built, or the file name of the first
7553 target if multiple targets are being built.
7556 The file names of all targets being built.
7559 The file name of the source of the build command, or the file name of the
7560 first source if multiple sources are being built.
7563 The file names of the sources of the build command.
7565 (Note that the above variables are reserved
7566 and may not be set in a construction environment.)
7569 For example, given the construction variable CC='cc', targets=['foo'], and
7570 sources=['foo.c', 'bar.c']:
7573 action='$CC -c -o $TARGET $SOURCES'
7576 would produce the command line:
7579 cc -c -o foo foo.c bar.c
7582 Variable names may be surrounded by curly braces ({})
7583 to separate the name from the trailing characters.
7584 Within the curly braces, a variable name may have
7585 a Python slice subscript appended to select one
7586 or more items from a list.
7587 In the previous example, the string:
7599 Additionally, a variable name may
7600 have the following special
7601 modifiers appended within the enclosing curly braces
7602 to modify the interpolated string:
7605 The base path of the file name,
7606 including the directory path
7607 but excluding any suffix.
7610 The name of the directory in which the file exists.
7614 minus any directory portion.
7617 Just the basename of the file,
7619 and minus the directory.
7622 Just the file suffix.
7625 The absolute path name of the file.
7628 The POSIX form of the path,
7629 with directories separated by
7633 This is sometimes necessary on Win32 systems
7634 when a path references a file on other (POSIX) systems.
7637 The directory and file name to the source file linked to this file
7638 through BuildDir. If this file isn't linked, it just returns the
7639 directory and filename unchanged.
7642 The directory containing the source file linked to this file
7643 through BuildDir. If this file isn't linked, it just returns the
7644 directory part of the filename.
7647 The directory and file name to the source file linked to this file
7648 through BuildDir. If the file does not exist locally but exists in
7649 a Repository, the path in the Repository is returned.
7650 If this file isn't linked, it just returns the
7651 directory and filename unchanged.
7654 The Repository directory containing the source file linked to this file
7655 through BuildDir. If this file isn't linked, it just returns the
7656 directory part of the filename.
7659 For example, the specified target will
7660 expand as follows for the corresponding modifiers:
7663 $TARGET => sub/dir/file.x
7664 ${TARGET.base} => sub/dir/file
7665 ${TARGET.dir} => sub/dir
7666 ${TARGET.file} => file.x
7667 ${TARGET.filebase} => file
7668 ${TARGET.suffix} => .x
7669 ${TARGET.abspath} => /top/dir/sub/dir/file.x
7671 BuildDir('sub/dir','src')
7672 $SOURCE => sub/dir/file.x
7673 ${SOURCE.srcpath} => src/file.x
7674 ${SOURCE.srcdir} => src
7676 Repository('/usr/repository')
7677 $SOURCE => sub/dir/file.x
7678 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
7679 ${SOURCE.rsrcdir} => /usr/repository/src
7682 Lastly, a variable name
7683 may be a callable Python function
7685 construction variable in the environment.
7687 take four arguments:
7689 - a list of target nodes,
7691 - a list of source nodes,
7693 - the construction environment,
7695 - a Boolean value that specifies
7696 whether the function is being called
7697 for generating a build signature.
7698 SCons will insert whatever
7699 the called function returns
7700 into the expanded string:
7703 def foo(target, source, env, for_signature):
7706 # Will expand $BAR to "bar baz"
7707 env=Environment(FOO=foo, BAR="$FOO baz")
7710 You can use this feature to pass arguments to a
7711 Python function by creating a callable class
7712 that stores one or more arguments in an object,
7713 and then uses them when the
7716 Note that in this case,
7717 the entire variable expansion must
7718 be enclosed by curly braces
7719 so that the arguments will
7720 be associated with the
7721 instantiation of the class:
7725 def __init__(self, arg):
7728 def __call__(self, target, source, env, for_signature):
7731 # Will expand $BAR to "my argument bar baz"
7732 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
7736 The special pseudo-variables
7740 may be used to surround parts of a command line
7743 causing a rebuild--that is,
7744 which are not included in the signature
7745 of target files built with this command.
7750 will be removed from the command line
7751 before it is added to file signatures,
7756 will be removed before the command is executed.
7757 For example, the command line:
7760 echo Last build occurred $( $TODAY $). > $TARGET
7764 would execute the command:
7767 echo Last build occurred $TODAY. > $TARGET
7771 but the command signature added to any target files would be:
7774 echo Last build occurred . > $TARGET
7777 SCons uses the following rules when converting construction variables into
7781 When the value is a string it is interpreted as a space delimited list of
7782 command line arguments.
7785 When the value is a list it is interpreted as a list of command line
7786 arguments. Each element of the list is converted to a string.
7789 Anything that is not a list or string is converted to a string and
7790 interpreted as a single command line argument.
7793 Newline characters (\\n) delimit lines. The newline parsing is done after
7794 all other parsing, so it is not possible for arguments (e.g. file names) to
7795 contain embedded newline characters. This limitation will likely go away in
7796 a future version of SCons.
7804 new file types for implicit dependencies.
7805 Scanner accepts the following arguments:
7808 A Python function that will process
7810 and return a list of strings (file names)
7811 representing the implicit
7812 dependencies found in the contents.
7813 The function takes three or four arguments:
7815 def scanner_function(node, env, path):
7817 def scanner_function(node, env, path, arg):
7821 argument is the internal
7822 SCons node representing the file.
7825 to fetch the name of the file, and
7826 .B node.get_contents()
7827 to fetch contents of the file.
7831 argument is the construction environment for the scan.
7832 Fetch values from it using the
7838 argument is a tuple (or list)
7839 of directories that can be searched
7841 This will usually be the tuple returned by the
7843 argument (see below).
7847 argument is the argument supplied
7848 when the scanner was created, if any.
7851 The name of the Scanner.
7853 to identify the Scanner internally.
7856 An optional argument that, if specified,
7857 will be passed to the scanner function
7859 and the path function
7863 An optional list that can be used to
7864 determine which scanner should be used for
7866 In the usual case of scanning for file names,
7867 this argument will be a list of suffixes
7868 for the different file types that this
7869 Scanner knows how to scan.
7870 If the argument is a string,
7871 then it will be expanded
7872 into a list by the current environment.
7875 A Python function that takes
7876 two or three arguments:
7877 a construction environment, directory Node,
7878 and optional argument supplied
7879 when the scanner was created.
7882 returns a tuple of directories
7883 that can be searched for files to be returned
7884 by this Scanner object.
7887 The class of Node that should be returned
7888 by this Scanner object.
7889 Any strings or other objects returned
7890 by the scanner function
7891 that are not of this class
7892 will be run through the
7897 A Python function that will take a string
7899 and turn it into the appropriate class of Node
7900 to be returned by this Scanner object.
7903 An optional Python function that takes two arguments,
7904 a Node (file) and a construction environment,
7905 and returns whether the
7906 Node should, in fact,
7907 be scanned for dependencies.
7908 This check can be used to eliminate unnecessary
7909 calls to the scanner function when,
7910 for example, the underlying file
7911 represented by a Node does not yet exist.
7914 An optional flag that
7915 specifies whether this scanner should be re-invoked
7916 on the dependency files returned by the scanner.
7917 When this flag is not set,
7918 the Node subsystem will
7919 only invoke the scanner on the file being scanned,
7920 and not (for example) also on the files
7921 specified by the #include lines
7922 in the file being scanned.
7924 .SH SYSTEM-SPECIFIC BEHAVIOR
7925 SCons and its configuration files are very portable,
7926 due largely to its implementation in Python.
7927 There are, however, a few portability
7928 issues waiting to trap the unwary.
7930 SCons handles the upper-case
7932 file suffix differently,
7933 depending on the capabilities of
7934 the underlying system.
7935 On a case-sensitive system
7936 such as Linux or UNIX,
7937 SCons treats a file with a
7939 suffix as a C++ source file.
7940 On a case-insensitive system
7942 SCons treats a file with a
7944 suffix as a C source file.
7946 SCons handles the upper-case
7948 file suffix differently,
7949 depending on the capabilities of
7950 the underlying system.
7951 On a case-sensitive system
7952 such as Linux or UNIX,
7953 SCons treats a file with a
7955 suffix as a Fortran source file
7956 that is to be first run through
7957 the standard C preprocessor.
7958 On a case-insensitive system
7960 SCons treats a file with a
7962 suffix as a Fortran source file that should
7964 be run through the C preprocessor.
7965 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
7966 Cygwin supplies a set of tools and utilities
7967 that let users work on a
7968 Windows system using a more POSIX-like environment.
7969 The Cygwin tools, including Cygwin Python,
7971 by sharing an ability to interpret UNIX-like path names.
7972 For example, the Cygwin tools
7973 will internally translate a Cygwin path name
7974 like /cygdrive/c/mydir
7975 to an equivalent Windows pathname
7976 of C:/mydir (equivalent to C:\\mydir).
7979 that are built for native Windows execution,
7980 such as the python.org and ActiveState versions,
7981 do not have the Cygwin path name semantics.
7982 This means that using a native Windows version of Python
7983 to build compiled programs using Cygwin tools
7984 (such as gcc, bison, and flex)
7985 may yield unpredictable results.
7986 "Mixing and matching" in this way
7987 can be made to work,
7988 but it requires careful attention to the use of path names
7989 in your SConscript files.
7991 In practice, users can sidestep
7992 the issue by adopting the following rules:
7994 use the Cygwin-supplied Python interpreter
7996 when using Microsoft Visual C/C++
7997 (or some other Windows compiler)
7998 use the python.org or ActiveState version of Python
8000 .SS WIN32: scons.bat file
8002 SCons is executed via a wrapper
8005 This has (at least) two ramifications:
8007 First, Windows command-line users
8008 that want to use variable assignment
8010 may have to put double quotes
8011 around the assignments:
8014 scons "FOO=BAR" "BAZ=BLEH"
8017 Second, the Cygwin shell does not
8018 recognize this file as being the same
8021 command issued at the command-line prompt.
8022 You can work around this either by
8025 from the Cygwin command line,
8026 or by creating a wrapper shell
8032 The MinGW bin directory must be in your PATH environment variable or the
8033 PATH variable under the ENV construction variable for SCons
8034 to detect and use the MinGW tools. When running under the native Windows
8035 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8036 tools, if they are both installed, regardless of the order of the bin
8037 directories in the PATH variable. If you have both MSVC and MinGW
8038 installed and you want to use MinGW instead of MSVC,
8039 then you must explictly tell SCons to use MinGW by passing
8045 to the Environment() function, because SCons will prefer the MSVC tools
8046 over the MinGW tools.
8050 To help you get started using SCons,
8051 this section contains a brief overview of some common tasks.
8053 .SS Basic Compilation From a Single Source File
8057 env.Program(target = 'foo', source = 'foo.c')
8060 Note: Build the file by specifying
8061 the target as an argument
8062 ("scons foo" or "scons foo.exe").
8063 or by specifying a dot ("scons .").
8065 .SS Basic Compilation From Multiple Source Files
8069 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8072 .SS Setting a Compilation Flag
8075 env = Environment(CCFLAGS = '-g')
8076 env.Program(target = 'foo', source = 'foo.c')
8079 .SS Search The Local Directory For .h Files
8083 need to set CCFLAGS to specify -I options by hand.
8084 SCons will construct the right -I options from CPPPATH.
8087 env = Environment(CPPPATH = ['.'])
8088 env.Program(target = 'foo', source = 'foo.c')
8091 .SS Search Multiple Directories For .h Files
8094 env = Environment(CPPPATH = ['include1', 'include2'])
8095 env.Program(target = 'foo', source = 'foo.c')
8098 .SS Building a Static Library
8102 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8103 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8106 .SS Building a Shared Library
8110 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8111 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8114 .SS Linking a Local Library Into a Program
8117 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8118 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8119 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8122 .SS Defining Your Own Builder Object
8124 Notice that when you invoke the Builder,
8125 you can leave off the target file suffix,
8126 and SCons will add it automatically.
8129 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8131 src_suffix = '.tex')
8132 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8133 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8135 # The following creates "bar.pdf" from "bar.tex"
8136 env.PDFBuilder(target = 'bar', source = 'bar')
8139 Note also that the above initialization
8140 overwrites the default Builder objects,
8141 so the Environment created above
8142 can not be used call Builders like env.Program(),
8143 env.Object(), env.StaticLibrary(), etc.
8145 .SS Adding Your Own Builder Object to an Environment
8148 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8150 src_suffix = '.tex')
8152 env.Append(BUILDERS = {'PDFBuilder' : bld})
8153 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8154 env.Program(target = 'bar', source = 'bar.c')
8157 You also can use other Pythonic techniques to add
8158 to the BUILDERS construction variable, such as:
8162 env['BUILDERS]['PDFBuilder'] = bld
8165 .SS Defining Your Own Scanner Object
8170 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8172 def kfile_scan(node, env, path, arg):
8173 contents = node.get_contents()
8174 includes = include_re.findall(contents)
8177 kscan = Scanner(name = 'kfile',
8178 function = kfile_scan,
8181 scanners = Environment().Dictionary('SCANNERS')
8182 env = Environment(SCANNERS = scanners + [kscan])
8184 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8186 bar_in = File('bar.in')
8187 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8188 bar_in.target_scanner = kscan
8191 .SS Creating a Hierarchical Build
8193 Notice that the file names specified in a subdirectory's
8195 file are relative to that subdirectory.
8201 env.Program(target = 'foo', source = 'foo.c')
8203 SConscript('sub/SConscript')
8208 # Builds sub/foo from sub/foo.c
8209 env.Program(target = 'foo', source = 'foo.c')
8211 SConscript('dir/SConscript')
8216 # Builds sub/dir/foo from sub/dir/foo.c
8217 env.Program(target = 'foo', source = 'foo.c')
8220 .SS Sharing Variables Between SConscript Files
8222 You must explicitly Export() and Import() variables that
8223 you want to share between SConscript files.
8229 env.Program(target = 'foo', source = 'foo.c')
8232 SConscript('subdirectory/SConscript')
8234 subdirectory/SConscript:
8237 env.Program(target = 'foo', source = 'foo.c')
8240 .SS Building Multiple Variants From the Same Source
8242 Use the BuildDir() method to establish
8243 one or more separate build directories for
8244 a given source directory,
8245 then use the SConscript() method
8246 to specify the SConscript files
8247 in the build directories:
8254 BuildDir('foo', 'src')
8255 SConscript('foo/SConscript')
8259 BuildDir('bar', 'src')
8260 SConscript('bar/SConscript')
8265 env = Environment(CCFLAGS = ccflags)
8266 env.Program(target = 'src', source = 'src.c')
8269 Note the use of the Export() method
8270 to set the "ccflags" variable to a different
8271 value for each variant build.
8273 .SS Hierarchical Build of Two Libraries Linked With a Program
8278 env = Environment(LIBPATH = ['#libA', '#libB'])
8280 SConscript('libA/SConscript')
8281 SConscript('libB/SConscript')
8282 SConscript('Main/SConscript')
8287 env.Library('a', Split('a1.c a2.c a3.c'))
8292 env.Library('b', Split('b1.c b2.c b3.c'))
8297 e = env.Copy(LIBS = ['a', ','b'])
8298 e.Program('foo', Split('m1.c m2.c m3.c'))
8301 The '#' in the LIBPATH directories specify that they're relative to the
8302 top-level directory, so they don't turn into "Main/libA" when they're
8303 used in Main/SConscript.
8305 Specifying only 'a' and 'b' for the library names
8306 allows SCons to append the appropriate library
8307 prefix and suffix for the current platform
8308 (for example, 'liba.a' on POSIX systems,
8309 'a.lib' on Windows).
8311 .SS Customizing contruction variables from the command line.
8313 The following would allow the C compiler to be specified on the command
8314 line or in the file custom.py.
8317 opts = Options('custom.py')
8318 opts.Add('CC', 'The C compiler.')
8319 env = Environment(options=opts)
8320 Help(opts.GenerateHelpText(env))
8323 The user could specify the C compiler on the command line:
8329 or in the custom.py file:
8335 or get documentation on the options:
8346 .SS Using Microsoft Visual C++ precompiled headers
8348 Since windows.h includes everything and the kitchen sink, it can take quite
8349 some time to compile it over and over again for a bunch of object files, so
8350 Microsoft provides a mechanism to compile a set of headers once and then
8351 include the previously compiled headers in any object file. This
8352 technology is called precompiled headers. The general recipe is to create a
8353 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
8354 then include every header you want to precompile in "StdAfx.h", and finally
8355 include "StdAfx.h" as the first header in all the source files you are
8356 compiling to object files. For example:
8360 #include <windows.h>
8361 #include <my_big_header.h>
8380 /* do some other stuff */
8386 env['PCHSTOP'] = 'StdAfx.h'
8387 env['PCH'] = env.PCH('StdAfx.cpp')[0]
8388 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8391 For more information see the document for the PCH builder, and the PCH and
8392 PCHSTOP construction variables. To learn about the details of precompiled
8393 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
8395 .SS Using Microsoft Visual C++ external debugging information
8397 Since including debugging information in programs and shared libraries can
8398 cause their size to increase significantly, Microsoft provides a mechanism
8399 for including the debugging information in an external file called a PDB
8400 file. SCons supports PDB files through the PDB construction
8406 env['PDB'] = 'MyApp.pdb'
8407 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8410 For more information see the document for the PDB construction variable.
8415 Specifies the directory that contains the SCons Python module directory
8416 (e.g. /home/aroach/scons-src-0.01/src/engine).
8419 A string of options that will be used by scons in addition to those passed
8420 on the command line.
8431 Steven Knight <knight@baldmt.com>
8433 Anthony Roach <aroach@electriceyeball.com>