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
762 Ignored for compatibility with GNU
764 (Touching a file to make it
765 appear up-to-date is unnecessary when using
769 -u, --up, --search-up
770 Walks up the directory structure until an
775 file is found, and uses that
776 as the top of the directory tree.
777 If no targets are specified on the command line,
778 only targets at or below the
779 current directory will be built.
783 Works exactly the same way as the
785 option except for the way default targets are handled.
786 When this option is used and no targets are specified on the command line,
787 all default targets that are defined in the SConscript(s) in the current
788 directory are built, regardless of what directory the resultant targets end
795 version, copyright information,
796 list of authors, and any other relevant information.
800 -w, --print-directory
801 Print a message containing the working directory before and
802 after other processing.
805 .RI --warn= type ", --warn=no-" type
806 Enable or disable warnings.
808 specifies the type of warnings to be enabled or disabled:
811 --warn=all, --warn=no-all
812 Enables or disables all warnings.
815 --warn=dependency, --warn=no-dependency
816 Enables or disables warnings about dependencies.
817 These warnings are disabled by default.
820 --warn=deprecated, --warn=no-deprecated
821 Enables or disables warnings about use of deprecated features.
822 These warnings are enabled by default.
825 --warn=missing-sconscript, --warn=no-missing-sconscript
826 Enables or disables warnings about missing SConscript files.
827 These warnings are enabled by default.
831 Turn off -w, even if it was turned on implicitly.
834 .\" .RI --write-filenames= file
835 .\" Write all filenames considered into
839 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
840 .\" Pretend that the target
843 .\" modified. When used with the
846 .\" show you what would be rebuilt if you were to modify that file.
852 .\" --warn-undefined-variables
853 .\" Warn when an undefined variable is referenced.
856 .RI -Y " repository" ", --repository=" repository
857 Search the specified repository for any input and target
858 files not found in the local directory hierarchy. Multiple
860 options may specified, in which case the
861 repositories are searched in the order specified.
863 .SH CONFIGURATION FILE REFERENCE
864 .\" .SS Python Basics
865 .\" XXX Adding this in the future would be a help.
866 .SS Construction Environments
867 A construction environment is the basic means by which the SConscript
868 files communicate build information to
870 A new construction environment is created using the
878 By default, a new construction environment is
879 initialized with a set of builder methods
880 and construction variables that are appropriate
881 for the current platform.
882 An optional platform keyword argument may be
883 used to specify that an environment should
884 be initialized for a different platform:
887 env = Environment(platform = 'cygwin')
888 env = Environment(platform = 'os2')
889 env = Environment(platform = 'posix')
890 env = Environment(platform = 'win32')
893 Specifying a platform initializes the appropriate
894 construction variables in the environment
895 to use and generate file names with prefixes
896 and suffixes appropriate for the platform.
902 variable from the user's external environment
903 to the construction environment's
906 This is so that any executed commands
907 that use sockets to connect with other systems
908 (such as fetching source files from
909 external CVS repository specifications like
910 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
911 will work on Win32 systems.
913 The platform argument may be function or callable object,
914 in which case the Environment() method
915 will call the specified argument to update
916 the new construction environment:
919 def my_platform(env):
922 env = Environment(platform = my_platform)
925 Additionally, a specific set of tools
926 with which to initialize the environment
927 may specified as an optional keyword argument:
930 env = Environment(tools = ['msvc', 'lex'])
933 Non-built-in tools may be specified using the toolpath argument:
936 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
939 This looks for a tool specification in tools/foo.py (as well as
940 using the ordinary default tools for the platform). foo.py should
941 have two functions: generate(env) and exists(env). generate()
942 modifies the passed in environment and exists() should return a true
943 value if the tool is available. Tools in the toolpath are used before
944 any of the built-in ones. For example, adding gcc.py to the toolpath
945 would override the built-in gcc tool.
947 The elements of the tools list may also
948 be functions or callable objects,
949 in which case the Environment() method
950 will call the specified elements
951 to update the new construction environment:
955 env['XYZZY'] = 'xyzzy'
957 env = Environment(tools = [my_tool])
960 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
961 the environment it receives to customize the tool for different platforms.
963 If no tool list is specified, then SCons will auto-detect the installed
964 tools using the PATH variable in the ENV construction variable and the
965 platform name when the Environment is constructed. Changing the PATH
966 variable after the Environment is constructed will not cause the tools to
969 SCons supports the following tool specifications out of the box:
1042 Additionally, there is a "tool" named
1044 which configures the
1045 environment with a default set of tools for the current platform.
1047 On posix and cygwin platforms
1048 the GNU tools (e.g. gcc) are preferred by SCons,
1049 on win32 the Microsoft tools (e.g. msvc)
1050 followed by MinGW are preferred by SCons,
1051 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1055 Build rules are specified by calling a construction
1056 environment's builder methods.
1057 The arguments to the builder methods are
1059 (a list of target files)
1062 (a list of source files).
1064 Because long lists of file names
1065 can lead to a lot of quoting,
1070 and a same-named environment method
1071 that split a single string
1072 into a list, separated on
1073 strings of white-space characters.
1074 (These are similar to the
1075 string.split() method
1076 from the standard Python library,
1077 but work even if the input isn't a string.)
1079 Like all Python arguments,
1080 the target and source arguments to a builder method
1081 can be specified either with or without
1082 the "target" and "source" keywords.
1083 When the keywords are omitted,
1084 the target is first,
1085 followed by the source.
1086 The following are equivalent examples of calling the Program builder method:
1089 env.Program('bar', ['bar.c', 'foo.c'])
1090 env.Program('bar', Split('bar.c foo.c'))
1091 env.Program('bar', env.Split('bar.c foo.c'))
1092 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1093 env.Program(target = 'bar', Split('bar.c foo.c'))
1094 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1095 env.Program('bar', source = string.split('bar.c foo.c'))
1098 When the target shares the same base name
1099 as the source and only the suffix varies,
1100 and if the builder method has a suffix defined for the target file type,
1101 then the target argument may be omitted completely,
1104 will deduce the target file name from
1105 the source file name.
1106 The following examples all build the
1112 (on Windows systems)
1113 from the bar.c source file:
1116 env.Program(target = 'bar', source = 'bar.c')
1117 env.Program('bar', source = 'bar.c')
1118 env.Program(source = 'bar.c')
1119 env.Program('bar.c')
1122 It is possible to override or add construction variables when calling a
1123 builder method by passing additional keyword arguments.
1124 These overridden or added
1125 variables will only be in effect when building the target, so they will not
1126 affect other parts of the build. For example, if you want to add additional
1127 libraries for just one program:
1130 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1133 or generate a shared library with a nonstandard suffix:
1136 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1139 Although the builder methods defined by
1142 methods of a construction environment object,
1143 they may also be called without an explicit environment:
1146 Program('hello', 'hello.c')
1147 SharedLibrary('word', 'word.cpp')
1151 the methods are called internally using a default construction
1152 environment that consists of the tools and values that
1154 has determined are appropriate for the local system.
1156 All builder methods return a list of Nodes
1157 that represent the target or targets that will be built.
1160 is an internal SCons object
1162 build targets or sources.
1164 The returned Node(s)
1165 can be passed to other builder methods as source(s)
1166 or passed to any SCons function or method
1167 where a filename would normally be accepted.
1168 For example, if it were necessary
1171 flag when compiling one specific object file:
1174 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1175 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1178 Using a Node in this way
1179 makes for a more portable build
1180 by avoiding having to specify
1181 a platform-specific object suffix
1182 when calling the Program() builder method.
1184 Note that Builder calls will automatically "flatten"
1185 the source and target file lists,
1186 so it's all right to have the bar_obj list
1187 return by the StaticObject() call
1188 in the middle of the source file list.
1189 If you need to manipulate a list of lists returned by Builders
1190 directly using Python,
1191 you can either build the list by hand:
1194 foo = Object('foo.c')
1195 bar = Object('bar.c')
1196 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1197 for object in objects:
1204 to create a list containing just the Nodes,
1205 which may be more convenient:
1208 foo = Object('foo.c')
1209 bar = Object('bar.c')
1210 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1211 for object in objects:
1215 The path name for a Node's file may be used
1216 by passing the Node to the Python-builtin
1221 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1222 print "The path to bar_obj is:", str(bar_obj_list[0])
1225 Note again that because the Builder call returns a list,
1226 we have to access the first element in the list
1227 .B (bar_obj_list[0])
1228 to get at the Node that actually represents
1232 provides the following builder methods:
1234 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1237 Builds a C source file given a lex (.l) or yacc (.y) input file.
1238 The suffix specified by the $CFILESUFFIX construction variable
1240 is automatically added to the target
1241 if it is not already present. Example:
1245 env.CFile(target = 'foo.c', source = 'foo.l')
1247 env.CFile(target = 'bar', source = 'bar.y')
1250 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1253 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1255 The suffix specified by the $CXXFILESUFFIX construction variable
1257 is automatically added to the target
1258 if it is not already present. Example:
1262 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1264 env.CXXFile(target = 'bar', source = 'bar.yy')
1267 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1270 Builds a .dvi file from a .tex, .ltx or .latex input file.
1271 If the source file suffix is .tex,
1273 will examine the contents of the file;
1278 is found, the file is assumed to be a LaTeX file and
1279 the target is built by invoking the $LATEXCOM command line;
1280 otherwise, the $TEXCOM command line is used.
1281 If the file is a LaTeX file,
1284 builder method will also examine the contents
1287 and invoke the $BIBTEX command line
1291 and will examine the contents
1293 file and re-run the $LATEXCOM command
1294 if the log file says it is necessary.
1297 (hard-coded within TeX itself)
1298 is automatically added to the target
1299 if it is not already present. Examples:
1302 # builds from aaa.tex
1303 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1305 env.DVI(target = 'bbb', source = 'bbb.ltx')
1306 # builds from ccc.latex
1307 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1310 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1313 Builds a Java archive (.jar) file
1314 from a source tree of .class files.
1315 If the $JARCHDIR value is set, the
1317 command will change to the specified directory using the
1320 If the contents any of the source files begin with the string
1321 .BR Manifest-Version ,
1322 the file is assumed to be a manifest
1323 and is passed to the
1330 env.Jar(target = 'foo.jar', source = 'classes')
1333 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1336 Builds one or more Java class files
1337 from one or more source trees of .java files.
1338 The class files will be placed underneath
1339 the specified target directory.
1340 SCons will parse each source .java file
1342 (including inner classes)
1343 defined within that file,
1344 and from that figure out the
1345 target .class files that will be created.
1346 SCons will also search each Java file
1347 for the Java package name,
1348 which it assumes can be found on a line
1349 beginning with the string
1351 in the first column;
1352 the resulting .class files
1353 will be placed in a directory reflecting
1354 the specified package name.
1358 defining a single public
1361 containing a package name of
1363 will generate a corresponding
1364 .IR sub/dir/Foo.class
1370 env.Java(target = 'classes', source = 'src')
1371 env.Java(target = 'classes', source = ['src1', 'src2'])
1374 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1377 Builds C header and source files for
1378 implementing Java native methods.
1379 The target can be either a directory
1380 in which the header files will be written,
1381 or a header file name which
1382 will contain all of the definitions.
1383 The source can be either the names of .class files,
1384 or the objects returned from the
1388 If the construction variable
1390 is set, either in the environment
1391 or in the call to the
1393 builder method itself,
1394 then the value of the variable
1395 will be stripped from the
1396 beginning of any .class file names.
1401 # builds java_native.h
1402 classes = env.Java(target = 'classdir', source = 'src')
1403 env.JavaH(target = 'java_native.h', source = classes)
1405 # builds include/package_foo.h and include/package_bar.h
1406 env.JavaH(target = 'include',
1407 source = ['package/foo.class', 'package/bar.class'])
1409 # builds export/foo.h and export/bar.h
1410 env.JavaH(target = 'export',
1411 source = ['classes/foo.class', 'classes/bar.class'],
1412 JAVACLASSDIR = 'classes')
1415 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1422 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1425 Builds an output file from an M4 input file.
1426 This uses a default $M4FLAGS value of
1428 which considers all warnings to be fatal
1429 and stops on the first warning
1430 when using the GNU version of m4.
1434 env.M4(target = 'foo.c', source = 'foo.c.m4')
1437 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1440 Builds an output file from a moc input file. Moc input files are either
1441 header files or cxx files. This builder is only available after using the
1442 tool 'qt'. See the QTDIR variable for more information.
1446 env.Moc('foo.h') # generates moc_foo.cc
1447 env.Moc('foo.cpp') # generates foo.moc
1450 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1452 .IP env.MSVSProject()
1453 Builds Microsoft Visual Studio project files.
1454 This builds a Visual Studio project file, based on the version of
1455 Visual Studio that is configured (either the latest installed version,
1456 or the version set by
1458 in the Environment constructor).
1459 For VS 6, it will generate
1463 files, for VS 7, it will
1470 It takes several lists of filenames to be placed into the project
1471 file, currently these are limited to
1472 .B srcs, incs, localincs, resources,
1475 These are pretty self explanatory, but it
1476 should be noted that the 'srcs' list is NOT added to the $SOURCES
1477 environment variable. This is because it represents a list of files
1478 to be added to the project file, not the source used to build the
1479 project file (in this case, the 'source' is the SConscript file used
1480 to call MSVSProject).
1482 In addition to these values (which are all optional, although not
1483 specifying any of them results in an empty project file), the
1484 following values must be specified:
1486 target: The name of the target .dsp or .vcproj file. The correct
1487 suffix for the version of Visual Studio must be used, but the value
1489 env['MSVSPROJECTSUFFIX']
1491 will be defined to the correct value (see example below).
1493 variant: The name of this particular variant. These are typically
1494 things like "Debug" or "Release", but really can be anything you want.
1495 Multiple calls to MSVSProject with different variants are allowed: all
1496 variants will be added to the project file with their appropriate
1497 build targets and sources.
1499 buildtarget: A list of SCons.Node.FS objects which is returned from
1500 the command which builds the target. This is used to tell SCons what
1501 to build when the 'build' button is pressed inside of the IDE.
1506 barsrcs = ['bar.cpp'],
1507 barincs = ['bar.h'],
1508 barlocalincs = ['StdAfx.h']
1509 barresources = ['bar.rc','resource.h']
1510 barmisc = ['bar_readme.txt']
1512 dll = local.SharedLibrary(target = 'bar.dll',
1515 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1518 localincs = barlocalincs,
1519 resources = barresources,
1522 variant = 'Release')
1525 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1532 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1535 Builds a Microsoft Visual C++ precompiled header.
1536 Calling this builder method
1537 returns a list of two targets: the PCH as the first element, and the object
1538 file as the second element. Normally the object file is ignored.
1539 This builder method is only
1540 provided when Microsoft Visual C++ is being used as the compiler.
1541 The PCH builder method is generally used in
1542 conjuction with the PCH construction variable to force object files to use
1543 the precompiled header:
1546 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1549 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1552 Builds a .pdf file from a .dvi input file
1553 (or, by extension, a .tex, .ltx, or .latex input file).
1554 The suffix specified by the $PDFSUFFIX construction variable
1556 is added automatically to the target
1557 if it is not already present. Example:
1560 # builds from aaa.tex
1561 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1562 # builds bbb.pdf from bbb.dvi
1563 env.PDF(target = 'bbb', source = 'bbb.dvi')
1566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1568 .IP env.PostScript()
1569 Builds a .ps file from a .dvi input file
1570 (or, by extension, a .tex, .ltx, or .latex input file).
1571 The suffix specified by the $PSSUFFIX construction variable
1573 is added automatically to the target
1574 if it is not already present. Example:
1577 # builds from aaa.tex
1578 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1579 # builds bbb.ps from bbb.dvi
1580 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1586 Builds an executable given one or more object files
1587 or C, C++, D, or Fortran source files.
1588 If any C, C++, D or Fortran source files are specified,
1589 then they will be automatically
1590 compiled to object files using the
1593 see that builder method's description for
1594 a list of legal source file suffixes
1595 and how they are interpreted.
1596 The target executable file prefix
1597 (specified by the $PROGPREFIX construction variable; nothing by default)
1599 (specified by the $PROGSUFFIX construction variable;
1600 by default, .exe on Windows systems, nothing on POSIX systems)
1601 are automatically added to the target if not already present.
1605 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1608 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1611 Builds a Microsoft Visual C++ resource file.
1612 This builder method is only provided
1613 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1617 for MinGW) suffix is added to the target name if no other suffix is given. The source
1618 file is scanned for implicit dependencies as though it were a C file. Example:
1621 env.RES('resource.rc')
1624 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1627 Builds stub and skeleton class files
1629 from Java .class files.
1630 The target is a directory
1631 relative to which the stub
1632 and skeleton class files will be written.
1633 The source can be the names of .class files,
1634 or the objects return from the
1638 If the construction variable
1640 is set, either in the environment
1641 or in the call to the
1643 builder method itself,
1644 then the value of the variable
1645 will be stripped from the
1646 beginning of any .class file names.
1649 classes = env.Java(target = 'classdir', source = 'src')
1650 env.RMIC(target = 'outdir1', source = classes)
1652 env.RMIC(target = 'outdir2',
1653 source = ['package/foo.class', 'package/bar.class'])
1655 env.RMIC(target = 'outdir3',
1656 source = ['classes/foo.class', 'classes/bar.class'],
1657 JAVACLASSDIR = 'classes')
1660 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1662 .IP env.RPCGenClient()
1663 Generates an RPC client stub (_clnt.c) file
1664 from a specified RPC (.x) source file.
1665 Because rpcgen only builds output files
1666 in the local directory,
1667 the command will be executed
1668 in the source file's directory by default.
1671 # Builds src/rpcif_clnt.c
1672 env.RPCGenClient('src/rpcif.x')
1675 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1677 .IP env.RPCGenHeader()
1678 Generates an RPC header (.h) file
1679 from a specified RPC (.x) source file.
1680 Because rpcgen only builds output files
1681 in the local directory,
1682 the command will be executed
1683 in the source file's directory by default.
1686 # Builds src/rpcif.h
1687 env.RPCGenHeader('src/rpcif.x')
1690 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1692 .IP env.RPCGenService()
1693 Generates an RPC server-skeleton (_svc.c) file
1694 from a specified RPC (.x) source file.
1695 Because rpcgen only builds output files
1696 in the local directory,
1697 the command will be executed
1698 in the source file's directory by default.
1701 # Builds src/rpcif_svc.c
1702 env.RPCGenClient('src/rpcif.x')
1705 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1708 Generates an RPC XDR routine (_xdr.c) file
1709 from a specified RPC (.x) source file.
1710 Because rpcgen only builds output files
1711 in the local directory,
1712 the command will be executed
1713 in the source file's directory by default.
1716 # Builds src/rpcif_xdr.c
1717 env.RPCGenClient('src/rpcif.x')
1720 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1722 .IP env.SharedLibrary()
1723 Builds a shared library
1724 (.so on a POSIX system, .dll on WIN32)
1725 given one or more object files
1726 or C, C++, D or Fortran source files.
1727 If any source files are given,
1728 then they will be automatically
1729 compiled to object files.
1730 The static library prefix and suffix (if any)
1731 are automatically added to the target.
1732 The target library file prefix
1733 (specified by the $SHLIBPREFIX construction variable;
1734 by default, lib on POSIX systems, nothing on Windows systems)
1736 (specified by the $SHLIBSUFFIX construction variable;
1737 by default, .dll on Windows systems, .so on POSIX systems)
1738 are automatically added to the target if not already present.
1742 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1745 On WIN32 systems, the
1747 builder method will always build an import (.lib) library
1748 in addition to the shared (.dll) library,
1749 adding a .lib library with the same basename
1750 if there is not already a .lib file explicitly
1751 listed in the targets.
1753 Any object files listed in the
1755 must have been built for a shared library
1760 will raise an error if there is any mismatch.
1762 On WIN32 systems, specifying "register=1" will cause the dll to be
1763 registered after it is built using REGSVR32. The command that is run
1764 ("regsvr32" by default) is determined by $REGSVR construction
1765 variable, and the flags passed are determined by $REGSVRFLAGS. By
1766 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1767 up and requiring user attention when it is run. If you change
1768 $REGSVRFLAGS, be sure to include "/s". For example,
1771 env.SharedLibrary(target = 'bar',
1772 source = ['bar.cxx', 'foo.obj'],
1777 will register "bar.dll" as a COM object when it is done linking it.
1779 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1781 .IP env.SharedObject()
1782 Builds an object file for
1783 inclusion in a shared library.
1784 Source files must have one of the same set of extensions
1785 specified above for the
1788 On some platforms building a shared object requires additional
1789 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1790 normal (static) object, but on some platforms there is no difference between a
1791 shared object and a normal (static) one. When there is a difference, SCons
1792 will only allow shared objects to be linked into a shared library, and will
1793 use a different suffix for shared objects. On platforms where there is no
1794 difference, SCons will allow both normal (static)
1795 and shared objects to be linked into a
1796 shared library, and will use the same suffix for shared and normal
1798 The target object file prefix
1799 (specified by the $SHOBJPREFIX construction variable;
1800 by default, the same as $OBJPREFIX)
1802 (specified by the $SHOBJSUFFIX construction variable)
1803 are automatically added to the target if not already present.
1807 env.SharedObject(target = 'ddd', source = 'ddd.c')
1808 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1809 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1812 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1814 .IP env.StaticLibrary()
1815 Builds a static library given one or more object files
1816 or C, C++, D or Fortran source files.
1817 If any source files are given,
1818 then they will be automatically
1819 compiled to object files.
1820 The static library prefix and suffix (if any)
1821 are automatically added to the target.
1822 The target library file prefix
1823 (specified by the $LIBPREFIX construction variable;
1824 by default, lib on POSIX systems, nothing on Windows systems)
1826 (specified by the $LIBSUFFIX construction variable;
1827 by default, .lib on Windows systems, .a on POSIX systems)
1828 are automatically added to the target if not already present.
1832 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1836 Any object files listed in the
1838 must have been built for a static library
1843 will raise an error if there is any mismatch.
1845 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1847 .IP env.StaticObject()
1848 Builds a static object file
1849 from one or more C, C++, D, or Fortran source files.
1850 Source files must have one of the following extensions:
1853 .asm assembly language file
1854 .ASM assembly language file
1866 .F WIN32: Fortran file
1867 POSIX: Fortran file + C pre-processor
1870 .fpp Fortran file + C pre-processor
1871 .FPP Fortran file + C pre-processor
1872 .s assembly language file
1873 .S WIN32: assembly language file
1874 POSIX: assembly language file + C pre-processor
1875 .spp assembly language file + C pre-processor
1876 .SPP assembly language file + C pre-processor
1879 The target object file prefix
1880 (specified by the $OBJPREFIX construction variable; nothing by default)
1882 (specified by the $OBJSUFFIX construction variable;
1883 \.obj on Windows systems, .o on POSIX systems)
1884 are automatically added to the target if not already present.
1888 env.StaticObject(target = 'aaa', source = 'aaa.c')
1889 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1890 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1893 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1896 Builds a tar archive of the specified files
1898 Unlike most builder methods,
1901 builder method may be called multiple times
1903 each additional call
1904 adds to the list of entries
1905 that will be built into the archive.
1908 env.Tar('src.tar', 'src')
1910 # Create the stuff.tar file.
1911 env.Tar('stuff', ['subdir1', 'subdir2'])
1912 # Also add "another" to the stuff.tar file.
1913 env.Tar('stuff', 'another')
1915 # Set TARFLAGS to create a gzip-filtered archive.
1916 env = Environment(TARFLAGS = '-c -z')
1917 env.Tar('foo.tar.gz', 'foo')
1919 # Also set the suffix to .tgz.
1920 env = Environment(TARFLAGS = '-c -z',
1925 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1927 .IP env.TypeLibrary()
1928 Builds a Windows type library (.tlb) file from and input IDL file
1929 (.idl). In addition, it will build the associated inteface stub and
1930 proxy source files. It names them according to the base name of the .idl file.
1935 env.TypeLibrary(source="foo.idl")
1938 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1940 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1943 Builds a header file, an implementation file and a moc file from an ui file.
1944 and returns the corresponding nodes in the above order.
1945 This builder is only available after using the tool 'qt'. Note: you can
1946 specify .ui files directly as inputs for Program, Library and SharedLibrary
1947 without using this builder. Using the builder lets you override the standard
1948 naming conventions (be careful: prefixes are always prepended to names of
1949 built files; if you don't want prefixes, you may set them to ``).
1950 See the QTDIR variable for more information.
1954 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
1955 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
1956 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
1959 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1962 Builds a zip archive of the specified files
1964 Unlike most builder methods,
1967 builder method may be called multiple times
1969 each additional call
1970 adds to the list of entries
1971 that will be built into the archive.
1974 env.Zip('src.zip', 'src')
1976 # Create the stuff.zip file.
1977 env.Zip('stuff', ['subdir1', 'subdir2'])
1978 # Also add "another" to the stuff.tar file.
1979 env.Zip('stuff', 'another')
1984 C source files, C++ source files,
1985 Fortran source files with
1987 (POSIX systems only),
1992 and assembly language files with
1994 (POSIX systems only),
1999 for C preprocessor dependencies,
2000 so the dependencies do not need to be specified explicitly.
2002 targets of builder methods automatically depend on their sources.
2003 An explicit dependency can
2004 be specified using the
2006 method of a construction environment (see below).
2008 .SS Methods and Functions to Do Things
2009 In addition to Builder methods,
2011 provides a number of other construction environment methods
2012 and global functions to
2013 manipulate the build configuration.
2015 Usually, a construction environment method
2016 and global function with the same name both exist
2017 so that you don't have to remember whether
2018 to a specific bit of functionality
2019 must be called with or without a construction environment.
2020 In the following list,
2021 if you call something as a global function
2024 .RI Function( arguments )
2026 and if you call something through a construction
2027 environment it looks like:
2029 .RI env.Function( arguments )
2031 If you can call the functionality in both ways,
2032 then both forms are listed.
2034 Except where otherwise noted,
2036 construction environment method
2038 provide the exact same functionality.
2039 The only difference is that,
2041 calling the functionality through a construction environment will
2042 substitute construction variables into
2043 any supplied strings.
2046 env = Environment(FOO = 'foo')
2050 the first call to the global
2052 function will actually add a target named
2054 to the list of default targets,
2055 while the second call to the
2057 construction environment method
2058 will expand the value
2059 and add a target named
2061 to the list of default targets.
2062 For more on construction variable expansion,
2063 see the next section on
2064 construction variables.
2066 Construction environment methods
2067 and global functions supported by
2071 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2073 .RI Action( action ", [" strfunction ", " varlist ])
2075 .RI env.Action( action ", [" strfunction ", " varlist ])
2076 Creates an Action object for
2079 See the section "Action Objects,"
2080 below, for a complete explanation of the arguments and behavior.
2082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2084 .RI AddPostAction( target ", " action )
2086 .RI env.AddPostAction( target ", " action )
2087 Arranges for the specified
2093 The specified action(s) may be
2094 an Action object, or anything that
2095 can be converted into an Action object
2098 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2100 .RI AddPreAction( target ", " action )
2102 .RI env.AddPreAction( target ", " action )
2103 Arranges for the specified
2106 before the specified
2109 The specified action(s) may be
2110 an Action object, or anything that
2111 can be converted into an Action object
2114 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2116 .RI Alias( alias ", [" targets ])
2118 .RI env.Alias( alias ", [" targets ])
2119 Creates one or more phony targets that
2120 expand to one or more other targets.
2121 Returns the Node object representing the alias,
2122 which exists outside of any file system.
2123 This Node object, or the alias name,
2124 may be used as a dependency of any other target,
2125 including another alias.
2127 can be called multiple times for the same
2128 alias to add additional targets to the alias.
2132 Alias('install', '/usr/bin')
2133 Alias(['install', 'install-lib'], '/usr/local/lib')
2135 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2136 env.Alias('install', ['/usr/local/man'])
2139 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2141 .RI AlwaysBuild( target ", ...)"
2143 .RI env.AlwaysBuild( target ", ...)"
2146 so that it is always assumed to be out of date,
2147 and will always be rebuilt if needed.
2150 does not add its target(s) to the default target list,
2151 so the targets will only be built
2152 if they are specified on the command line,
2153 or are a dependent of a target specified on the command line--but
2156 be built if so specified.
2157 Multiple targets can be passed in to a single call to
2160 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2162 .RI env.Append( key = val ", [...])"
2163 Appends the specified keyword arguments
2164 to the end of construction variables in the environment.
2165 If the Environment does not have
2166 the specified construction variable,
2167 it is simply added to the environment.
2168 If the values of the construction variable
2169 and the keyword argument are the same type,
2170 then the two values will be simply added together.
2171 Otherwise, the construction variable
2172 and the value of the keyword argument
2173 are both coerced to lists,
2174 and the lists are added together.
2175 (See also the Prepend method, below.)
2178 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2181 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2183 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2184 This appends new path elements to the given path in the
2185 specified external environment
2189 any particular path once (leaving the last one it encounters and
2190 ignoring the rest, to preserve path order),
2191 and to help assure this,
2192 will normalize all paths (using
2195 .BR os.path.normcase ).
2196 This can also handle the
2197 case where the given old path variable is a list instead of a
2198 string, in which case a list will be returned instead of a string.
2202 print 'before:',env['ENV']['INCLUDE']
2203 include_path = '/foo/bar:/foo'
2204 env.PrependENVPath('INCLUDE', include_path)
2205 print 'after:',env['ENV']['INCLUDE']
2209 after: /biz:/foo/bar:/foo
2212 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2214 .RI env.AppendUnique( key = val ", [...])"
2215 Appends the specified keyword arguments
2216 to the end of construction variables in the environment.
2217 If the Environment does not have
2218 the specified construction variable,
2219 it is simply added to the environment.
2220 If the construction variable being appended to is a list,
2221 then any value(s) that already exist in the
2222 construction variable will
2224 be added again to the list.
2227 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2230 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2233 A factory function that
2234 returns a Builder object
2235 to be used to fetch source files
2237 The returned Builder
2238 is intended to be passed to the
2243 env.SourceCode('.', env.BitKeeper())
2246 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2248 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2250 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2251 This specifies a build directory
2253 in which to build all derived files
2254 that would normally be built under
2256 Multiple build directories can be set up for multiple build variants, for
2259 must be underneath the SConstruct file's directory,
2262 may not be underneath the
2265 The default behavior is for
2267 to duplicate all of the files in the tree underneath
2271 and then build the derived files within the copied tree.
2272 (The duplication is performed by
2274 depending on the platform; see also the
2277 This guarantees correct builds
2278 regardless of whether intermediate source files
2279 are generated during the build,
2280 where preprocessors or other scanners search
2282 or whether individual compilers or other invoked tools
2283 are hard-coded to put derived files in the same directory as source files.
2285 This behavior of making a complete copy of the source tree
2286 may be disabled by setting
2291 to invoke Builders using the
2292 path names of source files in
2294 and the path names of derived files within
2296 This is always more efficient than
2298 and is usually safe for most builds.
2302 may cause build problems
2303 if source files are generated during the build,
2304 if any invoked tools are hard-coded to
2305 put derived files in the same directory as the source files.
2307 Note that specifying a
2309 works most naturally
2310 with a subsidiary SConscript file
2311 in the source directory.
2313 you would then call the subsidiary SConscript file
2314 not in the source directory,
2319 had made a virtual copy of the source tree
2320 regardless of the value of
2322 This is how you tell
2324 which variant of a source tree to build.
2328 BuildDir('build-variant1', 'src')
2329 SConscript('build-variant1/SConscript')
2330 BuildDir('build-variant2', 'src')
2331 SConscript('build-variant2/SConscript')
2337 function, described below,
2339 specify a build directory
2340 in conjunction with calling a subsidiary
2343 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2345 .RI Builder( action ", [" arguments ])
2347 .RI env.Builder( action ", [" arguments ])
2348 Creates a Builder object for
2351 See the section "Builder Objects,"
2352 below, for a complete explanation of the arguments and behavior.
2354 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2356 .RI CacheDir( cache_dir )
2358 .RI env.CacheDir( cache_dir )
2361 will maintain a cache of derived files in
2363 The derived files in the cache will be shared
2364 among all the builds using the same
2372 finds a derived file that needs to be rebuilt,
2373 it will first look in the cache to see if a
2374 derived file has already been built
2375 from identical input files and an identical build action
2376 (as incorporated into the MD5 build signature).
2379 will retrieve the file from the cache.
2380 If the derived file is not present in the cache,
2383 then place a copy of the built file in the cache
2384 (identified by its MD5 build signature),
2385 so that it may be retrieved by other
2386 builds that need to build the same derived file
2387 from identical inputs.
2391 may be disabled for any invocation
2400 will place a copy of
2402 derived files in the cache,
2403 even if they already existed
2404 and were not built by this invocation.
2405 This is useful to populate a cache
2408 is added to a build,
2417 "Retrieved `file' from cache,"
2420 option is being used.
2425 will print the action that
2427 have been used to build the file,
2428 without any indication that
2429 the file was actually retrieved from the cache.
2430 This is useful to generate build logs
2431 that are equivalent regardless of whether
2432 a given derived file has been built in-place
2433 or retrieved from the cache.
2435 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2437 .RI Clean( targets ", " files_or_dirs )
2439 .RI env.Clean( targets ", " files_or_dirs )
2440 This specifies a list of files or directories which should be removed
2441 whenever the targets are specified with the
2443 command line option.
2444 The specified targets may be a list
2445 or an individual target.
2449 and create new targets or add files and directories to the
2450 clean list for the specified targets.
2452 Multiple files or directories should be specified
2453 either as separate arguments to the
2455 method, or as a list.
2457 will also accept the return value of any of the construction environment
2462 Clean('foo', ['bar', 'baz'])
2463 Clean('dist', env.Program('hello', 'hello.c'))
2464 Clean(['foo', 'bar'], 'something_else_to_clean')
2467 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2469 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2471 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2472 Executes a specific action
2473 (or list of actions)
2474 to build a target file or files.
2475 This is more convenient
2476 than defining a separate Builder object
2477 for a single special-case build.
2478 Any keyword arguments specified override any
2479 same-named existing construction variables.
2481 Note that an action can be an external command,
2482 specified as a string,
2483 or a callable Python object;
2484 see "Action Objects," below.
2488 env.Command('foo.out', 'foo.in',
2489 "$FOO_BUILD < $SOURCES > $TARGET")
2491 env.Command('bar.out', 'bar.in',
2493 "$BAR_BUILD < $SOURCES > $TARGET"],
2494 ENV = {'PATH' : '/usr/local/bin/'})
2496 def rename(env, target, source):
2498 os.rename('.tmp', str(target[0]))
2500 env.Command('baz.out', 'baz.in',
2501 ["$BAZ_BUILD < $SOURCES > .tmp",
2505 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2507 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
2509 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
2510 Creates a Configure object for integrated
2511 functionality similar to GNU autoconf.
2512 See the section "Configure Contexts,"
2513 below, for a complete explanation of the arguments and behavior.
2515 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2517 .RI env.Copy([ key = val ", ...])"
2518 Return a separate copy of a construction environment.
2519 If there are any keyword arguments specified,
2520 they are added to the returned copy,
2521 overwriting any existing values
2526 env3 = env.Copy(CCFLAGS = '-g')
2529 Additionally, a list of tools and a toolpath may be specified, as in
2530 the Environment constructor:
2533 def MyTool(env): env['FOO'] = 'bar'
2534 env4 = env.Copy(tools = ['msvc', MyTool])
2537 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2539 .RI env.CVS( repository ", " module )
2540 A factory function that
2541 returns a Builder object
2542 to be used to fetch source files
2546 The returned Builder
2547 is intended to be passed to the
2551 The optional specified
2553 will be added to the beginning
2554 of all repository path names;
2555 this can be used, in essence,
2556 to strip initial directory names
2557 from the repository path names,
2558 so that you only have to
2559 replicate part of the repository
2560 directory hierarchy in your
2561 local build directory:
2564 # Will fetch foo/bar/src.c
2565 # from /usr/local/CVSROOT/foo/bar/src.c.
2566 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2568 # Will fetch bar/src.c
2569 # from /usr/local/CVSROOT/foo/bar/src.c.
2570 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2573 # from /usr/local/CVSROOT/foo/bar/src.c.
2574 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2577 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2579 .RI Default( targets )
2581 .RI env.Default( targets )
2582 This specifies a list of default targets,
2583 which will be built by
2585 if no explicit targets are given on the command line.
2589 and add to the list of default targets.
2591 Multiple targets should be specified as
2592 separate arguments to the
2594 method, or as a list.
2596 will also accept the Node returned by any
2597 of a construction environment's
2602 Default('foo', 'bar', 'baz')
2603 env.Default(['a', 'b', 'c'])
2604 hello = env.Program('hello', 'hello.c')
2612 will clear all default targets.
2615 will add to the (now empty) default-target list
2618 The current list of targets added using the
2620 function or method is available in the
2625 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2627 .RI DefaultEnvironment([ args ])
2628 Creates and returns a default construction environment object.
2629 This construction environment is used internally by SCons
2630 in order to execute many of the global functions in this list,
2631 and to fetch source files transparently
2632 from source code management systems.
2634 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2636 .RI Depends( target ", " dependency )
2638 .RI env.Depends( target ", " dependency )
2639 Specifies an explicit dependency;
2640 the target file(s) will be rebuilt
2641 whenever the dependency file(s) has changed.
2642 This should only be necessary
2643 for cases where the dependency
2644 is not caught by a Scanner
2648 env.Depends('foo', 'other-input-file-for-foo')
2651 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2653 .RI env.Dictionary([ vars ])
2654 Returns a dictionary object
2655 containing copies of all of the
2656 construction variables in the environment.
2657 If there are any variable names specified,
2658 only the specified construction
2659 variables are returned in the dictionary.
2662 dict = env.Dictionary()
2663 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2666 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2668 .RI Dir( name ", [" directory ])
2670 .RI env.Dir( name ", [" directory ])
2671 This returns a Directory Node,
2672 an object that represents the specified directory
2675 can be a relative or absolute path.
2677 is an optional directory that will be used as the parent directory.
2680 is specified, the current script's directory is used as the parent.
2682 Directory Nodes can be used anywhere you
2683 would supply a string as a directory name
2684 to a Builder method or function.
2685 Directory Nodes have attributes and methods
2686 that are useful in many situations;
2687 see "File and Directory Nodes," below.
2689 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2691 .RI env.Dump([ key ])
2692 Returns a pretty printable representation of the environment.
2696 should be a string containing the name of the variable of interest.
2701 print env.Dump('CCCOM')
2705 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2715 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2718 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2723 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2725 .RI EnsurePythonVersion( major ", " minor )
2727 .RI env.EnsurePythonVersion( major ", " minor )
2728 Ensure that the Python version is at least
2731 print out an error message and exit SCons with a non-zero exit code if the
2732 actual Python version is not late enough.
2735 EnsurePythonVersion(2,2)
2738 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2740 .RI EnsureSConsVersion( major ", " minor )
2742 .RI env.EnsureSConsVersion( major ", " minor )
2743 Ensure that the SCons version is at least
2746 print out an error message and exit SCons with a non-zero exit code if the
2747 actual SCons version is not late enough.
2750 EnsureSConsVersion(0,9)
2753 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2755 .RI Environment([ key = value ", ...])"
2757 .RI env.Environment([ key = value ", ...])"
2758 Return a new construction environment
2759 initialized with the specified
2763 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2765 .RI Execute( action ", [" strfunction ", " varlist ])
2767 .RI env.Execute( action ", [" strfunction ", " varlist ])
2768 Executes an Action object.
2771 may be an Action object
2772 (see the section "Action Objects,"
2773 below, for a complete explanation of the arguments and behavior),
2774 or it may be a command-line string,
2776 or executable Python function,
2777 each of which will be converted
2778 into an Action object
2780 The exit value of the command
2781 or return value of the Python function
2784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2788 .RI env.Exit([ value ])
2794 A default exit value of
2797 is used if no value is specified.
2799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2803 .RI env.Export( vars )
2806 to export a list of variables from the current
2807 SConscript file to all other SConscript files.
2808 The exported variables are kept in a global collection,
2809 so subsequent calls to
2811 will over-write previous exports that have the same name.
2812 Multiple variable names can be passed to
2814 as separate arguments or as a list. A dictionary can be used to map
2815 variables to a different name when exported. Both local variables and
2816 global variables can be exported.
2821 # Make env available for all SConscript files to Import().
2825 # Make env and package available for all SConscript files:.
2826 Export("env", "package")
2828 # Make env and package available for all SConscript files:
2829 Export(["env", "package"])
2831 # Make env available using the name debug:.
2832 Export({"debug":env})
2838 function supports an
2840 argument that makes it easier to to export a variable or
2841 set of variables to a single SConscript file.
2842 See the description of the
2846 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2848 .RI File( name ", [" directory ])
2850 .RI env.File( name ", [" directory ])
2853 an object that represents the specified file
2856 can be a relative or absolute path.
2858 is an optional directory that will be used as the parent directory.
2860 File Nodes can be used anywhere you
2861 would supply a string as a file name
2862 to a Builder method or function.
2863 File Nodes have attributes and methods
2864 that are useful in many situations;
2865 see "File and Directory Nodes," below.
2867 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2869 .RI FindFile( file ", " dirs )
2871 .RI env.FindFile( file ", " dirs )
2874 in the path specified by
2877 may be a list of file names or a single file name. In addition to searching
2878 for files that exist in the filesytem, this function also searches for
2879 derived files that have not yet been built.
2882 foo = env.FindFile('foo', ['dir1', 'dir2'])
2885 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2887 .RI Flatten( sequence )
2889 .RI env.Flatten( sequence )
2890 Takes a sequence (that is, a Python list or tuple)
2891 that may contain nested sequences
2892 and returns a flattened list containing
2893 all of the individual elements in any sequence.
2894 This can be helpful for collecting
2895 the lists returned by calls to Builders;
2896 other Builders will automatically
2897 flatten lists specified as input,
2898 but direct Python manipulation of
2899 these lists does not:
2902 foo = Object('foo.c')
2903 bar = Object('bar.c')
2905 # Because `foo' and `bar' are lists returned by the Object() Builder,
2906 # `objects' will be a list containing nested lists:
2907 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2909 # Passing such a list to another Builder is all right because
2910 # the Builder will flatten the list automatically:
2911 Program(source = objects)
2913 # If you need to manipulate the list directly using Python, you need to
2914 # call Flatten() yourself, or otherwise handle nested lists:
2915 for object in Flatten(objects):
2919 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2921 .RI GetBuildPath( file ", [" ... ])
2923 .RI env.GetBuildPath( file ", [" ... ])
2926 path name (or names) for the specified
2934 Nodes or strings representing path names.
2936 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2940 .RI env.GetLaunchDir()
2941 Returns the absolute path name of the directory from which
2944 was initially invoked.
2945 This can be useful when using the
2950 options, which internally
2951 change to the directory in which the
2955 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2957 .RI GetOption( name )
2959 .RI env.GetOption( name )
2960 This function provides a way to query a select subset of the scons command line
2961 options from a SConscript file. See
2963 for a description of the options available.
2965 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2967 '\".RI GlobalBuilders( flag )
2971 '\"adds the names of the default builders
2972 '\"(Program, Library, etc.)
2973 '\"to the global name space
2974 '\"so they can be called without an explicit construction environment.
2975 '\"(This is the default.)
2979 '\"the names of the default builders are removed
2980 '\"from the global name space
2981 '\"so that an explicit construction environment is required
2982 '\"to call all builders.
2984 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2988 .RI env.Help( text )
2989 This specifies help text to be printed if the
2991 argument is given to
2995 is called multiple times, the text is appended together in the order
3000 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3002 .RI Ignore( target ", " dependency )
3004 .RI env.Ignore( target ", " dependency )
3005 The specified dependency file(s)
3006 will be ignored when deciding if
3007 the target file(s) need to be rebuilt.
3010 env.Ignore('foo', 'foo.c')
3011 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3014 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3018 .RI env.Import( vars )
3021 to import a list of variables into the current SConscript file. This
3022 will import variables that were exported with
3028 Variables exported by
3031 Multiple variable names can be passed to
3033 as separate arguments or as a list. The variable "*" can be used
3034 to import all variables.
3039 Import("env", "variable")
3040 Import(["env", "variable"])
3044 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3046 .RI Install( dir ", " source )
3048 .RI env.Install( dir ", " source )
3049 Installs one or more files in a destination directory.
3050 The file names remain the same.
3053 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3056 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3058 .RI InstallAs( target ", " source )
3060 .RI env.InstallAs( target ", " source )
3061 Installs one or more files as specific file names,
3062 allowing changing a file name as part of the
3064 It is an error if the target and source
3065 list different numbers of files.
3068 env.InstallAs(target = '/usr/local/bin/foo',
3069 source = 'foo_debug')
3070 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3071 source = ['libFOO.a', 'libBAR.a'])
3074 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3076 .RI Literal( string )
3078 .RI env.Literal( string )
3081 will be preserved as-is
3082 and not have construction variables expanded.
3084 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3086 .RI Local( targets )
3088 .RI env.Local( targets )
3091 will have copies made in the local tree,
3092 even if an already up-to-date copy
3093 exists in a repository.
3094 Returns a list of the target Node or Nodes.
3096 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3098 .RI env.ParseConfig( command ", [" function ])
3101 to modify the environment as specified by the output of
3105 expects the output of a typical
3109 and parses the returned
3130 option gets added to both the
3137 option gets added to the
3140 Any other strings not associated with options
3141 are assumed to be the names of libraries
3144 construction variable.
3146 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3149 A factory function that
3150 returns a Builder object
3151 to be used to fetch source files
3152 from the Perforce source code management system.
3153 The returned Builder
3154 is intended to be passed to the
3159 env.SourceCode('.', env.Perforce())
3162 Perforce uses a number of external
3163 environment variables for its operation.
3164 Consequently, this function adds the
3165 following variables from the user's external environment
3166 to the construction environment's
3179 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3181 .RI Platform( string )
3182 Returns a callable object
3183 that can be used to initialize
3184 a construction environment using the
3185 platform keyword of the Environment() method:
3188 env = Environment(platform = Platform('win32'))
3191 .RI env.Platform( string )
3192 Applies the callable object for the specified platform
3194 to the environment through which the method was called.
3197 env.Platform('posix')
3204 variable from the user's external environment
3205 to the construction environment's
3208 This is so that any executed commands
3209 that use sockets to connect with other systems
3210 (such as fetching source files from
3211 external CVS repository specifications like
3212 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3213 will work on Win32 systems.
3215 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3217 .RI Precious( target ", ...)"
3219 .RI env.Precious( target ", ...)"
3222 as precious so it is not deleted before it is rebuilt. Normally
3224 deletes a target before building it.
3225 Multiple targets can be passed in to a single call to
3228 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3230 .RI env.Prepend( key = val ", [...])"
3231 Appends the specified keyword arguments
3232 to the beginning of construction variables in the environment.
3233 If the Environment does not have
3234 the specified construction variable,
3235 it is simply added to the environment.
3236 If the values of the construction variable
3237 and the keyword argument are the same type,
3238 then the two values will be simply added together.
3239 Otherwise, the construction variable
3240 and the value of the keyword argument
3241 are both coerced to lists,
3242 and the lists are added together.
3243 (See also the Append method, above.)
3246 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3249 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3251 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3252 This appends new path elements to the given path in the
3253 specified external environment
3257 any particular path once (leaving the first one it encounters and
3258 ignoring the rest, to preserve path order),
3259 and to help assure this,
3260 will normalize all paths (using
3263 .BR os.path.normcase ).
3264 This can also handle the
3265 case where the given old path variable is a list instead of a
3266 string, in which case a list will be returned instead of a string.
3270 print 'before:',env['ENV']['INCLUDE']
3271 include_path = '/foo/bar:/foo'
3272 env.PrependENVPath('INCLUDE', include_path)
3273 print 'after:',env['ENV']['INCLUDE']
3277 after: /foo/bar:/foo:/biz
3280 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3282 .RI env.AppendUnique( key = val ", [...])"
3283 Appends the specified keyword arguments
3284 to the beginning of construction variables in the environment.
3285 If the Environment does not have
3286 the specified construction variable,
3287 it is simply added to the environment.
3288 If the construction variable being appended to is a list,
3289 then any value(s) that already exist in the
3290 construction variable will
3292 be added again to the list.
3295 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3298 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3301 A factory function that
3302 returns a Builder object
3303 to be used to fetch source files
3305 The returned Builder
3306 is intended to be passed to the
3311 env.SourceCode('.', env.RCS())
3316 will fetch source files
3317 from RCS subdirectories automatically,
3319 as demonstrated in the above example
3320 should only be necessary if
3321 you are fetching from
3324 directory as the source files,
3325 or if you need to explicitly specify RCS
3326 for a specific subdirectory.
3328 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3330 .RI env.Replace( key = val ", [...])"
3331 Replaces construction variables in the Environment
3332 with the specified keyword arguments.
3335 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3338 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3340 .RI Repository( directory )
3342 .RI env.Repository( directory )
3345 is a repository to be searched for files.
3349 and each one adds to the list of
3350 repositories that will be searched.
3354 a repository is a copy of the source tree,
3355 from the top-level directory on down,
3357 both source files and derived files
3358 that can be used to build targets in
3359 the local source tree.
3360 The canonical example would be an
3361 official source tree maintained by an integrator.
3362 If the repository contains derived files,
3363 then the derived files should have been built using
3365 so that the repository contains the necessary
3366 signature information to allow
3368 to figure out when it is appropriate to
3369 use the repository copy of a derived file,
3370 instead of building one locally.
3372 Note that if an up-to-date derived file
3373 already exists in a repository,
3377 make a copy in the local directory tree.
3378 In order to guarantee that a local copy
3384 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3389 what variable(s) to use as the return value(s) of the current SConscript
3390 file. These variables will be returned to the "calling" SConscript file
3391 as the return value(s) of
3393 Multiple variable names should be passed to
3399 Return(["foo", "bar"])
3402 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3404 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3406 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3407 Creates a Scanner object for
3410 See the section "Scanner Objects,"
3411 below, for a complete explanation of the arguments and behavior.
3413 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3416 A factory function that
3417 returns a Builder object
3418 to be used to fetch source files
3420 The returned Builder
3421 is intended to be passed to the
3426 env.SourceCode('.', env.SCCS())
3431 will fetch source files
3432 from SCCS subdirectories automatically,
3434 as demonstrated in the above example
3435 should only be necessary if
3436 you are fetching from
3439 directory as the source files,
3440 or if you need to explicitly specify SCCS
3441 for a specific subdirectory.
3443 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3445 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3447 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3449 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3451 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3455 one or more subsidiary SConscript (configuration) files.
3456 There are two ways to call the
3460 The first way you can call
3462 is to explicitly specify one or more
3464 as the first argument.
3465 A single script may be specified as a string;
3466 multiple scripts must be specified as a list
3467 (either explicitly or as created by
3471 The second way you can call
3473 is to specify a list of (sub)directory names
3480 execute a subsidiary configuration file named
3482 in each of the specified directories.
3483 You may specify a name other than
3485 by supplying an optional
3491 argument provides a list of variable names or a dictionary of
3492 named values to export to the
3494 These variables are locally exported only to the specified
3496 and do not affect the
3497 global pool of variables used by
3501 '\"If multiple dirs are provided,
3502 '\"each script gets a fresh export.
3507 function to import the variables.
3511 argument specifies that all of the target files
3512 (for example, object files and executables)
3513 that would normally be built in the subdirectory in which
3515 resides should actually
3519 is interpreted relative to the directory
3520 of the calling SConscript file.
3524 argument specifies that the
3525 source files from which
3526 the target files should be built
3530 is interpreted relative to the directory
3531 of the calling SConscript file.
3535 will link or copy (depending on the platform)
3536 all the source files into the build directory.
3537 This behavior may be disabled by
3538 setting the optional
3541 (it is set to 1 by default),
3544 will refer directly to
3545 the source files in their source directory
3546 when building target files.
3549 is usually safe, and always more efficient
3552 but it may cause build problems in certain end-cases,
3553 such as compiling from source files that
3554 are generated by the build.)
3556 Any variables returned by
3560 will be returned by the call to
3566 SConscript('subdir/SConscript')
3567 foo = SConscript('sub/SConscript', exports='env')
3568 SConscript('dir/SConscript', exports=['env', 'variable'])
3569 SConscript('src/SConscript', build_dir='build', duplicate=0)
3570 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3571 SConscript(dirs=['sub1', 'sub2'])
3572 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3575 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3577 .RI SConscriptChdir( value )
3579 .RI env.SConscriptChdir( value )
3582 changes its working directory
3583 to the directory in which each
3584 subsidiary SConscript file lives.
3585 This behavior may be disabled
3586 by specifying either:
3590 env.SConscriptChdir(0)
3595 will stay in the top-level directory
3596 while reading all SConscript files.
3597 (This may be necessary when building from repositories,
3598 when all the directories in which SConscript files may be found
3599 don't necessarily exist locally.)
3601 You may enable and disable
3602 this ability by calling
3609 SConscript('foo/SConscript') # will not chdir to foo
3610 env.SConscriptChdir(1)
3611 SConscript('bar/SConscript') # will chdir to bar
3614 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3616 .RI SConsignFile([ file , dbm_module ])
3618 .RI env.SConsignFile([ file , dbm_module ])
3621 to store all file signatures
3631 is not an absolute path name,
3632 the file is placed in the same directory as the top-level
3638 argument can be used to specify
3639 which Python database module
3640 The default is to use a custom
3642 module that uses pickled
3643 Python data structures,
3644 and which works on all Python versions from 1.5.2 on.
3649 # Stores signatures in ".sconsign.dbm"
3650 # in the top-level SConstruct directory.
3653 # Stores signatures in the file "etc/scons-signatures"
3654 # relative to the top-level SConstruct directory.
3655 SConsignFile("etc/scons-signatures")
3657 # Stores signatures in the specified absolute file name.
3658 SConsignFile("/home/me/SCons/signatures")
3661 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3663 .RI env.SetDefault(key = val ", [...])"
3664 Sets construction variables to default values specified with the keyword
3665 arguments if (and only if) the variables are not already set.
3666 The following statements are equivalent:
3669 env.SetDefault(FOO = 'foo')
3671 if not env.has_key('FOO'): env['FOO'] = 'foo'
3674 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3676 .RI SetOption( name ", " value )
3678 .RI env.SetOption( name ", " value )
3679 This function provides a way to set a select subset of the scons command
3680 line options from a SConscript file. The options supported are:
3682 which corresponds to -c, --clean, and --remove;
3685 corresponds to --duplicate;
3687 which corresponds to --implicit-cache;
3689 which corresponds to --max-drift;
3691 which corresponds to -j and --jobs.
3692 See the documentation for the
3693 corresponding command line object for information about each specific
3697 SetOption('max_drift', 1)
3700 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3702 .RI SideEffect( side_effect ", " target )
3704 .RI env.SideEffect( side_effect ", " target )
3707 as a side effect of building
3713 can be a list, a file name, or a node.
3714 A side effect is a target that is created
3715 as a side effect of building other targets.
3716 For example, a Windows PDB
3717 file is created as a side effect of building the .obj
3718 files for a static library.
3719 If a target is a side effect of multiple build commands,
3721 will ensure that only one set of commands
3722 is executed at a time.
3723 Consequently, you only need to use this method
3724 for side-effect targets that are built as a result of
3725 multiple build commands.
3727 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3729 .RI SourceCode( entries ", " builder )
3731 .RI env.SourceCode( entries ", " builder )
3732 Arrange for non-existent source files to
3733 be fetched from a source code management system
3738 may be a Node, string or list of both,
3739 and may represent either individual
3740 source files or directories in which
3741 source files can be found.
3743 For any non-existent source files,
3745 will search up the directory tree
3755 will not use a builder to fetch
3756 source files for the specified
3760 builder has been specified
3761 for a directory higher up the tree.
3765 fetch files from SCCS or RCS subdirectories
3766 without explicit configuration.
3767 This takes some extra processing time
3768 to search for the necessary
3769 source code management files on disk.
3770 You can avoid these extra searches
3771 and speed up your build a little
3772 by disabling these searches as follows:
3775 env.SourceCode('.', None)
3779 Note that if the specified
3781 is one you create by hand,
3782 it must have an associated
3783 construction environment to use
3784 when fetching a source file.
3787 provides a set of canned factory
3788 functions that return appropriate
3789 Builders for various popular
3790 source code management systems.
3791 Canonical examples of invocation include:
3794 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3795 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3796 env.SourceCode('/', env.RCS())
3797 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3798 env.SourceCode('no_source.c', None)
3800 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3802 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3804 '\".RI Subversion( repository ", " module )
3805 '\"A factory function that
3806 '\"returns a Builder object
3807 '\"to be used to fetch source files
3808 '\"from the specified Subversion
3810 '\"The returned Builder
3811 '\"is intended to be passed to the
3815 '\"The optional specified
3817 '\"will be added to the beginning
3818 '\"of all repository path names;
3819 '\"this can be used, in essence,
3820 '\"to strip initial directory names
3821 '\"from the repository path names,
3822 '\"so that you only have to
3823 '\"replicate part of the repository
3824 '\"directory hierarchy in your
3825 '\"local build directory:
3828 '\"# Will fetch foo/bar/src.c
3829 '\"# from /usr/local/Subversion/foo/bar/src.c.
3830 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3832 '\"# Will fetch bar/src.c
3833 '\"# from /usr/local/Subversion/foo/bar/src.c.
3834 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3836 '\"# Will fetch src.c
3837 '\"# from /usr/local/Subversion/foo/bar/src.c.
3838 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3841 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3843 .RI SourceSignatures( type )
3845 .RI env.SourceSignatures( type )
3846 This function tells SCons what type of signature to use for source files:
3850 If the environment method is used,
3851 the specified type of source signature
3852 is only used when deciding whether targets
3853 built with that environment are up-to-date or must be rebuilt.
3854 If the global function is used,
3855 the specified type of source signature becomes the default
3856 used for all decisions
3857 about whether targets are up-to-date.
3859 "MD5" means the signature of a source file
3860 is the MD5 checksum of its contents.
3861 "timestamp" means the signature of a source file
3862 is its timestamp (modification time).
3863 There is no different between the two behaviors
3867 "MD5" signatures take longer to compute,
3868 but are more accurate than "timestamp" signatures.
3869 The default is "MD5".
3871 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3875 .RI env.Split( arg )
3876 Returns a list of file names or other objects.
3878 it will be split on strings of white-space characters
3880 making it easier to write long lists of file names.
3881 If arg is already a list,
3882 the list will be returned untouched.
3883 If arg is any other type of object,
3884 it will be returned as a list
3885 containing just the object.
3888 files = Split("f1.c f2.c f3.c")
3889 files = env.Split("f4.c f5.c f6.c")
3897 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3899 .RI TargetSignatures( type )
3901 .RI env.TargetSignatures( type )
3902 This function tells SCons what type of signatures to use
3907 If the environment method is used,
3908 the specified type of signature is only used
3909 for targets built with that environment.
3910 If the global function is used,
3911 the specified type of signature becomes the default
3912 used for all target files that
3913 don't have an explicit target signature type
3914 specified for their environments.
3916 "build" means the signature of a target file
3917 is made by concatenating all of the
3918 signatures of all its source files.
3919 "content" means the signature of a target
3920 file is an MD5 checksum of its contents.
3921 "build" signatures are usually faster to compute,
3922 but "content" signatures can prevent unnecessary rebuilds
3923 when a target file is rebuilt to the exact same contents
3924 as the previous build.
3925 The default is "build".
3927 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3929 .RI Tool( string, toolpath=[] )
3930 Returns a callable object
3931 that can be used to initialize
3932 a construction environment using the
3933 tools keyword of the Environment() method.
3934 The object may be called with a construction
3935 environment as an argument,
3936 in which case the object will be
3937 add the necessary variables
3938 to the construction environment
3939 and the name of the tool will be added to the
3941 construction variable.
3944 env = Environment(tools = [ Tool('msvc') ])
3948 t(env) # adds 'msvc' to the TOOLS variable
3949 u = Tool('opengl', toolpath = ['tools'])
3950 u(env) # adds 'opengl' to the TOOLS variable
3953 .RI env.Tool( string [, toolpath] )
3954 Applies the callable object for the specified tool
3956 to the environment through which the method was called.
3960 env.Tool('opengl', toolpath = ['build/tools'])
3963 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3967 .RI env.Value( value )
3968 Returns a Node object representing the specified Python value. Value
3969 nodes can be used as dependencies of targets. If the result of
3972 changes between SCons runs, any targets depending on
3974 will be rebuilt. When using timestamp source signatures, Value nodes'
3975 timestamps are equal to the system time when the node is created.
3978 def create(target, source, env):
3979 f = open(str(target[0]), 'wb')
3980 f.write('prefix=' + source[0].get_contents())
3982 prefix = ARGUMENTS.get('prefix', '/usr/local')
3984 env['BUILDERS']['Config'] = Builder(action = create)
3985 env.Config(target = 'package-config', source = Value(prefix))
3988 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3990 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
3992 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
3994 Searches for the specified executable
3996 returning the full path name to the program
3998 and returning None if not.
3999 Searches the specified
4001 the value of the calling environment's PATH
4002 (env['ENV']['PATH']),
4003 or the user's current external PATH
4004 (os.environ['PATH'])
4006 On Win32 systems, searches for executable
4007 programs with any of the file extensions
4008 listed in the specified
4010 the calling environment's PATHEXT
4011 (env['ENV']['PATHEXT'])
4012 or the user's current PATHEXT
4013 (os.environ['PATHEXT'])
4021 .SS SConscript Variables
4022 In addition to the global functions and methods,
4024 supports a number of Python variables
4025 that can be used in SConscript files
4026 to affect how you want the build to be performed.
4028 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4033 arguments specified on the command line.
4034 Each element in the list is a tuple
4036 .RI ( keyword , value )
4042 elements of the tuple
4044 subscripting for element
4048 of the tuple, respectively.
4051 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4052 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4053 third_tuple = ARGLIST[2]
4054 print "third keyword, value =", third_tuple[0], third_tuple[1]
4055 for key, value in ARGLIST:
4056 # process key and value
4059 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4062 A dictionary of all the
4064 arguments specified on the command line.
4065 The dictionary is not in order,
4066 and if a given keyword has
4067 more than one value assigned to it
4068 on the command line,
4069 the last (right-most) value is
4075 if ARGUMENTS.get('debug', 0):
4076 env = Environment(CCFLAGS = '-g')
4081 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4084 A list of the targets which
4086 will actually try to build,
4087 regardless of whether they were specified on
4088 the command line or via the
4091 The elements of this list may be strings
4093 nodes, so you should run the list through the Python
4095 function to make sure any Node path names
4096 are converted to strings.
4098 Because this list may be taken from the
4099 list of targets specified using the
4102 the contents of the list may change
4103 on each successive call to
4108 for additional information.
4111 if 'foo' in BUILD_TARGETS:
4112 print "Don't forget to test the `foo' program!"
4113 if 'special/program' in BUILD_TARGETS:
4114 SConscript('special')
4119 list only contains targets expected listed
4120 on the command line or via calls to the
4125 contain all dependent targets that will be built as
4126 a result of making the sure the explicitly-specified
4127 targets are up to date.
4129 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4131 COMMAND_LINE_TARGETS
4132 A list of the targets explicitly specified on
4134 If there are no targets specified on the command line,
4136 This can be used, for example,
4137 to take specific actions only
4138 when a certain target or targets
4139 is explicitly being built:
4142 if 'foo' in COMMAND_LINE_TARGETS:
4143 print "Don't forget to test the `foo' program!"
4144 if 'special/program' in COMMAND_LINE_TARGETS:
4145 SConscript('special')
4148 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4151 A list of the target
4153 that have been specified using the
4156 The elements of the list are nodes,
4157 so you need to run them through the Python
4159 function to get at the path name for each Node.
4162 print str(DEFAULT_TARGETS[0])
4163 if 'foo' in map(str, DEFAULT_TARGETS):
4164 print "Don't forget to test the `foo' program!"
4169 list change on on each successive call to the
4174 print map(str, DEFAULT_TARGETS) # originally []
4176 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4178 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4180 print map(str, DEFAULT_TARGETS) # back to []
4183 Consequently, be sure to use
4185 only after you've made all of your
4188 or else simply be careful of the order
4189 of these statements in your SConscript files
4190 so that you don't look for a specific
4191 default target before it's actually been added to the list.
4193 .SS Construction Variables
4194 .\" XXX From Gary Ruben, 23 April 2002:
4195 .\" I think it would be good to have an example with each construction
4196 .\" variable description in the documentation.
4198 .\" CC The C compiler
4199 .\" Example: env["CC"] = "c68x"
4200 .\" Default: env["CC"] = "cc"
4202 .\" CCCOM The command line ...
4204 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4205 .\" env["CC"] = "c68x"
4206 .\" env["CFLAGS"] = "-ps -qq -mr"
4207 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4209 .\" (I dunno what this is ;-)
4210 A construction environment has an associated dictionary of
4211 .I construction variables
4212 that are used by built-in or user-supplied build rules.
4213 Construction variables must follow the same rules for
4215 the initial character must be an underscore or letter,
4216 followed by any number of underscores, letters, or digits.
4218 A number of useful construction variables are automatically defined by
4219 scons for each supported platform, and additional construction variables
4220 can be defined by the user. The following is a list of the automatically
4221 defined construction variables:
4224 The static library archiver.
4227 The command line used to generate a static library from object files.
4230 General options passed to the static library archiver.
4236 The command line used to generate an object file
4237 from an assembly-language source file.
4240 General options passed to the assembler.
4243 The command line used to assemble an assembly-language
4244 source file into an object file
4245 after first running the file through the C preprocessor.
4246 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4247 are included on this command line.
4250 The bibliography generator for the TeX formatter and typesetter and the
4251 LaTeX structured formatter and typesetter.
4254 The command line used to call the bibliography generator for the
4255 TeX formatter and typesetter and the LaTeX structured formatter and
4259 General options passed to the bibliography generator for the TeX formatter
4260 and typesetter and the LaTeX structured formatter and typesetter.
4263 The BitKeeper executable.
4266 The command line for
4267 fetching source files using BitKEeper.
4270 The command ($BITKEEPER) and subcommand
4271 for fetching source files using BitKeeper.
4273 .IP BITKEEPERGETFLAGS
4274 Options that are passed to the BitKeeper
4279 A dictionary mapping the names of the builders
4280 available through this environment
4281 to underlying Builder objects.
4283 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4284 are available by default.
4285 If you initialize this variable when an
4286 Environment is created:
4289 env = Environment(BUILDERS = {'NewBuilder' : foo})
4292 the default Builders will no longer be available.
4293 To use a new Builder object in addition to the default Builders,
4294 add your new Builder object like this:
4298 env.Append(BUILDERS = {'NewBuilder' : foo})
4305 env['BUILDERS]['NewBuilder'] = foo
4312 The command line used to compile a C source file to a (static) object file.
4313 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4314 are included on this command line.
4317 General options that are passed to the C compiler.
4320 The suffix for C source files.
4321 This is used by the internal CFile builder
4322 when generating C files from Lex (.l) or YACC (.y) input files.
4323 The default suffix, of course, is
4326 On case-insensitive systems (like Win32),
4333 The version number of the C compiler.
4334 This may or may not be set,
4335 depending on the specific C compiler being used.
4338 A function used to produce variables like $_CPPINCFLAGS. It takes
4340 arguments: a prefix to concatenate onto each element, a list of
4341 elements, a suffix to concatenate onto each element, an environment
4342 for variable interpolation, and an optional function that will be
4343 called to transform the list before concatenation.
4346 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4350 A platform independent specification of C preprocessor definitions.
4351 The definitions will be added to command lines
4352 through the automatically-generated
4353 $_CPPDEFFLAGS construction variable (see below),
4354 which is constructed according to
4355 the type of value of $CPPDEFINES:
4358 If $CPPDEFINES is a string,
4360 $CPPDEFPREFIX and $CPPDEFSUFFIX
4361 construction variables
4362 will be added to the beginning and end.
4365 # Will add -Dxyz to POSIX compiler command lines,
4366 # and /Dxyz to Microsoft Visual C++ command lines.
4367 env = Environment(CPPDEFINES='xyz')
4371 If $CPPDEFINES is a list,
4373 $CPPDEFPREFIX and $CPPDEFSUFFIX
4374 construction variables
4375 will be appended to the beginning and end
4376 of each element in the list.
4377 If any element is a list or tuple,
4378 then the first item is the name being
4379 defined and the second item is its value:
4382 # Will add -DB=2 -DA to POSIX compiler command lines,
4383 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4384 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4388 If $CPPDEFINES is a dictionary,
4390 $CPPDEFPREFIX and $CPPDEFSUFFIX
4391 construction variables
4392 will be appended to the beginning and end
4393 of each item from the dictionary.
4394 The key of each dictionary item
4395 is a name being defined
4396 to the dictionary item's corresponding value;
4399 then the name is defined without an explicit value.
4400 Note that the resulting flags are sorted by keyword
4401 to ensure that the order of the options on the
4402 command line is consistent each time
4407 # Will add -DA -DB=2 to POSIX compiler command lines,
4408 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4409 env = Environment(CPPDEFINES={'B':2, 'A':None})
4413 An automatically-generated construction variable
4414 containing the C preprocessor command-line options
4416 The value of $_CPPDEFFLAGS is created
4417 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4418 to the beginning and end
4419 of each directory in $CPPDEFINES.
4422 The prefix used to specify preprocessor definitions
4423 on the C compiler command line.
4424 This will be appended to the beginning of each definition
4425 in the $CPPDEFINES construction variable
4426 when the $_CPPDEFFLAGS variable is automatically generated.
4429 The suffix used to specify preprocessor definitions
4430 on the C compiler command line.
4431 This will be appended to the end of each definition
4432 in the $CPPDEFINES construction variable
4433 when the $_CPPDEFFLAGS variable is automatically generated.
4436 User-specified C preprocessor options.
4437 These will be included in any command that uses the C preprocessor,
4438 including not just compilation of C and C++ source files
4439 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4440 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4441 $F77PPCOM and $SHF77PPCOM command lines
4442 used to compile a Fortran source file,
4443 and the $ASPPCOM command line
4444 used to assemble an assembly language source file,
4445 after first running each file through the C preprocessor.
4446 Note that this variable does
4450 (or similar) include search path options
4451 that scons generates automatically from $CPPPATH.
4455 for the variable that expands to those options.
4458 An automatically-generated construction variable
4459 containing the C preprocessor command-line options
4460 for specifying directories to be searched for include files.
4461 The value of $_CPPINCFLAGS is created
4462 by appending $INCPREFIX and $INCSUFFIX
4463 to the beginning and end
4464 of each directory in $CPPPATH.
4467 The list of directories that the C preprocessor will search for include
4468 directories. The C/C++ implicit dependency scanner will search these
4469 directories for include files. Don't explicitly put include directory
4470 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4471 and the directories will not be searched by the dependency scanner. Note:
4472 directory names in CPPPATH will be looked-up relative to the SConscript
4473 directory when they are used in a command. To force
4475 to look-up a directory relative to the root of the source tree use #:
4478 env = Environment(CPPPATH='#/include')
4482 The directory look-up can also be forced using the
4487 include = Dir('include')
4488 env = Environment(CPPPATH=include)
4492 The directory list will be added to command lines
4493 through the automatically-generated
4495 construction variable,
4496 which is constructed by
4497 appending the values of the
4498 $INCPREFIX and $INCSUFFIX
4499 construction variables
4500 to the beginning and end
4501 of each directory in $CPPPATH.
4502 Any command lines you define that need
4503 the CPPPATH directory list should
4504 include $_CPPINCFLAGS:
4507 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4511 The list of suffixes of files that will be scanned
4512 for C preprocessor implicit dependencies
4514 The default list is:
4517 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4518 ".h", ".H", ".hxx", ".hpp", ".hh",
4519 ".F", ".fpp", ".FPP",
4520 ".S", ".spp", ".SPP"]
4527 Options that are passed to the CVS checkout subcommand.
4530 The command line used to
4531 fetch source files from a CVS repository.
4534 General options that are passed to CVS.
4535 By default, this is set to
4537 to specify from where the files must be fetched.
4540 The path to the CVS repository.
4541 This is referenced in the default
4548 The suffix for C++ source files.
4549 This is used by the internal CXXFile builder
4550 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4551 The default suffix is
4553 SCons also treats files with the suffixes
4560 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4567 The command line used to compile a C++ source file to an object file.
4568 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4569 are included on this command line.
4572 General options that are passed to the C++ compiler.
4575 The version number of the C++ compiler.
4576 This may or may not be set,
4577 depending on the specific C++ compiler being used.
4580 A function that converts a file name into a Dir instance relative to the
4584 The list of suffixes of files that will be scanned
4585 for imported D package files.
4586 The default list is:
4593 The TeX DVI file to PDF file converter.
4596 General options passed to the TeX DVI file to PDF file converter.
4599 The command line used to convert TeX DVI files into a PDF file.
4602 The TeX DVI file to PostScript converter.
4605 General options passed to the TeX DVI file to PostScript converter.
4608 A dictionary of environment variables
4609 to use when invoking commands. When ENV is used in a command all list
4610 values will be joined using the path separator and any other non-string
4611 values will simply be coerced to a string.
4612 Note that, by default,
4616 propagate the environment in force when you
4619 to the commands used to build target files.
4620 This is so that builds will be guaranteed
4621 repeatable regardless of the environment
4622 variables set at the time
4626 If you want to propagate your
4627 environment variables
4628 to the commands executed
4629 to build target files,
4630 you must do so explicitly:
4634 env = Environment(ENV = os.environ)
4638 Note that you can choose only to propagate
4639 certain environment variables.
4643 environment variable,
4646 uses the same utilities
4647 as the invoking shell (or other process):
4652 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4656 A function that will be called to escape shell special characters in
4657 command lines. The function should take one argument: the command line
4658 string to escape; and should return the escaped command line.
4661 The Fortran 77 compiler.
4662 You should normally set the $FORTRAN variable,
4663 which specifies the default Fortran compiler
4664 for all Fortran versions.
4665 You only need to set $F77 if you need to use a specific compiler
4666 or compiler version for Fortran 77 files.
4669 The command line used to compile a Fortran 77 source file to an object file.
4670 You only need to set $F77COM if you need to use a specific
4671 command line for Fortran 77 files.
4672 You should normally set the $FORTRANCOM variable,
4673 which specifies the default command line
4674 for all Fortran versions.
4677 General user-specified options that are passed to the Fortran 77 compiler.
4678 Note that this variable does
4682 (or similar) include search path options
4683 that scons generates automatically from $F77PATH.
4687 for the variable that expands to those options.
4688 You only need to set $F77FLAGS if you need to define specific
4689 user options for Fortran 77 files.
4690 You should normally set the $FORTRANFLAGS variable,
4691 which specifies the user-specified options
4692 passed to the default Fortran compiler
4693 for all Fortran versions.
4696 An automatically-generated construction variable
4697 containing the Fortran 77 compiler command-line options
4698 for specifying directories to be searched for include files.
4699 The value of $_F77INCFLAGS is created
4700 by appending $INCPREFIX and $INCSUFFIX
4701 to the beginning and end
4702 of each directory in $F77PATH.
4705 The list of directories that the Fortran 77 compiler will search for include
4706 directories. The implicit dependency scanner will search these
4707 directories for include files. Don't explicitly put include directory
4708 arguments in $F77FLAGS because the result will be non-portable
4709 and the directories will not be searched by the dependency scanner. Note:
4710 directory names in $F77PATH will be looked-up relative to the SConscript
4711 directory when they are used in a command. To force
4713 to look-up a directory relative to the root of the source tree use #:
4714 You only need to set $F77PATH if you need to define a specific
4715 include path for Fortran 77 files.
4716 You should normally set the $FORTRANPATH variable,
4717 which specifies the include path
4718 for the default Fortran compiler
4719 for all Fortran versions.
4722 env = Environment(F77PATH='#/include')
4726 The directory look-up can also be forced using the
4731 include = Dir('include')
4732 env = Environment(F77PATH=include)
4736 The directory list will be added to command lines
4737 through the automatically-generated
4739 construction variable,
4740 which is constructed by
4741 appending the values of the
4742 $INCPREFIX and $INCSUFFIX
4743 construction variables
4744 to the beginning and end
4745 of each directory in $F77PATH.
4746 Any command lines you define that need
4747 the F77PATH directory list should
4748 include $_F77INCFLAGS:
4751 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4755 The command line used to compile a Fortran 77 source file to an object file
4756 after first running the file through the C preprocessor.
4757 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4758 are included on this command line.
4759 You only need to set $F77PPCOM if you need to use a specific
4760 C-preprocessor command line for Fortran 77 files.
4761 You should normally set the $FORTRANPPCOM variable,
4762 which specifies the default C-preprocessor command line
4763 for all Fortran versions.
4766 The Fortran 90 compiler.
4767 You should normally set the $FORTRAN variable,
4768 which specifies the default Fortran compiler
4769 for all Fortran versions.
4770 You only need to set $F90 if you need to use a specific compiler
4771 or compiler version for Fortran 90 files.
4774 The command line used to compile a Fortran 90 source file to an object file.
4775 You only need to set $F90COM if you need to use a specific
4776 command line for Fortran 90 files.
4777 You should normally set the $FORTRANCOM variable,
4778 which specifies the default command line
4779 for all Fortran versions.
4782 General user-specified options that are passed to the Fortran 90 compiler.
4783 Note that this variable does
4787 (or similar) include search path options
4788 that scons generates automatically from $F90PATH.
4792 for the variable that expands to those options.
4793 You only need to set $F90FLAGS if you need to define specific
4794 user options for Fortran 90 files.
4795 You should normally set the $FORTRANFLAGS variable,
4796 which specifies the user-specified options
4797 passed to the default Fortran compiler
4798 for all Fortran versions.
4801 An automatically-generated construction variable
4802 containing the Fortran 90 compiler command-line options
4803 for specifying directories to be searched for include files.
4804 The value of $_F90INCFLAGS is created
4805 by appending $INCPREFIX and $INCSUFFIX
4806 to the beginning and end
4807 of each directory in $F90PATH.
4810 The list of directories that the Fortran 90 compiler will search for include
4811 directories. The implicit dependency scanner will search these
4812 directories for include files. Don't explicitly put include directory
4813 arguments in $F90FLAGS because the result will be non-portable
4814 and the directories will not be searched by the dependency scanner. Note:
4815 directory names in $F90PATH will be looked-up relative to the SConscript
4816 directory when they are used in a command. To force
4818 to look-up a directory relative to the root of the source tree use #:
4819 You only need to set $F90PATH if you need to define a specific
4820 include path for Fortran 90 files.
4821 You should normally set the $FORTRANPATH variable,
4822 which specifies the include path
4823 for the default Fortran compiler
4824 for all Fortran versions.
4827 env = Environment(F90PATH='#/include')
4831 The directory look-up can also be forced using the
4836 include = Dir('include')
4837 env = Environment(F90PATH=include)
4841 The directory list will be added to command lines
4842 through the automatically-generated
4844 construction variable,
4845 which is constructed by
4846 appending the values of the
4847 $INCPREFIX and $INCSUFFIX
4848 construction variables
4849 to the beginning and end
4850 of each directory in $F90PATH.
4851 Any command lines you define that need
4852 the F90PATH directory list should
4853 include $_F90INCFLAGS:
4856 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
4860 The command line used to compile a Fortran 90 source file to an object file
4861 after first running the file through the C preprocessor.
4862 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
4863 are included on this command line.
4864 You only need to set $F90PPCOM if you need to use a specific
4865 C-preprocessor command line for Fortran 90 files.
4866 You should normally set the $FORTRANPPCOM variable,
4867 which specifies the default C-preprocessor command line
4868 for all Fortran versions.
4871 The Fortran 95 compiler.
4872 You should normally set the $FORTRAN variable,
4873 which specifies the default Fortran compiler
4874 for all Fortran versions.
4875 You only need to set $F95 if you need to use a specific compiler
4876 or compiler version for Fortran 95 files.
4879 The command line used to compile a Fortran 95 source file to an object file.
4880 You only need to set $F95COM if you need to use a specific
4881 command line for Fortran 95 files.
4882 You should normally set the $FORTRANCOM variable,
4883 which specifies the default command line
4884 for all Fortran versions.
4887 General user-specified options that are passed to the Fortran 95 compiler.
4888 Note that this variable does
4892 (or similar) include search path options
4893 that scons generates automatically from $F95PATH.
4897 for the variable that expands to those options.
4898 You only need to set $F95FLAGS if you need to define specific
4899 user options for Fortran 95 files.
4900 You should normally set the $FORTRANFLAGS variable,
4901 which specifies the user-specified options
4902 passed to the default Fortran compiler
4903 for all Fortran versions.
4906 An automatically-generated construction variable
4907 containing the Fortran 95 compiler command-line options
4908 for specifying directories to be searched for include files.
4909 The value of $_F95INCFLAGS is created
4910 by appending $INCPREFIX and $INCSUFFIX
4911 to the beginning and end
4912 of each directory in $F95PATH.
4915 The list of directories that the Fortran 95 compiler will search for include
4916 directories. The implicit dependency scanner will search these
4917 directories for include files. Don't explicitly put include directory
4918 arguments in $F95FLAGS because the result will be non-portable
4919 and the directories will not be searched by the dependency scanner. Note:
4920 directory names in $F95PATH will be looked-up relative to the SConscript
4921 directory when they are used in a command. To force
4923 to look-up a directory relative to the root of the source tree use #:
4924 You only need to set $F95PATH if you need to define a specific
4925 include path for Fortran 95 files.
4926 You should normally set the $FORTRANPATH variable,
4927 which specifies the include path
4928 for the default Fortran compiler
4929 for all Fortran versions.
4932 env = Environment(F95PATH='#/include')
4936 The directory look-up can also be forced using the
4941 include = Dir('include')
4942 env = Environment(F95PATH=include)
4946 The directory list will be added to command lines
4947 through the automatically-generated
4949 construction variable,
4950 which is constructed by
4951 appending the values of the
4952 $INCPREFIX and $INCSUFFIX
4953 construction variables
4954 to the beginning and end
4955 of each directory in $F95PATH.
4956 Any command lines you define that need
4957 the F95PATH directory list should
4958 include $_F95INCFLAGS:
4961 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
4965 The command line used to compile a Fortran 95 source file to an object file
4966 after first running the file through the C preprocessor.
4967 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
4968 are included on this command line.
4969 You only need to set $F95PPCOM if you need to use a specific
4970 C-preprocessor command line for Fortran 95 files.
4971 You should normally set the $FORTRANPPCOM variable,
4972 which specifies the default C-preprocessor command line
4973 for all Fortran versions.
4976 The default Fortran compiler
4977 for all versions of Fortran.
4980 The command line used to compile a Fortran source file to an object file.
4981 By default, any options specified
4982 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
4983 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
4984 are included on this command line.
4987 General user-specified options that are passed to the Fortran compiler.
4988 Note that this variable does
4992 (or similar) include or module search path options
4993 that scons generates automatically from $FORTRANPATH.
4995 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
4997 for the variables that expand those options.
4999 .IP _FORTRANINCFLAGS
5000 An automatically-generated construction variable
5001 containing the Fortran compiler command-line options
5002 for specifying directories to be searched for include
5003 files and module files.
5004 The value of $_FORTRANINCFLAGS is created
5005 by prepending/appending $INCPREFIX and $INCSUFFIX
5006 to the beginning and end
5007 of each directory in $FORTRANPATH.
5010 Directory location where the Fortran compiler should place
5011 any module files it generates. This variable is empty, by default. Some
5012 Fortran compilers will internally append this directory in the search path
5013 for module files, as well
5015 .IP FORTRANMODDIRPREFIX
5016 The prefix used to specify a module directory on the Fortran compiler command
5018 This will be appended to the beginning of the directory
5019 in the $FORTRANMODDIR construction variables
5020 when the $_FORTRANMODFLAG variables is automatically generated.
5022 .IP FORTRANMODDIRSUFFIX
5023 The suffix used to specify a module directory on the Fortran compiler command
5025 This will be appended to the beginning of the directory
5026 in the $FORTRANMODDIR construction variables
5027 when the $_FORTRANMODFLAG variables is automatically generated.
5030 An automatically-generated construction variable
5031 containing the Fortran compiler command-line option
5032 for specifying the directory location where the Fortran
5033 compiler should place any module files that happen to get
5034 generated during compilation.
5035 The value of $_FORTRANMODFLAG is created
5036 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5037 to the beginning and end of the directory in $FORTRANMODDIR.
5039 .IP FORTRANMODPREFIX
5040 The module file prefix used by the Fortran compiler. SCons assumes that
5041 the Fortran compiler follows the quasi-standard naming convention for
5043 .I <module_name>.mod.
5044 As a result, this variable is left empty, by default. For situations in
5045 which the compiler does not necessarily follow the normal convention,
5046 the user may use this variable. Its value will be appended to every
5047 module file name as scons attempts to resolve dependencies.
5049 .IP FORTRANMODSUFFIX
5050 The module file suffix used by the Fortran compiler. SCons assumes that
5051 the Fortran compiler follows the quasi-standard naming convention for
5053 .I <module_name>.mod.
5054 As a result, this variable is set to ".mod", by default. For situations
5055 in which the compiler does not necessarily follow the normal convention,
5056 the user may use this variable. Its value will be appended to every
5057 module file name as scons attempts to resolve dependencies.
5060 The list of directories that the Fortran compiler will search for
5061 include files and (for some compilers) module files. The Fortran implicit
5062 dependency scanner will search these directories for include files (but
5063 not module files since they are autogenerated and, as such, may not
5064 actually exist at the time the scan takes place). Don't explicitly put
5065 include directory arguments in FORTRANFLAGS because the result will be
5066 non-portable and the directories will not be searched by the dependency
5067 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5068 to the SConscript directory when they are used in a command. To force
5070 to look-up a directory relative to the root of the source tree use #:
5073 env = Environment(FORTRANPATH='#/include')
5077 The directory look-up can also be forced using the
5082 include = Dir('include')
5083 env = Environment(FORTRANPATH=include)
5087 The directory list will be added to command lines
5088 through the automatically-generated
5090 construction variable,
5091 which is constructed by
5092 appending the values of the
5093 $INCPREFIX and $INCSUFFIX
5094 construction variables
5095 to the beginning and end
5096 of each directory in $FORTRANPATH.
5097 Any command lines you define that need
5098 the FORTRANPATH directory list should
5099 include $_FORTRANINCFLAGS:
5102 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5106 The command line used to compile a Fortran source file to an object file
5107 after first running the file through the C preprocessor.
5108 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5109 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5110 construction variables are included on this command line.
5113 The list of suffixes of files that will be scanned
5114 for Fortran implicit dependencies
5115 (INCLUDE lines & USE statements).
5116 The default list is:
5119 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5120 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5124 A function that converts a file name into a File instance relative to the
5128 The Ghostscript program used to convert PostScript to PDF files.
5131 General options passed to the Ghostscript program
5132 when converting PostScript to PDF files.
5135 The Ghostscript command line used to convert PostScript to PDF files.
5138 The list of suffixes of files that will be scanned
5139 for IDL implicit dependencies
5140 (#include or import lines).
5141 The default list is:
5148 The prefix used to specify an include directory on the C compiler command
5150 This will be appended to the beginning of each directory
5151 in the $CPPPATH and $FORTRANPATH construction variables
5152 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5153 variables are automatically generated.
5156 The suffix used to specify an include directory on the C compiler command
5158 This will be appended to the end of each directory
5159 in the $CPPPATH and $FORTRANPATH construction variables
5160 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5161 variables are automatically generated.
5164 A function to be called to install a file into a
5165 destination file name.
5166 The default function copies the file into the destination
5167 (and sets the destination file's mode and permission bits
5168 to match the source file's).
5169 The function takes the following arguments:
5172 def install(dest, source, env):
5176 is the path name of the destination file.
5178 is the path name of the source file.
5180 is the construction environment
5181 (a dictionary of construction values)
5182 in force for this file installation.
5185 The Java archive tool.
5188 The directory to which the Java archive tool should change
5194 The command line used to call the Java archive tool.
5197 General options passed to the Java archive tool.
5198 By default this is set to
5200 to create the necessary
5205 The suffix for Java archives:
5213 The command line used to compile a directory tree containing
5214 Java source files to
5215 corresponding Java class files.
5216 Any options specified in the $JAVACFLAGS construction variable
5217 are included on this command line.
5220 General options that are passed to the Java compiler.
5223 The directory in which Java class files may be found.
5224 This is stripped from the beginning of any Java .class
5225 file names supplied to the
5230 The suffix for Java class files;
5235 The Java generator for C header and stub files.
5238 The command line used to generate C header and stub files
5240 Any options specified in the $JAVAHFLAGS construction variable
5241 are included on this command line.
5244 General options passed to the C header and stub file generator
5248 The suffix for Java files;
5253 The LaTeX structured formatter and typesetter.
5256 The command line used to call the LaTeX structured formatter and typesetter.
5259 General options passed to the LaTeX structured formatter and typesetter.
5262 The lexical analyzer generator.
5265 General options passed to the lexical analyzer generator.
5268 The command line used to call the lexical analyzer generator
5269 to generate a source file.
5272 An automatically-generated construction variable
5273 containing the linker command-line options
5274 for specifying directories to be searched for library.
5275 The value of $_LIBDIRFLAGS is created
5276 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5277 to the beginning and end
5278 of each directory in $LIBPATH.
5281 The prefix used to specify a library directory on the linker command line.
5282 This will be appended to the beginning of each directory
5283 in the $LIBPATH construction variable
5284 when the $_LIBDIRFLAGS variable is automatically generated.
5287 The suffix used to specify a library directory on the linker command line.
5288 This will be appended to the end of each directory
5289 in the $LIBPATH construction variable
5290 when the $_LIBDIRFLAGS variable is automatically generated.
5293 An automatically-generated construction variable
5294 containing the linker command-line options
5295 for specifying libraries to be linked with the resulting target.
5296 The value of $_LIBFLAGS is created
5297 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5298 to the beginning and end
5299 of each directory in $LIBS.
5302 The prefix used to specify a library to link on the linker command line.
5303 This will be appended to the beginning of each library
5304 in the $LIBS construction variable
5305 when the $_LIBFLAGS variable is automatically generated.
5308 The suffix used to specify a library to link on the linker command line.
5309 This will be appended to the end of each library
5310 in the $LIBS construction variable
5311 when the $_LIBFLAGS variable is automatically generated.
5314 The list of directories that will be searched for libraries.
5315 The implicit dependency scanner will search these
5316 directories for include files. Don't explicitly put include directory
5317 arguments in $LINKFLAGS or $SHLINKFLAGS
5318 because the result will be non-portable
5319 and the directories will not be searched by the dependency scanner. Note:
5320 directory names in LIBPATH will be looked-up relative to the SConscript
5321 directory when they are used in a command. To force
5323 to look-up a directory relative to the root of the source tree use #:
5326 env = Environment(LIBPATH='#/libs')
5330 The directory look-up can also be forced using the
5336 env = Environment(LIBPATH=libs)
5340 The directory list will be added to command lines
5341 through the automatically-generated
5343 construction variable,
5344 which is constructed by
5345 appending the values of the
5346 $LIBDIRPREFIX and $LIBDIRSUFFIX
5347 construction variables
5348 to the beginning and end
5349 of each directory in $LIBPATH.
5350 Any command lines you define that need
5351 the LIBPATH directory list should
5352 include $_LIBDIRFLAGS:
5355 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5359 The prefix used for (static) library file names.
5360 A default value is set for each platform
5361 (posix, win32, os2, etc.),
5362 but the value is overridden by individual tools
5363 (ar, mslib, sgiar, sunar, tlib, etc.)
5364 to reflect the names of the libraries they create.
5367 An array of legal prefixes for library file names.
5370 A list of one or more libraries
5371 that will be linked with
5372 any executable programs
5373 created by this environment.
5376 The library list will be added to command lines
5377 through the automatically-generated
5379 construction variable,
5380 which is constructed by
5381 appending the values of the
5382 $LIBLINKPREFIX and $LIBLINKSUFFIX
5383 construction variables
5384 to the beginning and end
5385 of each directory in $LIBS.
5386 Any command lines you define that need
5387 the LIBS library list should
5391 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5395 The suffix used for (static) library file names.
5396 A default value is set for each platform
5397 (posix, win32, os2, etc.),
5398 but the value is overridden by individual tools
5399 (ar, mslib, sgiar, sunar, tlib, etc.)
5400 to reflect the names of the libraries they create.
5403 An array of legal suffixes for library file names.
5409 General user options passed to the linker.
5410 Note that this variable should
5414 (or similar) options for linking with the libraries listed in $LIBS,
5417 (or similar) library search path options
5418 that scons generates automatically from $LIBPATH.
5422 for the variable that expands to library-link options,
5426 for the variable that expands to library search path options.
5429 The command line used to link object files into an executable.
5432 The M4 macro preprocessor.
5435 General options passed to the M4 macro preprocessor.
5438 The command line used to pass files through the macro preprocessor.
5441 The maximum number of characters allowed on an external command line.
5443 link lines longer than this many characters
5444 are linke via a temporary file name.
5447 When the Microsoft Visual Studio tools are initialized, they set up
5448 this dictionary with the following keys:
5451 the version of MSVS being used (can be set via
5455 the available versions of MSVS installed
5458 installed directory of Visual C++
5461 installed directory of Visual Studio
5464 installed directory of the .NET framework
5466 .B FRAMEWORKVERSIONS:
5467 list of installed versions of the .NET framework, sorted latest to oldest.
5469 .B FRAMEWORKVERSION:
5470 latest installed version of the .NET framework
5473 installed location of the .NET SDK.
5476 installed location of the Platform SDK.
5478 .B PLATFORMSDK_MODULES:
5479 dictionary of installed Platform SDK modules,
5480 where the dictionary keys are keywords for the various modules, and
5481 the values are 2-tuples where the first is the release date, and the
5482 second is the version number.
5484 If a value isn't set, it wasn't available in the registry.
5486 .IP MSVS_IGNORE_IDE_PATHS
5487 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5488 instead of the settings from the IDE.
5490 For Visual Studio, SCons will (by default) automatically determine
5491 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5492 set by the IDE. You can override this behavior by setting these
5493 variables after Environment initialization, or by setting
5494 .B MSVS_IGNORE_IDE_PATHS = 1
5495 in the Environment initialization.
5496 Specifying this will not leave these unset, but will set them to a
5497 minimal set of paths needed to run the tools successfully.
5500 For VS6, the mininimal set is:
5501 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5502 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5503 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5505 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5506 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5507 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5511 Where '<VSDir>' is the installed location of Visual Studio.
5513 .IP MSVS_USE_MFC_DIRS
5514 Tells the MS Visual Studio tool(s) to use
5515 the MFC directories in its default paths
5516 for compiling and linking.
5517 Under MSVS version 6,
5519 .B MSVS_USE_MFC_DIRS
5528 external environment variable,
5534 external environment variable.
5535 Under MSVS version 7,
5537 .B MSVS_USE_MFC_DIRS
5540 .B "atlmfc\\\\include"
5541 directory to the default
5543 external environment variable,
5546 directory to the default
5548 external environment variable.
5549 The current default value is
5551 which means these directories
5552 are added to the paths by default.
5553 This default value is likely to change
5554 in a future release,
5555 so users who want the ATL and MFC
5556 values included in their paths
5557 are encouraged to enable the
5558 .B MSVS_USE_MFC_DIRS
5560 to avoid future incompatibility.
5561 This variable has no effect if the
5565 environment variables are set explictly.
5568 Sets the preferred version of MSVS to use.
5570 SCons will (by default) select the latest version of MSVS
5571 installed on your machine. So, if you have version 6 and version 7
5572 (MSVS .NET) installed, it will prefer version 7. You can override this by
5575 variable in the Environment initialization, setting it to the
5576 appropriate version ('6.0' or '7.0', for example).
5577 If the given version isn't installed, tool initialization will fail.
5580 The action used to generate Microsoft Visual Studio
5581 project and solution files.
5583 .IP MSVSPROJECTSUFFIX
5584 The suffix used for Microsoft Visual Studio project (DSP) files.
5585 The default value is
5587 when using Visual Studio version 7.x (.NET),
5590 when using earlier versions of Visual Studio.
5592 .IP MSVSSOLUTIONSUFFIX
5593 The suffix used for Microsoft Visual Studio solution (DSW) files.
5594 The default value is
5596 when using Visual Studio version 7.x (.NET),
5599 when using earlier versions of Visual Studio.
5602 When set to non-zero,
5603 suppresses creation of a corresponding Win32 static import lib by the
5605 builder when used with
5606 MinGW or Microsoft Visual Studio.
5607 This also suppresses creation
5608 of an export (.exp) file
5609 when using Microsoft Visual Studio.
5612 The prefix used for (static) object file names.
5615 The suffix used for (static) object file names.
5618 The Perforce executable.
5621 The command line used to
5622 fetch source files from Perforce.
5625 General options that are passed to Perforce.
5628 The Microsoft Visual C++ precompiled header that will be used when compiling
5629 object files. This variable is ignored by tools other than Microsoft Visual C++.
5630 When this variable is
5631 defined SCons will add options to the compiler command line to
5632 cause it to use the precompiled header, and will also set up the
5633 dependencies for the PCH file. Example:
5636 env['PCH'] = 'StdAfx.pch'
5640 This variable specifies how much of a source file is precompiled. This
5641 variable is ignored by tools other than Microsoft Visual C++, or when
5642 the PCH variable is not being used. When this variable is define it
5643 must be a string that is the name of the header that
5644 is included at the end of the precompiled portion of the source files, or
5645 the empty string if the "#pragma hrdstop" construct is being used:
5648 env['PCHSTOP'] = 'StdAfx.h'
5652 The Microsoft Visual C++ PDB file that will store debugging information for
5653 object files, shared libraries, and programs. This variable is ignored by
5654 tools other than Microsoft Visual C++.
5655 When this variable is
5656 defined SCons will add options to the compiler and linker command line to
5657 cause them to generate external debugging information, and will also set up the
5658 dependencies for the PDB file. Example:
5661 env['PDB'] = 'hello.pdb'
5665 A deprecated synonym for $DVIPDFCOM.
5668 The prefix used for PDF file names.
5671 The suffix used for PDF file names.
5674 The name of the platform used to create the Environment. If no platform is
5675 specified when the Environment is created,
5677 autodetects the platform.
5680 env = Environment(tools = [])
5681 if env['PLATFORM'] == 'cygwin':
5688 The prefix used for executable file names.
5691 The suffix used for executable file names.
5694 The command line used to convert TeX DVI files into a PostScript file.
5697 The prefix used for PostScript file names.
5700 The prefix used for PostScript file names.
5703 The qt tool tries to take this from os.environ.
5704 It also initializes all QT_*
5705 construction variables listed below.
5706 (Note that all paths are constructed
5707 with python's os.path.join() method,
5708 but are listed here with the '/' separator
5709 for easier reading.)
5710 In addition, the construction environment
5711 variables CPPPATH, LIBPATH and LIBS may be modified
5713 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5714 are modified. Because the build-performance is affected when using this tool,
5715 you have to explicitly specify it at Environment creation:
5718 Environment(tools=['default','qt'])
5721 The qt tool supports the following operations:
5723 .B Automatic moc file generation from header files.
5724 You do not have to specify moc files explicitly, the tool does it for you.
5725 However, there are a few preconditions to do so: Your header file must have
5726 the same filebase as your implementation file and must stay in the same
5727 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
5728 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
5729 See also the corresponding builder method
5732 .B Automatic moc file generation from cxx files.
5733 As stated in the qt documentation, include the moc file at the end of
5734 the cxx file. Note that you have to include the file, which is generated
5735 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
5736 <basename>.moc. A warning is generated after building the moc file, if you
5737 do not include the correct file. If you are using BuildDir, you may
5738 need to specify duplicate=1. You can turn off automatic moc file generation
5739 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
5742 .B Automatic handling of .ui files.
5743 The implementation files generated from .ui files are handled much the same
5744 as yacc or lex files. Each .ui file given as a source of Program, Library or
5745 SharedLibrary will generate three files, the declaration file, the
5746 implementation file and a moc file. Because there are also generated headers,
5747 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
5751 Turn off scanning for mocable files. Use the Moc Builder to explicitely
5752 specify files to run moc on.
5755 The path where the qt binaries are installed.
5756 The default value is '$QTDIR/bin'.
5759 The path where the qt header files are installed.
5760 The default value is '$QTDIR/include'.
5761 Note: If you set this variable to None, the tool won't change the CPPPATH
5762 construction variable.
5765 Prints lots of debugging information while scanning for moc files.
5768 The path where the qt libraries are installed.
5769 The default value is '$QTDIR/lib'.
5770 Note: If you set this variable to None, the tool won't change the LIBPATH
5771 construction variable.
5774 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
5775 this variable to None, the tool won't change the LIBS variable.
5778 Default value is '$QT_BINPATH/moc'.
5781 Default value is ''. Prefix for moc output files, when source is a cxx file.
5784 Default value is '.moc'. Suffix for moc output files, when source is a cxx
5787 .IP QT_MOCFROMCPPFLAGS
5788 Default value is '-i'. These flags are passed to moc, when moccing a
5791 .IP QT_MOCFROMCXXCOM
5792 Command to generate a moc file from a cpp file.
5795 Command to generate a moc file from a header.
5797 .IP QT_MOCFROMHFLAGS
5798 Default value is ''. These flags are passed to moc, when moccing a header
5802 Default value is 'moc_'. Prefix for moc output files, when source is a header.
5805 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
5809 Default value is '$QT_BINPATH/uic'.
5812 Command to generate header files from .ui files.
5815 Default value is ''. These flags are passed to uic, when creating a a h
5816 file from a .ui file.
5818 .IP QT_UICDECLPREFIX
5819 Default value is ''. Prefix for uic generated header files.
5821 .IP QT_UICDECLSUFFIX
5822 Default value is '.h'. Suffix for uic generated header files.
5825 Command to generate cxx files from .ui files.
5828 Default value is ''. These flags are passed to uic, when creating a cxx
5829 file from a .ui file.
5831 .IP QT_UICIMPLPREFIX
5832 Default value is 'uic_'. Prefix for uic generated implementation files.
5834 .IP QT_UICIMPLSUFFIX
5835 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
5839 Default value is '.ui'. Suffix of designer input files.
5842 The archive indexer.
5845 General options passed to the archive indexer.
5848 The resource compiler used by the RES builder.
5851 The command line used by the RES builder.
5854 The flags passed to the resource compiler by the RES builder.
5858 Note that this variable is not actually used
5859 for the command to fetch source files from RCS;
5862 construction variable, below.
5865 The RCS "checkout" executable,
5866 used to fetch source files from RCS.
5869 The command line used to
5870 fetch (checkout) source files from RCS.
5873 Options that are passed to the $RCS_CO command.
5876 A function that converts a file name into a list of Dir instances by
5877 searching the repositories.
5880 The Java RMI stub compiler.
5883 The command line used to compile stub
5884 and skeleton class files
5885 from Java classes that contain RMI implementations.
5886 Any options specified in the $RMICFLAGS construction variable
5887 are included on this command line.
5890 General options passed to the Java RMI stub compiler.
5893 The RPC protocol compiler.
5895 .IP RPCGENCLIENTFLAGS
5896 Options passed to the RPC protocol compiler
5897 when generating client side stubs.
5898 These are in addition to any flags specified in the
5900 construction variable.
5903 General options passed to the RPC protocol compiler.
5905 .IP RPCGENHEADERFLAGS
5906 Options passed to the RPC protocol compiler
5907 when generating a header file.
5908 These are in addition to any flags specified in the
5910 construction variable.
5912 .IP RPCGENSERVICEFLAGS
5913 Options passed to the RPC protocol compiler
5914 when generating server side stubs.
5915 These are in addition to any flags specified in the
5917 construction variable.
5920 Options passed to the RPC protocol compiler
5921 when generating XDR routines.
5922 These are in addition to any flags specified in the
5924 construction variable.
5927 A list of paths to search for shared libraries when running programs.
5928 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
5929 Ignored on platforms and toolchains that don't support it.
5930 Note that the paths added to RPATH
5931 are not transformed by
5933 in any way: if you want an absolute
5934 path, you must make it absolute yourself.
5937 A list of the available implicit dependency scanners.
5938 New file scanners may be added by
5939 appending to this list,
5940 although the more flexible approach
5941 is to associate scanners
5942 with a specific Builder.
5943 See the sections "Builder Objects"
5944 and "Scanner Objects,"
5945 below, for more information.
5948 The SCCS executable.
5951 The command line used to
5952 fetch source files from SCCS.
5955 General options that are passed to SCCS.
5958 Options that are passed specifically to the SCCS "get" subcommand.
5959 This can be set, for example, to
5961 to check out editable files from SCCS.
5964 The C compiler used for generating shared-library objects.
5967 The command line used to compile a C source file
5968 to a shared-library object file.
5969 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
5970 are included on this command line.
5973 Options that are passed to the C compiler
5974 to generate shared-library objects.
5977 The C++ compiler used for generating shared-library objects.
5980 The command line used to compile a C++ source file
5981 to a shared-library object file.
5982 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
5983 are included on this command line.
5986 Options that are passed to the C++ compiler
5987 to generate shared-library objects.
5990 A string naming the shell program that will be passed to the
5995 construction variable for more information.
5998 The Fortran 77 compiler used for generating shared-library objects.
5999 You should normally set the $SHFORTRANC variable,
6000 which specifies the default Fortran compiler
6001 for all Fortran versions.
6002 You only need to set $SHF77 if you need to use a specific compiler
6003 or compiler version for Fortran 77 files.
6006 The command line used to compile a Fortran 77 source file
6007 to a shared-library object file.
6008 You only need to set $SHF77COM if you need to use a specific
6009 command line for Fortran 77 files.
6010 You should normally set the $SHFORTRANCOM variable,
6011 which specifies the default command line
6012 for all Fortran versions.
6015 Options that are passed to the Fortran 77 compiler
6016 to generated shared-library objects.
6017 You only need to set $SHF77FLAGS if you need to define specific
6018 user options for Fortran 77 files.
6019 You should normally set the $SHFORTRANFLAGS variable,
6020 which specifies the user-specified options
6021 passed to the default Fortran compiler
6022 for all Fortran versions.
6025 The command line used to compile a Fortran 77 source file to a
6026 shared-library object file
6027 after first running the file through the C preprocessor.
6028 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6029 are included on this command line.
6030 You only need to set $SHF77PPCOM if you need to use a specific
6031 C-preprocessor command line for Fortran 77 files.
6032 You should normally set the $SHFORTRANPPCOM variable,
6033 which specifies the default C-preprocessor command line
6034 for all Fortran versions.
6037 The Fortran 90 compiler used for generating shared-library objects.
6038 You should normally set the $SHFORTRANC variable,
6039 which specifies the default Fortran compiler
6040 for all Fortran versions.
6041 You only need to set $SHF90 if you need to use a specific compiler
6042 or compiler version for Fortran 90 files.
6045 The command line used to compile a Fortran 90 source file
6046 to a shared-library object file.
6047 You only need to set $SHF90COM if you need to use a specific
6048 command line for Fortran 90 files.
6049 You should normally set the $SHFORTRANCOM variable,
6050 which specifies the default command line
6051 for all Fortran versions.
6054 Options that are passed to the Fortran 90 compiler
6055 to generated shared-library objects.
6056 You only need to set $SHF90FLAGS if you need to define specific
6057 user options for Fortran 90 files.
6058 You should normally set the $SHFORTRANFLAGS variable,
6059 which specifies the user-specified options
6060 passed to the default Fortran compiler
6061 for all Fortran versions.
6064 The command line used to compile a Fortran 90 source file to a
6065 shared-library object file
6066 after first running the file through the C preprocessor.
6067 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6068 are included on this command line.
6069 You only need to set $SHF90PPCOM if you need to use a specific
6070 C-preprocessor command line for Fortran 90 files.
6071 You should normally set the $SHFORTRANPPCOM variable,
6072 which specifies the default C-preprocessor command line
6073 for all Fortran versions.
6076 The Fortran 95 compiler used for generating shared-library objects.
6077 You should normally set the $SHFORTRANC variable,
6078 which specifies the default Fortran compiler
6079 for all Fortran versions.
6080 You only need to set $SHF95 if you need to use a specific compiler
6081 or compiler version for Fortran 95 files.
6084 The command line used to compile a Fortran 95 source file
6085 to a shared-library object file.
6086 You only need to set $SHF95COM if you need to use a specific
6087 command line for Fortran 95 files.
6088 You should normally set the $SHFORTRANCOM variable,
6089 which specifies the default command line
6090 for all Fortran versions.
6093 Options that are passed to the Fortran 95 compiler
6094 to generated shared-library objects.
6095 You only need to set $SHF95FLAGS if you need to define specific
6096 user options for Fortran 95 files.
6097 You should normally set the $SHFORTRANFLAGS variable,
6098 which specifies the user-specified options
6099 passed to the default Fortran compiler
6100 for all Fortran versions.
6103 The command line used to compile a Fortran 95 source file to a
6104 shared-library object file
6105 after first running the file through the C preprocessor.
6106 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6107 are included on this command line.
6108 You only need to set $SHF95PPCOM if you need to use a specific
6109 C-preprocessor command line for Fortran 95 files.
6110 You should normally set the $SHFORTRANPPCOM variable,
6111 which specifies the default C-preprocessor command line
6112 for all Fortran versions.
6115 The default Fortran compiler used for generating shared-library objects.
6118 The command line used to compile a Fortran source file
6119 to a shared-library object file.
6122 Options that are passed to the Fortran compiler
6123 to generate shared-library objects.
6126 The command line used to compile a Fortran source file to a
6127 shared-library object file
6128 after first running the file through the C preprocessor.
6129 Any options specified
6130 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6131 are included on this command line.
6134 The prefix used for shared library file names.
6137 The suffix used for shared library file names.
6140 The linker for programs that use shared libraries.
6143 General user options passed to the linker for programs using shared libraries.
6144 Note that this variable should
6148 (or similar) options for linking with the libraries listed in $LIBS,
6151 (or similar) include search path options
6152 that scons generates automatically from $LIBPATH.
6156 for the variable that expands to library-link options,
6160 for the variable that expands to library search path options.
6163 The prefix used for shared object file names.
6166 The suffix used for shared object file names.
6169 A reserved variable name
6170 that may not be set or used in a construction environment.
6171 (See "Variable Substitution," below.)
6174 A reserved variable name
6175 that may not be set or used in a construction environment.
6176 (See "Variable Substitution," below.)
6179 A command interpreter function that will be called to execute command line
6180 strings. The function must expect the following arguments:
6183 def spawn(shell, escape, cmd, args, env):
6187 is a string naming the shell program to use.
6189 is a function that can be called to escape shell special characters in
6192 is the path to the command to be executed.
6194 is the arguments to the command.
6196 is a dictionary of the environment variables
6197 in which the command should be executed.
6200 '\"The Subversion executable (usually named
6204 '\"The command line used to
6205 '\"fetch source files from a Subversion repository.
6208 '\"General options that are passed to Subversion.
6211 The scripting language wrapper and interface generator.
6214 The suffix that will be used for intermediate C
6215 source files generated by
6216 the scripting language wrapper and interface generator.
6217 The default value is
6218 .BR _wrap$CFILESUFFIX .
6219 By default, this value is used whenever the
6223 specified as part of the
6225 construction variable.
6228 The command line used to call
6229 the scripting language wrapper and interface generator.
6231 .IP SWIGCXXFILESUFFIX
6232 The suffix that will be used for intermediate C++
6233 source files generated by
6234 the scripting language wrapper and interface generator.
6235 The default value is
6236 .BR _wrap$CFILESUFFIX .
6237 By default, this value is used whenever the
6239 option is specified as part of the
6241 construction variable.
6244 General options passed to
6245 the scripting language wrapper and interface generator.
6246 This is where you should set
6250 or whatever other options you want to specify to SWIG.
6253 option in this variable,
6256 generate a C++ intermediate source file
6257 with the extension that is specified as the
6265 The command line used to call the tar archiver.
6268 General options passed to the tar archiver.
6271 A reserved variable name
6272 that may not be set or used in a construction environment.
6273 (See "Variable Substitution," below.)
6276 A reserved variable name
6277 that may not be set or used in a construction environment.
6278 (See "Variable Substitution," below.)
6281 The suffix used for tar file names.
6284 The TeX formatter and typesetter.
6287 The command line used to call the TeX formatter and typesetter.
6290 General options passed to the TeX formatter and typesetter.
6293 A list of the names of the Tool specifications
6294 that are part of this construction environment.
6296 .IP WIN32_INSERT_DEF
6297 When this is set to true,
6298 a library build of a WIN32 shared library (.dll file)
6299 will also build a corresponding .def file at the same time,
6300 if a .def file is not already listed as a build target.
6301 The default is 0 (do not build a .def file).
6304 The prefix used for WIN32 .def file names.
6307 The suffix used for WIN32 .def file names.
6310 The parser generator.
6313 The command line used to call the parser generator
6314 to generate a source file.
6317 General options passed to the parser generator.
6318 If $YACCFLAGS contains a \-d option,
6319 SCons assumes that the call will also create a .h file
6320 (if the yacc source file ends in a .y suffix)
6322 (if the yacc source file ends in a .yy suffix)
6325 The zip compression and file packaging utility.
6328 The command line used to call the zip utility,
6329 or the internal Python function used to create a
6338 module used by the internal Python function
6339 to control whether the zip archive
6340 is compressed or not.
6341 The default value is
6342 .BR zipfile.ZIP_DEFLATED ,
6343 which creates a compressed zip archive.
6344 This value has no effect when using Python 1.5.2
6347 module is otherwise unavailable.
6350 General options passed to the zip utility.
6353 Construction variables can be retrieved and set using the
6355 method of the construction environment:
6358 dict = env.Dictionary()
6362 or using the [] operator:
6368 Construction variables can also be passed to the construction environment
6372 env = Environment(CC="cc")
6375 or when copying a construction environment using the
6380 env2 = env.Copy(CC="cl.exe")
6383 .SS Configure Contexts
6387 .I configure contexts,
6388 an integrated mechanism similar to the
6389 various AC_CHECK macros in GNU autoconf
6390 for testing for the existence of C header
6391 files, libraries, etc.
6392 In contrast to autoconf,
6394 does not maintain an explicit cache of the tested values,
6395 but uses its normal dependency tracking to keep the checked values
6397 The following methods can be used to perform checks:
6400 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
6402 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
6403 This creates a configure context, which can be used to perform checks.
6405 specifies the environment for building the tests.
6406 This environment may be modified when performing checks.
6408 is a dictionary containing custom tests.
6409 See also the section about custom tests below.
6410 By default, no custom tests are added to the configure context.
6412 specifies a directory where the test cases are built.
6413 Note that this directory is not used for building
6415 The default value is the directory
6418 specifies a file which collects the output from commands
6419 that are executed to check for the existence of header files, libraries, etc.
6420 The default is the file #/config.log.
6421 If you are using the
6424 you may want to specify a subdirectory under your build directory.
6429 instance has the following associated methods:
6432 .RI Configure.Finish( self )
6433 This method should be called after configuration is done.
6434 It returns the environment as modified
6435 by the configuration checks performed.
6436 After this method is called, no further checks can be performed
6437 with this configuration context.
6438 However, you can create a new
6440 context to perform additional checks.
6441 Only one context should be active at a time.
6443 The following Checks are predefined.
6444 (This list will likely grow larger as time
6445 goes by and developers contribute new useful tests.)
6448 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6451 is usable in the specified language.
6454 in which case the last item in the list
6455 is the header file to be checked,
6456 and the previous list items are
6459 lines should precede the
6460 header line being checked for.
6461 The optional argument
6464 a two character string, where the first character denotes the opening
6465 quote and the second character denotes the closing quote.
6466 By default, both characters are " (double quote).
6467 The optional argument
6473 and selects the compiler to be used for the check.
6474 Returns 1 on success and 0 on failure.
6477 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6478 This is a wrapper around
6479 .B Configure.CheckHeader
6482 is usable in the C language.
6485 in which case the last item in the list
6486 is the header file to be checked,
6487 and the previous list items are
6490 lines should precede the
6491 header line being checked for.
6492 The optional argument
6495 a two character string, where the first character denotes the opening
6496 quote and the second character denotes the closing quote (both default
6498 Returns 1 on success and 0 on failure.
6501 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6502 This is a wrapper around
6503 .B Configure.CheckHeader
6506 is usable in the C++ language.
6509 in which case the last item in the list
6510 is the header file to be checked,
6511 and the previous list items are
6514 lines should precede the
6515 header line being checked for.
6516 The optional argument
6519 a two character string, where the first character denotes the opening
6520 quote and the second character denotes the closing quote (both default
6522 Returns 1 on success and 0 on failure.
6525 .RI Configure.CheckFunc( self ", " function_name ", [" language ])
6526 Checks if the specified
6527 C or C++ function is available.
6529 is the name of the function to check for.
6536 and selects the compiler to be used for the check;
6540 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
6547 is 1 and the library provides the specified
6549 appends the library to the LIBS construction environment variable.
6551 may also be None (the default),
6554 is checked with the current LIBS variable,
6555 or a list of library names,
6556 in which case each library in the list
6563 you can link against the specified
6571 and selects the compiler to be used for the check;
6573 The default value for
6576 It is assumed, that the C-language is used.
6577 This method returns 1 on success and 0 on error.
6580 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
6583 .RI Configure.CheckLib
6584 call, this call provides a more sophisticated way to check against libraries.
6587 specifies the library or a list of libraries to check.
6589 specifies a header to check for.
6592 in which case the last item in the list
6593 is the header file to be checked,
6594 and the previous list items are
6597 lines should precede the
6598 header line being checked for.
6600 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6602 can be any valid expression (with a trailing ';'). The default is 'main();'.
6604 specifies whether to add the library to the environment (only if the check
6605 succeeds). This method returns 1 on success and 0 on error.
6608 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
6609 Checks for the existence of a type defined by
6612 specifies the typedef name to check for.
6614 is a string containing one or more
6616 lines that will be inserted into the program
6617 that will be run to test for the existence of the type.
6624 and selects the compiler to be used for the check;
6628 Example of a typical Configure usage:
6632 conf = Configure( env )
6633 if not conf.CheckCHeader( 'math.h' ):
6634 print 'We really need math.h!'
6636 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6637 # do stuff for qt - usage, e.g.
6638 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6643 You can define your own custom checks.
6644 in addition to the predefined checks.
6645 These are passed in a dictionary to the Configure function.
6646 This dictionary maps the names of the checks
6647 to user defined Python callables
6648 (either Python functions or class instances implementing the
6651 The first argument of the call is always a
6653 instance followed by the arguments,
6654 which must be supplied by the user of the check.
6655 These CheckContext instances define the following methods:
6658 .RI CheckContext.Message( self ", " text )
6660 Usually called before the check is started.
6662 will be displayed to the user, e.g. 'Checking for library X...'
6665 .RI CheckContext.Result( self, ", " res )
6667 Usually called after the check is done.
6669 can be either an integer or a string. In the former case, 'ok' (res != 0)
6670 or 'failed' (res == 0) is displayed to the user, in the latter case the
6671 given string is displayed.
6674 .RI CheckContext.TryCompile( self ", " text ", " extension )
6675 Checks if a file with the specified
6677 (e.g. '.c') containing
6679 can be compiled using the environment's
6681 builder. Returns 1 on success and 0 on failure.
6684 .RI CheckContext.TryLink( self ", " text ", " extension )
6685 Checks, if a file with the specified
6687 (e.g. '.c') containing
6689 can be compiled using the environment's
6691 builder. Returns 1 on success and 0 on failure.
6694 .RI CheckContext.TryRun( self ", " text ", " extension )
6695 Checks, if a file with the specified
6697 (e.g. '.c') containing
6699 can be compiled using the environment's
6701 builder. On success, the program is run. If the program
6702 executes successfully
6703 (that is, its return status is 0),
6708 is the standard output of the
6710 If the program fails execution
6711 (its return status is non-zero),
6712 then (0, '') is returned.
6715 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
6716 Checks if the specified
6718 with an optional source file (contents
6725 may be anything which can be converted to a
6732 is the content of the target file.
6738 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
6739 Low level implementation for testing specific builds;
6740 the methods above are based on this method.
6741 Given the Builder instance
6745 of a source file with optional
6747 this method returns 1 on success and 0 on failure. In addition,
6749 is set to the build target node, if the build was successful.
6752 Example for implementing and using custom tests:
6755 def CheckQt(context, qtdir):
6756 context.Message( 'Checking for qt ...' )
6757 lastLIBS = context.env['LIBS']
6758 lastLIBPATH = context.env['LIBPATH']
6759 lastCPPPATH= context.env['CPPPATH']
6760 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
6761 ret = context.TryLink("""
6763 int main(int argc, char **argv) {
6764 QApplication qapp(argc, argv);
6769 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
6770 context.Result( ret )
6774 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
6775 if not conf.CheckQt('/usr/lib/qt'):
6776 print 'We really need qt!'
6781 .SS Construction Variable Options
6783 Often when building software, various options need to be specified at build
6784 time that are not known when the SConstruct/SConscript files are
6785 written. For example, libraries needed for the build may be in non-standard
6786 locations, or site-specific compiler options may need to be passed to the
6789 provides a mechanism for overridding construction variables from the
6790 command line or a text-based SConscript file through an Options
6791 object. To create an Options object, call the Options() function:
6794 .RI Options([ files "], [" args ])
6795 This creates an Options object that will read construction variables from
6796 the file or list of filenames specified in
6798 If no files are specified,
6803 then no files will be read.
6804 The optional argument
6807 values that will override anything read from the specified files;
6808 it is primarily intended to be passed the
6810 dictionary that holds variables
6811 specified on the command line.
6815 opts = Options('custom.py')
6816 opts = Options('overrides.py', ARGUMENTS)
6817 opts = Options(None, {FOO:'expansion', BAR:7})
6820 Options objects have the following methods:
6823 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
6824 This adds a customizable construction variable to the Options object.
6826 is the name of the variable.
6828 is the help text for the variable.
6830 is the default value of the variable.
6832 is called to validate the value of the variable, and should take three
6833 arguments: key, value, and environment
6835 is called to convert the value before putting it in the environment, and
6836 should take a single argument: value. Example:
6839 opts.Add('CC', 'The C compiler')
6843 .RI AddOptions( list )
6844 A wrapper script that adds
6845 multiple customizable construction variables
6846 to an Options object.
6848 is a list of tuple or list objects
6849 that contain the arguments
6850 for an individual call to the
6857 ('CC', 'The C compiler'),
6858 ('VALIDATE', 'An option for testing validation',
6859 'notset', validator, None),
6864 .RI Update( env ", [" args ])
6865 This updates a construction environment
6867 with the customized construction variables. Normally this method is not
6868 called directly, but is called indirectly by passing the Options object to
6869 the Environment() function:
6872 env = Environment(options=opts)
6876 .RI Save( filename ", " env )
6877 This saves the currently set options into a script file named
6879 that can be used on the next invocation to automatically load the current
6880 settings. This method combined with the Options method can be used to
6881 support caching of options between runs.
6885 opts = Options(['options.cache', 'custom.py'])
6888 opts.Save('options.cache', env)
6892 .RI GenerateHelpText( env ", [" sort ])
6893 This generates help text documenting the customizable construction
6894 variables suitable to passing in to the Help() function.
6896 is the construction environment that will be used to get the actual values
6897 of customizable variables. Calling with
6901 will cause the output to be sorted
6902 by the specified argument.
6906 should take two arguments
6909 (like the standard Python
6914 Help(opts.GenerateHelpText(env))
6915 Help(opts.GenerateHelpText(env, sort=cmp))
6918 The text based SConscript file is executed as a Python script, and the
6919 global variables are queried for customizable construction
6926 To make it more convenient to work with customizable Options,
6928 provides a number of functions
6929 that make it easy to set up
6930 various types of Options:
6933 .RI BoolOption( key ", " help ", " default )
6934 Return a tuple of arguments
6935 to set up a Boolean option.
6939 have a default value of
6941 and display the specified
6944 The option will interpret the values
6966 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
6967 Return a tuple of arguments
6969 whose value may be one
6970 of a specified list of legal enumerated values.
6974 have a default value of
6976 and display the specified
6979 The option will only support those
6985 argument is a dictionary
6986 that can be used to convert
6987 input values into specific legal values
6996 then the values are case-sensitive.
7001 then values will be matched
7007 then values will be matched
7009 and all input values will be
7010 converted to lower case.
7013 .RI ListOption( key ", " help ", " default ", " names )
7014 Return a tuple of arguments
7016 whose value may be one or more
7017 of a specified list of legal enumerated values.
7021 have a default value of
7023 and display the specified
7026 The option will only support the values
7029 or the values in the
7032 More than one value may be specified,
7033 with all values separated by commas.
7036 .RI PackageOption( key ", " help ", " default )
7037 Return a tuple of arguments
7039 whose value is a path name
7040 of a package that may be
7041 enabled, disabled or
7042 given an explicit path name.
7046 have a default value of
7048 and display the specified
7051 The option will support the values
7058 in which case the specified
7061 or the option may be set to an
7063 (typically the path name to a package
7064 that is being enabled).
7065 The option will also support the values
7071 to disable use of the specified option.
7074 .RI PathOption( key ", " help ", " default )
7075 Return a tuple of arguments
7077 whose value is expected to be a path name.
7081 have a default value of
7083 and display the specified
7088 These functions make it
7089 convenient to create a number
7090 of options with consistent behavior
7091 in a single call to the
7097 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7098 EnumOption('debug', 'debug output and symbols', 'no'
7099 allowed_values=('yes', 'no', 'full'),
7100 map={}, ignorecase=0), # case sensitive
7101 ListOption('shared',
7102 'libraries to build as shared libraries',
7104 names = list_of_libs),
7105 PackageOption('x11',
7106 'use X11 installed here (yes = search some places)',
7108 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7112 .SS File and Directory Nodes
7122 Nodes, respectively.
7123 python objects, respectively.
7124 Those objects have several user-visible attributes
7125 and methods that are often useful:
7131 This path is relative to the top-level directory
7135 The build path is the same as the source path if
7140 The absolute build path of the given file or directory.
7150 object representing the
7159 # Get the current build dir's path, relative to top.
7161 # Current dir's absolute path
7163 # Next line is always '.', because it is the top dir's path relative to itself.
7165 File('foo.c').srcnode().path # source path of the given source file.
7167 # Builders also return File objects:
7168 foo = env.Program('foo.c')
7169 print "foo will be built in %s"%foo.path
7175 can be extended to build different types of targets
7176 by adding new Builder objects
7177 to a construction environment.
7179 you should only need to add a new Builder object
7180 when you want to build a new type of file or other external target.
7181 If you just want to invoke a different compiler or other tool
7182 to build a Program, Object, Library, or any other
7183 type of output file for which
7185 already has an existing Builder,
7186 it is generally much easier to
7187 use those existing Builders
7188 in a construction environment
7189 that sets the appropriate construction variables
7192 Builder objects are created
7198 function accepts the following arguments:
7201 The command line string used to build the target from the source.
7204 a list of strings representing the command
7205 to be executed and its arguments
7206 (suitable for enclosing white space in an argument),
7208 mapping source file name suffixes to
7209 any combination of command line strings
7210 (if the builder should accept multiple source file extensions),
7213 (see the next section);
7214 or a list of any of the above.
7217 takes three arguments:
7219 - a list of source nodes,
7221 - a list of target nodes,
7223 - the construction environment.
7226 The prefix that will be prepended to the target file name.
7227 This may be a simple string, or a callable object that takes
7228 two arguments, a construction environment and a list of sources,
7229 and returns a prefix.
7232 b = Builder("build_it < $SOURCE > $TARGET"
7235 def gen_prefix(env, sources):
7236 return "file-" + env['PLATFORM'] + '-'
7237 b = Builder("build_it < $SOURCE > $TARGET"
7238 prefix = gen_prefix)
7242 The suffix that will be appended to the target file name.
7243 This may be a simple string, or a callable object that takes
7244 two arguments, a construction environment and a list of sources,
7245 and returns a suffix.
7246 If the suffix is a string, then
7248 will append a '.' to the beginning of the
7249 suffix if it's not already there.
7250 The string returned by callable object
7251 is untouched and must append its own '.'
7252 to the beginning if one is desired.
7255 b = Builder("build_it < $SOURCE > $TARGET"
7258 def gen_suffix(env, sources):
7259 return "." + env['PLATFORM'] + "-file"
7260 b = Builder("build_it < $SOURCE > $TARGET"
7261 suffix = gen_suffix)
7265 The expected source file name suffix.
7268 A Scanner object that
7269 will be invoked to find
7270 implicit dependencies for this target file.
7271 This keyword argument should be used
7272 for Scanner objects that find
7273 implicit dependencies
7274 based only on the target file
7275 and the construction environment,
7278 (See the section "Scanner Objects," below,
7279 for information about creating Scanner objects.)
7282 A Scanner object that
7284 find implicit dependences in
7286 used to build this target file.
7287 This is where you would
7288 specify a scanner to
7291 lines in source files.
7292 (See the section "Scanner Objects," below,
7293 for information about creating Scanner objects.)
7296 A factory function that the Builder will use
7297 to turn any targets specified as strings into SCons Nodes.
7299 SCons assumes that all targets are files.
7300 Other useful target_factory
7303 for when a Builder creates a directory target,
7306 for when a Builder can create either a file
7307 or directory target.
7312 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7314 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7315 env.MakeDirectory('new_directory')
7319 A factory function that the Builder will use
7320 to turn any sources specified as strings into SCons Nodes.
7322 SCons assumes that all source are files.
7323 Other useful source_factory
7326 for when a Builder uses a directory as a source,
7329 for when a Builder can use files
7330 or directories (or both) as sources.
7335 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7337 env.Append(BUILDERS = {'Collect':CollectBuilder})
7338 env.Collect('archive', ['directory_name', 'file_name'])
7342 A function or list of functions to manipulate the target and source
7343 lists before dependencies are established
7344 and the target(s) are actually built.
7346 can also be a string containing a construction variable to expand
7347 to an emitter function or list of functions,
7348 or a dictionary mapping source file suffixes
7349 to emitter functions.
7350 (Only the suffix of the first source file
7351 is used to select the actual emitter function
7352 from an emitter dictionary.)
7355 takes three arguments:
7357 - a list of source nodes,
7359 - a list of target nodes,
7361 - the construction environment.
7362 An emitter must return a tuple containing two lists,
7363 the list of targets to be built by this builder,
7364 and the list of sources for this builder.
7369 def e(target, source, env):
7370 return (target + ['foo.foo'], source + ['foo.src'])
7372 # Simple association of an emitter function with a Builder.
7373 b = Builder("my_build < $TARGET > $SOURCE",
7376 def e2(target, source, env):
7377 return (target + ['bar.foo'], source + ['bar.src'])
7379 # Simple association of a list of emitter functions with a Builder.
7380 b = Builder("my_build < $TARGET > $SOURCE",
7383 # Calling an emitter function through a construction variable.
7384 env = Environment(MY_EMITTER = e)
7385 b = Builder("my_build < $TARGET > $SOURCE",
7386 emitter = '$MY_EMITTER')
7388 # Calling a list of emitter functions through a construction variable.
7389 env = Environment(EMITTER_LIST = [e, e2])
7390 b = Builder("my_build < $TARGET > $SOURCE",
7391 emitter = '$EMITTER_LIST')
7393 # Associating multiple emitters with different file
7394 # suffixes using a dictionary.
7395 def e_suf1(target, source, env):
7396 return (target + ['another_target_file'], source)
7397 def e_suf2(target, source, env):
7398 return (target, source + ['another_source_file'])
7399 b = Builder("my_build < $TARGET > $SOURCE",
7400 emitter = {'.suf1' : e_suf1,
7408 arguments must not both be used for the same Builder.
7411 Specifies whether this builder is allowed to be called multiple times for
7412 the same target file(s). The default is 0, which means the builder
7413 can not be called multiple times for the same target file(s). Calling a
7414 builder multiple times for the same target simply adds additional source
7415 files to the target; it is not allowed to change the environment associated
7416 with the target, specify addition environment overrides, or associate a different
7417 builder with the target.
7420 A construction environment that can be used
7421 to fetch source code using this Builder.
7422 (Note that this environment is
7424 used for normal builds of normal target files,
7425 which use the environment that was
7426 used to call the Builder for the target file.)
7429 A function that returns a list of actions that will be executed to build
7430 the target(s) from the source(s).
7431 The returned action(s) may be
7432 an Action object, or anything that
7433 can be converted into an Action object
7434 (see the next section).
7436 The generator function
7437 takes four arguments:
7439 - a list of source nodes,
7441 - a list of target nodes,
7443 - the construction environment,
7445 - a Boolean value that specifies
7446 whether the generator is being called
7447 for generating a build signature
7448 (as opposed to actually executing the command).
7452 def g(source, target, env, for_signature):
7453 return [["gcc", "-c", "-o"] + target + source]
7455 b = Builder(generator=g)
7459 Specifies a builder to use when a source file name suffix does not match
7460 any of the suffixes of the builder. Using this argument produces a
7461 multi-stage builder.
7464 Specifies that this builder expects exactly one source file per call. Giving
7465 more than one source files without target files results in implicitely calling
7466 the builder multiple times (once for each source given). Giving multiple
7467 source files together with target files results in a UserError exception.
7475 arguments must not both be used for the same Builder.
7478 A construction environment that can be used
7479 to fetch source code using this Builder.
7480 (Note that this environment is
7482 used for normal builds of normal target files,
7483 which use the environment that was
7484 used to call the Builder for the target file.)
7487 b = Builder(action="build < $SOURCE > $TARGET")
7488 env = Environment(BUILDERS = {'MyBuild' : b})
7489 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
7493 Any additional keyword arguments supplied
7494 when a Builder object is created
7495 (that is, when the Builder() function is called)
7496 will be set in the executing construction
7497 environment when the Builder object is called.
7498 The canonical example here would be
7499 to set a construction variable to
7500 the repository of a source code system.
7502 Any additional keyword arguments supplied
7506 will only be associated with the target
7507 created by that particular Builder call
7508 (and any other files built as a
7509 result of the call).
7511 These extra keyword arguments are passed to the
7512 following functions:
7513 command generator functions,
7515 and emitter functions.
7521 function will turn its
7523 keyword argument into an appropriate
7524 internal Action object.
7525 You can also explicity create Action objects
7529 which can then be passed to the
7532 This can be used to configure
7533 an Action object more flexibly,
7534 or it may simply be more efficient
7535 than letting each separate Builder object
7536 create a separate Action
7538 Builder objects need to do the same thing.
7543 returns an appropriate object for the action
7544 represented by the type of the first argument:
7547 If the first argument is already an Action object,
7548 the object is simply returned.
7551 If the first argument is a string,
7552 a command-line Action is returned.
7555 Action('$CC -c -o $TARGET $SOURCES')
7558 .\" XXX From Gary Ruben, 23 April 2002:
7559 .\" What would be useful is a discussion of how you execute command
7560 .\" shell commands ie. what is the process used to spawn the shell, pass
7561 .\" environment variables to it etc., whether there is one shell per
7562 .\" environment or one per command etc. It might help to look at the Gnu
7563 .\" make documentation to see what they think is important to discuss about
7564 .\" a build system. I'm sure you can do a better job of organising the
7565 .\" documentation than they have :-)
7569 If the first argument is a list,
7570 then a list of Action objects is returned.
7571 An Action object is created as necessary
7572 for each element in the list.
7575 the list is itself a list,
7576 the internal list is the
7577 command and arguments to be executed via
7579 This allows white space to be enclosed
7580 in an argument by defining
7581 a command in a list within a list:
7584 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7588 If the first argument is a Python function,
7589 a function Action is returned.
7590 The Python function takes three keyword arguments,
7592 (a Node object representing the target file),
7594 (a Node object representing the source file)
7597 (the construction environment
7598 used for building the target file).
7603 arguments may be lists of Node objects if there is
7604 more than one target file or source file.
7605 The actual target and source file name(s) may
7606 be retrieved from their Node objects
7607 via the built-in Python str() function:
7610 target_file_name = str(target)
7611 source_file_names = map(lambda x: str(x), source)
7614 The function should return
7618 to indicate a successful build of the target file(s).
7619 The function may raise an exception
7620 or return a non-zero exit status
7621 to indicate an unsuccessful build.
7624 def build_it(target = None, source = None, env = None):
7625 # build the target from the source
7628 a = Action(build_it)
7631 The second, optional argument
7632 is a Python function that returns
7633 a string to be printed to describe the action being executed.
7634 Like a function to build a file,
7635 this function takes three arguments:
7637 (a Node object representing the target file),
7639 (a Node object representing the source file)
7642 (a construction environment).
7647 arguments may be lists of Node objects if there is
7648 more than one target file or source file.
7652 def build_it(target, source, env):
7653 # build the target from the source
7656 def string_it(target, source, env):
7657 return "building '%s' from '%s'" % (target[0], source[0])
7659 # Use a positional argument.
7660 a = Action(build_it, string_it)
7662 # Alternatively, use a keyword argument.
7663 a = Action(build_it, strfunction=string_it)
7666 The third, also optional argument
7667 is a list of construction variables
7668 whose values will be included
7669 in the signature of the Action
7670 when deciding whether a target should
7671 be rebuilt because the action changed.
7672 This is necessary whenever you want a target to
7673 be rebuilt when a specific
7674 construction variable changes,
7675 because the underlying Python code for a function
7676 will not change when the value of the construction variable does.
7679 def build_it(target, source, env):
7680 # build the target from the 'XXX' construction variable
7681 open(target[0], 'w').write(env['XXX'])
7684 def string_it(target, source):
7685 return "building '%s' from '%s'" % (target[0], source[0])
7687 # Use positional arguments.
7688 a = Action(build_it, string_it, ['XXX'])
7690 # Alternatively, use a keyword argument.
7691 a = Action(build_it, varlist=['XXX'])
7694 If the action argument is not one of the above,
7697 .SS Miscellaneous Action Functions
7700 supplies a number of functions
7701 that arrange for various common
7702 file and directory manipulations
7704 These are similar in concept to "tasks" in the
7706 although the implementation is slightly different.
7707 These functions do not actually
7708 perform the specified action
7709 at the time the function is called,
7710 but instead return an Action object
7711 that can be executed at the
7713 (In Object-Oriented terminology,
7718 that return Action objects.)
7721 there are two natural ways
7724 are intended to be used.
7728 to perform the action
7729 at the time the SConscript
7733 global function to do so:
7735 Execute(Touch('file'))
7739 you can use these functions
7740 to supply Actions in a list
7744 This can allow you to
7745 perform more complicated
7746 sequences of file manipulation
7748 on platform-specific
7752 env = Environment(TMPBUILD = '/tmp/builddir')
7753 env.Command('foo.out', 'foo.in',
7754 [Mkdir('$TMPBUILD'),
7755 Copy('${SOURCE.dir}', '$TMPBUILD')
7756 "cd $TMPBUILD && make",
7757 Delete('$TMPBUILD')])
7761 .RI Chmod( dest ", " mode )
7762 Returns an Action object that
7763 changes the permissions on the specified
7765 file or directory to the specified
7770 Execute(Chmod('file', 0755))
7772 env.Command('foo.out', 'foo.in',
7773 [Copy('$TARGET', '$SOURCE'),
7774 Chmod('$TARGET', 0755)])
7778 .RI Copy( dest ", " src )
7779 Returns an Action object
7782 source file or directory to the
7784 destination file or directory.
7788 Execute(Copy('foo.output', 'foo.input'))
7790 env.Command('bar.out', 'bar.in',
7791 Copy('$TARGET', '$SOURCE'))
7795 .RI Delete( entry ", [" must_exist ])
7796 Returns an Action that
7797 deletes the specified
7799 which may be a file or a directory tree.
7800 If a directory is specified,
7801 the entire directory tree
7806 then a Python error will be thrown
7807 if the specified entry does not exist;
7810 that is, the Action will silently do nothing
7811 if the entry does not exist.
7815 Execute(Delete('/tmp/buildroot'))
7817 env.Command('foo.out', 'foo.in',
7818 [Delete('${TARGET.dir}'),
7821 Execute(Delete('file_that_must_exist', must_exist=1))
7827 that creates the specified
7833 Execute(Mkdir('/tmp/outputdir'))
7835 env.Command('foo.out', 'foo.in',
7836 [Mkdir('/tmp/builddir',
7837 Copy('$SOURCE', '/tmp/builddir')
7838 "cd /tmp/builddir && ])
7843 .RI Move( dest ", " src )
7845 that moves the specified
7847 file or directory to
7854 Execute(Move('file.destination', 'file.source'))
7856 env.Command('output_file', 'input_file',
7858 Move('$TARGET', 'file_created_by_MyBuildAction')])
7864 that updates the modification time
7870 Execute(Touch('file_to_be_touched'))
7872 env.Command('marker', 'input_file',
7877 .SS Variable Substitution
7879 Before executing a command,
7881 performs construction variable interpolation on the strings that make up
7882 the command line of builders.
7883 Variables are introduced by a
7886 Besides construction variables, scons provides the following
7887 variables for each command execution:
7890 The file name of the target being built, or the file name of the first
7891 target if multiple targets are being built.
7894 The file names of all targets being built.
7897 The file name of the source of the build command, or the file name of the
7898 first source if multiple sources are being built.
7901 The file names of the sources of the build command.
7903 (Note that the above variables are reserved
7904 and may not be set in a construction environment.)
7907 For example, given the construction variable CC='cc', targets=['foo'], and
7908 sources=['foo.c', 'bar.c']:
7911 action='$CC -c -o $TARGET $SOURCES'
7914 would produce the command line:
7917 cc -c -o foo foo.c bar.c
7920 Variable names may be surrounded by curly braces ({})
7921 to separate the name from the trailing characters.
7922 Within the curly braces, a variable name may have
7923 a Python slice subscript appended to select one
7924 or more items from a list.
7925 In the previous example, the string:
7937 Additionally, a variable name may
7938 have the following special
7939 modifiers appended within the enclosing curly braces
7940 to modify the interpolated string:
7943 The base path of the file name,
7944 including the directory path
7945 but excluding any suffix.
7948 The name of the directory in which the file exists.
7952 minus any directory portion.
7955 Just the basename of the file,
7957 and minus the directory.
7960 Just the file suffix.
7963 The absolute path name of the file.
7966 The POSIX form of the path,
7967 with directories separated by
7971 This is sometimes necessary on Win32 systems
7972 when a path references a file on other (POSIX) systems.
7975 The directory and file name to the source file linked to this file
7976 through BuildDir. If this file isn't linked, it just returns the
7977 directory and filename unchanged.
7980 The directory containing the source file linked to this file
7981 through BuildDir. If this file isn't linked, it just returns the
7982 directory part of the filename.
7985 The directory and file name to the source file linked to this file
7986 through BuildDir. If the file does not exist locally but exists in
7987 a Repository, the path in the Repository is returned.
7988 If this file isn't linked, it just returns the
7989 directory and filename unchanged.
7992 The Repository directory containing the source file linked to this file
7993 through BuildDir. If this file isn't linked, it just returns the
7994 directory part of the filename.
7997 For example, the specified target will
7998 expand as follows for the corresponding modifiers:
8001 $TARGET => sub/dir/file.x
8002 ${TARGET.base} => sub/dir/file
8003 ${TARGET.dir} => sub/dir
8004 ${TARGET.file} => file.x
8005 ${TARGET.filebase} => file
8006 ${TARGET.suffix} => .x
8007 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8009 BuildDir('sub/dir','src')
8010 $SOURCE => sub/dir/file.x
8011 ${SOURCE.srcpath} => src/file.x
8012 ${SOURCE.srcdir} => src
8014 Repository('/usr/repository')
8015 $SOURCE => sub/dir/file.x
8016 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8017 ${SOURCE.rsrcdir} => /usr/repository/src
8020 Lastly, a variable name
8021 may be a callable Python function
8023 construction variable in the environment.
8025 take four arguments:
8027 - a list of target nodes,
8029 - a list of source nodes,
8031 - the construction environment,
8033 - a Boolean value that specifies
8034 whether the function is being called
8035 for generating a build signature.
8036 SCons will insert whatever
8037 the called function returns
8038 into the expanded string:
8041 def foo(target, source, env, for_signature):
8044 # Will expand $BAR to "bar baz"
8045 env=Environment(FOO=foo, BAR="$FOO baz")
8048 You can use this feature to pass arguments to a
8049 Python function by creating a callable class
8050 that stores one or more arguments in an object,
8051 and then uses them when the
8054 Note that in this case,
8055 the entire variable expansion must
8056 be enclosed by curly braces
8057 so that the arguments will
8058 be associated with the
8059 instantiation of the class:
8063 def __init__(self, arg):
8066 def __call__(self, target, source, env, for_signature):
8069 # Will expand $BAR to "my argument bar baz"
8070 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8074 The special pseudo-variables
8078 may be used to surround parts of a command line
8081 causing a rebuild--that is,
8082 which are not included in the signature
8083 of target files built with this command.
8088 will be removed from the command line
8089 before it is added to file signatures,
8094 will be removed before the command is executed.
8095 For example, the command line:
8098 echo Last build occurred $( $TODAY $). > $TARGET
8102 would execute the command:
8105 echo Last build occurred $TODAY. > $TARGET
8109 but the command signature added to any target files would be:
8112 echo Last build occurred . > $TARGET
8115 SCons uses the following rules when converting construction variables into
8119 When the value is a string it is interpreted as a space delimited list of
8120 command line arguments.
8123 When the value is a list it is interpreted as a list of command line
8124 arguments. Each element of the list is converted to a string.
8127 Anything that is not a list or string is converted to a string and
8128 interpreted as a single command line argument.
8131 Newline characters (\\n) delimit lines. The newline parsing is done after
8132 all other parsing, so it is not possible for arguments (e.g. file names) to
8133 contain embedded newline characters. This limitation will likely go away in
8134 a future version of SCons.
8142 new file types for implicit dependencies.
8143 Scanner accepts the following arguments:
8146 A Python function that will process
8148 and return a list of strings (file names)
8149 representing the implicit
8150 dependencies found in the contents.
8151 The function takes three or four arguments:
8153 def scanner_function(node, env, path):
8155 def scanner_function(node, env, path, arg):
8159 argument is the internal
8160 SCons node representing the file.
8163 to fetch the name of the file, and
8164 .B node.get_contents()
8165 to fetch contents of the file.
8169 argument is the construction environment for the scan.
8170 Fetch values from it using the
8176 argument is a tuple (or list)
8177 of directories that can be searched
8179 This will usually be the tuple returned by the
8181 argument (see below).
8185 argument is the argument supplied
8186 when the scanner was created, if any.
8189 The name of the Scanner.
8191 to identify the Scanner internally.
8194 An optional argument that, if specified,
8195 will be passed to the scanner function
8197 and the path function
8201 An optional list that can be used to
8202 determine which scanner should be used for
8204 In the usual case of scanning for file names,
8205 this argument will be a list of suffixes
8206 for the different file types that this
8207 Scanner knows how to scan.
8208 If the argument is a string,
8209 then it will be expanded
8210 into a list by the current environment.
8213 A Python function that takes
8214 two or three arguments:
8215 a construction environment, directory Node,
8216 and optional argument supplied
8217 when the scanner was created.
8220 returns a tuple of directories
8221 that can be searched for files to be returned
8222 by this Scanner object.
8225 The class of Node that should be returned
8226 by this Scanner object.
8227 Any strings or other objects returned
8228 by the scanner function
8229 that are not of this class
8230 will be run through the
8235 A Python function that will take a string
8237 and turn it into the appropriate class of Node
8238 to be returned by this Scanner object.
8241 An optional Python function that takes two arguments,
8242 a Node (file) and a construction environment,
8243 and returns whether the
8244 Node should, in fact,
8245 be scanned for dependencies.
8246 This check can be used to eliminate unnecessary
8247 calls to the scanner function when,
8248 for example, the underlying file
8249 represented by a Node does not yet exist.
8252 An optional flag that
8253 specifies whether this scanner should be re-invoked
8254 on the dependency files returned by the scanner.
8255 When this flag is not set,
8256 the Node subsystem will
8257 only invoke the scanner on the file being scanned,
8258 and not (for example) also on the files
8259 specified by the #include lines
8260 in the file being scanned.
8262 .SH SYSTEM-SPECIFIC BEHAVIOR
8263 SCons and its configuration files are very portable,
8264 due largely to its implementation in Python.
8265 There are, however, a few portability
8266 issues waiting to trap the unwary.
8268 SCons handles the upper-case
8270 file suffix differently,
8271 depending on the capabilities of
8272 the underlying system.
8273 On a case-sensitive system
8274 such as Linux or UNIX,
8275 SCons treats a file with a
8277 suffix as a C++ source file.
8278 On a case-insensitive system
8280 SCons treats a file with a
8282 suffix as a C source file.
8284 SCons handles the upper-case
8286 file suffix differently,
8287 depending on the capabilities of
8288 the underlying system.
8289 On a case-sensitive system
8290 such as Linux or UNIX,
8291 SCons treats a file with a
8293 suffix as a Fortran source file
8294 that is to be first run through
8295 the standard C preprocessor.
8296 On a case-insensitive system
8298 SCons treats a file with a
8300 suffix as a Fortran source file that should
8302 be run through the C preprocessor.
8303 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
8304 Cygwin supplies a set of tools and utilities
8305 that let users work on a
8306 Windows system using a more POSIX-like environment.
8307 The Cygwin tools, including Cygwin Python,
8309 by sharing an ability to interpret UNIX-like path names.
8310 For example, the Cygwin tools
8311 will internally translate a Cygwin path name
8312 like /cygdrive/c/mydir
8313 to an equivalent Windows pathname
8314 of C:/mydir (equivalent to C:\\mydir).
8317 that are built for native Windows execution,
8318 such as the python.org and ActiveState versions,
8319 do not have the Cygwin path name semantics.
8320 This means that using a native Windows version of Python
8321 to build compiled programs using Cygwin tools
8322 (such as gcc, bison, and flex)
8323 may yield unpredictable results.
8324 "Mixing and matching" in this way
8325 can be made to work,
8326 but it requires careful attention to the use of path names
8327 in your SConscript files.
8329 In practice, users can sidestep
8330 the issue by adopting the following rules:
8332 use the Cygwin-supplied Python interpreter
8334 when using Microsoft Visual C/C++
8335 (or some other Windows compiler)
8336 use the python.org or ActiveState version of Python
8338 .SS WIN32: scons.bat file
8340 SCons is executed via a wrapper
8343 This has (at least) two ramifications:
8345 First, Windows command-line users
8346 that want to use variable assignment
8348 may have to put double quotes
8349 around the assignments:
8352 scons "FOO=BAR" "BAZ=BLEH"
8355 Second, the Cygwin shell does not
8356 recognize this file as being the same
8359 command issued at the command-line prompt.
8360 You can work around this either by
8363 from the Cygwin command line,
8364 or by creating a wrapper shell
8370 The MinGW bin directory must be in your PATH environment variable or the
8371 PATH variable under the ENV construction variable for SCons
8372 to detect and use the MinGW tools. When running under the native Windows
8373 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8374 tools, if they are both installed, regardless of the order of the bin
8375 directories in the PATH variable. If you have both MSVC and MinGW
8376 installed and you want to use MinGW instead of MSVC,
8377 then you must explictly tell SCons to use MinGW by passing
8383 to the Environment() function, because SCons will prefer the MSVC tools
8384 over the MinGW tools.
8388 To help you get started using SCons,
8389 this section contains a brief overview of some common tasks.
8391 .SS Basic Compilation From a Single Source File
8395 env.Program(target = 'foo', source = 'foo.c')
8398 Note: Build the file by specifying
8399 the target as an argument
8400 ("scons foo" or "scons foo.exe").
8401 or by specifying a dot ("scons .").
8403 .SS Basic Compilation From Multiple Source Files
8407 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8410 .SS Setting a Compilation Flag
8413 env = Environment(CCFLAGS = '-g')
8414 env.Program(target = 'foo', source = 'foo.c')
8417 .SS Search The Local Directory For .h Files
8421 need to set CCFLAGS to specify -I options by hand.
8422 SCons will construct the right -I options from CPPPATH.
8425 env = Environment(CPPPATH = ['.'])
8426 env.Program(target = 'foo', source = 'foo.c')
8429 .SS Search Multiple Directories For .h Files
8432 env = Environment(CPPPATH = ['include1', 'include2'])
8433 env.Program(target = 'foo', source = 'foo.c')
8436 .SS Building a Static Library
8440 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8441 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8444 .SS Building a Shared Library
8448 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8449 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8452 .SS Linking a Local Library Into a Program
8455 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8456 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8457 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8460 .SS Defining Your Own Builder Object
8462 Notice that when you invoke the Builder,
8463 you can leave off the target file suffix,
8464 and SCons will add it automatically.
8467 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8469 src_suffix = '.tex')
8470 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8471 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8473 # The following creates "bar.pdf" from "bar.tex"
8474 env.PDFBuilder(target = 'bar', source = 'bar')
8477 Note also that the above initialization
8478 overwrites the default Builder objects,
8479 so the Environment created above
8480 can not be used call Builders like env.Program(),
8481 env.Object(), env.StaticLibrary(), etc.
8483 .SS Adding Your Own Builder Object to an Environment
8486 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8488 src_suffix = '.tex')
8490 env.Append(BUILDERS = {'PDFBuilder' : bld})
8491 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8492 env.Program(target = 'bar', source = 'bar.c')
8495 You also can use other Pythonic techniques to add
8496 to the BUILDERS construction variable, such as:
8500 env['BUILDERS]['PDFBuilder'] = bld
8503 .SS Defining Your Own Scanner Object
8508 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8510 def kfile_scan(node, env, path, arg):
8511 contents = node.get_contents()
8512 includes = include_re.findall(contents)
8515 kscan = Scanner(name = 'kfile',
8516 function = kfile_scan,
8519 scanners = Environment().Dictionary('SCANNERS')
8520 env = Environment(SCANNERS = scanners + [kscan])
8522 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8524 bar_in = File('bar.in')
8525 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8526 bar_in.target_scanner = kscan
8529 .SS Creating a Hierarchical Build
8531 Notice that the file names specified in a subdirectory's
8533 file are relative to that subdirectory.
8539 env.Program(target = 'foo', source = 'foo.c')
8541 SConscript('sub/SConscript')
8546 # Builds sub/foo from sub/foo.c
8547 env.Program(target = 'foo', source = 'foo.c')
8549 SConscript('dir/SConscript')
8554 # Builds sub/dir/foo from sub/dir/foo.c
8555 env.Program(target = 'foo', source = 'foo.c')
8558 .SS Sharing Variables Between SConscript Files
8560 You must explicitly Export() and Import() variables that
8561 you want to share between SConscript files.
8567 env.Program(target = 'foo', source = 'foo.c')
8570 SConscript('subdirectory/SConscript')
8572 subdirectory/SConscript:
8575 env.Program(target = 'foo', source = 'foo.c')
8578 .SS Building Multiple Variants From the Same Source
8580 Use the BuildDir() method to establish
8581 one or more separate build directories for
8582 a given source directory,
8583 then use the SConscript() method
8584 to specify the SConscript files
8585 in the build directories:
8592 BuildDir('foo', 'src')
8593 SConscript('foo/SConscript')
8597 BuildDir('bar', 'src')
8598 SConscript('bar/SConscript')
8603 env = Environment(CCFLAGS = ccflags)
8604 env.Program(target = 'src', source = 'src.c')
8607 Note the use of the Export() method
8608 to set the "ccflags" variable to a different
8609 value for each variant build.
8611 .SS Hierarchical Build of Two Libraries Linked With a Program
8616 env = Environment(LIBPATH = ['#libA', '#libB'])
8618 SConscript('libA/SConscript')
8619 SConscript('libB/SConscript')
8620 SConscript('Main/SConscript')
8625 env.Library('a', Split('a1.c a2.c a3.c'))
8630 env.Library('b', Split('b1.c b2.c b3.c'))
8635 e = env.Copy(LIBS = ['a', 'b'])
8636 e.Program('foo', Split('m1.c m2.c m3.c'))
8639 The '#' in the LIBPATH directories specify that they're relative to the
8640 top-level directory, so they don't turn into "Main/libA" when they're
8641 used in Main/SConscript.
8643 Specifying only 'a' and 'b' for the library names
8644 allows SCons to append the appropriate library
8645 prefix and suffix for the current platform
8646 (for example, 'liba.a' on POSIX systems,
8647 'a.lib' on Windows).
8649 .SS Customizing contruction variables from the command line.
8651 The following would allow the C compiler to be specified on the command
8652 line or in the file custom.py.
8655 opts = Options('custom.py')
8656 opts.Add('CC', 'The C compiler.')
8657 env = Environment(options=opts)
8658 Help(opts.GenerateHelpText(env))
8661 The user could specify the C compiler on the command line:
8667 or in the custom.py file:
8673 or get documentation on the options:
8684 .SS Using Microsoft Visual C++ precompiled headers
8686 Since windows.h includes everything and the kitchen sink, it can take quite
8687 some time to compile it over and over again for a bunch of object files, so
8688 Microsoft provides a mechanism to compile a set of headers once and then
8689 include the previously compiled headers in any object file. This
8690 technology is called precompiled headers. The general recipe is to create a
8691 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
8692 then include every header you want to precompile in "StdAfx.h", and finally
8693 include "StdAfx.h" as the first header in all the source files you are
8694 compiling to object files. For example:
8698 #include <windows.h>
8699 #include <my_big_header.h>
8718 /* do some other stuff */
8724 env['PCHSTOP'] = 'StdAfx.h'
8725 env['PCH'] = env.PCH('StdAfx.cpp')[0]
8726 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8729 For more information see the document for the PCH builder, and the PCH and
8730 PCHSTOP construction variables. To learn about the details of precompiled
8731 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
8733 .SS Using Microsoft Visual C++ external debugging information
8735 Since including debugging information in programs and shared libraries can
8736 cause their size to increase significantly, Microsoft provides a mechanism
8737 for including the debugging information in an external file called a PDB
8738 file. SCons supports PDB files through the PDB construction
8744 env['PDB'] = 'MyApp.pdb'
8745 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8748 For more information see the document for the PDB construction variable.
8753 Specifies the directory that contains the SCons Python module directory
8754 (e.g. /home/aroach/scons-src-0.01/src/engine).
8757 A string of options that will be used by scons in addition to those passed
8758 on the command line.
8769 Steven Knight <knight@baldmt.com>
8771 Anthony Roach <aroach@electriceyeball.com>