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 = ['default', 'foo'], toolpath = ['tools'])
951 This looks for a tool specification in tools/foo.py (as well as
952 using the ordinary default tools for the platform). foo.py should
953 have two functions: generate(env) and exists(env). generate()
954 modifies the passed in environment and exists() should return a true
955 value if the tool is available. Tools in the toolpath are used before
956 any of the built-in ones. For example, adding gcc.py to the toolpath
957 would override the built-in gcc tool.
959 The elements of the tools list may also
960 be functions or callable objects,
961 in which case the Environment() method
962 will call the specified elements
963 to update the new construction environment:
967 env['XYZZY'] = 'xyzzy'
969 env = Environment(tools = [my_tool])
972 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
973 the environment it receives to customize the tool for different platforms.
975 If no tool list is specified, then SCons will auto-detect the installed
976 tools using the PATH variable in the ENV construction variable and the
977 platform name when the Environment is constructed. Changing the PATH
978 variable after the Environment is constructed will not cause the tools to
981 SCons supports the following tool specifications out of the box:
1053 Additionally, there is a "tool" named
1055 which configures the
1056 environment with a default set of tools for the current platform.
1058 On posix and cygwin platforms
1059 the GNU tools (e.g. gcc) are preferred by SCons,
1060 on win32 the Microsoft tools (e.g. msvc)
1061 followed by MinGW are preferred by SCons,
1062 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1066 Build rules are specified by calling a construction
1067 environment's builder methods.
1068 The arguments to the builder methods are
1070 (a list of target files)
1073 (a list of source files).
1075 Because long lists of file names
1076 can lead to a lot of quoting,
1081 and a same-named environment method
1082 that split a single string
1083 into a list, separated on
1084 strings of white-space characters.
1085 (These are similar to the
1086 string.split() method
1087 from the standard Python library,
1088 but work even if the input isn't a string.)
1090 Like all Python arguments,
1091 the target and source arguments to a builder method
1092 can be specified either with or without
1093 the "target" and "source" keywords.
1094 When the keywords are omitted,
1095 the target is first,
1096 followed by the source.
1097 The following are equivalent examples of calling the Program builder method:
1100 env.Program('bar', ['bar.c', 'foo.c'])
1101 env.Program('bar', Split('bar.c foo.c'))
1102 env.Program('bar', env.Split('bar.c foo.c'))
1103 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1104 env.Program(target = 'bar', Split('bar.c foo.c'))
1105 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1106 env.Program('bar', source = string.split('bar.c foo.c'))
1109 When the target shares the same base name
1110 as the source and only the suffix varies,
1111 and if the builder method has a suffix defined for the target file type,
1112 then the target argument may be omitted completely,
1115 will deduce the target file name from
1116 the source file name.
1117 The following examples all build the
1123 (on Windows systems)
1124 from the bar.c source file:
1127 env.Program(target = 'bar', source = 'bar.c')
1128 env.Program('bar', source = 'bar.c')
1129 env.Program(source = 'bar.c')
1130 env.Program('bar.c')
1133 It is possible to override or add construction variables when calling a
1134 builder method by passing additional keyword arguments.
1135 These overridden or added
1136 variables will only be in effect when building the target, so they will not
1137 affect other parts of the build. For example, if you want to add additional
1138 libraries for just one program:
1141 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1144 or generate a shared library with a nonstandard suffix:
1147 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1150 Although the builder methods defined by
1153 methods of a construction environment object,
1154 they may also be called without an explicit environment:
1157 Program('hello', 'hello.c')
1158 SharedLibrary('word', 'word.cpp')
1162 the methods are called internally using a default construction
1163 environment that consists of the tools and values that
1165 has determined are appropriate for the local system.
1167 All builder methods return a list of Nodes
1168 that represent the target or targets that will be built.
1171 is an internal SCons object
1173 build targets or sources.
1175 The returned Node(s)
1176 can be passed to other builder methods as source(s)
1177 or passed to any SCons function or method
1178 where a filename would normally be accepted.
1179 For example, if it were necessary
1182 flag when compiling one specific object file:
1185 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1186 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1189 Using a Node in this way
1190 makes for a more portable build
1191 by avoiding having to specify
1192 a platform-specific object suffix
1193 when calling the Program() builder method.
1195 Note that Builder calls will automatically "flatten"
1196 the source and target file lists,
1197 so it's all right to have the bar_obj list
1198 return by the StaticObject() call
1199 in the middle of the source file list.
1200 If you need to manipulate a list of lists returned by Builders
1201 directly using Python,
1202 you can either build the list by hand:
1205 foo = Object('foo.c')
1206 bar = Object('bar.c')
1207 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1208 for object in objects:
1215 to create a list containing just the Nodes,
1216 which may be more convenient:
1219 foo = Object('foo.c')
1220 bar = Object('bar.c')
1221 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1222 for object in objects:
1226 The path name for a Node's file may be used
1227 by passing the Node to the Python-builtin
1232 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1233 print "The path to bar_obj is:", str(bar_obj_list[0])
1236 Note again that because the Builder call returns a list,
1237 we have to access the first element in the list
1238 .B (bar_obj_list[0])
1239 to get at the Node that actually represents
1243 provides the following builder methods:
1245 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1248 Builds a C source file given a lex (.l) or yacc (.y) input file.
1249 The suffix specified by the $CFILESUFFIX construction variable
1251 is automatically added to the target
1252 if it is not already present. Example:
1256 env.CFile(target = 'foo.c', source = 'foo.l')
1258 env.CFile(target = 'bar', source = 'bar.y')
1261 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1264 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1266 The suffix specified by the $CXXFILESUFFIX construction variable
1268 is automatically added to the target
1269 if it is not already present. Example:
1273 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1275 env.CXXFile(target = 'bar', source = 'bar.yy')
1278 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1281 Builds a .dvi file from a .tex, .ltx or .latex input file.
1282 If the source file suffix is .tex,
1284 will examine the contents of the file;
1289 is found, the file is assumed to be a LaTeX file and
1290 the target is built by invoking the $LATEXCOM command line;
1291 otherwise, the $TEXCOM command line is used.
1292 If the file is a LaTeX file,
1295 builder method will also examine the contents
1298 and invoke the $BIBTEX command line
1302 and will examine the contents
1304 file and re-run the $LATEXCOM command
1305 if the log file says it is necessary.
1308 (hard-coded within TeX itself)
1309 is automatically added to the target
1310 if it is not already present. Examples:
1313 # builds from aaa.tex
1314 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1316 env.DVI(target = 'bbb', source = 'bbb.ltx')
1317 # builds from ccc.latex
1318 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1321 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1324 Builds a Java archive (.jar) file
1325 from a source tree of .class files.
1326 If the $JARCHDIR value is set, the
1328 command will change to the specified directory using the
1331 If the contents any of the source files begin with the string
1332 .BR Manifest-Version ,
1333 the file is assumed to be a manifest
1334 and is passed to the
1341 env.Jar(target = 'foo.jar', source = 'classes')
1344 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1347 Builds one or more Java class files
1348 from one or more source trees of .java files.
1349 The class files will be placed underneath
1350 the specified target directory.
1351 SCons will parse each source .java file
1353 (including inner classes)
1354 defined within that file,
1355 and from that figure out the
1356 target .class files that will be created.
1357 SCons will also search each Java file
1358 for the Java package name,
1359 which it assumes can be found on a line
1360 beginning with the string
1362 in the first column;
1363 the resulting .class files
1364 will be placed in a directory reflecting
1365 the specified package name.
1369 defining a single public
1372 containing a package name of
1374 will generate a corresponding
1375 .IR sub/dir/Foo.class
1381 env.Java(target = 'classes', source = 'src')
1382 env.Java(target = 'classes', source = ['src1', 'src2'])
1385 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1388 Builds C header and source files for
1389 implementing Java native methods.
1390 The target can be either a directory
1391 in which the header files will be written,
1392 or a header file name which
1393 will contain all of the definitions.
1394 The source can be either the names of .class files,
1395 or the objects returned from the
1399 If the construction variable
1401 is set, either in the environment
1402 or in the call to the
1404 builder method itself,
1405 then the value of the variable
1406 will be stripped from the
1407 beginning of any .class file names.
1412 # builds java_native.h
1413 classes = env.Java(target = 'classdir', source = 'src')
1414 env.JavaH(target = 'java_native.h', source = classes)
1416 # builds include/package_foo.h and include/package_bar.h
1417 env.JavaH(target = 'include',
1418 source = ['package/foo.class', 'package/bar.class'])
1420 # builds export/foo.h and export/bar.h
1421 env.JavaH(target = 'export',
1422 source = ['classes/foo.class', 'classes/bar.class'],
1423 JAVACLASSDIR = 'classes')
1426 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1433 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1436 Builds an output file from an M4 input file.
1437 This uses a default $M4FLAGS value of
1439 which considers all warnings to be fatal
1440 and stops on the first warning
1441 when using the GNU version of m4.
1445 env.M4(target = 'foo.c', source = 'foo.c.m4')
1448 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1451 Builds an output file from a moc input file. Moc input files are either
1452 header files or cxx files. This builder is only available after using the
1453 tool 'qt'. See the QTDIR variable for more information.
1457 env.Moc('foo.h') # generates moc_foo.cc
1458 env.Moc('foo.cpp') # generates foo.moc
1461 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1463 .IP env.MSVSProject()
1464 Builds Microsoft Visual Studio project files.
1465 This builds a Visual Studio project file, based on the version of
1466 Visual Studio that is configured (either the latest installed version,
1467 or the version set by
1469 in the Environment constructor).
1470 For VS 6, it will generate
1474 files, for VS 7, it will
1481 It takes several lists of filenames to be placed into the project
1482 file, currently these are limited to
1483 .B srcs, incs, localincs, resources,
1486 These are pretty self explanatory, but it
1487 should be noted that the 'srcs' list is NOT added to the $SOURCES
1488 environment variable. This is because it represents a list of files
1489 to be added to the project file, not the source used to build the
1490 project file (in this case, the 'source' is the SConscript file used
1491 to call MSVSProject).
1493 In addition to these values (which are all optional, although not
1494 specifying any of them results in an empty project file), the
1495 following values must be specified:
1497 target: The name of the target .dsp or .vcproj file. The correct
1498 suffix for the version of Visual Studio must be used, but the value
1500 env['MSVSPROJECTSUFFIX']
1502 will be defined to the correct value (see example below).
1504 variant: The name of this particular variant. These are typically
1505 things like "Debug" or "Release", but really can be anything you want.
1506 Multiple calls to MSVSProject with different variants are allowed: all
1507 variants will be added to the project file with their appropriate
1508 build targets and sources.
1510 buildtarget: A list of SCons.Node.FS objects which is returned from
1511 the command which builds the target. This is used to tell SCons what
1512 to build when the 'build' button is pressed inside of the IDE.
1517 barsrcs = ['bar.cpp'],
1518 barincs = ['bar.h'],
1519 barlocalincs = ['StdAfx.h']
1520 barresources = ['bar.rc','resource.h']
1521 barmisc = ['bar_readme.txt']
1523 dll = local.SharedLibrary(target = 'bar.dll',
1526 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1529 localincs = barlocalincs,
1530 resources = barresources,
1533 variant = 'Release')
1536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1543 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1546 Builds a Microsoft Visual C++ precompiled header.
1547 Calling this builder method
1548 returns a list of two targets: the PCH as the first element, and the object
1549 file as the second element. Normally the object file is ignored.
1550 This builder method is only
1551 provided when Microsoft Visual C++ is being used as the compiler.
1552 The PCH builder method is generally used in
1553 conjuction with the PCH construction variable to force object files to use
1554 the precompiled header:
1557 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1560 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1563 Builds a .pdf file from a .dvi input file
1564 (or, by extension, a .tex, .ltx, or .latex input file).
1565 The suffix specified by the $PDFSUFFIX construction variable
1567 is added automatically to the target
1568 if it is not already present. Example:
1571 # builds from aaa.tex
1572 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1573 # builds bbb.pdf from bbb.dvi
1574 env.PDF(target = 'bbb', source = 'bbb.dvi')
1577 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1579 .IP env.PostScript()
1580 Builds a .ps file from a .dvi input file
1581 (or, by extension, a .tex, .ltx, or .latex input file).
1582 The suffix specified by the $PSSUFFIX construction variable
1584 is added automatically to the target
1585 if it is not already present. Example:
1588 # builds from aaa.tex
1589 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1590 # builds bbb.ps from bbb.dvi
1591 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1594 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1597 Builds an executable given one or more object files
1598 or C, C++, D, or Fortran source files.
1599 If any C, C++, D or Fortran source files are specified,
1600 then they will be automatically
1601 compiled to object files using the
1604 see that builder method's description for
1605 a list of legal source file suffixes
1606 and how they are interpreted.
1607 The target executable file prefix
1608 (specified by the $PROGPREFIX construction variable; nothing by default)
1610 (specified by the $PROGSUFFIX construction variable;
1611 by default, .exe on Windows systems, nothing on POSIX systems)
1612 are automatically added to the target if not already present.
1616 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1619 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1622 Builds a Microsoft Visual C++ resource file.
1623 This builder method is only provided
1624 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1628 for MinGW) suffix is added to the target name if no other suffix is given. The source
1629 file is scanned for implicit dependencies as though it were a C file. Example:
1632 env.RES('resource.rc')
1635 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1638 Builds stub and skeleton class files
1640 from Java .class files.
1641 The target is a directory
1642 relative to which the stub
1643 and skeleton class files will be written.
1644 The source can be the names of .class files,
1645 or the objects return from the
1649 If the construction variable
1651 is set, either in the environment
1652 or in the call to the
1654 builder method itself,
1655 then the value of the variable
1656 will be stripped from the
1657 beginning of any .class file names.
1660 classes = env.Java(target = 'classdir', source = 'src')
1661 env.RMIC(target = 'outdir1', source = classes)
1663 env.RMIC(target = 'outdir2',
1664 source = ['package/foo.class', 'package/bar.class'])
1666 env.RMIC(target = 'outdir3',
1667 source = ['classes/foo.class', 'classes/bar.class'],
1668 JAVACLASSDIR = 'classes')
1671 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1673 .IP env.SharedLibrary()
1674 Builds a shared library
1675 (.so on a POSIX system, .dll on WIN32)
1676 given one or more object files
1677 or C, C++, D or Fortran source files.
1678 If any source files are given,
1679 then they will be automatically
1680 compiled to object files.
1681 The static library prefix and suffix (if any)
1682 are automatically added to the target.
1683 The target library file prefix
1684 (specified by the $SHLIBPREFIX construction variable;
1685 by default, lib on POSIX systems, nothing on Windows systems)
1687 (specified by the $SHLIBSUFFIX construction variable;
1688 by default, .dll on Windows systems, .so on POSIX systems)
1689 are automatically added to the target if not already present.
1693 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1696 On WIN32 systems, the
1698 builder method will always build an import (.lib) library
1699 in addition to the shared (.dll) library,
1700 adding a .lib library with the same basename
1701 if there is not already a .lib file explicitly
1702 listed in the targets.
1704 Any object files listed in the
1706 must have been built for a shared library
1711 will raise an error if there is any mismatch.
1713 On WIN32 systems, specifying "register=1" will cause the dll to be
1714 registered after it is built using REGSVR32. The command that is run
1715 ("regsvr32" by default) is determined by $REGSVR construction
1716 variable, and the flags passed are determined by $REGSVRFLAGS. By
1717 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1718 up and requiring user attention when it is run. If you change
1719 $REGSVRFLAGS, be sure to include "/s". For example,
1722 env.SharedLibrary(target = 'bar',
1723 source = ['bar.cxx', 'foo.obj'],
1728 will register "bar.dll" as a COM object when it is done linking it.
1730 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1732 .IP env.SharedObject()
1733 Builds an object file for
1734 inclusion in a shared library.
1735 Source files must have one of the same set of extensions
1736 specified above for the
1739 On some platforms building a shared object requires additional
1740 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1741 normal (static) object, but on some platforms there is no difference between a
1742 shared object and a normal (static) one. When there is a difference, SCons
1743 will only allow shared objects to be linked into a shared library, and will
1744 use a different suffix for shared objects. On platforms where there is no
1745 difference, SCons will allow both normal (static)
1746 and shared objects to be linked into a
1747 shared library, and will use the same suffix for shared and normal
1749 The target object file prefix
1750 (specified by the $SHOBJPREFIX construction variable;
1751 by default, the same as $OBJPREFIX)
1753 (specified by the $SHOBJSUFFIX construction variable)
1754 are automatically added to the target if not already present.
1758 env.SharedObject(target = 'ddd', source = 'ddd.c')
1759 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1760 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1763 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1765 .IP env.StaticLibrary()
1766 Builds a static library given one or more object files
1767 or C, C++, D or Fortran source files.
1768 If any source files are given,
1769 then they will be automatically
1770 compiled to object files.
1771 The static library prefix and suffix (if any)
1772 are automatically added to the target.
1773 The target library file prefix
1774 (specified by the $LIBPREFIX construction variable;
1775 by default, lib on POSIX systems, nothing on Windows systems)
1777 (specified by the $LIBSUFFIX construction variable;
1778 by default, .lib on Windows systems, .a on POSIX systems)
1779 are automatically added to the target if not already present.
1783 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1787 Any object files listed in the
1789 must have been built for a static library
1794 will raise an error if there is any mismatch.
1796 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1798 .IP env.StaticObject()
1799 Builds a static object file
1800 from one or more C, C++, D, or Fortran source files.
1801 Source files must have one of the following extensions:
1804 .asm assembly language file
1805 .ASM assembly language file
1817 .F WIN32: Fortran file
1818 POSIX: Fortran file + C pre-processor
1821 .fpp Fortran file + C pre-processor
1822 .FPP Fortran file + C pre-processor
1823 .s assembly language file
1824 .S WIN32: assembly language file
1825 POSIX: assembly language file + C pre-processor
1826 .spp assembly language file + C pre-processor
1827 .SPP assembly language file + C pre-processor
1830 The target object file prefix
1831 (specified by the $OBJPREFIX construction variable; nothing by default)
1833 (specified by the $OBJSUFFIX construction variable;
1834 \.obj on Windows systems, .o on POSIX systems)
1835 are automatically added to the target if not already present.
1839 env.StaticObject(target = 'aaa', source = 'aaa.c')
1840 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1841 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1844 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1847 Builds a tar archive of the specified files
1849 Unlike most builder methods,
1852 builder method may be called multiple times
1854 each additional call
1855 adds to the list of entries
1856 that will be built into the archive.
1859 env.Tar('src.tar', 'src')
1861 # Create the stuff.tar file.
1862 env.Tar('stuff', ['subdir1', 'subdir2'])
1863 # Also add "another" to the stuff.tar file.
1864 env.Tar('stuff', 'another')
1866 # Set TARFLAGS to create a gzip-filtered archive.
1867 env = Environment(TARFLAGS = '-c -z')
1868 env.Tar('foo.tar.gz', 'foo')
1870 # Also set the suffix to .tgz.
1871 env = Environment(TARFLAGS = '-c -z',
1876 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1878 .IP env.TypeLibrary()
1879 Builds a Windows type library (.tlb) file from and input IDL file
1880 (.idl). In addition, it will build the associated inteface stub and
1881 proxy source files. It names them according to the base name of the .idl file.
1886 env.TypeLibrary(source="foo.idl")
1889 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1891 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1894 Builds a header file, an implementation file and a moc file from an ui file.
1895 and returns the corresponding nodes in the above order.
1896 This builder is only available after using the tool 'qt'. Note: you can
1897 specify .ui files directly as inputs for Program, Library and SharedLibrary
1898 without using this builder. Using the builder lets you override the standard
1899 naming conventions (be careful: prefixes are always prepended to names of
1900 built files; if you don't want prefixes, you may set them to ``).
1901 See the QTDIR variable for more information.
1905 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
1906 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
1907 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
1910 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1913 Builds a zip archive of the specified files
1915 Unlike most builder methods,
1918 builder method may be called multiple times
1920 each additional call
1921 adds to the list of entries
1922 that will be built into the archive.
1925 env.Zip('src.zip', 'src')
1927 # Create the stuff.zip file.
1928 env.Zip('stuff', ['subdir1', 'subdir2'])
1929 # Also add "another" to the stuff.tar file.
1930 env.Zip('stuff', 'another')
1935 C source files, C++ source files,
1936 Fortran source files with
1938 (POSIX systems only),
1943 and assembly language files with
1945 (POSIX systems only),
1950 for C preprocessor dependencies,
1951 so the dependencies do not need to be specified explicitly.
1953 targets of builder methods automatically depend on their sources.
1954 An explicit dependency can
1955 be specified using the
1957 method of a construction environment (see below).
1959 .SS Methods and Functions to Do Things
1960 In addition to Builder methods,
1962 provides a number of other construction environment methods
1963 and global functions to
1964 manipulate the build configuration.
1966 Usually, a construction environment method
1967 and global function with the same name both exist
1968 so that you don't have to remember whether
1969 to a specific bit of functionality
1970 must be called with or without a construction environment.
1971 In the following list,
1972 if you call something as a global function
1975 .RI Function( arguments )
1977 and if you call something through a construction
1978 environment it looks like:
1980 .RI env.Function( arguments )
1982 If you can call the functionality in both ways,
1983 then both forms are listed.
1985 Except where otherwise noted,
1987 construction environment method
1989 provide the exact same functionality.
1990 The only difference is that,
1992 calling the functionality through a construction environment will
1993 substitute construction variables into
1994 any supplied strings.
1997 env = Environment(FOO = 'foo')
2001 the first call to the global
2003 function will actually add a target named
2005 to the list of default targets,
2006 while the second call to the
2008 construction environment method
2009 will expand the value
2010 and add a target named
2012 to the list of default targets.
2013 For more on construction variable expansion,
2014 see the next section on
2015 construction variables.
2017 Construction environment methods
2018 and global functions supported by
2022 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2024 .RI Action( action ", [" strfunction ", " varlist ])
2026 .RI env.Action( action ", [" strfunction ", " varlist ])
2027 Creates an Action object for
2030 See the section "Action Objects,"
2031 below, for a complete explanation of the arguments and behavior.
2033 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2035 .RI AddPostAction( target ", " action )
2037 .RI env.AddPostAction( target ", " action )
2038 Arranges for the specified
2044 The specified action(s) may be
2045 an Action object, or anything that
2046 can be converted into an Action object
2049 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2051 .RI AddPreAction( target ", " action )
2053 .RI env.AddPreAction( target ", " action )
2054 Arranges for the specified
2057 before the specified
2060 The specified action(s) may be
2061 an Action object, or anything that
2062 can be converted into an Action object
2065 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2067 .RI Alias( alias ", [" targets ])
2069 .RI env.Alias( alias ", [" targets ])
2070 Creates one or more phony targets that
2071 expand to one or more other targets.
2072 Returns the Node object representing the alias,
2073 which exists outside of any file system.
2074 This Node object, or the alias name,
2075 may be used as a dependency of any other target,
2076 including another alias.
2078 can be called multiple times for the same
2079 alias to add additional targets to the alias.
2083 Alias('install', '/usr/bin')
2084 Alias(['install', 'install-lib'], '/usr/local/lib')
2086 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2087 env.Alias('install', ['/usr/local/man'])
2090 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2092 .RI AlwaysBuild( target ", ...)"
2094 .RI env.AlwaysBuild( target ", ...)"
2097 so that it is always assumed to be out of date,
2098 and will always be rebuilt if needed.
2101 does not add its target(s) to the default target list,
2102 so the targets will only be built
2103 if they are specified on the command line,
2104 or are a dependent of a target specified on the command line--but
2107 be built if so specified.
2108 Multiple targets can be passed in to a single call to
2111 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2113 .RI env.Append( key = val ", [...])"
2114 Appends the specified keyword arguments
2115 to the end of construction variables in the environment.
2116 If the Environment does not have
2117 the specified construction variable,
2118 it is simply added to the environment.
2119 If the values of the construction variable
2120 and the keyword argument are the same type,
2121 then the two values will be simply added together.
2122 Otherwise, the construction variable
2123 and the value of the keyword argument
2124 are both coerced to lists,
2125 and the lists are added together.
2126 (See also the Prepend method, below.)
2129 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2132 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2134 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2135 This appends new path elements to the given path in the
2136 specified external environment
2140 any particular path once (leaving the last one it encounters and
2141 ignoring the rest, to preserve path order),
2142 and to help assure this,
2143 will normalize all paths (using
2146 .BR os.path.normcase ).
2147 This can also handle the
2148 case where the given old path variable is a list instead of a
2149 string, in which case a list will be returned instead of a string.
2153 print 'before:',env['ENV']['INCLUDE']
2154 include_path = '/foo/bar:/foo'
2155 env.PrependENVPath('INCLUDE', include_path)
2156 print 'after:',env['ENV']['INCLUDE']
2160 after: /biz:/foo/bar:/foo
2163 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2165 .RI env.AppendUnique( key = val ", [...])"
2166 Appends the specified keyword arguments
2167 to the end of construction variables in the environment.
2168 If the Environment does not have
2169 the specified construction variable,
2170 it is simply added to the environment.
2171 If the construction variable being appended to is a list,
2172 then any value(s) that already exist in the
2173 construction variable will
2175 be added again to the list.
2178 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2181 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2184 A factory function that
2185 returns a Builder object
2186 to be used to fetch source files
2188 The returned Builder
2189 is intended to be passed to the
2194 env.SourceCode('.', env.BitKeeper())
2197 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2199 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2201 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2202 This specifies a build directory
2204 in which to build all derived files
2205 that would normally be built under
2207 Multiple build directories can be set up for multiple build variants, for
2210 must be underneath the SConstruct file's directory,
2213 may not be underneath the
2216 The default behavior is for
2218 to duplicate all of the files in the tree underneath
2222 and then build the derived files within the copied tree.
2223 (The duplication is performed by
2225 depending on the platform; see also the
2228 This guarantees correct builds
2229 regardless of whether intermediate source files
2230 are generated during the build,
2231 where preprocessors or other scanners search
2233 or whether individual compilers or other invoked tools
2234 are hard-coded to put derived files in the same directory as source files.
2236 This behavior of making a complete copy of the source tree
2237 may be disabled by setting
2242 to invoke Builders using the
2243 path names of source files in
2245 and the path names of derived files within
2247 This is always more efficient than
2249 and is usually safe for most builds.
2253 may cause build problems
2254 if source files are generated during the build,
2255 if any invoked tools are hard-coded to
2256 put derived files in the same directory as the source files.
2258 Note that specifying a
2260 works most naturally
2261 with a subsidiary SConscript file
2262 in the source directory.
2264 you would then call the subsidiary SConscript file
2265 not in the source directory,
2270 had made a virtual copy of the source tree
2271 regardless of the value of
2273 This is how you tell
2275 which variant of a source tree to build.
2279 BuildDir('build-variant1', 'src')
2280 SConscript('build-variant1/SConscript')
2281 BuildDir('build-variant2', 'src')
2282 SConscript('build-variant2/SConscript')
2288 function, described below,
2290 specify a build directory
2291 in conjunction with calling a subsidiary
2294 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2296 .RI Builder( action ", [" arguments ])
2298 .RI env.Builder( action ", [" arguments ])
2299 Creates a Builder object for
2302 See the section "Builder Objects,"
2303 below, for a complete explanation of the arguments and behavior.
2305 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2307 .RI CacheDir( cache_dir )
2309 .RI env.CacheDir( cache_dir )
2312 will maintain a cache of derived files in
2314 The derived files in the cache will be shared
2315 among all the builds using the same
2323 finds a derived file that needs to be rebuilt,
2324 it will first look in the cache to see if a
2325 derived file has already been built
2326 from identical input files and an identical build action
2327 (as incorporated into the MD5 build signature).
2330 will retrieve the file from the cache.
2331 If the derived file is not present in the cache,
2334 then place a copy of the built file in the cache
2335 (identified by its MD5 build signature),
2336 so that it may be retrieved by other
2337 builds that need to build the same derived file
2338 from identical inputs.
2342 may be disabled for any invocation
2351 will place a copy of
2353 derived files in the cache,
2354 even if they already existed
2355 and were not built by this invocation.
2356 This is useful to populate a cache
2359 is added to a build,
2368 "Retrieved `file' from cache,"
2371 option is being used.
2376 will print the action that
2378 have been used to build the file,
2379 without any indication that
2380 the file was actually retrieved from the cache.
2381 This is useful to generate build logs
2382 that are equivalent regardless of whether
2383 a given derived file has been built in-place
2384 or retrieved from the cache.
2386 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2388 .RI Clean( targets ", " files_or_dirs )
2390 .RI env.Clean( targets ", " files_or_dirs )
2391 This specifies a list of files or directories which should be removed
2392 whenever the targets are specified with the
2394 command line option.
2395 The specified targets may be a list
2396 or an individual target.
2400 and create new targets or add files and directories to the
2401 clean list for the specified targets.
2403 Multiple files or directories should be specified
2404 either as separate arguments to the
2406 method, or as a list.
2408 will also accept the return value of any of the construction environment
2413 Clean('foo', ['bar', 'baz'])
2414 Clean('dist', env.Program('hello', 'hello.c'))
2415 Clean(['foo', 'bar'], 'something_else_to_clean')
2418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2420 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2422 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2423 Executes a specific action
2424 (or list of actions)
2425 to build a target file or files.
2426 This is more convenient
2427 than defining a separate Builder object
2428 for a single special-case build.
2429 Any keyword arguments specified override any
2430 same-named existing construction variables.
2432 Note that an action can be an external command,
2433 specified as a string,
2434 or a callable Python object;
2435 see "Action Objects," below.
2439 env.Command('foo.out', 'foo.in',
2440 "$FOO_BUILD < $SOURCES > $TARGET")
2442 env.Command('bar.out', 'bar.in',
2444 "$BAR_BUILD < $SOURCES > $TARGET"],
2445 ENV = {'PATH' : '/usr/local/bin/'})
2447 def rename(env, target, source):
2449 os.rename('.tmp', str(target[0]))
2451 env.Command('baz.out', 'baz.in',
2452 ["$BAZ_BUILD < $SOURCES > .tmp",
2456 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2458 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
2460 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
2461 Creates a Configure object for integrated
2462 functionality similar to GNU autoconf.
2463 See the section "Configure Contexts,"
2464 below, for a complete explanation of the arguments and behavior.
2466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2468 .RI env.Copy([ key = val ", ...])"
2469 Return a separate copy of a construction environment.
2470 If there are any keyword arguments specified,
2471 they are added to the returned copy,
2472 overwriting any existing values
2477 env3 = env.Copy(CCFLAGS = '-g')
2480 Additionally, a list of tools and a toolpath may be specified, as in
2481 the Environment constructor:
2484 def MyTool(env): env['FOO'] = 'bar'
2485 env4 = env.Copy(tools = ['msvc', MyTool])
2488 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2490 .RI env.CVS( repository ", " module )
2491 A factory function that
2492 returns a Builder object
2493 to be used to fetch source files
2497 The returned Builder
2498 is intended to be passed to the
2502 The optional specified
2504 will be added to the beginning
2505 of all repository path names;
2506 this can be used, in essence,
2507 to strip initial directory names
2508 from the repository path names,
2509 so that you only have to
2510 replicate part of the repository
2511 directory hierarchy in your
2512 local build directory:
2515 # Will fetch foo/bar/src.c
2516 # from /usr/local/CVSROOT/foo/bar/src.c.
2517 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2519 # Will fetch bar/src.c
2520 # from /usr/local/CVSROOT/foo/bar/src.c.
2521 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2524 # from /usr/local/CVSROOT/foo/bar/src.c.
2525 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2528 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2530 .RI Default( targets )
2532 .RI env.Default( targets )
2533 This specifies a list of default targets,
2534 which will be built by
2536 if no explicit targets are given on the command line.
2540 and add to the list of default targets.
2542 Multiple targets should be specified as
2543 separate arguments to the
2545 method, or as a list.
2547 will also accept the Node returned by any
2548 of a construction environment's
2553 Default('foo', 'bar', 'baz')
2554 env.Default(['a', 'b', 'c'])
2555 hello = env.Program('hello', 'hello.c')
2563 will clear all default targets.
2566 will add to the (now empty) default-target list
2569 The current list of targets added using the
2571 function or method is available in the
2576 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2578 .RI DefaultEnvironment([ args ])
2579 Creates and returns a default construction environment object.
2580 This construction environment is used internally by SCons
2581 in order to execute many of the global functions in this list,
2582 and to fetch source files transparently
2583 from source code management systems.
2585 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2587 .RI Depends( target ", " dependency )
2589 .RI env.Depends( target ", " dependency )
2590 Specifies an explicit dependency;
2591 the target file(s) will be rebuilt
2592 whenever the dependency file(s) has changed.
2593 This should only be necessary
2594 for cases where the dependency
2595 is not caught by a Scanner
2599 env.Depends('foo', 'other-input-file-for-foo')
2602 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2604 .RI env.Dictionary([ vars ])
2605 Returns a dictionary object
2606 containing copies of all of the
2607 construction variables in the environment.
2608 If there are any variable names specified,
2609 only the specified construction
2610 variables are returned in the dictionary.
2613 dict = env.Dictionary()
2614 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2617 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2619 .RI Dir( name ", [" directory ])
2621 .RI env.Dir( name ", [" directory ])
2622 This returns a Directory Node,
2623 an object that represents the specified directory
2626 can be a relative or absolute path.
2628 is an optional directory that will be used as the parent directory.
2631 is specified, the current script's directory is used as the parent.
2633 Directory Nodes can be used anywhere you
2634 would supply a string as a directory name
2635 to a Builder method or function.
2636 Directory Nodes have attributes and methods
2637 that are useful in many situations;
2638 see "File and Directory Nodes," below.
2640 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2642 .RI EnsurePythonVersion( major ", " minor )
2644 .RI env.EnsurePythonVersion( major ", " minor )
2645 Ensure that the Python version is at least
2648 print out an error message and exit SCons with a non-zero exit code if the
2649 actual Python version is not late enough.
2652 EnsurePythonVersion(2,2)
2655 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2657 .RI EnsureSConsVersion( major ", " minor )
2659 .RI env.EnsureSConsVersion( major ", " minor )
2660 Ensure that the SCons version is at least
2663 print out an error message and exit SCons with a non-zero exit code if the
2664 actual SCons version is not late enough.
2667 EnsureSConsVersion(0,9)
2670 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2672 .RI Environment([ key = value ", ...])"
2674 .RI env.Environment([ key = value ", ...])"
2675 Return a new construction environment
2676 initialized with the specified
2680 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2682 .RI Execute( action ", [" strfunction ", " varlist ])
2684 .RI env.Execute( action ", [" strfunction ", " varlist ])
2685 Executes an Action object.
2688 may be an Action object
2689 (see the section "Action Objects,"
2690 below, for a complete explanation of the arguments and behavior),
2691 or it may be a command-line string,
2693 or executable Python function,
2694 each of which will be converted
2695 into an Action object
2697 The exit value of the command
2698 or return value of the Python function
2701 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2705 .RI env.Exit([ value ])
2711 A default exit value of
2714 is used if no value is specified.
2716 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2720 .RI env.Export( vars )
2723 to export a list of variables from the current
2724 SConscript file to all other SConscript files.
2725 The exported variables are kept in a global collection,
2726 so subsequent calls to
2728 will over-write previous exports that have the same name.
2729 Multiple variable names can be passed to
2731 as separate arguments or as a list. A dictionary can be used to map
2732 variables to a different name when exported. Both local variables and
2733 global variables can be exported.
2738 # Make env available for all SConscript files to Import().
2742 # Make env and package available for all SConscript files:.
2743 Export("env", "package")
2745 # Make env and package available for all SConscript files:
2746 Export(["env", "package"])
2748 # Make env available using the name debug:.
2749 Export({"debug":env})
2755 function supports an
2757 argument that makes it easier to to export a variable or
2758 set of variables to a single SConscript file.
2759 See the description of the
2763 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2765 .RI File( name ", [" directory ])
2767 .RI env.File( name ", [" directory ])
2770 an object that represents the specified file
2773 can be a relative or absolute path.
2775 is an optional directory that will be used as the parent directory.
2777 File Nodes can be used anywhere you
2778 would supply a string as a file name
2779 to a Builder method or function.
2780 File Nodes have attributes and methods
2781 that are useful in many situations;
2782 see "File and Directory Nodes," below.
2784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2786 .RI FindFile( file ", " dirs )
2788 .RI env.FindFile( file ", " dirs )
2791 in the path specified by
2794 may be a list of file names or a single file name. In addition to searching
2795 for files that exist in the filesytem, this function also searches for
2796 derived files that have not yet been built.
2799 foo = env.FindFile('foo', ['dir1', 'dir2'])
2802 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2804 .RI Flatten( sequence )
2806 .RI env.Flatten( sequence )
2807 Takes a sequence (that is, a Python list or tuple)
2808 that may contain nested sequences
2809 and returns a flattened list containing
2810 all of the individual elements in any sequence.
2811 This can be helpful for collecting
2812 the lists returned by calls to Builders;
2813 other Builders will automatically
2814 flatten lists specified as input,
2815 but direct Python manipulation of
2816 these lists does not:
2819 foo = Object('foo.c')
2820 bar = Object('bar.c')
2822 # Because `foo' and `bar' are lists returned by the Object() Builder,
2823 # `objects' will be a list containing nested lists:
2824 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2826 # Passing such a list to another Builder is all right because
2827 # the Builder will flatten the list automatically:
2828 Program(source = objects)
2830 # If you need to manipulate the list directly using Python, you need to
2831 # call Flatten() yourself, or otherwise handle nested lists:
2832 for object in Flatten(objects):
2836 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2838 .RI GetBuildPath( file ", [" ... ])
2840 .RI env.GetBuildPath( file ", [" ... ])
2843 path name (or names) for the specified
2851 Nodes or strings representing path names.
2853 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2857 .RI env.GetLaunchDir()
2858 Returns the absolute path name of the directory from which
2861 was initially invoked.
2862 This can be useful when using the
2867 options, which internally
2868 change to the directory in which the
2872 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2874 .RI GetOption( name )
2876 .RI env.GetOption( name )
2877 This function provides a way to query a select subset of the scons command line
2878 options from a SConscript file. See
2880 for a description of the options available.
2882 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2884 '\".RI GlobalBuilders( flag )
2888 '\"adds the names of the default builders
2889 '\"(Program, Library, etc.)
2890 '\"to the global name space
2891 '\"so they can be called without an explicit construction environment.
2892 '\"(This is the default.)
2896 '\"the names of the default builders are removed
2897 '\"from the global name space
2898 '\"so that an explicit construction environment is required
2899 '\"to call all builders.
2901 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2905 .RI env.Help( text )
2906 This specifies help text to be printed if the
2908 argument is given to
2911 will exit after printing out the help text.
2913 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2915 .RI Ignore( target ", " dependency )
2917 .RI env.Ignore( target ", " dependency )
2918 The specified dependency file(s)
2919 will be ignored when deciding if
2920 the target file(s) need to be rebuilt.
2923 env.Ignore('foo', 'foo.c')
2924 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2927 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2931 .RI env.Import( vars )
2934 to import a list of variables into the current SConscript file. This
2935 will import variables that were exported with
2941 Variables exported by
2944 Multiple variable names can be passed to
2946 as separate arguments or as a list. The variable "*" can be used
2947 to import all variables.
2952 Import("env", "variable")
2953 Import(["env", "variable"])
2957 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2959 .RI Install( dir ", " source )
2961 .RI env.Install( dir ", " source )
2962 Installs one or more files in a destination directory.
2963 The file names remain the same.
2966 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2969 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2971 .RI InstallAs( target ", " source )
2973 .RI env.InstallAs( target ", " source )
2974 Installs one or more files as specific file names,
2975 allowing changing a file name as part of the
2977 It is an error if the target and source
2978 list different numbers of files.
2981 env.InstallAs(target = '/usr/local/bin/foo',
2982 source = 'foo_debug')
2983 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2984 source = ['libFOO.a', 'libBAR.a'])
2987 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2989 .RI Literal( string )
2991 .RI env.Literal( string )
2994 will be preserved as-is
2995 and not have construction variables expanded.
2997 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2999 .RI Local( targets )
3001 .RI env.Local( targets )
3004 will have copies made in the local tree,
3005 even if an already up-to-date copy
3006 exists in a repository.
3007 Returns a list of the target Node or Nodes.
3009 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3011 .RI env.ParseConfig( command ", [" function ])
3014 to modify the environment as specified by the output of
3018 expects the output of a typical
3022 and parses the returned
3043 option gets added to both the
3049 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3052 A factory function that
3053 returns a Builder object
3054 to be used to fetch source files
3055 from the Perforce source code management system.
3056 The returned Builder
3057 is intended to be passed to the
3062 env.SourceCode('.', env.Perforce())
3065 Perforce uses a number of external
3066 environment variables for its operation.
3067 Consequently, this function adds the
3068 following variables from the user's external environment
3069 to the construction environment's
3082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3084 .RI Platform( string )
3085 Returns a callable object
3086 that can be used to initialize
3087 a construction environment using the
3088 platform keyword of the Environment() method:
3091 env = Environment(platform = Platform('win32'))
3094 .RI env.Platform( string )
3095 Applies the callable object for the specified platform
3097 to the environment through which the method was called.
3100 env.Platform('posix')
3107 variable from the user's external environment
3108 to the construction environment's
3111 This is so that any executed commands
3112 that use sockets to connect with other systems
3113 (such as fetching source files from
3114 external CVS repository specifications like
3115 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3116 will work on Win32 systems.
3118 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3120 .RI Precious( target ", ...)"
3122 .RI env.Precious( target ", ...)"
3125 as precious so it is not deleted before it is rebuilt. Normally
3127 deletes a target before building it.
3128 Multiple targets can be passed in to a single call to
3131 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3133 .RI env.Prepend( key = val ", [...])"
3134 Appends the specified keyword arguments
3135 to the beginning of construction variables in the environment.
3136 If the Environment does not have
3137 the specified construction variable,
3138 it is simply added to the environment.
3139 If the values of the construction variable
3140 and the keyword argument are the same type,
3141 then the two values will be simply added together.
3142 Otherwise, the construction variable
3143 and the value of the keyword argument
3144 are both coerced to lists,
3145 and the lists are added together.
3146 (See also the Append method, above.)
3149 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3152 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3154 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3155 This appends new path elements to the given path in the
3156 specified external environment
3160 any particular path once (leaving the first one it encounters and
3161 ignoring the rest, to preserve path order),
3162 and to help assure this,
3163 will normalize all paths (using
3166 .BR os.path.normcase ).
3167 This can also handle the
3168 case where the given old path variable is a list instead of a
3169 string, in which case a list will be returned instead of a string.
3173 print 'before:',env['ENV']['INCLUDE']
3174 include_path = '/foo/bar:/foo'
3175 env.PrependENVPath('INCLUDE', include_path)
3176 print 'after:',env['ENV']['INCLUDE']
3180 after: /foo/bar:/foo:/biz
3183 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3185 .RI env.AppendUnique( key = val ", [...])"
3186 Appends the specified keyword arguments
3187 to the beginning of construction variables in the environment.
3188 If the Environment does not have
3189 the specified construction variable,
3190 it is simply added to the environment.
3191 If the construction variable being appended to is a list,
3192 then any value(s) that already exist in the
3193 construction variable will
3195 be added again to the list.
3198 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3201 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3204 A factory function that
3205 returns a Builder object
3206 to be used to fetch source files
3208 The returned Builder
3209 is intended to be passed to the
3214 env.SourceCode('.', env.RCS())
3219 will fetch source files
3220 from RCS subdirectories automatically,
3222 as demonstrated in the above example
3223 should only be necessary if
3224 you are fetching from
3227 directory as the source files,
3228 or if you need to explicitly specify RCS
3229 for a specific subdirectory.
3231 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3233 .RI env.Replace( key = val ", [...])"
3234 Replaces construction variables in the Environment
3235 with the specified keyword arguments.
3238 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3241 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3243 .RI Repository( directory )
3245 .RI env.Repository( directory )
3248 is a repository to be searched for files.
3252 and each one adds to the list of
3253 repositories that will be searched.
3257 a repository is a copy of the source tree,
3258 from the top-level directory on down,
3260 both source files and derived files
3261 that can be used to build targets in
3262 the local source tree.
3263 The canonical example would be an
3264 official source tree maintained by an integrator.
3265 If the repository contains derived files,
3266 then the derived files should have been built using
3268 so that the repository contains the necessary
3269 signature information to allow
3271 to figure out when it is appropriate to
3272 use the repository copy of a derived file,
3273 instead of building one locally.
3275 Note that if an up-to-date derived file
3276 already exists in a repository,
3280 make a copy in the local directory tree.
3281 In order to guarantee that a local copy
3287 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3292 what variable(s) to use as the return value(s) of the current SConscript
3293 file. These variables will be returned to the "calling" SConscript file
3294 as the return value(s) of
3296 Multiple variable names should be passed to
3302 Return(["foo", "bar"])
3305 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3307 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3309 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3310 Creates a Scanner object for
3313 See the section "Scanner Objects,"
3314 below, for a complete explanation of the arguments and behavior.
3316 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3319 A factory function that
3320 returns a Builder object
3321 to be used to fetch source files
3323 The returned Builder
3324 is intended to be passed to the
3329 env.SourceCode('.', env.SCCS())
3334 will fetch source files
3335 from SCCS subdirectories automatically,
3337 as demonstrated in the above example
3338 should only be necessary if
3339 you are fetching from
3342 directory as the source files,
3343 or if you need to explicitly specify SCCS
3344 for a specific subdirectory.
3346 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3348 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3350 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3352 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3354 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3358 one or more subsidiary SConscript (configuration) files.
3359 There are two ways to call the
3363 The first way you can call
3365 is to explicitly specify one or more
3367 as the first argument.
3368 A single script may be specified as a string;
3369 multiple scripts must be specified as a list
3370 (either explicitly or as created by
3374 The second way you can call
3376 is to specify a list of (sub)directory names
3383 execute a subsidiary configuration file named
3385 in each of the specified directories.
3386 You may specify a name other than
3388 by supplying an optional
3394 argument provides a list of variable names or a dictionary of
3395 named values to export to the
3397 These variables are locally exported only to the specified
3399 and do not affect the
3400 global pool of variables used by
3404 '\"If multiple dirs are provided,
3405 '\"each script gets a fresh export.
3410 function to import the variables.
3414 argument specifies that all of the target files
3415 (for example, object files and executables)
3416 that would normally be built in the subdirectory in which
3418 resides should actually
3422 is interpreted relative to the directory
3423 of the calling SConscript file.
3427 argument specifies that the
3428 source files from which
3429 the target files should be built
3433 is interpreted relative to the directory
3434 of the calling SConscript file.
3438 will link or copy (depending on the platform)
3439 all the source files into the build directory.
3440 This behavior may be disabled by
3441 setting the optional
3444 (it is set to 1 by default),
3447 will refer directly to
3448 the source files in their source directory
3449 when building target files.
3452 is usually safe, and always more efficient
3455 but it may cause build problems in certain end-cases,
3456 such as compiling from source files that
3457 are generated by the build.)
3459 Any variables returned by
3463 will be returned by the call to
3469 SConscript('subdir/SConscript')
3470 foo = SConscript('sub/SConscript', exports='env')
3471 SConscript('dir/SConscript', exports=['env', 'variable'])
3472 SConscript('src/SConscript', build_dir='build', duplicate=0)
3473 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3474 SConscript(dirs=['sub1', 'sub2'])
3475 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3478 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3480 .RI SConscriptChdir( value )
3482 .RI env.SConscriptChdir( value )
3485 changes its working directory
3486 to the directory in which each
3487 subsidiary SConscript file lives.
3488 This behavior may be disabled
3489 by specifying either:
3493 env.SConscriptChdir(0)
3498 will stay in the top-level directory
3499 while reading all SConscript files.
3500 (This may be necessary when building from repositories,
3501 when all the directories in which SConscript files may be found
3502 don't necessarily exist locally.)
3504 You may enable and disable
3505 this ability by calling
3512 SConscript('foo/SConscript') # will not chdir to foo
3513 env.SConscriptChdir(1)
3514 SConscript('bar/SConscript') # will chdir to bar
3517 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3519 .RI SConsignFile([ file , dbm_module ])
3521 .RI env.SConsignFile([ file , dbm_module ])
3524 to store all file signatures
3534 is not an absolute path name,
3535 the file is placed in the same directory as the top-level
3541 argument can be used to specify
3542 which Python database module
3543 The default is to use a custom
3545 module that uses pickled
3546 Python data structures,
3547 and which works on all Python versions from 1.5.2 on.
3552 # Stores signatures in ".sconsign.dbm"
3553 # in the top-level SConstruct directory.
3556 # Stores signatures in the file "etc/scons-signatures"
3557 # relative to the top-level SConstruct directory.
3558 SConsignFile("etc/scons-signatures")
3560 # Stores signatures in the specified absolute file name.
3561 SConsignFile("/home/me/SCons/signatures")
3564 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3566 .RI SetOption( name ", " value )
3568 .RI env.SetOption( name ", " value )
3569 This function provides a way to set a select subset of the scons command
3570 line options from a SConscript file. The options supported are:
3572 which corresponds to -c, --clean, and --remove;
3575 corresponds to --duplicate;
3577 which corresponds to --implicit-cache;
3579 which corresponds to --max-drift;
3581 which corresponds to -j and --jobs;
3582 .B save_explain_info
3583 which corresponds to --save-explain-info.
3584 See the documentation for the
3585 corresponding command line object for information about each specific
3589 SetOption('max_drift', 1)
3592 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3594 .RI SideEffect( side_effect ", " target )
3596 .RI env.SideEffect( side_effect ", " target )
3599 as a side effect of building
3605 can be a list, a file name, or a node.
3606 A side effect is a target that is created
3607 as a side effect of building other targets.
3608 For example, a Windows PDB
3609 file is created as a side effect of building the .obj
3610 files for a static library.
3611 If a target is a side effect of multiple build commands,
3613 will ensure that only one set of commands
3614 is executed at a time.
3615 Consequently, you only need to use this method
3616 for side-effect targets that are built as a result of
3617 multiple build commands.
3619 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3621 .RI SourceCode( entries ", " builder )
3623 .RI env.SourceCode( entries ", " builder )
3624 Arrange for non-existent source files to
3625 be fetched from a source code management system
3630 may be a Node, string or list of both,
3631 and may represent either individual
3632 source files or directories in which
3633 source files can be found.
3635 For any non-existent source files,
3637 will search up the directory tree
3647 will not use a builder to fetch
3648 source files for the specified
3652 builder has been specified
3653 for a directory higher up the tree.
3657 fetch files from SCCS or RCS subdirectories
3658 without explicit configuration.
3659 This takes some extra processing time
3660 to search for the necessary
3661 source code management files on disk.
3662 You can avoid these extra searches
3663 and speed up your build a little
3664 by disabling these searches as follows:
3667 env.SourceCode('.', None)
3671 Note that if the specified
3673 is one you create by hand,
3674 it must have an associated
3675 construction environment to use
3676 when fetching a source file.
3679 provides a set of canned factory
3680 functions that return appropriate
3681 Builders for various popular
3682 source code management systems.
3683 Canonical examples of invocation include:
3686 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3687 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3688 env.SourceCode('/', env.RCS())
3689 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3690 env.SourceCode('no_source.c', None)
3692 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3694 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3696 '\".RI Subversion( repository ", " module )
3697 '\"A factory function that
3698 '\"returns a Builder object
3699 '\"to be used to fetch source files
3700 '\"from the specified Subversion
3702 '\"The returned Builder
3703 '\"is intended to be passed to the
3707 '\"The optional specified
3709 '\"will be added to the beginning
3710 '\"of all repository path names;
3711 '\"this can be used, in essence,
3712 '\"to strip initial directory names
3713 '\"from the repository path names,
3714 '\"so that you only have to
3715 '\"replicate part of the repository
3716 '\"directory hierarchy in your
3717 '\"local build directory:
3720 '\"# Will fetch foo/bar/src.c
3721 '\"# from /usr/local/Subversion/foo/bar/src.c.
3722 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3724 '\"# Will fetch bar/src.c
3725 '\"# from /usr/local/Subversion/foo/bar/src.c.
3726 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3728 '\"# Will fetch src.c
3729 '\"# from /usr/local/Subversion/foo/bar/src.c.
3730 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3733 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3735 .RI SourceSignatures( type )
3737 .RI env.SourceSignatures( type )
3738 This function tells SCons what type of signature to use for source files:
3742 If the environment method is used,
3743 the specified type of source signature
3744 is only used when deciding whether targets
3745 built with that environment are up-to-date or must be rebuilt.
3746 If the global function is used,
3747 the specified type of source signature becomes the default
3748 used for all decisions
3749 about whether targets are up-to-date.
3751 "MD5" means the signature of a source file
3752 is the MD5 checksum of its contents.
3753 "timestamp" means the signature of a source file
3754 is its timestamp (modification time).
3755 There is no different between the two behaviors
3759 "MD5" signatures take longer to compute,
3760 but are more accurate than "timestamp" signatures.
3761 The default is "MD5".
3763 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3767 .RI env.Split( arg )
3768 Returns a list of file names or other objects.
3770 it will be split on strings of white-space characters
3772 making it easier to write long lists of file names.
3773 If arg is already a list,
3774 the list will be returned untouched.
3775 If arg is any other type of object,
3776 it will be returned as a list
3777 containing just the object.
3780 files = Split("f1.c f2.c f3.c")
3781 files = env.Split("f4.c f5.c f6.c")
3789 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3791 .RI TargetSignatures( type )
3793 .RI env.TargetSignatures( type )
3794 This function tells SCons what type of signatures to use
3799 If the environment method is used,
3800 the specified type of signature is only used
3801 for targets built with that environment.
3802 If the global function is used,
3803 the specified type of signature becomes the default
3804 used for all target files that
3805 don't have an explicit target signature type
3806 specified for their environments.
3808 "build" means the signature of a target file
3809 is made by concatenating all of the
3810 signatures of all its source files.
3811 "content" means the signature of a target
3812 file is an MD5 checksum of its contents.
3813 "build" signatures are usually faster to compute,
3814 but "content" signatures can prevent unnecessary rebuilds
3815 when a target file is rebuilt to the exact same contents
3816 as the previous build.
3817 The default is "build".
3819 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3821 .RI Tool( string, toolpath=[] )
3822 Returns a callable object
3823 that can be used to initialize
3824 a construction environment using the
3825 tools keyword of the Environment() method.
3826 The object may be called with a construction
3827 environment as an argument,
3828 in which case the object will be
3829 add the necessary variables
3830 to the construction environment
3831 and the name of the tool will be added to the
3833 construction variable.
3836 env = Environment(tools = [ Tool('msvc') ])
3840 t(env) # adds 'msvc' to the TOOLS variable
3841 u = Tool('opengl', toolpath = ['tools'])
3842 u(env) # adds 'opengl' to the TOOLS variable
3845 .RI env.Tool( string [, toolpath] )
3846 Applies the callable object for the specified tool
3848 to the environment through which the method was called.
3852 env.Tool('opengl', toolpath = ['build/tools'])
3855 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3859 .RI env.Value( value )
3860 Returns a Node object representing the specified Python value. Value
3861 nodes can be used as dependencies of targets. If the result of
3864 changes between SCons runs, any targets depending on
3866 will be rebuilt. When using timestamp source signatures, Value nodes'
3867 timestamps are equal to the system time when the node is created.
3870 def create(target, source, env):
3871 f = open(str(target[0]), 'wb')
3872 f.write('prefix=' + source[0].get_contents())
3874 prefix = ARGUMENTS.get('prefix', '/usr/local')
3876 env['BUILDERS']['Config'] = Builder(action = create)
3877 env.Config(target = 'package-config', source = Value(prefix))
3880 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3882 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
3884 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
3886 Searches for the specified executable
3888 returning the full path name to the program
3890 and returning None if not.
3891 Searches the specified
3893 the value of the calling environment's PATH
3894 (env['ENV']['PATH']),
3895 or the user's current external PATH
3896 (os.environ['PATH'])
3898 On Win32 systems, searches for executable
3899 programs with any of the file extensions
3900 listed in the specified
3902 the calling environment's PATHEXT
3903 (env['ENV']['PATHEXT'])
3904 or the user's current PATHEXT
3905 (os.environ['PATHEXT'])
3913 .SS SConscript Variables
3914 In addition to the global functions and methods,
3916 supports a number of Python variables
3917 that can be used in SConscript files
3918 to affect how you want the build to be performed.
3920 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3925 arguments specified on the command line.
3926 Each element in the list is a tuple
3928 .RI ( keyword , value )
3934 elements of the tuple
3936 subscripting for element
3940 of the tuple, respectively.
3943 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
3944 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
3945 third_tuple = ARGLIST[2]
3946 print "third keyword, value =", third_tuple[0], third_tuple[1]
3947 for key, value in ARGLIST:
3948 # process key and value
3951 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3954 A dictionary of all the
3956 arguments specified on the command line.
3957 The dictionary is not in order,
3958 and if a given keyword has
3959 more than one value assigned to it
3960 on the command line,
3961 the last (right-most) value is
3967 if ARGUMENTS.get('debug', 0):
3968 env = Environment(CCFLAGS = '-g')
3973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3976 A list of the targets which
3978 will actually try to build,
3979 regardless of whether they were specified on
3980 the command line or via the
3983 The elements of this list may be strings
3985 nodes, so you should run the list through the Python
3987 function to make sure any Node path names
3988 are converted to strings.
3990 Because this list may be taken from the
3991 list of targets specified using the
3994 the contents of the list may change
3995 on each successive call to
4000 for additional information.
4003 if 'foo' in BUILD_TARGETS:
4004 print "Don't forget to test the `foo' program!"
4005 if 'special/program' in BUILD_TARGETS:
4006 SConscript('special')
4011 list only contains targets expected listed
4012 on the command line or via calls to the
4017 contain all dependent targets that will be built as
4018 a result of making the sure the explicitly-specified
4019 targets are up to date.
4021 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4023 COMMAND_LINE_TARGETS
4024 A list of the targets explicitly specified on
4026 If there are no targets specified on the command line,
4028 This can be used, for example,
4029 to take specific actions only
4030 when a certain target or targets
4031 is explicitly being built:
4034 if 'foo' in COMMAND_LINE_TARGETS:
4035 print "Don't forget to test the `foo' program!"
4036 if 'special/program' in COMMAND_LINE_TARGETS:
4037 SConscript('special')
4040 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4043 A list of the target
4045 that have been specified using the
4048 The elements of the list are nodes,
4049 so you need to run them through the Python
4051 function to get at the path name for each Node.
4054 print str(DEFAULT_TARGETS[0])
4055 if 'foo' in map(str, DEFAULT_TARGETS):
4056 print "Don't forget to test the `foo' program!"
4061 list change on on each successive call to the
4066 print map(str, DEFAULT_TARGETS) # originally []
4068 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4070 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4072 print map(str, DEFAULT_TARGETS) # back to []
4075 Consequently, be sure to use
4077 only after you've made all of your
4080 or else simply be careful of the order
4081 of these statements in your SConscript files
4082 so that you don't look for a specific
4083 default target before it's actually been added to the list.
4085 .SS Construction Variables
4086 .\" XXX From Gary Ruben, 23 April 2002:
4087 .\" I think it would be good to have an example with each construction
4088 .\" variable description in the documentation.
4090 .\" CC The C compiler
4091 .\" Example: env["CC"] = "c68x"
4092 .\" Default: env["CC"] = "cc"
4094 .\" CCCOM The command line ...
4096 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4097 .\" env["CC"] = "c68x"
4098 .\" env["CFLAGS"] = "-ps -qq -mr"
4099 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4101 .\" (I dunno what this is ;-)
4102 A construction environment has an associated dictionary of
4103 .I construction variables
4104 that are used by built-in or user-supplied build rules.
4105 Construction variables must follow the same rules for
4107 the initial character must be an underscore or letter,
4108 followed by any number of underscores, letters, or digits.
4110 A number of useful construction variables are automatically defined by
4111 scons for each supported platform, and additional construction variables
4112 can be defined by the user. The following is a list of the automatically
4113 defined construction variables:
4116 The static library archiver.
4119 The command line used to generate a static library from object files.
4122 General options passed to the static library archiver.
4128 The command line used to generate an object file
4129 from an assembly-language source file.
4132 General options passed to the assembler.
4135 The command line used to assemble an assembly-language
4136 source file into an object file
4137 after first running the file through the C preprocessor.
4138 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4139 are included on this command line.
4142 The bibliography generator for the TeX formatter and typesetter and the
4143 LaTeX structured formatter and typesetter.
4146 The command line used to call the bibliography generator for the
4147 TeX formatter and typesetter and the LaTeX structured formatter and
4151 General options passed to the bibliography generator for the TeX formatter
4152 and typesetter and the LaTeX structured formatter and typesetter.
4155 The BitKeeper executable.
4158 The command line for
4159 fetching source files using BitKEeper.
4162 The command ($BITKEEPER) and subcommand
4163 for fetching source files using BitKeeper.
4165 .IP BITKEEPERGETFLAGS
4166 Options that are passed to the BitKeeper
4171 A dictionary mapping the names of the builders
4172 available through this environment
4173 to underlying Builder objects.
4175 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4176 are available by default.
4177 If you initialize this variable when an
4178 Environment is created:
4181 env = Environment(BUILDERS = {'NewBuilder' : foo})
4184 the default Builders will no longer be available.
4185 To use a new Builder object in addition to the default Builders,
4186 add your new Builder object like this:
4190 env.Append(BUILDERS = {'NewBuilder' : foo})
4197 env['BUILDERS]['NewBuilder'] = foo
4204 The command line used to compile a C source file to a (static) object file.
4205 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4206 are included on this command line.
4209 General options that are passed to the C compiler.
4212 The suffix for C source files.
4213 This is used by the internal CFile builder
4214 when generating C files from Lex (.l) or YACC (.y) input files.
4215 The default suffix, of course, is
4218 On case-insensitive systems (like Win32),
4225 The version number of the C compiler.
4226 This may or may not be set,
4227 depending on the specific C compiler being used.
4230 A function used to produce variables like $_CPPINCFLAGS. It takes
4232 arguments: a prefix to concatenate onto each element, a list of
4233 elements, a suffix to concatenate onto each element, an environment
4234 for variable interpolation, and an optional function that will be
4235 called to transform the list before concatenation.
4238 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4242 A platform independent specification of C preprocessor definitions.
4243 The definitions will be added to command lines
4244 through the automatically-generated
4245 $_CPPDEFFLAGS construction variable (see below),
4246 which is constructed according to
4247 the type of value of $CPPDEFINES:
4250 If $CPPDEFINES is a string,
4252 $CPPDEFPREFIX and $CPPDEFSUFFIX
4253 construction variables
4254 will be added to the beginning and end.
4257 # Will add -Dxyz to POSIX compiler command lines,
4258 # and /Dxyz to Microsoft Visual C++ command lines.
4259 env = Environment(CPPDEFINES='xyz')
4263 If $CPPDEFINES is a list,
4265 $CPPDEFPREFIX and $CPPDEFSUFFIX
4266 construction variables
4267 will be appended to the beginning and end
4268 of each element in the list.
4269 If any element is a list or tuple,
4270 then the first item is the name being
4271 defined and the second item is its value:
4274 # Will add -DB=2 -DA to POSIX compiler command lines,
4275 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4276 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4280 If $CPPDEFINES is a dictionary,
4282 $CPPDEFPREFIX and $CPPDEFSUFFIX
4283 construction variables
4284 will be appended to the beginning and end
4285 of each item from the dictionary.
4286 The key of each dictionary item
4287 is a name being defined
4288 to the dictionary item's corresponding value;
4291 then the name is defined without an explicit value.
4292 Note that the resulting flags are sorted by keyword
4293 to ensure that the order of the options on the
4294 command line is consistent each time
4299 # Will add -DA -DB=2 to POSIX compiler command lines,
4300 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4301 env = Environment(CPPDEFINES={'B':2, 'A':None})
4305 An automatically-generated construction variable
4306 containing the C preprocessor command-line options
4308 The value of $_CPPDEFFLAGS is created
4309 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4310 to the beginning and end
4311 of each directory in $CPPDEFINES.
4314 The prefix used to specify preprocessor definitions
4315 on the C compiler command line.
4316 This will be appended to the beginning of each definition
4317 in the $CPPDEFINES construction variable
4318 when the $_CPPDEFFLAGS variable is automatically generated.
4321 The suffix used to specify preprocessor definitions
4322 on the C compiler command line.
4323 This will be appended to the end of each definition
4324 in the $CPPDEFINES construction variable
4325 when the $_CPPDEFFLAGS variable is automatically generated.
4328 User-specified C preprocessor options.
4329 These will be included in any command that uses the C preprocessor,
4330 including not just compilation of C and C++ source files
4331 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4332 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4333 $F77PPCOM and $SHF77PPCOM command lines
4334 used to compile a Fortran source file,
4335 and the $ASPPCOM command line
4336 used to assemble an assembly language source file,
4337 after first running each file through the C preprocessor.
4338 Note that this variable does
4342 (or similar) include search path options
4343 that scons generates automatically from $CPPPATH.
4347 for the variable that expands to those options.
4350 An automatically-generated construction variable
4351 containing the C preprocessor command-line options
4352 for specifying directories to be searched for include files.
4353 The value of $_CPPINCFLAGS is created
4354 by appending $INCPREFIX and $INCSUFFIX
4355 to the beginning and end
4356 of each directory in $CPPPATH.
4359 The list of directories that the C preprocessor will search for include
4360 directories. The C/C++ implicit dependency scanner will search these
4361 directories for include files. Don't explicitly put include directory
4362 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4363 and the directories will not be searched by the dependency scanner. Note:
4364 directory names in CPPPATH will be looked-up relative to the SConscript
4365 directory when they are used in a command. To force
4367 to look-up a directory relative to the root of the source tree use #:
4370 env = Environment(CPPPATH='#/include')
4374 The directory look-up can also be forced using the
4379 include = Dir('include')
4380 env = Environment(CPPPATH=include)
4384 The directory list will be added to command lines
4385 through the automatically-generated
4387 construction variable,
4388 which is constructed by
4389 appending the values of the
4390 $INCPREFIX and $INCSUFFIX
4391 construction variables
4392 to the beginning and end
4393 of each directory in $CPPPATH.
4394 Any command lines you define that need
4395 the CPPPATH directory list should
4396 include $_CPPINCFLAGS:
4399 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4403 The list of suffixes of files that will be scanned
4404 for C preprocessor implicit dependencies
4406 The default list is:
4409 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4410 ".h", ".H", ".hxx", ".hpp", ".hh",
4411 ".F", ".fpp", ".FPP",
4412 ".S", ".spp", ".SPP"]
4419 Options that are passed to the CVS checkout subcommand.
4422 The command line used to
4423 fetch source files from a CVS repository.
4426 General options that are passed to CVS.
4427 By default, this is set to
4429 to specify from where the files must be fetched.
4432 The path to the CVS repository.
4433 This is referenced in the default
4440 The suffix for C++ source files.
4441 This is used by the internal CXXFile builder
4442 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4443 The default suffix is
4445 SCons also treats files with the suffixes
4452 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4459 The command line used to compile a C++ source file to an object file.
4460 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4461 are included on this command line.
4464 General options that are passed to the C++ compiler.
4467 The version number of the C++ compiler.
4468 This may or may not be set,
4469 depending on the specific C++ compiler being used.
4472 A function that converts a file name into a Dir instance relative to the
4476 The list of suffixes of files that will be scanned
4477 for imported D package files.
4478 The default list is:
4485 The TeX DVI file to PDF file converter.
4488 General options passed to the TeX DVI file to PDF file converter.
4491 The command line used to convert TeX DVI files into a PDF file.
4494 The TeX DVI file to PostScript converter.
4497 General options passed to the TeX DVI file to PostScript converter.
4500 A dictionary of environment variables
4501 to use when invoking commands. When ENV is used in a command all list
4502 values will be joined using the path separator and any other non-string
4503 values will simply be coerced to a string.
4504 Note that, by default,
4508 propagate the environment in force when you
4511 to the commands used to build target files.
4512 This is so that builds will be guaranteed
4513 repeatable regardless of the environment
4514 variables set at the time
4518 If you want to propagate your
4519 environment variables
4520 to the commands executed
4521 to build target files,
4522 you must do so explicitly:
4526 env = Environment(ENV = os.environ)
4530 Note that you can choose only to propagate
4531 certain environment variables.
4535 environment variable,
4538 uses the same utilities
4539 as the invoking shell (or other process):
4544 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4548 A function that will be called to escape shell special characters in
4549 command lines. The function should take one argument: the command line
4550 string to escape; and should return the escaped command line.
4553 The Fortran 77 compiler.
4554 You should normally set the $FORTRAN variable,
4555 which specifies the default Fortran compiler
4556 for all Fortran versions.
4557 You only need to set $F77 if you need to use a specific compiler
4558 or compiler version for Fortran 77 files.
4561 The command line used to compile a Fortran 77 source file to an object file.
4562 You only need to set $F77COM if you need to use a specific
4563 command line for Fortran 77 files.
4564 You should normally set the $FORTRANCOM variable,
4565 which specifies the default command line
4566 for all Fortran versions.
4569 General user-specified options that are passed to the Fortran 77 compiler.
4570 Note that this variable does
4574 (or similar) include search path options
4575 that scons generates automatically from $F77PATH.
4579 for the variable that expands to those options.
4580 You only need to set $F77FLAGS if you need to define specific
4581 user options for Fortran 77 files.
4582 You should normally set the $FORTRANFLAGS variable,
4583 which specifies the user-specified options
4584 passed to the default Fortran compiler
4585 for all Fortran versions.
4588 An automatically-generated construction variable
4589 containing the Fortran 77 compiler command-line options
4590 for specifying directories to be searched for include files.
4591 The value of $_F77INCFLAGS is created
4592 by appending $INCPREFIX and $INCSUFFIX
4593 to the beginning and end
4594 of each directory in $F77PATH.
4597 The list of directories that the Fortran 77 compiler will search for include
4598 directories. The implicit dependency scanner will search these
4599 directories for include files. Don't explicitly put include directory
4600 arguments in $F77FLAGS because the result will be non-portable
4601 and the directories will not be searched by the dependency scanner. Note:
4602 directory names in $F77PATH will be looked-up relative to the SConscript
4603 directory when they are used in a command. To force
4605 to look-up a directory relative to the root of the source tree use #:
4606 You only need to set $F77PATH if you need to define a specific
4607 include path for Fortran 77 files.
4608 You should normally set the $FORTRANPATH variable,
4609 which specifies the include path
4610 for the default Fortran compiler
4611 for all Fortran versions.
4614 env = Environment(F77PATH='#/include')
4618 The directory look-up can also be forced using the
4623 include = Dir('include')
4624 env = Environment(F77PATH=include)
4628 The directory list will be added to command lines
4629 through the automatically-generated
4631 construction variable,
4632 which is constructed by
4633 appending the values of the
4634 $INCPREFIX and $INCSUFFIX
4635 construction variables
4636 to the beginning and end
4637 of each directory in $F77PATH.
4638 Any command lines you define that need
4639 the F77PATH directory list should
4640 include $_F77INCFLAGS:
4643 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4647 The command line used to compile a Fortran 77 source file to an object file
4648 after first running the file through the C preprocessor.
4649 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4650 are included on this command line.
4651 You only need to set $F77PPCOM if you need to use a specific
4652 C-preprocessor command line for Fortran 77 files.
4653 You should normally set the $FORTRANPPCOM variable,
4654 which specifies the default C-preprocessor command line
4655 for all Fortran versions.
4658 The Fortran 90 compiler.
4659 You should normally set the $FORTRAN variable,
4660 which specifies the default Fortran compiler
4661 for all Fortran versions.
4662 You only need to set $F90 if you need to use a specific compiler
4663 or compiler version for Fortran 90 files.
4666 The command line used to compile a Fortran 90 source file to an object file.
4667 You only need to set $F90COM if you need to use a specific
4668 command line for Fortran 90 files.
4669 You should normally set the $FORTRANCOM variable,
4670 which specifies the default command line
4671 for all Fortran versions.
4674 General user-specified options that are passed to the Fortran 90 compiler.
4675 Note that this variable does
4679 (or similar) include search path options
4680 that scons generates automatically from $F90PATH.
4684 for the variable that expands to those options.
4685 You only need to set $F90FLAGS if you need to define specific
4686 user options for Fortran 90 files.
4687 You should normally set the $FORTRANFLAGS variable,
4688 which specifies the user-specified options
4689 passed to the default Fortran compiler
4690 for all Fortran versions.
4693 An automatically-generated construction variable
4694 containing the Fortran 90 compiler command-line options
4695 for specifying directories to be searched for include files.
4696 The value of $_F90INCFLAGS is created
4697 by appending $INCPREFIX and $INCSUFFIX
4698 to the beginning and end
4699 of each directory in $F90PATH.
4702 The list of directories that the Fortran 90 compiler will search for include
4703 directories. The implicit dependency scanner will search these
4704 directories for include files. Don't explicitly put include directory
4705 arguments in $F90FLAGS because the result will be non-portable
4706 and the directories will not be searched by the dependency scanner. Note:
4707 directory names in $F90PATH will be looked-up relative to the SConscript
4708 directory when they are used in a command. To force
4710 to look-up a directory relative to the root of the source tree use #:
4711 You only need to set $F90PATH if you need to define a specific
4712 include path for Fortran 90 files.
4713 You should normally set the $FORTRANPATH variable,
4714 which specifies the include path
4715 for the default Fortran compiler
4716 for all Fortran versions.
4719 env = Environment(F90PATH='#/include')
4723 The directory look-up can also be forced using the
4728 include = Dir('include')
4729 env = Environment(F90PATH=include)
4733 The directory list will be added to command lines
4734 through the automatically-generated
4736 construction variable,
4737 which is constructed by
4738 appending the values of the
4739 $INCPREFIX and $INCSUFFIX
4740 construction variables
4741 to the beginning and end
4742 of each directory in $F90PATH.
4743 Any command lines you define that need
4744 the F90PATH directory list should
4745 include $_F90INCFLAGS:
4748 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
4752 The command line used to compile a Fortran 90 source file to an object file
4753 after first running the file through the C preprocessor.
4754 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
4755 are included on this command line.
4756 You only need to set $F90PPCOM if you need to use a specific
4757 C-preprocessor command line for Fortran 90 files.
4758 You should normally set the $FORTRANPPCOM variable,
4759 which specifies the default C-preprocessor command line
4760 for all Fortran versions.
4763 The Fortran 95 compiler.
4764 You should normally set the $FORTRAN variable,
4765 which specifies the default Fortran compiler
4766 for all Fortran versions.
4767 You only need to set $F95 if you need to use a specific compiler
4768 or compiler version for Fortran 95 files.
4771 The command line used to compile a Fortran 95 source file to an object file.
4772 You only need to set $F95COM if you need to use a specific
4773 command line for Fortran 95 files.
4774 You should normally set the $FORTRANCOM variable,
4775 which specifies the default command line
4776 for all Fortran versions.
4779 General user-specified options that are passed to the Fortran 95 compiler.
4780 Note that this variable does
4784 (or similar) include search path options
4785 that scons generates automatically from $F95PATH.
4789 for the variable that expands to those options.
4790 You only need to set $F95FLAGS if you need to define specific
4791 user options for Fortran 95 files.
4792 You should normally set the $FORTRANFLAGS variable,
4793 which specifies the user-specified options
4794 passed to the default Fortran compiler
4795 for all Fortran versions.
4798 An automatically-generated construction variable
4799 containing the Fortran 95 compiler command-line options
4800 for specifying directories to be searched for include files.
4801 The value of $_F95INCFLAGS is created
4802 by appending $INCPREFIX and $INCSUFFIX
4803 to the beginning and end
4804 of each directory in $F95PATH.
4807 The list of directories that the Fortran 95 compiler will search for include
4808 directories. The implicit dependency scanner will search these
4809 directories for include files. Don't explicitly put include directory
4810 arguments in $F95FLAGS because the result will be non-portable
4811 and the directories will not be searched by the dependency scanner. Note:
4812 directory names in $F95PATH will be looked-up relative to the SConscript
4813 directory when they are used in a command. To force
4815 to look-up a directory relative to the root of the source tree use #:
4816 You only need to set $F95PATH if you need to define a specific
4817 include path for Fortran 95 files.
4818 You should normally set the $FORTRANPATH variable,
4819 which specifies the include path
4820 for the default Fortran compiler
4821 for all Fortran versions.
4824 env = Environment(F95PATH='#/include')
4828 The directory look-up can also be forced using the
4833 include = Dir('include')
4834 env = Environment(F95PATH=include)
4838 The directory list will be added to command lines
4839 through the automatically-generated
4841 construction variable,
4842 which is constructed by
4843 appending the values of the
4844 $INCPREFIX and $INCSUFFIX
4845 construction variables
4846 to the beginning and end
4847 of each directory in $F95PATH.
4848 Any command lines you define that need
4849 the F95PATH directory list should
4850 include $_F95INCFLAGS:
4853 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
4857 The command line used to compile a Fortran 95 source file to an object file
4858 after first running the file through the C preprocessor.
4859 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
4860 are included on this command line.
4861 You only need to set $F95PPCOM if you need to use a specific
4862 C-preprocessor command line for Fortran 95 files.
4863 You should normally set the $FORTRANPPCOM variable,
4864 which specifies the default C-preprocessor command line
4865 for all Fortran versions.
4868 The default Fortran compiler
4869 for all versions of Fortran.
4872 The command line used to compile a Fortran source file to an object file.
4873 By default, any options specified
4874 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
4875 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
4876 are included on this command line.
4879 General user-specified options that are passed to the Fortran compiler.
4880 Note that this variable does
4884 (or similar) include or module search path options
4885 that scons generates automatically from $FORTRANPATH.
4887 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
4889 for the variables that expand those options.
4891 .IP _FORTRANINCFLAGS
4892 An automatically-generated construction variable
4893 containing the Fortran compiler command-line options
4894 for specifying directories to be searched for include
4895 files and module files.
4896 The value of $_FORTRANINCFLAGS is created
4897 by prepending/appending $INCPREFIX and $INCSUFFIX
4898 to the beginning and end
4899 of each directory in $FORTRANPATH.
4902 Directory location where the Fortran compiler should place
4903 any module files it generates. This variable is empty, by default. Some
4904 Fortran compilers will internally append this directory in the search path
4905 for module files, as well
4907 .IP FORTRANMODDIRPREFIX
4908 The prefix used to specify a module directory on the Fortran compiler command
4910 This will be appended to the beginning of the directory
4911 in the $FORTRANMODDIR construction variables
4912 when the $_FORTRANMODFLAG variables is automatically generated.
4914 .IP FORTRANMODDIRSUFFIX
4915 The suffix used to specify a module directory on the Fortran compiler command
4917 This will be appended to the beginning of the directory
4918 in the $FORTRANMODDIR construction variables
4919 when the $_FORTRANMODFLAG variables is automatically generated.
4922 An automatically-generated construction variable
4923 containing the Fortran compiler command-line option
4924 for specifying the directory location where the Fortran
4925 compiler should place any module files that happen to get
4926 generated during compilation.
4927 The value of $_FORTRANMODFLAG is created
4928 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
4929 to the beginning and end of the directory in $FORTRANMODDIR.
4931 .IP FORTRANMODPREFIX
4932 The module file prefix used by the Fortran compiler. SCons assumes that
4933 the Fortran compiler follows the quasi-standard naming convention for
4935 .I <module_name>.mod.
4936 As a result, this variable is left empty, by default. For situations in
4937 which the compiler does not necessarily follow the normal convention,
4938 the user may use this variable. Its value will be appended to every
4939 module file name as scons attempts to resolve dependencies.
4941 .IP FORTRANMODSUFFIX
4942 The module file suffix used by the Fortran compiler. SCons assumes that
4943 the Fortran compiler follows the quasi-standard naming convention for
4945 .I <module_name>.mod.
4946 As a result, this variable is set to ".mod", by default. For situations
4947 in which the compiler does not necessarily follow the normal convention,
4948 the user may use this variable. Its value will be appended to every
4949 module file name as scons attempts to resolve dependencies.
4952 The list of directories that the Fortran compiler will search for
4953 include files and (for some compilers) module files. The Fortran implicit
4954 dependency scanner will search these directories for include files (but
4955 not module files since they are autogenerated and, as such, may not
4956 actually exist at the time the scan takes place). Don't explicitly put
4957 include directory arguments in FORTRANFLAGS because the result will be
4958 non-portable and the directories will not be searched by the dependency
4959 scanner. Note: directory names in FORTRANPATH will be looked-up relative
4960 to the SConscript directory when they are used in a command. To force
4962 to look-up a directory relative to the root of the source tree use #:
4965 env = Environment(FORTRANPATH='#/include')
4969 The directory look-up can also be forced using the
4974 include = Dir('include')
4975 env = Environment(FORTRANPATH=include)
4979 The directory list will be added to command lines
4980 through the automatically-generated
4982 construction variable,
4983 which is constructed by
4984 appending the values of the
4985 $INCPREFIX and $INCSUFFIX
4986 construction variables
4987 to the beginning and end
4988 of each directory in $FORTRANPATH.
4989 Any command lines you define that need
4990 the FORTRANPATH directory list should
4991 include $_FORTRANINCFLAGS:
4994 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
4998 The command line used to compile a Fortran source file to an object file
4999 after first running the file through the C preprocessor.
5000 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5001 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5002 construction variables are included on this command line.
5005 The list of suffixes of files that will be scanned
5006 for Fortran implicit dependencies
5007 (INCLUDE lines & USE statements).
5008 The default list is:
5011 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5012 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5016 A function that converts a file name into a File instance relative to the
5020 The Ghostscript program used to convert PostScript to PDF files.
5023 General options passed to the Ghostscript program
5024 when converting PostScript to PDF files.
5027 The Ghostscript command line used to convert PostScript to PDF files.
5030 The list of suffixes of files that will be scanned
5031 for IDL implicit dependencies
5032 (#include or import lines).
5033 The default list is:
5040 The prefix used to specify an include directory on the C compiler command
5042 This will be appended to the beginning of each directory
5043 in the $CPPPATH and $FORTRANPATH construction variables
5044 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5045 variables are automatically generated.
5048 The suffix used to specify an include directory on the C compiler command
5050 This will be appended to the end of each directory
5051 in the $CPPPATH and $FORTRANPATH construction variables
5052 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5053 variables are automatically generated.
5056 A function to be called to install a file into a
5057 destination file name.
5058 The default function copies the file into the destination
5059 (and sets the destination file's mode and permission bits
5060 to match the source file's).
5061 The function takes the following arguments:
5064 def install(dest, source, env):
5068 is the path name of the destination file.
5070 is the path name of the source file.
5072 is the construction environment
5073 (a dictionary of construction values)
5074 in force for this file installation.
5077 The Java archive tool.
5080 The directory to which the Java archive tool should change
5086 The command line used to call the Java archive tool.
5089 General options passed to the Java archive tool.
5090 By default this is set to
5092 to create the necessary
5097 The suffix for Java archives:
5105 The command line used to compile a directory tree containing
5106 Java source files to
5107 corresponding Java class files.
5108 Any options specified in the $JAVACFLAGS construction variable
5109 are included on this command line.
5112 General options that are passed to the Java compiler.
5115 The directory in which Java class files may be found.
5116 This is stripped from the beginning of any Java .class
5117 file names supplied to the
5122 The suffix for Java class files;
5127 The Java generator for C header and stub files.
5130 The command line used to generate C header and stub files
5132 Any options specified in the $JAVAHFLAGS construction variable
5133 are included on this command line.
5136 General options passed to the C header and stub file generator
5140 The suffix for Java files;
5145 The LaTeX structured formatter and typesetter.
5148 The command line used to call the LaTeX structured formatter and typesetter.
5151 General options passed to the LaTeX structured formatter and typesetter.
5154 The lexical analyzer generator.
5157 General options passed to the lexical analyzer generator.
5160 The command line used to call the lexical analyzer generator
5161 to generate a source file.
5164 An automatically-generated construction variable
5165 containing the linker command-line options
5166 for specifying directories to be searched for library.
5167 The value of $_LIBDIRFLAGS is created
5168 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5169 to the beginning and end
5170 of each directory in $LIBPATH.
5173 The prefix used to specify a library directory on the linker command line.
5174 This will be appended to the beginning of each directory
5175 in the $LIBPATH construction variable
5176 when the $_LIBDIRFLAGS variable is automatically generated.
5179 The suffix used to specify a library directory on the linker command line.
5180 This will be appended to the end of each directory
5181 in the $LIBPATH construction variable
5182 when the $_LIBDIRFLAGS variable is automatically generated.
5185 An automatically-generated construction variable
5186 containing the linker command-line options
5187 for specifying libraries to be linked with the resulting target.
5188 The value of $_LIBFLAGS is created
5189 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5190 to the beginning and end
5191 of each directory in $LIBS.
5194 The prefix used to specify a library to link on the linker command line.
5195 This will be appended to the beginning of each library
5196 in the $LIBS construction variable
5197 when the $_LIBFLAGS variable is automatically generated.
5200 The suffix used to specify a library to link on the linker command line.
5201 This will be appended to the end of each library
5202 in the $LIBS construction variable
5203 when the $_LIBFLAGS variable is automatically generated.
5206 The list of directories that will be searched for libraries.
5207 The implicit dependency scanner will search these
5208 directories for include files. Don't explicitly put include directory
5209 arguments in $LINKFLAGS or $SHLINKFLAGS
5210 because the result will be non-portable
5211 and the directories will not be searched by the dependency scanner. Note:
5212 directory names in LIBPATH will be looked-up relative to the SConscript
5213 directory when they are used in a command. To force
5215 to look-up a directory relative to the root of the source tree use #:
5218 env = Environment(LIBPATH='#/libs')
5222 The directory look-up can also be forced using the
5228 env = Environment(LIBPATH=libs)
5232 The directory list will be added to command lines
5233 through the automatically-generated
5235 construction variable,
5236 which is constructed by
5237 appending the values of the
5238 $LIBDIRPREFIX and $LIBDIRSUFFIX
5239 construction variables
5240 to the beginning and end
5241 of each directory in $LIBPATH.
5242 Any command lines you define that need
5243 the LIBPATH directory list should
5244 include $_LIBDIRFLAGS:
5247 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5251 The prefix used for (static) library file names.
5252 A default value is set for each platform
5253 (posix, win32, os2, etc.),
5254 but the value is overridden by individual tools
5255 (ar, mslib, sgiar, sunar, tlib, etc.)
5256 to reflect the names of the libraries they create.
5259 An array of legal prefixes for library file names.
5262 A list of one or more libraries
5263 that will be linked with
5264 any executable programs
5265 created by this environment.
5268 The library list will be added to command lines
5269 through the automatically-generated
5271 construction variable,
5272 which is constructed by
5273 appending the values of the
5274 $LIBLINKPREFIX and $LIBLINKSUFFIX
5275 construction variables
5276 to the beginning and end
5277 of each directory in $LIBS.
5278 Any command lines you define that need
5279 the LIBS library list should
5283 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5287 The suffix used for (static) library file names.
5288 A default value is set for each platform
5289 (posix, win32, os2, etc.),
5290 but the value is overridden by individual tools
5291 (ar, mslib, sgiar, sunar, tlib, etc.)
5292 to reflect the names of the libraries they create.
5295 An array of legal suffixes for library file names.
5301 General user options passed to the linker.
5302 Note that this variable should
5306 (or similar) options for linking with the libraries listed in $LIBS,
5309 (or similar) library search path options
5310 that scons generates automatically from $LIBPATH.
5314 for the variable that expands to library-link options,
5318 for the variable that expands to library search path options.
5321 The command line used to link object files into an executable.
5324 The M4 macro preprocessor.
5327 General options passed to the M4 macro preprocessor.
5330 The command line used to pass files through the macro preprocessor.
5333 The maximum number of characters allowed on an external command line.
5335 link lines longer than this many characters
5336 are linke via a temporary file name.
5339 When the Microsoft Visual Studio tools are initialized, they set up
5340 this dictionary with the following keys:
5343 the version of MSVS being used (can be set via
5347 the available versions of MSVS installed
5350 installed directory of Visual C++
5353 installed directory of Visual Studio
5356 installed directory of the .NET framework
5358 .B FRAMEWORKVERSIONS:
5359 list of installed versions of the .NET framework, sorted latest to oldest.
5361 .B FRAMEWORKVERSION:
5362 latest installed version of the .NET framework
5365 installed location of the .NET SDK.
5368 installed location of the Platform SDK.
5370 .B PLATFORMSDK_MODULES:
5371 dictionary of installed Platform SDK modules,
5372 where the dictionary keys are keywords for the various modules, and
5373 the values are 2-tuples where the first is the release date, and the
5374 second is the version number.
5376 If a value isn't set, it wasn't available in the registry.
5378 .IP MSVS_IGNORE_IDE_PATHS
5379 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5380 instead of the settings from the IDE.
5382 For Visual Studio, SCons will (by default) automatically determine
5383 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5384 set by the IDE. You can override this behavior by setting these
5385 variables after Environment initialization, or by setting
5386 .B MSVS_IGNORE_IDE_PATHS = 1
5387 in the Environment initialization.
5388 Specifying this will not leave these unset, but will set them to a
5389 minimal set of paths needed to run the tools successfully.
5392 For VS6, the mininimal set is:
5393 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5394 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5395 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5397 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5398 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5399 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5403 Where '<VSDir>' is the installed location of Visual Studio.
5405 .IP MSVS_USE_MFC_DIRS
5406 Tells the MS Visual Studio tool(s) to use
5407 the MFC directories in its default paths
5408 for compiling and linking.
5409 Under MSVS version 6,
5411 .B MSVS_USE_MFC_DIRS
5420 external environment variable,
5426 external environment variable.
5427 Under MSVS version 7,
5429 .B MSVS_USE_MFC_DIRS
5432 .B "atlmfc\\\\include"
5433 directory to the default
5435 external environment variable,
5438 directory to the default
5440 external environment variable.
5441 The current default value is
5443 which means these directories
5444 are added to the paths by default.
5445 This default value is likely to change
5446 in a future release,
5447 so users who want the ATL and MFC
5448 values included in their paths
5449 are encouraged to enable the
5450 .B MSVS_USE_MFC_DIRS
5452 to avoid future incompatibility.
5453 This variable has no effect if the
5457 environment variables are set explictly.
5460 Sets the preferred version of MSVS to use.
5462 SCons will (by default) select the latest version of MSVS
5463 installed on your machine. So, if you have version 6 and version 7
5464 (MSVS .NET) installed, it will prefer version 7. You can override this by
5467 variable in the Environment initialization, setting it to the
5468 appropriate version ('6.0' or '7.0', for example).
5469 If the given version isn't installed, tool initialization will fail.
5472 The action used to generate Microsoft Visual Studio
5473 project and solution files.
5475 .IP MSVSPROJECTSUFFIX
5476 The suffix used for Microsoft Visual Studio project (DSP) files.
5477 The default value is
5479 when using Visual Studio version 7.x (.NET),
5482 when using earlier versions of Visual Studio.
5484 .IP MSVSSOLUTIONSUFFIX
5485 The suffix used for Microsoft Visual Studio solution (DSW) files.
5486 The default value is
5488 when using Visual Studio version 7.x (.NET),
5491 when using earlier versions of Visual Studio.
5494 When set to non-zero,
5495 suppresses creation of a corresponding Win32 static import lib by the
5497 builder when used with
5498 MinGW or Microsoft Visual Studio.
5499 This also suppresses creation
5500 of an export (.exp) file
5501 when using Microsoft Visual Studio.
5504 The prefix used for (static) object file names.
5507 The suffix used for (static) object file names.
5510 The Perforce executable.
5513 The command line used to
5514 fetch source files from Perforce.
5517 General options that are passed to Perforce.
5520 The Microsoft Visual C++ precompiled header that will be used when compiling
5521 object files. This variable is ignored by tools other than Microsoft Visual C++.
5522 When this variable is
5523 defined SCons will add options to the compiler command line to
5524 cause it to use the precompiled header, and will also set up the
5525 dependencies for the PCH file. Example:
5528 env['PCH'] = 'StdAfx.pch'
5532 This variable specifies how much of a source file is precompiled. This
5533 variable is ignored by tools other than Microsoft Visual C++, or when
5534 the PCH variable is not being used. When this variable is define it
5535 must be a string that is the name of the header that
5536 is included at the end of the precompiled portion of the source files, or
5537 the empty string if the "#pragma hrdstop" construct is being used:
5540 env['PCHSTOP'] = 'StdAfx.h'
5544 The Microsoft Visual C++ PDB file that will store debugging information for
5545 object files, shared libraries, and programs. This variable is ignored by
5546 tools other than Microsoft Visual C++.
5547 When this variable is
5548 defined SCons will add options to the compiler and linker command line to
5549 cause them to generate external debugging information, and will also set up the
5550 dependencies for the PDB file. Example:
5553 env['PDB'] = 'hello.pdb'
5557 A deprecated synonym for $DVIPDFCOM.
5560 The prefix used for PDF file names.
5563 The suffix used for PDF file names.
5566 The name of the platform used to create the Environment. If no platform is
5567 specified when the Environment is created,
5569 autodetects the platform.
5572 env = Environment(tools = [])
5573 if env['PLATFORM'] == 'cygwin':
5580 The prefix used for executable file names.
5583 The suffix used for executable file names.
5586 The command line used to convert TeX DVI files into a PostScript file.
5589 The prefix used for PostScript file names.
5592 The prefix used for PostScript file names.
5595 The qt tool tries to take this from os.environ.
5596 It also initializes all QT_*
5597 construction variables listed below.
5598 (Note that all paths are constructed
5599 with python's os.path.join() method,
5600 but are listed here with the '/' separator
5601 for easier reading.)
5602 In addition, the construction environment
5603 variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5604 are modified. Because the build-performance is affected when using this tool,
5605 you have to explicitly specify it at Environment creation:
5608 Environment(tools=['default','qt'])
5611 The qt tool supports the following operations:
5613 .B Automatic moc file generation from header files.
5614 You do not have to specify moc files explicitly, the tool does it for you.
5615 However, there are a few preconditions to do so: Your header file must have
5616 the same filebase as your implementation file and must stay in the same
5617 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
5618 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
5619 See also the corresponding builder method
5622 .B Automatic moc file generation from cxx files.
5623 As stated in the qt documentation, include the moc file at the end of
5624 the cxx file. Note that you have to include the file, which is generated
5625 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
5626 <basename>.moc. A warning is generated after building the moc file, if you
5627 do not include the correct file. If you are using BuildDir, you may
5628 need to specify duplicate=1. You can turn off automatic moc file generation
5629 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
5632 .B Automatic handling of .ui files.
5633 The implementation files generated from .ui files are handled much the same
5634 as yacc or lex files. Each .ui file given as a source of Program, Library or
5635 SharedLibrary will generate three files, the declaration file, the
5636 implementation file and a moc file. Because there are also generated headers,
5637 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
5641 Turn off scanning for mocable files. Use the Moc Builder to explicitely
5642 specify files to run moc on.
5645 Prints lots of debugging information while scanning for moc files.
5648 Default value is 'qt'. You may want to set this to 'qt-mt'.
5651 Default value is '$QTDIR/bin/moc'.
5654 Default value is ''. Prefix for moc output files, when source is a cxx file.
5657 Default value is '.moc'. Suffix for moc output files, when source is a cxx
5660 .IP QT_MOCFROMCPPFLAGS
5661 Default value is '-i'. These flags are passed to moc, when moccing a
5664 .IP QT_MOCFROMCXXCOM
5665 Command to generate a moc file from a cpp file.
5668 Command to generate a moc file from a header.
5670 .IP QT_MOCFROMHFLAGS
5671 Default value is ''. These flags are passed to moc, when moccing a header
5675 Default value is 'moc_'. Prefix for moc output files, when source is a header.
5678 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
5682 Default value is '$QTDIR/bin/uic'.
5685 Command to generate header files from .ui files.
5688 Default value is ''. These flags are passed to uic, when creating a a h
5689 file from a .ui file.
5691 .IP QT_UICDECLPREFIX
5692 Default value is ''. Prefix for uic generated header files.
5694 .IP QT_UICDECLSUFFIX
5695 Default value is '.h'. Suffix for uic generated header files.
5698 Command to generate cxx files from .ui files.
5701 Default value is ''. These flags are passed to uic, when creating a cxx
5702 file from a .ui file.
5704 .IP QT_UICIMPLPREFIX
5705 Default value is 'uic_'. Prefix for uic generated implementation files.
5707 .IP QT_UICIMPLSUFFIX
5708 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
5712 Default value is '.ui'. Suffix of designer input files.
5715 The archive indexer.
5718 General options passed to the archive indexer.
5721 The resource compiler used by the RES builder.
5724 The command line used by the RES builder.
5727 The flags passed to the resource compiler by the RES builder.
5731 Note that this variable is not actually used
5732 for the command to fetch source files from RCS;
5735 construction variable, below.
5738 The RCS "checkout" executable,
5739 used to fetch source files from RCS.
5742 The command line used to
5743 fetch (checkout) source files from RCS.
5746 Options that are passed to the $RCS_CO command.
5749 A function that converts a file name into a list of Dir instances by
5750 searching the repositories.
5753 The Java RMI stub compiler.
5756 The command line used to compile stub
5757 and skeleton class files
5758 from Java classes that contain RMI implementations.
5759 Any options specified in the $RMICFLAGS construction variable
5760 are included on this command line.
5763 General options passed to the Java RMI stub compiler.
5766 A list of paths to search for shared libraries when running programs.
5767 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
5768 Ignored on platforms and toolchains that don't support it.
5769 Note that the paths added to RPATH
5770 are not transformed by
5772 in any way: if you want an absolute
5773 path, you must make it absolute yourself.
5776 A list of the available implicit dependency scanners.
5777 New file scanners may be added by
5778 appending to this list,
5779 although the more flexible approach
5780 is to associate scanners
5781 with a specific Builder.
5782 See the sections "Builder Objects"
5783 and "Scanner Objects,"
5784 below, for more information.
5787 The SCCS executable.
5790 The command line used to
5791 fetch source files from SCCS.
5794 General options that are passed to SCCS.
5797 Options that are passed specifically to the SCCS "get" subcommand.
5798 This can be set, for example, to
5800 to check out editable files from SCCS.
5803 The C compiler used for generating shared-library objects.
5806 The command line used to compile a C source file
5807 to a shared-library object file.
5808 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
5809 are included on this command line.
5812 Options that are passed to the C compiler
5813 to generate shared-library objects.
5816 The C++ compiler used for generating shared-library objects.
5819 The command line used to compile a C++ source file
5820 to a shared-library object file.
5821 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
5822 are included on this command line.
5825 Options that are passed to the C++ compiler
5826 to generate shared-library objects.
5829 A string naming the shell program that will be passed to the
5834 construction variable for more information.
5837 The Fortran 77 compiler used for generating shared-library objects.
5838 You should normally set the $SHFORTRANC variable,
5839 which specifies the default Fortran compiler
5840 for all Fortran versions.
5841 You only need to set $SHF77 if you need to use a specific compiler
5842 or compiler version for Fortran 77 files.
5845 The command line used to compile a Fortran 77 source file
5846 to a shared-library object file.
5847 You only need to set $SHF77COM if you need to use a specific
5848 command line for Fortran 77 files.
5849 You should normally set the $SHFORTRANCOM variable,
5850 which specifies the default command line
5851 for all Fortran versions.
5854 Options that are passed to the Fortran 77 compiler
5855 to generated shared-library objects.
5856 You only need to set $SHF77FLAGS if you need to define specific
5857 user options for Fortran 77 files.
5858 You should normally set the $SHFORTRANFLAGS variable,
5859 which specifies the user-specified options
5860 passed to the default Fortran compiler
5861 for all Fortran versions.
5864 The command line used to compile a Fortran 77 source file to a
5865 shared-library object file
5866 after first running the file through the C preprocessor.
5867 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
5868 are included on this command line.
5869 You only need to set $SHF77PPCOM if you need to use a specific
5870 C-preprocessor command line for Fortran 77 files.
5871 You should normally set the $SHFORTRANPPCOM variable,
5872 which specifies the default C-preprocessor command line
5873 for all Fortran versions.
5876 The Fortran 90 compiler used for generating shared-library objects.
5877 You should normally set the $SHFORTRANC variable,
5878 which specifies the default Fortran compiler
5879 for all Fortran versions.
5880 You only need to set $SHF90 if you need to use a specific compiler
5881 or compiler version for Fortran 90 files.
5884 The command line used to compile a Fortran 90 source file
5885 to a shared-library object file.
5886 You only need to set $SHF90COM if you need to use a specific
5887 command line for Fortran 90 files.
5888 You should normally set the $SHFORTRANCOM variable,
5889 which specifies the default command line
5890 for all Fortran versions.
5893 Options that are passed to the Fortran 90 compiler
5894 to generated shared-library objects.
5895 You only need to set $SHF90FLAGS if you need to define specific
5896 user options for Fortran 90 files.
5897 You should normally set the $SHFORTRANFLAGS variable,
5898 which specifies the user-specified options
5899 passed to the default Fortran compiler
5900 for all Fortran versions.
5903 The command line used to compile a Fortran 90 source file to a
5904 shared-library object file
5905 after first running the file through the C preprocessor.
5906 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
5907 are included on this command line.
5908 You only need to set $SHF90PPCOM if you need to use a specific
5909 C-preprocessor command line for Fortran 90 files.
5910 You should normally set the $SHFORTRANPPCOM variable,
5911 which specifies the default C-preprocessor command line
5912 for all Fortran versions.
5915 The Fortran 95 compiler used for generating shared-library objects.
5916 You should normally set the $SHFORTRANC variable,
5917 which specifies the default Fortran compiler
5918 for all Fortran versions.
5919 You only need to set $SHF95 if you need to use a specific compiler
5920 or compiler version for Fortran 95 files.
5923 The command line used to compile a Fortran 95 source file
5924 to a shared-library object file.
5925 You only need to set $SHF95COM if you need to use a specific
5926 command line for Fortran 95 files.
5927 You should normally set the $SHFORTRANCOM variable,
5928 which specifies the default command line
5929 for all Fortran versions.
5932 Options that are passed to the Fortran 95 compiler
5933 to generated shared-library objects.
5934 You only need to set $SHF95FLAGS if you need to define specific
5935 user options for Fortran 95 files.
5936 You should normally set the $SHFORTRANFLAGS variable,
5937 which specifies the user-specified options
5938 passed to the default Fortran compiler
5939 for all Fortran versions.
5942 The command line used to compile a Fortran 95 source file to a
5943 shared-library object file
5944 after first running the file through the C preprocessor.
5945 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
5946 are included on this command line.
5947 You only need to set $SHF95PPCOM if you need to use a specific
5948 C-preprocessor command line for Fortran 95 files.
5949 You should normally set the $SHFORTRANPPCOM variable,
5950 which specifies the default C-preprocessor command line
5951 for all Fortran versions.
5954 The default Fortran compiler used for generating shared-library objects.
5957 The command line used to compile a Fortran source file
5958 to a shared-library object file.
5961 Options that are passed to the Fortran compiler
5962 to generate shared-library objects.
5965 The command line used to compile a Fortran source file to a
5966 shared-library object file
5967 after first running the file through the C preprocessor.
5968 Any options specified
5969 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
5970 are included on this command line.
5973 The prefix used for shared library file names.
5976 The suffix used for shared library file names.
5979 The linker for programs that use shared libraries.
5982 General user options passed to the linker for programs using shared libraries.
5983 Note that this variable should
5987 (or similar) options for linking with the libraries listed in $LIBS,
5990 (or similar) include search path options
5991 that scons generates automatically from $LIBPATH.
5995 for the variable that expands to library-link options,
5999 for the variable that expands to library search path options.
6002 The prefix used for shared object file names.
6005 The suffix used for shared object file names.
6008 A reserved variable name
6009 that may not be set or used in a construction environment.
6010 (See "Variable Substitution," below.)
6013 A reserved variable name
6014 that may not be set or used in a construction environment.
6015 (See "Variable Substitution," below.)
6018 A command interpreter function that will be called to execute command line
6019 strings. The function must expect 4 arguments:
6022 def spawn(shell, escape, cmd, args, env):
6026 is a string naming the shell program to use.
6028 is a function that can be called to escape shell special characters in
6031 is the path to the command to be executed.
6033 is that arguments to the command.
6035 is a dictionary of the environment variables
6036 in which the command should be executed.
6039 '\"The Subversion executable (usually named
6043 '\"The command line used to
6044 '\"fetch source files from a Subversion repository.
6047 '\"General options that are passed to Subversion.
6050 The scripting language wrapper and interface generator.
6053 The suffix that will be used for intermediate C
6054 source files generated by
6055 the scripting language wrapper and interface generator.
6056 The default value is
6057 .BR _wrap$CFILESUFFIX .
6058 By default, this value is used whenever the
6062 specified as part of the
6064 construction variable.
6067 The command line used to call
6068 the scripting language wrapper and interface generator.
6070 .IP SWIGCXXFILESUFFIX
6071 The suffix that will be used for intermediate C++
6072 source files generated by
6073 the scripting language wrapper and interface generator.
6074 The default value is
6075 .BR _wrap$CFILESUFFIX .
6076 By default, this value is used whenever the
6078 option is specified as part of the
6080 construction variable.
6083 General options passed to
6084 the scripting language wrapper and interface generator.
6085 This is where you should set
6089 or whatever other options you want to specify to SWIG.
6092 option in this variable,
6095 generate a C++ intermediate source file
6096 with the extension that is specified as the
6104 The command line used to call the tar archiver.
6107 General options passed to the tar archiver.
6110 A reserved variable name
6111 that may not be set or used in a construction environment.
6112 (See "Variable Substitution," below.)
6115 A reserved variable name
6116 that may not be set or used in a construction environment.
6117 (See "Variable Substitution," below.)
6120 The suffix used for tar file names.
6123 The TeX formatter and typesetter.
6126 The command line used to call the TeX formatter and typesetter.
6129 General options passed to the TeX formatter and typesetter.
6132 A list of the names of the Tool specifications
6133 that are part of this construction environment.
6135 .IP WIN32_INSERT_DEF
6136 When this is set to true,
6137 a library build of a WIN32 shared library (.dll file)
6138 will also build a corresponding .def file at the same time,
6139 if a .def file is not already listed as a build target.
6140 The default is 0 (do not build a .def file).
6143 The prefix used for WIN32 .def file names.
6146 The suffix used for WIN32 .def file names.
6149 The parser generator.
6152 The command line used to call the parser generator
6153 to generate a source file.
6156 General options passed to the parser generator.
6157 If $YACCFLAGS contains a \-d option,
6158 SCons assumes that the call will also create a .h file
6159 (if the yacc source file ends in a .y suffix)
6161 (if the yacc source file ends in a .yy suffix)
6164 The zip compression and file packaging utility.
6167 The command line used to call the zip utility,
6168 or the internal Python function used to create a
6177 module used by the internal Python function
6178 to control whether the zip archive
6179 is compressed or not.
6180 The default value is
6181 .BR zipfile.ZIP_DEFLATED ,
6182 which creates a compressed zip archive.
6183 This value has no effect when using Python 1.5.2
6186 module is otherwise unavailable.
6189 General options passed to the zip utility.
6192 Construction variables can be retrieved and set using the
6194 method of the construction environment:
6197 dict = env.Dictionary()
6201 or using the [] operator:
6207 Construction variables can also be passed to the construction environment
6211 env = Environment(CC="cc")
6214 or when copying a construction environment using the
6219 env2 = env.Copy(CC="cl.exe")
6222 .SS Configure Contexts
6226 .I configure contexts,
6227 an integrated mechanism similar to the
6228 various AC_CHECK macros in GNU autoconf
6229 for testing for the existence of C header
6230 files, libraries, etc.
6231 In contrast to autoconf,
6233 does not maintain an explicit cache of the tested values,
6234 but uses its normal dependency tracking to keep the checked values
6236 The following methods can be used to perform checks:
6239 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
6241 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
6242 This creates a configure context, which can be used to perform checks.
6244 specifies the environment for building the tests.
6245 This environment may be modified when performing checks.
6247 is a dictionary containing custom tests.
6248 See also the section about custom tests below.
6249 By default, no custom tests are added to the configure context.
6251 specifies a directory where the test cases are built.
6252 Note that this directory is not used for building
6254 The default value is the directory
6257 specifies a file which collects the output from commands
6258 that are executed to check for the existence of header files, libraries, etc.
6259 The default is the file #/config.log.
6260 If you are using the
6263 you may want to specify a subdirectory under your build directory.
6268 instance has the following associated methods:
6271 .RI Configure.Finish( self )
6272 This method should be called after configuration is done.
6273 It returns the environment as modified
6274 by the configuration checks performed.
6275 After this method is called, no further checks can be performed
6276 with this configuration context.
6277 However, you can create a new
6279 context to perform additional checks.
6280 Only one context should be active at a time.
6282 The following Checks are predefined.
6283 (This list will likely grow larger as time
6284 goes by and developers contribute new useful tests.)
6287 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6290 is usable in the specified language.
6293 in which case the last item in the list
6294 is the header file to be checked,
6295 and the previous list items are
6298 lines should precede the
6299 header line being checked for.
6300 The optional argument
6303 a two character string, where the first character denotes the opening
6304 quote and the second character denotes the closing quote.
6305 By default, both characters are " (double quote).
6306 The optional argument
6312 and selects the compiler to be used for the check.
6313 Returns 1 on success and 0 on failure.
6316 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6317 This is a wrapper around
6318 .B Configure.CheckHeader
6321 is usable in the C language.
6324 in which case the last item in the list
6325 is the header file to be checked,
6326 and the previous list items are
6329 lines should precede the
6330 header line being checked for.
6331 The optional argument
6334 a two character string, where the first character denotes the opening
6335 quote and the second character denotes the closing quote (both default
6337 Returns 1 on success and 0 on failure.
6340 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6341 This is a wrapper around
6342 .B Configure.CheckHeader
6345 is usable in the C++ language.
6348 in which case the last item in the list
6349 is the header file to be checked,
6350 and the previous list items are
6353 lines should precede the
6354 header line being checked for.
6355 The optional argument
6358 a two character string, where the first character denotes the opening
6359 quote and the second character denotes the closing quote (both default
6361 Returns 1 on success and 0 on failure.
6364 .RI Configure.CheckFunc( self ", " function_name ", [" language ])
6365 Checks if the specified
6366 C or C++ function is available.
6368 is the name of the function to check for.
6375 and selects the compiler to be used for the check;
6379 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
6386 is 1 and the library provides the specified
6388 appends the library to the LIBS construction environment variable.
6390 may also be None (the default),
6393 is checked with the current LIBS variable,
6394 or a list of library names,
6395 in which case each library in the list
6402 you can link against the specified
6410 and selects the compiler to be used for the check;
6412 The default value for
6415 It is assumed, that the C-language is used.
6416 This method returns 1 on success and 0 on error.
6419 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
6422 .RI Configure.CheckLib
6423 call, this call provides a more sophisticated way to check against libraries.
6426 specifies the library or a list of libraries to check.
6428 specifies a header to check for.
6431 in which case the last item in the list
6432 is the header file to be checked,
6433 and the previous list items are
6436 lines should precede the
6437 header line being checked for.
6439 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6441 can be any valid expression (with a trailing ';'). The default is 'main();'.
6443 specifies whether to add the library to the environment (only if the check
6444 succeeds). This method returns 1 on success and 0 on error.
6447 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
6448 Checks for the existence of a type defined by
6451 specifies the typedef name to check for.
6453 is a string containing one or more
6455 lines that will be inserted into the program
6456 that will be run to test for the existence of the type.
6463 and selects the compiler to be used for the check;
6467 Example of a typical Configure usage:
6471 conf = Configure( env )
6472 if not conf.CheckCHeader( 'math.h' ):
6473 print 'We really need math.h!'
6475 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6476 # do stuff for qt - usage, e.g.
6477 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6482 You can define your own custom checks.
6483 in addition to the predefined checks.
6484 These are passed in a dictionary to the Configure function.
6485 This dictionary maps the names of the checks
6486 to user defined Python callables
6487 (either Python functions or class instances implementing the
6490 The first argument of the call is always a
6492 instance followed by the arguments,
6493 which must be supplied by the user of the check.
6494 These CheckContext instances define the following methods:
6497 .RI CheckContext.Message( self ", " text )
6499 Usually called before the check is started.
6501 will be displayed to the user, e.g. 'Checking for library X...'
6504 .RI CheckContext.Result( self, ", " res )
6506 Usually called after the check is done.
6508 can be either an integer or a string. In the former case, 'ok' (res != 0)
6509 or 'failed' (res == 0) is displayed to the user, in the latter case the
6510 given string is displayed.
6513 .RI CheckContext.TryCompile( self ", " text ", " extension )
6514 Checks if a file with the specified
6516 (e.g. '.c') containing
6518 can be compiled using the environment's
6520 builder. Returns 1 on success and 0 on failure.
6523 .RI CheckContext.TryLink( self ", " text ", " extension )
6524 Checks, if a file with the specified
6526 (e.g. '.c') containing
6528 can be compiled using the environment's
6530 builder. Returns 1 on success and 0 on failure.
6533 .RI CheckContext.TryRun( self ", " text ", " extension )
6534 Checks, if a file with the specified
6536 (e.g. '.c') containing
6538 can be compiled using the environment's
6540 builder. On success, the program is run. If the program
6541 executes successfully
6542 (that is, its return status is 0),
6547 is the standard output of the
6549 If the program fails execution
6550 (its return status is non-zero),
6551 then (0, '') is returned.
6554 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
6555 Checks if the specified
6557 with an optional source file (contents
6564 may be anything which can be converted to a
6571 is the content of the target file.
6577 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
6578 Low level implementation for testing specific builds;
6579 the methods above are based on this method.
6580 Given the Builder instance
6584 of a source file with optional
6586 this method returns 1 on success and 0 on failure. In addition,
6588 is set to the build target node, if the build was successful.
6591 Example for implementing and using custom tests:
6594 def CheckQt(context, qtdir):
6595 context.Message( 'Checking for qt ...' )
6596 lastLIBS = context.env['LIBS']
6597 lastLIBPATH = context.env['LIBPATH']
6598 lastCPPPATH= context.env['CPPPATH']
6599 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
6600 ret = context.TryLink("""
6602 int main(int argc, char **argv) {
6603 QApplication qapp(argc, argv);
6608 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
6609 context.Result( ret )
6613 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
6614 if not conf.CheckQt('/usr/lib/qt'):
6615 print 'We really need qt!'
6620 .SS Construction Variable Options
6622 Often when building software, various options need to be specified at build
6623 time that are not known when the SConstruct/SConscript files are
6624 written. For example, libraries needed for the build may be in non-standard
6625 locations, or site-specific compiler options may need to be passed to the
6628 provides a mechanism for overridding construction variables from the
6629 command line or a text-based SConscript file through an Options
6630 object. To create an Options object, call the Options() function:
6633 .RI Options([ files "], [" args ])
6634 This creates an Options object that will read construction variables from
6635 the file or list of filenames specified in
6637 If no files are specified,
6642 then no files will be read.
6643 The optional argument
6646 values that will override anything read from the specified files;
6647 it is primarily intended to be passed the
6649 dictionary that holds variables
6650 specified on the command line.
6654 opts = Options('custom.py')
6655 opts = Options('overrides.py', ARGUMENTS)
6656 opts = Options(None, {FOO:'expansion', BAR:7})
6659 Options objects have the following methods:
6662 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
6663 This adds a customizable construction variable to the Options object.
6665 is the name of the variable.
6667 is the help text for the variable.
6669 is the default value of the variable.
6671 is called to validate the value of the variable, and should take three
6672 arguments: key, value, and environment
6674 is called to convert the value before putting it in the environment, and
6675 should take a single argument: value. Example:
6678 opts.Add('CC', 'The C compiler')
6682 .RI AddOptions( list )
6683 A wrapper script that adds
6684 multiple customizable construction variables
6685 to an Options object.
6687 is a list of tuple or list objects
6688 that contain the arguments
6689 for an individual call to the
6696 ('CC', 'The C compiler'),
6697 ('VALIDATE', 'An option for testing validation',
6698 'notset', validator, None),
6703 .RI Update( env ", [" args ])
6704 This updates a construction environment
6706 with the customized construction variables. Normally this method is not
6707 called directly, but is called indirectly by passing the Options object to
6708 the Environment() function:
6711 env = Environment(options=opts)
6715 .RI Save( filename ", " env )
6716 This saves the currently set options into a script file named
6718 that can be used on the next invocation to automatically load the current
6719 settings. This method combined with the Options method can be used to
6720 support caching of options between runs.
6724 opts = Options(['options.cache', 'custom.py'])
6727 opts.Save('options.cache', env)
6731 .RI GenerateHelpText( env ", [" sort ])
6732 This generates help text documenting the customizable construction
6733 variables suitable to passing in to the Help() function.
6735 is the construction environment that will be used to get the actual values
6736 of customizable variables. Calling with
6740 will cause the output to be sorted
6741 by the specified argument.
6745 should take two arguments
6748 (like the standard Python
6753 Help(opts.GenerateHelpText(env))
6754 Help(opts.GenerateHelpText(env, sort=cmp))
6757 The text based SConscript file is executed as a Python script, and the
6758 global variables are queried for customizable construction
6765 To make it more convenient to work with customizable Options,
6767 provides a number of functions
6768 that make it easy to set up
6769 various types of Options:
6772 .RI BoolOption( key ", " help ", " default )
6773 Return a tuple of arguments
6774 to set up a Boolean option.
6778 have a default value of
6780 and display the specified
6783 The option will interpret the values
6805 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
6806 Return a tuple of arguments
6808 whose value may be one
6809 of a specified list of legal enumerated values.
6813 have a default value of
6815 and display the specified
6818 The option will only support those
6824 argument is a dictionary
6825 that can be used to convert
6826 input values into specific legal values
6835 then the values are case-sensitive.
6840 then values will be matched
6846 then values will be matched
6848 and all input values will be
6849 converted to lower case.
6852 .RI ListOption( key ", " help ", " default ", " names )
6853 Return a tuple of arguments
6855 whose value may be one or more
6856 of a specified list of legal enumerated values.
6860 have a default value of
6862 and display the specified
6865 The option will only support the values
6868 or the values in the
6871 More than one value may be specified,
6872 with all values separated by commas.
6875 .RI PackageOption( key ", " help ", " default )
6876 Return a tuple of arguments
6878 whose value is a path name
6879 of a package that may be
6880 enabled, disabled or
6881 given an explicit path name.
6885 have a default value of
6887 and display the specified
6890 The option will support the values
6897 in which case the specified
6900 or the option may be set to an
6902 (typically the path name to a package
6903 that is being enabled).
6904 The option will also support the values
6910 to disable use of the specified option.
6913 .RI PathOption( key ", " help ", " default )
6914 Return a tuple of arguments
6916 whose value is expected to be a path name.
6920 have a default value of
6922 and display the specified
6927 These functions make it
6928 convenient to create a number
6929 of options with consistent behavior
6930 in a single call to the
6936 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
6937 EnumOption('debug', 'debug output and symbols', 'no'
6938 allowed_values=('yes', 'no', 'full'),
6939 map={}, ignorecase=0), # case sensitive
6940 ListOption('shared',
6941 'libraries to build as shared libraries',
6943 names = list_of_libs),
6944 PackageOption('x11',
6945 'use X11 installed here (yes = search some places)',
6947 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
6951 .SS File and Directory Nodes
6961 Nodes, respectively.
6962 python objects, respectively.
6963 Those objects have several user-visible attributes
6964 and methods that are often useful:
6970 This path is relative to the top-level directory
6974 The build path is the same as the source path if
6979 The absolute build path of the given file or directory.
6989 object representing the
6998 # Get the current build dir's path, relative to top.
7000 # Current dir's absolute path
7002 # Next line is always '.', because it is the top dir's path relative to itself.
7004 File('foo.c').srcnode().path # source path of the given source file.
7006 # Builders also return File objects:
7007 foo = env.Program('foo.c')
7008 print "foo will be built in %s"%foo.path
7014 can be extended to build different types of targets
7015 by adding new Builder objects
7016 to a construction environment.
7018 you should only need to add a new Builder object
7019 when you want to build a new type of file or other external target.
7020 If you just want to invoke a different compiler or other tool
7021 to build a Program, Object, Library, or any other
7022 type of output file for which
7024 already has an existing Builder,
7025 it is generally much easier to
7026 use those existing Builders
7027 in a construction environment
7028 that sets the appropriate construction variables
7031 Builder objects are created
7037 function accepts the following arguments:
7040 The command line string used to build the target from the source.
7043 a list of strings representing the command
7044 to be executed and its arguments
7045 (suitable for enclosing white space in an argument),
7047 mapping source file name suffixes to
7048 any combination of command line strings
7049 (if the builder should accept multiple source file extensions),
7052 (see the next section);
7053 or a list of any of the above.
7056 takes three arguments:
7058 - a list of source nodes,
7060 - a list of target nodes,
7062 - the construction environment.
7065 The prefix that will be prepended to the target file name.
7066 This may be a simple string, or a callable object that takes
7067 two arguments, a construction environment and a list of sources,
7068 and returns a prefix.
7071 b = Builder("build_it < $SOURCE > $TARGET"
7074 def gen_prefix(env, sources):
7075 return "file-" + env['PLATFORM'] + '-'
7076 b = Builder("build_it < $SOURCE > $TARGET"
7077 prefix = gen_prefix)
7081 The suffix that will be appended to the target file name.
7082 This may be a simple string, or a callable object that takes
7083 two arguments, a construction environment and a list of sources,
7084 and returns a suffix.
7085 If the suffix is a string, then
7087 will append a '.' to the beginning of the
7088 suffix if it's not already there.
7089 The string returned by callable object
7090 is untouched and must append its own '.'
7091 to the beginning if one is desired.
7094 b = Builder("build_it < $SOURCE > $TARGET"
7097 def gen_suffix(env, sources):
7098 return "." + env['PLATFORM'] + "-file"
7099 b = Builder("build_it < $SOURCE > $TARGET"
7100 suffix = gen_suffix)
7104 The expected source file name suffix.
7107 A Scanner object that
7108 will be invoked to find
7109 implicit dependencies for this target file.
7110 This keyword argument should be used
7111 for Scanner objects that find
7112 implicit dependencies
7113 based only on the target file
7114 and the construction environment,
7117 (See the section "Scanner Objects," below,
7118 for information about creating Scanner objects.)
7121 A Scanner object that
7123 find implicit dependences in
7125 used to build this target file.
7126 This is where you would
7127 specify a scanner to
7130 lines in source files.
7131 (See the section "Scanner Objects," below,
7132 for information about creating Scanner objects.)
7135 A factory function that the Builder will use
7136 to turn any targets specified as strings into SCons Nodes.
7138 SCons assumes that all targets are files.
7139 Other useful target_factory
7142 for when a Builder creates a directory target,
7145 for when a Builder can create either a file
7146 or directory target.
7151 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7153 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7154 env.MakeDirectory('new_directory')
7158 A factory function that the Builder will use
7159 to turn any sources specified as strings into SCons Nodes.
7161 SCons assumes that all source are files.
7162 Other useful source_factory
7165 for when a Builder uses a directory as a source,
7168 for when a Builder can use files
7169 or directories (or both) as sources.
7174 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7176 env.Append(BUILDERS = {'Collect':CollectBuilder})
7177 env.Collect('archive', ['directory_name', 'file_name'])
7181 A function or list of functions to manipulate the target and source
7182 lists before dependencies are established
7183 and the target(s) are actually built.
7185 can also be a string containing a construction variable to expand
7186 to an emitter function or list of functions,
7187 or a dictionary mapping source file suffixes
7188 to emitter functions.
7189 (Only the suffix of the first source file
7190 is used to select the actual emitter function
7191 from an emitter dictionary.)
7194 takes three arguments:
7196 - a list of source nodes,
7198 - a list of target nodes,
7200 - the construction environment.
7201 An emitter must return a tuple containing two lists,
7202 the list of targets to be built by this builder,
7203 and the list of sources for this builder.
7208 def e(target, source, env):
7209 return (target + ['foo.foo'], source + ['foo.src'])
7211 # Simple association of an emitter function with a Builder.
7212 b = Builder("my_build < $TARGET > $SOURCE",
7215 def e2(target, source, env):
7216 return (target + ['bar.foo'], source + ['bar.src'])
7218 # Simple association of a list of emitter functions with a Builder.
7219 b = Builder("my_build < $TARGET > $SOURCE",
7222 # Calling an emitter function through a construction variable.
7223 env = Environment(MY_EMITTER = e)
7224 b = Builder("my_build < $TARGET > $SOURCE",
7225 emitter = '$MY_EMITTER')
7227 # Calling a list of emitter functions through a construction variable.
7228 env = Environment(EMITTER_LIST = [e, e2])
7229 b = Builder("my_build < $TARGET > $SOURCE",
7230 emitter = '$EMITTER_LIST')
7232 # Associating multiple emitters with different file
7233 # suffixes using a dictionary.
7234 def e_suf1(target, source, env):
7235 return (target + ['another_target_file'], source)
7236 def e_suf2(target, source, env):
7237 return (target, source + ['another_source_file'])
7238 b = Builder("my_build < $TARGET > $SOURCE",
7239 emitter = {'.suf1' : e_suf1,
7247 arguments must not both be used for the same Builder.
7250 Specifies whether this builder is allowed to be called multiple times for
7251 the same target file(s). The default is 0, which means the builder
7252 can not be called multiple times for the same target file(s). Calling a
7253 builder multiple times for the same target simply adds additional source
7254 files to the target; it is not allowed to change the environment associated
7255 with the target, specify addition environment overrides, or associate a different
7256 builder with the target.
7259 A construction environment that can be used
7260 to fetch source code using this Builder.
7261 (Note that this environment is
7263 used for normal builds of normal target files,
7264 which use the environment that was
7265 used to call the Builder for the target file.)
7268 A function that returns a list of actions that will be executed to build
7269 the target(s) from the source(s).
7270 The returned action(s) may be
7271 an Action object, or anything that
7272 can be converted into an Action object
7273 (see the next section).
7275 The generator function
7276 takes four arguments:
7278 - a list of source nodes,
7280 - a list of target nodes,
7282 - the construction environment,
7284 - a Boolean value that specifies
7285 whether the generator is being called
7286 for generating a build signature
7287 (as opposed to actually executing the command).
7291 def g(source, target, env, for_signature):
7292 return [["gcc", "-c", "-o"] + target + source]
7294 b = Builder(generator=g)
7298 Specifies a builder to use when a source file name suffix does not match
7299 any of the suffixes of the builder. Using this argument produces a
7300 multi-stage builder.
7303 Specifies that this builder expects exactly one source file per call. Giving
7304 more than one source files without target files results in implicitely calling
7305 the builder multiple times (once for each source given). Giving multiple
7306 source files together with target files results in a UserError exception.
7314 arguments must not both be used for the same Builder.
7317 A construction environment that can be used
7318 to fetch source code using this Builder.
7319 (Note that this environment is
7321 used for normal builds of normal target files,
7322 which use the environment that was
7323 used to call the Builder for the target file.)
7326 b = Builder(action="build < $SOURCE > $TARGET")
7327 env = Environment(BUILDERS = {'MyBuild' : b})
7328 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
7332 Any additional keyword arguments supplied
7333 when a Builder object is created
7334 (that is, when the Builder() function is called)
7335 will be set in the executing construction
7336 environment when the Builder object is called.
7337 The canonical example here would be
7338 to set a construction variable to
7339 the repository of a source code system.
7341 Any additional keyword arguments supplied
7345 will only be associated with the target
7346 created by that particular Builder call
7347 (and any other files built as a
7348 result of the call).
7350 These extra keyword arguments are passed to the
7351 following functions:
7352 command generator functions,
7354 and emitter functions.
7360 function will turn its
7362 keyword argument into an appropriate
7363 internal Action object.
7364 You can also explicity create Action objects
7368 which can then be passed to the
7371 This can be used to configure
7372 an Action object more flexibly,
7373 or it may simply be more efficient
7374 than letting each separate Builder object
7375 create a separate Action
7377 Builder objects need to do the same thing.
7382 returns an appropriate object for the action
7383 represented by the type of the first argument:
7386 If the first argument is already an Action object,
7387 the object is simply returned.
7390 If the first argument is a string,
7391 a command-line Action is returned.
7394 Action('$CC -c -o $TARGET $SOURCES')
7397 .\" XXX From Gary Ruben, 23 April 2002:
7398 .\" What would be useful is a discussion of how you execute command
7399 .\" shell commands ie. what is the process used to spawn the shell, pass
7400 .\" environment variables to it etc., whether there is one shell per
7401 .\" environment or one per command etc. It might help to look at the Gnu
7402 .\" make documentation to see what they think is important to discuss about
7403 .\" a build system. I'm sure you can do a better job of organising the
7404 .\" documentation than they have :-)
7408 If the first argument is a list,
7409 then a list of Action objects is returned.
7410 An Action object is created as necessary
7411 for each element in the list.
7414 the list is itself a list,
7415 the internal list is the
7416 command and arguments to be executed via
7418 This allows white space to be enclosed
7419 in an argument by defining
7420 a command in a list within a list:
7423 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7427 If the first argument is a Python function,
7428 a function Action is returned.
7429 The Python function takes three keyword arguments,
7431 (a Node object representing the target file),
7433 (a Node object representing the source file)
7436 (the construction environment
7437 used for building the target file).
7442 arguments may be lists of Node objects if there is
7443 more than one target file or source file.
7444 The actual target and source file name(s) may
7445 be retrieved from their Node objects
7446 via the built-in Python str() function:
7449 target_file_name = str(target)
7450 source_file_names = map(lambda x: str(x), source)
7453 The function should return
7457 to indicate a successful build of the target file(s).
7458 The function may raise an exception
7459 or return a non-zero exit status
7460 to indicate an unsuccessful build.
7463 def build_it(target = None, source = None, env = None):
7464 # build the target from the source
7467 a = Action(build_it)
7470 The second, optional argument
7471 is a Python function that returns
7472 a string to be printed to describe the action being executed.
7473 Like a function to build a file,
7474 this function takes three arguments:
7476 (a Node object representing the target file),
7478 (a Node object representing the source file)
7481 (a construction environment).
7486 arguments may be lists of Node objects if there is
7487 more than one target file or source file.
7491 def build_it(target, source, env):
7492 # build the target from the source
7495 def string_it(target, source, env):
7496 return "building '%s' from '%s'" % (target[0], source[0])
7498 # Use a positional argument.
7499 a = Action(build_it, string_it)
7501 # Alternatively, use a keyword argument.
7502 a = Action(build_it, strfunction=string_it)
7505 The third, also optional argument
7506 is a list of construction variables
7507 whose values will be included
7508 in the signature of the Action
7509 when deciding whether a target should
7510 be rebuilt because the action changed.
7511 This is necessary whenever you want a target to
7512 be rebuilt when a specific
7513 construction variable changes,
7514 because the underlying Python code for a function
7515 will not change when the value of the construction variable does.
7518 def build_it(target, source, env):
7519 # build the target from the 'XXX' construction variable
7520 open(target[0], 'w').write(env['XXX'])
7523 def string_it(target, source):
7524 return "building '%s' from '%s'" % (target[0], source[0])
7526 # Use positional arguments.
7527 a = Action(build_it, string_it, ['XXX'])
7529 # Alternatively, use a keyword argument.
7530 a = Action(build_it, varlist=['XXX'])
7533 If the action argument is not one of the above,
7536 .SS Miscellaneous Action Functions
7539 supplies a number of functions
7540 that arrange for various common
7541 file and directory manipulations
7543 These are similar in concept to "tasks" in the
7545 although the implementation is slightly different.
7546 These functions do not actually
7547 perform the specified action
7548 at the time the function is called,
7549 but instead return an Action object
7550 that can be executed at the
7552 (In Object-Oriented terminology,
7557 that return Action objects.)
7560 there are two natural ways
7563 are intended to be used.
7567 to perform the action
7568 at the time the SConscript
7572 global function to do so:
7574 Execute(Touch('file'))
7578 you can use these functions
7579 to supply Actions in a list
7583 This can allow you to
7584 perform more complicated
7585 sequences of file manipulation
7587 on platform-specific
7591 env = Environment(TMPBUILD = '/tmp/builddir')
7592 env.Command('foo.out', 'foo.in',
7593 [Mkdir('$TMPBUILD'),
7594 Copy('${SOURCE.dir}', '$TMPBUILD')
7595 "cd $TMPBUILD && make",
7596 Delete('$TMPBUILD')])
7600 .RI Chmod( dest ", " mode )
7601 Returns an Action object that
7602 changes the permissions on the specified
7604 file or directory to the specified
7609 Execute(Chmod('file', 0755))
7611 env.Command('foo.out', 'foo.in',
7612 [Copy('$TARGET', '$SOURCE'),
7613 Chmod('$TARGET', 0755)])
7617 .RI Copy( dest ", " src )
7618 Returns an Action object
7621 source file or directory to the
7623 destination file or directory.
7627 Execute(Copy('foo.output', 'foo.input'))
7629 env.Command('bar.out', 'bar.in',
7630 Copy('$TARGET', '$SOURCE'))
7635 Returns an Action that
7636 deletes the specified
7638 which may be a file or a directory tree.
7639 If a directory is specified,
7640 the entire directory tree
7645 Execute(Delete('/tmp/buildroot'))
7647 env.Command('foo.out', 'foo.in',
7648 [Delete('${TARGET.dir}'),
7655 that creates the specified
7661 Execute(Mkdir('/tmp/outputdir'))
7663 env.Command('foo.out', 'foo.in',
7664 [Mkdir('/tmp/builddir',
7665 Copy('$SOURCE', '/tmp/builddir')
7666 "cd /tmp/builddir && ])
7671 .RI Move( dest ", " src )
7673 that moves the specified
7675 file or directory to
7682 Execute(Move('file.destination', 'file.source'))
7684 env.Command('output_file', 'input_file',
7686 Move('$TARGET', 'file_created_by_MyBuildAction')])
7692 that updates the modification time
7698 Execute(Touch('file_to_be_touched'))
7700 env.Command('marker', 'input_file',
7705 .SS Variable Substitution
7707 Before executing a command,
7709 performs construction variable interpolation on the strings that make up
7710 the command line of builders.
7711 Variables are introduced by a
7714 Besides construction variables, scons provides the following
7715 variables for each command execution:
7718 The file name of the target being built, or the file name of the first
7719 target if multiple targets are being built.
7722 The file names of all targets being built.
7725 The file name of the source of the build command, or the file name of the
7726 first source if multiple sources are being built.
7729 The file names of the sources of the build command.
7731 (Note that the above variables are reserved
7732 and may not be set in a construction environment.)
7735 For example, given the construction variable CC='cc', targets=['foo'], and
7736 sources=['foo.c', 'bar.c']:
7739 action='$CC -c -o $TARGET $SOURCES'
7742 would produce the command line:
7745 cc -c -o foo foo.c bar.c
7748 Variable names may be surrounded by curly braces ({})
7749 to separate the name from the trailing characters.
7750 Within the curly braces, a variable name may have
7751 a Python slice subscript appended to select one
7752 or more items from a list.
7753 In the previous example, the string:
7765 Additionally, a variable name may
7766 have the following special
7767 modifiers appended within the enclosing curly braces
7768 to modify the interpolated string:
7771 The base path of the file name,
7772 including the directory path
7773 but excluding any suffix.
7776 The name of the directory in which the file exists.
7780 minus any directory portion.
7783 Just the basename of the file,
7785 and minus the directory.
7788 Just the file suffix.
7791 The absolute path name of the file.
7794 The POSIX form of the path,
7795 with directories separated by
7799 This is sometimes necessary on Win32 systems
7800 when a path references a file on other (POSIX) systems.
7803 The directory and file name to the source file linked to this file
7804 through BuildDir. If this file isn't linked, it just returns the
7805 directory and filename unchanged.
7808 The directory containing the source file linked to this file
7809 through BuildDir. If this file isn't linked, it just returns the
7810 directory part of the filename.
7813 The directory and file name to the source file linked to this file
7814 through BuildDir. If the file does not exist locally but exists in
7815 a Repository, the path in the Repository is returned.
7816 If this file isn't linked, it just returns the
7817 directory and filename unchanged.
7820 The Repository directory containing the source file linked to this file
7821 through BuildDir. If this file isn't linked, it just returns the
7822 directory part of the filename.
7825 For example, the specified target will
7826 expand as follows for the corresponding modifiers:
7829 $TARGET => sub/dir/file.x
7830 ${TARGET.base} => sub/dir/file
7831 ${TARGET.dir} => sub/dir
7832 ${TARGET.file} => file.x
7833 ${TARGET.filebase} => file
7834 ${TARGET.suffix} => .x
7835 ${TARGET.abspath} => /top/dir/sub/dir/file.x
7837 BuildDir('sub/dir','src')
7838 $SOURCE => sub/dir/file.x
7839 ${SOURCE.srcpath} => src/file.x
7840 ${SOURCE.srcdir} => src
7842 Repository('/usr/repository')
7843 $SOURCE => sub/dir/file.x
7844 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
7845 ${SOURCE.rsrcdir} => /usr/repository/src
7848 Lastly, a variable name
7849 may be a callable Python function
7851 construction variable in the environment.
7853 take four arguments:
7855 - a list of target nodes,
7857 - a list of source nodes,
7859 - the construction environment,
7861 - a Boolean value that specifies
7862 whether the function is being called
7863 for generating a build signature.
7864 SCons will insert whatever
7865 the called function returns
7866 into the expanded string:
7869 def foo(target, source, env, for_signature):
7872 # Will expand $BAR to "bar baz"
7873 env=Environment(FOO=foo, BAR="$FOO baz")
7876 You can use this feature to pass arguments to a
7877 Python function by creating a callable class
7878 that stores one or more arguments in an object,
7879 and then uses them when the
7882 Note that in this case,
7883 the entire variable expansion must
7884 be enclosed by curly braces
7885 so that the arguments will
7886 be associated with the
7887 instantiation of the class:
7891 def __init__(self, arg):
7894 def __call__(self, target, source, env, for_signature):
7897 # Will expand $BAR to "my argument bar baz"
7898 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
7902 The special pseudo-variables
7906 may be used to surround parts of a command line
7909 causing a rebuild--that is,
7910 which are not included in the signature
7911 of target files built with this command.
7916 will be removed from the command line
7917 before it is added to file signatures,
7922 will be removed before the command is executed.
7923 For example, the command line:
7926 echo Last build occurred $( $TODAY $). > $TARGET
7930 would execute the command:
7933 echo Last build occurred $TODAY. > $TARGET
7937 but the command signature added to any target files would be:
7940 echo Last build occurred . > $TARGET
7943 SCons uses the following rules when converting construction variables into
7947 When the value is a string it is interpreted as a space delimited list of
7948 command line arguments.
7951 When the value is a list it is interpreted as a list of command line
7952 arguments. Each element of the list is converted to a string.
7955 Anything that is not a list or string is converted to a string and
7956 interpreted as a single command line argument.
7959 Newline characters (\\n) delimit lines. The newline parsing is done after
7960 all other parsing, so it is not possible for arguments (e.g. file names) to
7961 contain embedded newline characters. This limitation will likely go away in
7962 a future version of SCons.
7970 new file types for implicit dependencies.
7971 Scanner accepts the following arguments:
7974 A Python function that will process
7976 and return a list of strings (file names)
7977 representing the implicit
7978 dependencies found in the contents.
7979 The function takes three or four arguments:
7981 def scanner_function(node, env, path):
7983 def scanner_function(node, env, path, arg):
7987 argument is the internal
7988 SCons node representing the file.
7991 to fetch the name of the file, and
7992 .B node.get_contents()
7993 to fetch contents of the file.
7997 argument is the construction environment for the scan.
7998 Fetch values from it using the
8004 argument is a tuple (or list)
8005 of directories that can be searched
8007 This will usually be the tuple returned by the
8009 argument (see below).
8013 argument is the argument supplied
8014 when the scanner was created, if any.
8017 The name of the Scanner.
8019 to identify the Scanner internally.
8022 An optional argument that, if specified,
8023 will be passed to the scanner function
8025 and the path function
8029 An optional list that can be used to
8030 determine which scanner should be used for
8032 In the usual case of scanning for file names,
8033 this argument will be a list of suffixes
8034 for the different file types that this
8035 Scanner knows how to scan.
8036 If the argument is a string,
8037 then it will be expanded
8038 into a list by the current environment.
8041 A Python function that takes
8042 two or three arguments:
8043 a construction environment, directory Node,
8044 and optional argument supplied
8045 when the scanner was created.
8048 returns a tuple of directories
8049 that can be searched for files to be returned
8050 by this Scanner object.
8053 The class of Node that should be returned
8054 by this Scanner object.
8055 Any strings or other objects returned
8056 by the scanner function
8057 that are not of this class
8058 will be run through the
8063 A Python function that will take a string
8065 and turn it into the appropriate class of Node
8066 to be returned by this Scanner object.
8069 An optional Python function that takes two arguments,
8070 a Node (file) and a construction environment,
8071 and returns whether the
8072 Node should, in fact,
8073 be scanned for dependencies.
8074 This check can be used to eliminate unnecessary
8075 calls to the scanner function when,
8076 for example, the underlying file
8077 represented by a Node does not yet exist.
8080 An optional flag that
8081 specifies whether this scanner should be re-invoked
8082 on the dependency files returned by the scanner.
8083 When this flag is not set,
8084 the Node subsystem will
8085 only invoke the scanner on the file being scanned,
8086 and not (for example) also on the files
8087 specified by the #include lines
8088 in the file being scanned.
8090 .SH SYSTEM-SPECIFIC BEHAVIOR
8091 SCons and its configuration files are very portable,
8092 due largely to its implementation in Python.
8093 There are, however, a few portability
8094 issues waiting to trap the unwary.
8096 SCons handles the upper-case
8098 file suffix differently,
8099 depending on the capabilities of
8100 the underlying system.
8101 On a case-sensitive system
8102 such as Linux or UNIX,
8103 SCons treats a file with a
8105 suffix as a C++ source file.
8106 On a case-insensitive system
8108 SCons treats a file with a
8110 suffix as a C source file.
8112 SCons handles the upper-case
8114 file suffix differently,
8115 depending on the capabilities of
8116 the underlying system.
8117 On a case-sensitive system
8118 such as Linux or UNIX,
8119 SCons treats a file with a
8121 suffix as a Fortran source file
8122 that is to be first run through
8123 the standard C preprocessor.
8124 On a case-insensitive system
8126 SCons treats a file with a
8128 suffix as a Fortran source file that should
8130 be run through the C preprocessor.
8131 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
8132 Cygwin supplies a set of tools and utilities
8133 that let users work on a
8134 Windows system using a more POSIX-like environment.
8135 The Cygwin tools, including Cygwin Python,
8137 by sharing an ability to interpret UNIX-like path names.
8138 For example, the Cygwin tools
8139 will internally translate a Cygwin path name
8140 like /cygdrive/c/mydir
8141 to an equivalent Windows pathname
8142 of C:/mydir (equivalent to C:\\mydir).
8145 that are built for native Windows execution,
8146 such as the python.org and ActiveState versions,
8147 do not have the Cygwin path name semantics.
8148 This means that using a native Windows version of Python
8149 to build compiled programs using Cygwin tools
8150 (such as gcc, bison, and flex)
8151 may yield unpredictable results.
8152 "Mixing and matching" in this way
8153 can be made to work,
8154 but it requires careful attention to the use of path names
8155 in your SConscript files.
8157 In practice, users can sidestep
8158 the issue by adopting the following rules:
8160 use the Cygwin-supplied Python interpreter
8162 when using Microsoft Visual C/C++
8163 (or some other Windows compiler)
8164 use the python.org or ActiveState version of Python
8166 .SS WIN32: scons.bat file
8168 SCons is executed via a wrapper
8171 This has (at least) two ramifications:
8173 First, Windows command-line users
8174 that want to use variable assignment
8176 may have to put double quotes
8177 around the assignments:
8180 scons "FOO=BAR" "BAZ=BLEH"
8183 Second, the Cygwin shell does not
8184 recognize this file as being the same
8187 command issued at the command-line prompt.
8188 You can work around this either by
8191 from the Cygwin command line,
8192 or by creating a wrapper shell
8198 The MinGW bin directory must be in your PATH environment variable or the
8199 PATH variable under the ENV construction variable for SCons
8200 to detect and use the MinGW tools. When running under the native Windows
8201 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8202 tools, if they are both installed, regardless of the order of the bin
8203 directories in the PATH variable. If you have both MSVC and MinGW
8204 installed and you want to use MinGW instead of MSVC,
8205 then you must explictly tell SCons to use MinGW by passing
8211 to the Environment() function, because SCons will prefer the MSVC tools
8212 over the MinGW tools.
8216 To help you get started using SCons,
8217 this section contains a brief overview of some common tasks.
8219 .SS Basic Compilation From a Single Source File
8223 env.Program(target = 'foo', source = 'foo.c')
8226 Note: Build the file by specifying
8227 the target as an argument
8228 ("scons foo" or "scons foo.exe").
8229 or by specifying a dot ("scons .").
8231 .SS Basic Compilation From Multiple Source Files
8235 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8238 .SS Setting a Compilation Flag
8241 env = Environment(CCFLAGS = '-g')
8242 env.Program(target = 'foo', source = 'foo.c')
8245 .SS Search The Local Directory For .h Files
8249 need to set CCFLAGS to specify -I options by hand.
8250 SCons will construct the right -I options from CPPPATH.
8253 env = Environment(CPPPATH = ['.'])
8254 env.Program(target = 'foo', source = 'foo.c')
8257 .SS Search Multiple Directories For .h Files
8260 env = Environment(CPPPATH = ['include1', 'include2'])
8261 env.Program(target = 'foo', source = 'foo.c')
8264 .SS Building a Static Library
8268 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8269 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8272 .SS Building a Shared Library
8276 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8277 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8280 .SS Linking a Local Library Into a Program
8283 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8284 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8285 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8288 .SS Defining Your Own Builder Object
8290 Notice that when you invoke the Builder,
8291 you can leave off the target file suffix,
8292 and SCons will add it automatically.
8295 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8297 src_suffix = '.tex')
8298 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8299 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8301 # The following creates "bar.pdf" from "bar.tex"
8302 env.PDFBuilder(target = 'bar', source = 'bar')
8305 Note also that the above initialization
8306 overwrites the default Builder objects,
8307 so the Environment created above
8308 can not be used call Builders like env.Program(),
8309 env.Object(), env.StaticLibrary(), etc.
8311 .SS Adding Your Own Builder Object to an Environment
8314 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8316 src_suffix = '.tex')
8318 env.Append(BUILDERS = {'PDFBuilder' : bld})
8319 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8320 env.Program(target = 'bar', source = 'bar.c')
8323 You also can use other Pythonic techniques to add
8324 to the BUILDERS construction variable, such as:
8328 env['BUILDERS]['PDFBuilder'] = bld
8331 .SS Defining Your Own Scanner Object
8336 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8338 def kfile_scan(node, env, path, arg):
8339 contents = node.get_contents()
8340 includes = include_re.findall(contents)
8343 kscan = Scanner(name = 'kfile',
8344 function = kfile_scan,
8347 scanners = Environment().Dictionary('SCANNERS')
8348 env = Environment(SCANNERS = scanners + [kscan])
8350 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8352 bar_in = File('bar.in')
8353 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8354 bar_in.target_scanner = kscan
8357 .SS Creating a Hierarchical Build
8359 Notice that the file names specified in a subdirectory's
8361 file are relative to that subdirectory.
8367 env.Program(target = 'foo', source = 'foo.c')
8369 SConscript('sub/SConscript')
8374 # Builds sub/foo from sub/foo.c
8375 env.Program(target = 'foo', source = 'foo.c')
8377 SConscript('dir/SConscript')
8382 # Builds sub/dir/foo from sub/dir/foo.c
8383 env.Program(target = 'foo', source = 'foo.c')
8386 .SS Sharing Variables Between SConscript Files
8388 You must explicitly Export() and Import() variables that
8389 you want to share between SConscript files.
8395 env.Program(target = 'foo', source = 'foo.c')
8398 SConscript('subdirectory/SConscript')
8400 subdirectory/SConscript:
8403 env.Program(target = 'foo', source = 'foo.c')
8406 .SS Building Multiple Variants From the Same Source
8408 Use the BuildDir() method to establish
8409 one or more separate build directories for
8410 a given source directory,
8411 then use the SConscript() method
8412 to specify the SConscript files
8413 in the build directories:
8420 BuildDir('foo', 'src')
8421 SConscript('foo/SConscript')
8425 BuildDir('bar', 'src')
8426 SConscript('bar/SConscript')
8431 env = Environment(CCFLAGS = ccflags)
8432 env.Program(target = 'src', source = 'src.c')
8435 Note the use of the Export() method
8436 to set the "ccflags" variable to a different
8437 value for each variant build.
8439 .SS Hierarchical Build of Two Libraries Linked With a Program
8444 env = Environment(LIBPATH = ['#libA', '#libB'])
8446 SConscript('libA/SConscript')
8447 SConscript('libB/SConscript')
8448 SConscript('Main/SConscript')
8453 env.Library('a', Split('a1.c a2.c a3.c'))
8458 env.Library('b', Split('b1.c b2.c b3.c'))
8463 e = env.Copy(LIBS = ['a', 'b'])
8464 e.Program('foo', Split('m1.c m2.c m3.c'))
8467 The '#' in the LIBPATH directories specify that they're relative to the
8468 top-level directory, so they don't turn into "Main/libA" when they're
8469 used in Main/SConscript.
8471 Specifying only 'a' and 'b' for the library names
8472 allows SCons to append the appropriate library
8473 prefix and suffix for the current platform
8474 (for example, 'liba.a' on POSIX systems,
8475 'a.lib' on Windows).
8477 .SS Customizing contruction variables from the command line.
8479 The following would allow the C compiler to be specified on the command
8480 line or in the file custom.py.
8483 opts = Options('custom.py')
8484 opts.Add('CC', 'The C compiler.')
8485 env = Environment(options=opts)
8486 Help(opts.GenerateHelpText(env))
8489 The user could specify the C compiler on the command line:
8495 or in the custom.py file:
8501 or get documentation on the options:
8512 .SS Using Microsoft Visual C++ precompiled headers
8514 Since windows.h includes everything and the kitchen sink, it can take quite
8515 some time to compile it over and over again for a bunch of object files, so
8516 Microsoft provides a mechanism to compile a set of headers once and then
8517 include the previously compiled headers in any object file. This
8518 technology is called precompiled headers. The general recipe is to create a
8519 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
8520 then include every header you want to precompile in "StdAfx.h", and finally
8521 include "StdAfx.h" as the first header in all the source files you are
8522 compiling to object files. For example:
8526 #include <windows.h>
8527 #include <my_big_header.h>
8546 /* do some other stuff */
8552 env['PCHSTOP'] = 'StdAfx.h'
8553 env['PCH'] = env.PCH('StdAfx.cpp')[0]
8554 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8557 For more information see the document for the PCH builder, and the PCH and
8558 PCHSTOP construction variables. To learn about the details of precompiled
8559 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
8561 .SS Using Microsoft Visual C++ external debugging information
8563 Since including debugging information in programs and shared libraries can
8564 cause their size to increase significantly, Microsoft provides a mechanism
8565 for including the debugging information in an external file called a PDB
8566 file. SCons supports PDB files through the PDB construction
8572 env['PDB'] = 'MyApp.pdb'
8573 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8576 For more information see the document for the PDB construction variable.
8581 Specifies the directory that contains the SCons Python module directory
8582 (e.g. /home/aroach/scons-src-0.01/src/engine).
8585 A string of options that will be used by scons in addition to those passed
8586 on the command line.
8597 Steven Knight <knight@baldmt.com>
8599 Anthony Roach <aroach@electriceyeball.com>