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:
1041 Additionally, there is a "tool" named
1043 which configures the
1044 environment with a default set of tools for the current platform.
1046 On posix and cygwin platforms
1047 the GNU tools (e.g. gcc) are preferred by SCons,
1048 on win32 the Microsoft tools (e.g. msvc)
1049 followed by MinGW are preferred by SCons,
1050 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1054 Build rules are specified by calling a construction
1055 environment's builder methods.
1056 The arguments to the builder methods are
1058 (a list of target files)
1061 (a list of source files).
1063 Because long lists of file names
1064 can lead to a lot of quoting,
1069 and a same-named environment method
1070 that split a single string
1071 into a list, separated on
1072 strings of white-space characters.
1073 (These are similar to the
1074 string.split() method
1075 from the standard Python library,
1076 but work even if the input isn't a string.)
1078 Like all Python arguments,
1079 the target and source arguments to a builder method
1080 can be specified either with or without
1081 the "target" and "source" keywords.
1082 When the keywords are omitted,
1083 the target is first,
1084 followed by the source.
1085 The following are equivalent examples of calling the Program builder method:
1088 env.Program('bar', ['bar.c', 'foo.c'])
1089 env.Program('bar', Split('bar.c foo.c'))
1090 env.Program('bar', env.Split('bar.c foo.c'))
1091 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1092 env.Program(target = 'bar', Split('bar.c foo.c'))
1093 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1094 env.Program('bar', source = string.split('bar.c foo.c'))
1097 When the target shares the same base name
1098 as the source and only the suffix varies,
1099 and if the builder method has a suffix defined for the target file type,
1100 then the target argument may be omitted completely,
1103 will deduce the target file name from
1104 the source file name.
1105 The following examples all build the
1111 (on Windows systems)
1112 from the bar.c source file:
1115 env.Program(target = 'bar', source = 'bar.c')
1116 env.Program('bar', source = 'bar.c')
1117 env.Program(source = 'bar.c')
1118 env.Program('bar.c')
1121 It is possible to override or add construction variables when calling a
1122 builder method by passing additional keyword arguments.
1123 These overridden or added
1124 variables will only be in effect when building the target, so they will not
1125 affect other parts of the build. For example, if you want to add additional
1126 libraries for just one program:
1129 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1132 or generate a shared library with a nonstandard suffix:
1135 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1138 Although the builder methods defined by
1141 methods of a construction environment object,
1142 they may also be called without an explicit environment:
1145 Program('hello', 'hello.c')
1146 SharedLibrary('word', 'word.cpp')
1150 the methods are called internally using a default construction
1151 environment that consists of the tools and values that
1153 has determined are appropriate for the local system.
1155 All builder methods return a list of Nodes
1156 that represent the target or targets that will be built.
1159 is an internal SCons object
1161 build targets or sources.
1163 The returned Node(s)
1164 can be passed to other builder methods as source(s)
1165 or passed to any SCons function or method
1166 where a filename would normally be accepted.
1167 For example, if it were necessary
1170 flag when compiling one specific object file:
1173 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1174 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1177 Using a Node in this way
1178 makes for a more portable build
1179 by avoiding having to specify
1180 a platform-specific object suffix
1181 when calling the Program() builder method.
1183 Note that Builder calls will automatically "flatten"
1184 the source and target file lists,
1185 so it's all right to have the bar_obj list
1186 return by the StaticObject() call
1187 in the middle of the source file list.
1188 If you need to manipulate a list of lists returned by Builders
1189 directly using Python,
1190 you can either build the list by hand:
1193 foo = Object('foo.c')
1194 bar = Object('bar.c')
1195 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1196 for object in objects:
1203 to create a list containing just the Nodes,
1204 which may be more convenient:
1207 foo = Object('foo.c')
1208 bar = Object('bar.c')
1209 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1210 for object in objects:
1214 The path name for a Node's file may be used
1215 by passing the Node to the Python-builtin
1220 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1221 print "The path to bar_obj is:", str(bar_obj_list[0])
1224 Note again that because the Builder call returns a list,
1225 we have to access the first element in the list
1226 .B (bar_obj_list[0])
1227 to get at the Node that actually represents
1231 provides the following builder methods:
1233 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1236 Builds a C source file given a lex (.l) or yacc (.y) input file.
1237 The suffix specified by the $CFILESUFFIX construction variable
1239 is automatically added to the target
1240 if it is not already present. Example:
1244 env.CFile(target = 'foo.c', source = 'foo.l')
1246 env.CFile(target = 'bar', source = 'bar.y')
1249 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1252 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1254 The suffix specified by the $CXXFILESUFFIX construction variable
1256 is automatically added to the target
1257 if it is not already present. Example:
1261 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1263 env.CXXFile(target = 'bar', source = 'bar.yy')
1266 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1269 Builds a .dvi file from a .tex, .ltx or .latex input file.
1270 If the source file suffix is .tex,
1272 will examine the contents of the file;
1277 is found, the file is assumed to be a LaTeX file and
1278 the target is built by invoking the $LATEXCOM command line;
1279 otherwise, the $TEXCOM command line is used.
1280 If the file is a LaTeX file,
1283 builder method will also examine the contents
1286 and invoke the $BIBTEX command line
1290 and will examine the contents
1292 file and re-run the $LATEXCOM command
1293 if the log file says it is necessary.
1296 (hard-coded within TeX itself)
1297 is automatically added to the target
1298 if it is not already present. Examples:
1301 # builds from aaa.tex
1302 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1304 env.DVI(target = 'bbb', source = 'bbb.ltx')
1305 # builds from ccc.latex
1306 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1309 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1312 Builds a Java archive (.jar) file
1313 from a source tree of .class files.
1314 If the $JARCHDIR value is set, the
1316 command will change to the specified directory using the
1319 If the contents any of the source files begin with the string
1320 .BR Manifest-Version ,
1321 the file is assumed to be a manifest
1322 and is passed to the
1329 env.Jar(target = 'foo.jar', source = 'classes')
1332 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1335 Builds one or more Java class files
1336 from one or more source trees of .java files.
1337 The class files will be placed underneath
1338 the specified target directory.
1339 SCons will parse each source .java file
1341 (including inner classes)
1342 defined within that file,
1343 and from that figure out the
1344 target .class files that will be created.
1345 SCons will also search each Java file
1346 for the Java package name,
1347 which it assumes can be found on a line
1348 beginning with the string
1350 in the first column;
1351 the resulting .class files
1352 will be placed in a directory reflecting
1353 the specified package name.
1357 defining a single public
1360 containing a package name of
1362 will generate a corresponding
1363 .IR sub/dir/Foo.class
1369 env.Java(target = 'classes', source = 'src')
1370 env.Java(target = 'classes', source = ['src1', 'src2'])
1373 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1376 Builds C header and source files for
1377 implementing Java native methods.
1378 The target can be either a directory
1379 in which the header files will be written,
1380 or a header file name which
1381 will contain all of the definitions.
1382 The source can be either the names of .class files,
1383 or the objects returned from the
1387 If the construction variable
1389 is set, either in the environment
1390 or in the call to the
1392 builder method itself,
1393 then the value of the variable
1394 will be stripped from the
1395 beginning of any .class file names.
1400 # builds java_native.h
1401 classes = env.Java(target = 'classdir', source = 'src')
1402 env.JavaH(target = 'java_native.h', source = classes)
1404 # builds include/package_foo.h and include/package_bar.h
1405 env.JavaH(target = 'include',
1406 source = ['package/foo.class', 'package/bar.class'])
1408 # builds export/foo.h and export/bar.h
1409 env.JavaH(target = 'export',
1410 source = ['classes/foo.class', 'classes/bar.class'],
1411 JAVACLASSDIR = 'classes')
1414 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1421 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1424 Builds an output file from an M4 input file.
1425 This uses a default $M4FLAGS value of
1427 which considers all warnings to be fatal
1428 and stops on the first warning
1429 when using the GNU version of m4.
1433 env.M4(target = 'foo.c', source = 'foo.c.m4')
1436 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1439 Builds an output file from a moc input file. Moc input files are either
1440 header files or cxx files. This builder is only available after using the
1441 tool 'qt'. See the QTDIR variable for more information.
1445 env.Moc('foo.h') # generates moc_foo.cc
1446 env.Moc('foo.cpp') # generates foo.moc
1449 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1451 .IP env.MSVSProject()
1452 Builds Microsoft Visual Studio project files.
1453 This builds a Visual Studio project file, based on the version of
1454 Visual Studio that is configured (either the latest installed version,
1455 or the version set by
1457 in the Environment constructor).
1458 For VS 6, it will generate
1462 files, for VS 7, it will
1469 It takes several lists of filenames to be placed into the project
1470 file, currently these are limited to
1471 .B srcs, incs, localincs, resources,
1474 These are pretty self explanatory, but it
1475 should be noted that the 'srcs' list is NOT added to the $SOURCES
1476 environment variable. This is because it represents a list of files
1477 to be added to the project file, not the source used to build the
1478 project file (in this case, the 'source' is the SConscript file used
1479 to call MSVSProject).
1481 In addition to these values (which are all optional, although not
1482 specifying any of them results in an empty project file), the
1483 following values must be specified:
1485 target: The name of the target .dsp or .vcproj file. The correct
1486 suffix for the version of Visual Studio must be used, but the value
1488 env['MSVSPROJECTSUFFIX']
1490 will be defined to the correct value (see example below).
1492 variant: The name of this particular variant. These are typically
1493 things like "Debug" or "Release", but really can be anything you want.
1494 Multiple calls to MSVSProject with different variants are allowed: all
1495 variants will be added to the project file with their appropriate
1496 build targets and sources.
1498 buildtarget: A list of SCons.Node.FS objects which is returned from
1499 the command which builds the target. This is used to tell SCons what
1500 to build when the 'build' button is pressed inside of the IDE.
1505 barsrcs = ['bar.cpp'],
1506 barincs = ['bar.h'],
1507 barlocalincs = ['StdAfx.h']
1508 barresources = ['bar.rc','resource.h']
1509 barmisc = ['bar_readme.txt']
1511 dll = local.SharedLibrary(target = 'bar.dll',
1514 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1517 localincs = barlocalincs,
1518 resources = barresources,
1521 variant = 'Release')
1524 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1531 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1534 Builds a Microsoft Visual C++ precompiled header.
1535 Calling this builder method
1536 returns a list of two targets: the PCH as the first element, and the object
1537 file as the second element. Normally the object file is ignored.
1538 This builder method is only
1539 provided when Microsoft Visual C++ is being used as the compiler.
1540 The PCH builder method is generally used in
1541 conjuction with the PCH construction variable to force object files to use
1542 the precompiled header:
1545 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1548 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1551 Builds a .pdf file from a .dvi input file
1552 (or, by extension, a .tex, .ltx, or .latex input file).
1553 The suffix specified by the $PDFSUFFIX construction variable
1555 is added automatically to the target
1556 if it is not already present. Example:
1559 # builds from aaa.tex
1560 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1561 # builds bbb.pdf from bbb.dvi
1562 env.PDF(target = 'bbb', source = 'bbb.dvi')
1565 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1567 .IP env.PostScript()
1568 Builds a .ps file from a .dvi input file
1569 (or, by extension, a .tex, .ltx, or .latex input file).
1570 The suffix specified by the $PSSUFFIX construction variable
1572 is added automatically to the target
1573 if it is not already present. Example:
1576 # builds from aaa.tex
1577 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1578 # builds bbb.ps from bbb.dvi
1579 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1582 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1585 Builds an executable given one or more object files
1586 or C, C++, D, or Fortran source files.
1587 If any C, C++, D or Fortran source files are specified,
1588 then they will be automatically
1589 compiled to object files using the
1592 see that builder method's description for
1593 a list of legal source file suffixes
1594 and how they are interpreted.
1595 The target executable file prefix
1596 (specified by the $PROGPREFIX construction variable; nothing by default)
1598 (specified by the $PROGSUFFIX construction variable;
1599 by default, .exe on Windows systems, nothing on POSIX systems)
1600 are automatically added to the target if not already present.
1604 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1607 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1610 Builds a Microsoft Visual C++ resource file.
1611 This builder method is only provided
1612 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1616 for MinGW) suffix is added to the target name if no other suffix is given. The source
1617 file is scanned for implicit dependencies as though it were a C file. Example:
1620 env.RES('resource.rc')
1623 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1626 Builds stub and skeleton class files
1628 from Java .class files.
1629 The target is a directory
1630 relative to which the stub
1631 and skeleton class files will be written.
1632 The source can be the names of .class files,
1633 or the objects return from the
1637 If the construction variable
1639 is set, either in the environment
1640 or in the call to the
1642 builder method itself,
1643 then the value of the variable
1644 will be stripped from the
1645 beginning of any .class file names.
1648 classes = env.Java(target = 'classdir', source = 'src')
1649 env.RMIC(target = 'outdir1', source = classes)
1651 env.RMIC(target = 'outdir2',
1652 source = ['package/foo.class', 'package/bar.class'])
1654 env.RMIC(target = 'outdir3',
1655 source = ['classes/foo.class', 'classes/bar.class'],
1656 JAVACLASSDIR = 'classes')
1659 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1661 .IP env.SharedLibrary()
1662 Builds a shared library
1663 (.so on a POSIX system, .dll on WIN32)
1664 given one or more object files
1665 or C, C++, D or Fortran source files.
1666 If any source files are given,
1667 then they will be automatically
1668 compiled to object files.
1669 The static library prefix and suffix (if any)
1670 are automatically added to the target.
1671 The target library file prefix
1672 (specified by the $SHLIBPREFIX construction variable;
1673 by default, lib on POSIX systems, nothing on Windows systems)
1675 (specified by the $SHLIBSUFFIX construction variable;
1676 by default, .dll on Windows systems, .so on POSIX systems)
1677 are automatically added to the target if not already present.
1681 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1684 On WIN32 systems, the
1686 builder method will always build an import (.lib) library
1687 in addition to the shared (.dll) library,
1688 adding a .lib library with the same basename
1689 if there is not already a .lib file explicitly
1690 listed in the targets.
1692 Any object files listed in the
1694 must have been built for a shared library
1699 will raise an error if there is any mismatch.
1701 On WIN32 systems, specifying "register=1" will cause the dll to be
1702 registered after it is built using REGSVR32. The command that is run
1703 ("regsvr32" by default) is determined by $REGSVR construction
1704 variable, and the flags passed are determined by $REGSVRFLAGS. By
1705 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1706 up and requiring user attention when it is run. If you change
1707 $REGSVRFLAGS, be sure to include "/s". For example,
1710 env.SharedLibrary(target = 'bar',
1711 source = ['bar.cxx', 'foo.obj'],
1716 will register "bar.dll" as a COM object when it is done linking it.
1718 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1720 .IP env.SharedObject()
1721 Builds an object file for
1722 inclusion in a shared library.
1723 Source files must have one of the same set of extensions
1724 specified above for the
1727 On some platforms building a shared object requires additional
1728 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1729 normal (static) object, but on some platforms there is no difference between a
1730 shared object and a normal (static) one. When there is a difference, SCons
1731 will only allow shared objects to be linked into a shared library, and will
1732 use a different suffix for shared objects. On platforms where there is no
1733 difference, SCons will allow both normal (static)
1734 and shared objects to be linked into a
1735 shared library, and will use the same suffix for shared and normal
1737 The target object file prefix
1738 (specified by the $SHOBJPREFIX construction variable;
1739 by default, the same as $OBJPREFIX)
1741 (specified by the $SHOBJSUFFIX construction variable)
1742 are automatically added to the target if not already present.
1746 env.SharedObject(target = 'ddd', source = 'ddd.c')
1747 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1748 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1751 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1753 .IP env.StaticLibrary()
1754 Builds a static library given one or more object files
1755 or C, C++, D or Fortran source files.
1756 If any source files are given,
1757 then they will be automatically
1758 compiled to object files.
1759 The static library prefix and suffix (if any)
1760 are automatically added to the target.
1761 The target library file prefix
1762 (specified by the $LIBPREFIX construction variable;
1763 by default, lib on POSIX systems, nothing on Windows systems)
1765 (specified by the $LIBSUFFIX construction variable;
1766 by default, .lib on Windows systems, .a on POSIX systems)
1767 are automatically added to the target if not already present.
1771 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1775 Any object files listed in the
1777 must have been built for a static library
1782 will raise an error if there is any mismatch.
1784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1786 .IP env.StaticObject()
1787 Builds a static object file
1788 from one or more C, C++, D, or Fortran source files.
1789 Source files must have one of the following extensions:
1792 .asm assembly language file
1793 .ASM assembly language file
1805 .F WIN32: Fortran file
1806 POSIX: Fortran file + C pre-processor
1809 .fpp Fortran file + C pre-processor
1810 .FPP Fortran file + C pre-processor
1811 .s assembly language file
1812 .S WIN32: assembly language file
1813 POSIX: assembly language file + C pre-processor
1814 .spp assembly language file + C pre-processor
1815 .SPP assembly language file + C pre-processor
1818 The target object file prefix
1819 (specified by the $OBJPREFIX construction variable; nothing by default)
1821 (specified by the $OBJSUFFIX construction variable;
1822 \.obj on Windows systems, .o on POSIX systems)
1823 are automatically added to the target if not already present.
1827 env.StaticObject(target = 'aaa', source = 'aaa.c')
1828 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1829 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1832 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1835 Builds a tar archive of the specified files
1837 Unlike most builder methods,
1840 builder method may be called multiple times
1842 each additional call
1843 adds to the list of entries
1844 that will be built into the archive.
1847 env.Tar('src.tar', 'src')
1849 # Create the stuff.tar file.
1850 env.Tar('stuff', ['subdir1', 'subdir2'])
1851 # Also add "another" to the stuff.tar file.
1852 env.Tar('stuff', 'another')
1854 # Set TARFLAGS to create a gzip-filtered archive.
1855 env = Environment(TARFLAGS = '-c -z')
1856 env.Tar('foo.tar.gz', 'foo')
1858 # Also set the suffix to .tgz.
1859 env = Environment(TARFLAGS = '-c -z',
1864 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1866 .IP env.TypeLibrary()
1867 Builds a Windows type library (.tlb) file from and input IDL file
1868 (.idl). In addition, it will build the associated inteface stub and
1869 proxy source files. It names them according to the base name of the .idl file.
1874 env.TypeLibrary(source="foo.idl")
1877 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1879 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1882 Builds a header file, an implementation file and a moc file from an ui file.
1883 and returns the corresponding nodes in the above order.
1884 This builder is only available after using the tool 'qt'. Note: you can
1885 specify .ui files directly as inputs for Program, Library and SharedLibrary
1886 without using this builder. Using the builder lets you override the standard
1887 naming conventions (be careful: prefixes are always prepended to names of
1888 built files; if you don't want prefixes, you may set them to ``).
1889 See the QTDIR variable for more information.
1893 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
1894 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
1895 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
1898 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1901 Builds a zip archive of the specified files
1903 Unlike most builder methods,
1906 builder method may be called multiple times
1908 each additional call
1909 adds to the list of entries
1910 that will be built into the archive.
1913 env.Zip('src.zip', 'src')
1915 # Create the stuff.zip file.
1916 env.Zip('stuff', ['subdir1', 'subdir2'])
1917 # Also add "another" to the stuff.tar file.
1918 env.Zip('stuff', 'another')
1923 C source files, C++ source files,
1924 Fortran source files with
1926 (POSIX systems only),
1931 and assembly language files with
1933 (POSIX systems only),
1938 for C preprocessor dependencies,
1939 so the dependencies do not need to be specified explicitly.
1941 targets of builder methods automatically depend on their sources.
1942 An explicit dependency can
1943 be specified using the
1945 method of a construction environment (see below).
1947 .SS Methods and Functions to Do Things
1948 In addition to Builder methods,
1950 provides a number of other construction environment methods
1951 and global functions to
1952 manipulate the build configuration.
1954 Usually, a construction environment method
1955 and global function with the same name both exist
1956 so that you don't have to remember whether
1957 to a specific bit of functionality
1958 must be called with or without a construction environment.
1959 In the following list,
1960 if you call something as a global function
1963 .RI Function( arguments )
1965 and if you call something through a construction
1966 environment it looks like:
1968 .RI env.Function( arguments )
1970 If you can call the functionality in both ways,
1971 then both forms are listed.
1973 Except where otherwise noted,
1975 construction environment method
1977 provide the exact same functionality.
1978 The only difference is that,
1980 calling the functionality through a construction environment will
1981 substitute construction variables into
1982 any supplied strings.
1985 env = Environment(FOO = 'foo')
1989 the first call to the global
1991 function will actually add a target named
1993 to the list of default targets,
1994 while the second call to the
1996 construction environment method
1997 will expand the value
1998 and add a target named
2000 to the list of default targets.
2001 For more on construction variable expansion,
2002 see the next section on
2003 construction variables.
2005 Construction environment methods
2006 and global functions supported by
2010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2012 .RI Action( action ", [" strfunction ", " varlist ])
2014 .RI env.Action( action ", [" strfunction ", " varlist ])
2015 Creates an Action object for
2018 See the section "Action Objects,"
2019 below, for a complete explanation of the arguments and behavior.
2021 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2023 .RI AddPostAction( target ", " action )
2025 .RI env.AddPostAction( target ", " action )
2026 Arranges for the specified
2032 The specified action(s) may be
2033 an Action object, or anything that
2034 can be converted into an Action object
2037 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2039 .RI AddPreAction( target ", " action )
2041 .RI env.AddPreAction( target ", " action )
2042 Arranges for the specified
2045 before the specified
2048 The specified action(s) may be
2049 an Action object, or anything that
2050 can be converted into an Action object
2053 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2055 .RI Alias( alias ", [" targets ])
2057 .RI env.Alias( alias ", [" targets ])
2058 Creates one or more phony targets that
2059 expand to one or more other targets.
2060 Returns the Node object representing the alias,
2061 which exists outside of any file system.
2062 This Node object, or the alias name,
2063 may be used as a dependency of any other target,
2064 including another alias.
2066 can be called multiple times for the same
2067 alias to add additional targets to the alias.
2071 Alias('install', '/usr/bin')
2072 Alias(['install', 'install-lib'], '/usr/local/lib')
2074 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2075 env.Alias('install', ['/usr/local/man'])
2078 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2080 .RI AlwaysBuild( target ", ...)"
2082 .RI env.AlwaysBuild( target ", ...)"
2085 so that it is always assumed to be out of date,
2086 and will always be rebuilt if needed.
2089 does not add its target(s) to the default target list,
2090 so the targets will only be built
2091 if they are specified on the command line,
2092 or are a dependent of a target specified on the command line--but
2095 be built if so specified.
2096 Multiple targets can be passed in to a single call to
2099 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2101 .RI env.Append( key = val ", [...])"
2102 Appends the specified keyword arguments
2103 to the end of construction variables in the environment.
2104 If the Environment does not have
2105 the specified construction variable,
2106 it is simply added to the environment.
2107 If the values of the construction variable
2108 and the keyword argument are the same type,
2109 then the two values will be simply added together.
2110 Otherwise, the construction variable
2111 and the value of the keyword argument
2112 are both coerced to lists,
2113 and the lists are added together.
2114 (See also the Prepend method, below.)
2117 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2120 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2122 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2123 This appends new path elements to the given path in the
2124 specified external environment
2128 any particular path once (leaving the last one it encounters and
2129 ignoring the rest, to preserve path order),
2130 and to help assure this,
2131 will normalize all paths (using
2134 .BR os.path.normcase ).
2135 This can also handle the
2136 case where the given old path variable is a list instead of a
2137 string, in which case a list will be returned instead of a string.
2141 print 'before:',env['ENV']['INCLUDE']
2142 include_path = '/foo/bar:/foo'
2143 env.PrependENVPath('INCLUDE', include_path)
2144 print 'after:',env['ENV']['INCLUDE']
2148 after: /biz:/foo/bar:/foo
2151 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2153 .RI env.AppendUnique( key = val ", [...])"
2154 Appends the specified keyword arguments
2155 to the end of construction variables in the environment.
2156 If the Environment does not have
2157 the specified construction variable,
2158 it is simply added to the environment.
2159 If the construction variable being appended to is a list,
2160 then any value(s) that already exist in the
2161 construction variable will
2163 be added again to the list.
2166 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2169 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2172 A factory function that
2173 returns a Builder object
2174 to be used to fetch source files
2176 The returned Builder
2177 is intended to be passed to the
2182 env.SourceCode('.', env.BitKeeper())
2185 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2187 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2189 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2190 This specifies a build directory
2192 in which to build all derived files
2193 that would normally be built under
2195 Multiple build directories can be set up for multiple build variants, for
2198 must be underneath the SConstruct file's directory,
2201 may not be underneath the
2204 The default behavior is for
2206 to duplicate all of the files in the tree underneath
2210 and then build the derived files within the copied tree.
2211 (The duplication is performed by
2213 depending on the platform; see also the
2216 This guarantees correct builds
2217 regardless of whether intermediate source files
2218 are generated during the build,
2219 where preprocessors or other scanners search
2221 or whether individual compilers or other invoked tools
2222 are hard-coded to put derived files in the same directory as source files.
2224 This behavior of making a complete copy of the source tree
2225 may be disabled by setting
2230 to invoke Builders using the
2231 path names of source files in
2233 and the path names of derived files within
2235 This is always more efficient than
2237 and is usually safe for most builds.
2241 may cause build problems
2242 if source files are generated during the build,
2243 if any invoked tools are hard-coded to
2244 put derived files in the same directory as the source files.
2246 Note that specifying a
2248 works most naturally
2249 with a subsidiary SConscript file
2250 in the source directory.
2252 you would then call the subsidiary SConscript file
2253 not in the source directory,
2258 had made a virtual copy of the source tree
2259 regardless of the value of
2261 This is how you tell
2263 which variant of a source tree to build.
2267 BuildDir('build-variant1', 'src')
2268 SConscript('build-variant1/SConscript')
2269 BuildDir('build-variant2', 'src')
2270 SConscript('build-variant2/SConscript')
2276 function, described below,
2278 specify a build directory
2279 in conjunction with calling a subsidiary
2282 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2284 .RI Builder( action ", [" arguments ])
2286 .RI env.Builder( action ", [" arguments ])
2287 Creates a Builder object for
2290 See the section "Builder Objects,"
2291 below, for a complete explanation of the arguments and behavior.
2293 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2295 .RI CacheDir( cache_dir )
2297 .RI env.CacheDir( cache_dir )
2300 will maintain a cache of derived files in
2302 The derived files in the cache will be shared
2303 among all the builds using the same
2311 finds a derived file that needs to be rebuilt,
2312 it will first look in the cache to see if a
2313 derived file has already been built
2314 from identical input files and an identical build action
2315 (as incorporated into the MD5 build signature).
2318 will retrieve the file from the cache.
2319 If the derived file is not present in the cache,
2322 then place a copy of the built file in the cache
2323 (identified by its MD5 build signature),
2324 so that it may be retrieved by other
2325 builds that need to build the same derived file
2326 from identical inputs.
2330 may be disabled for any invocation
2339 will place a copy of
2341 derived files in the cache,
2342 even if they already existed
2343 and were not built by this invocation.
2344 This is useful to populate a cache
2347 is added to a build,
2356 "Retrieved `file' from cache,"
2359 option is being used.
2364 will print the action that
2366 have been used to build the file,
2367 without any indication that
2368 the file was actually retrieved from the cache.
2369 This is useful to generate build logs
2370 that are equivalent regardless of whether
2371 a given derived file has been built in-place
2372 or retrieved from the cache.
2374 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2376 .RI Clean( targets ", " files_or_dirs )
2378 .RI env.Clean( targets ", " files_or_dirs )
2379 This specifies a list of files or directories which should be removed
2380 whenever the targets are specified with the
2382 command line option.
2383 The specified targets may be a list
2384 or an individual target.
2388 and create new targets or add files and directories to the
2389 clean list for the specified targets.
2391 Multiple files or directories should be specified
2392 either as separate arguments to the
2394 method, or as a list.
2396 will also accept the return value of any of the construction environment
2401 Clean('foo', ['bar', 'baz'])
2402 Clean('dist', env.Program('hello', 'hello.c'))
2403 Clean(['foo', 'bar'], 'something_else_to_clean')
2406 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2408 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2410 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2411 Executes a specific action
2412 (or list of actions)
2413 to build a target file or files.
2414 This is more convenient
2415 than defining a separate Builder object
2416 for a single special-case build.
2417 Any keyword arguments specified override any
2418 same-named existing construction variables.
2420 Note that an action can be an external command,
2421 specified as a string,
2422 or a callable Python object;
2423 see "Action Objects," below.
2427 env.Command('foo.out', 'foo.in',
2428 "$FOO_BUILD < $SOURCES > $TARGET")
2430 env.Command('bar.out', 'bar.in',
2432 "$BAR_BUILD < $SOURCES > $TARGET"],
2433 ENV = {'PATH' : '/usr/local/bin/'})
2435 def rename(env, target, source):
2437 os.rename('.tmp', str(target[0]))
2439 env.Command('baz.out', 'baz.in',
2440 ["$BAZ_BUILD < $SOURCES > .tmp",
2444 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2446 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
2448 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
2449 Creates a Configure object for integrated
2450 functionality similar to GNU autoconf.
2451 See the section "Configure Contexts,"
2452 below, for a complete explanation of the arguments and behavior.
2454 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2456 .RI env.Copy([ key = val ", ...])"
2457 Return a separate copy of a construction environment.
2458 If there are any keyword arguments specified,
2459 they are added to the returned copy,
2460 overwriting any existing values
2465 env3 = env.Copy(CCFLAGS = '-g')
2468 Additionally, a list of tools and a toolpath may be specified, as in
2469 the Environment constructor:
2472 def MyTool(env): env['FOO'] = 'bar'
2473 env4 = env.Copy(tools = ['msvc', MyTool])
2476 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2478 .RI env.CVS( repository ", " module )
2479 A factory function that
2480 returns a Builder object
2481 to be used to fetch source files
2485 The returned Builder
2486 is intended to be passed to the
2490 The optional specified
2492 will be added to the beginning
2493 of all repository path names;
2494 this can be used, in essence,
2495 to strip initial directory names
2496 from the repository path names,
2497 so that you only have to
2498 replicate part of the repository
2499 directory hierarchy in your
2500 local build directory:
2503 # Will fetch foo/bar/src.c
2504 # from /usr/local/CVSROOT/foo/bar/src.c.
2505 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2507 # Will fetch bar/src.c
2508 # from /usr/local/CVSROOT/foo/bar/src.c.
2509 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2512 # from /usr/local/CVSROOT/foo/bar/src.c.
2513 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2516 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2518 .RI Default( targets )
2520 .RI env.Default( targets )
2521 This specifies a list of default targets,
2522 which will be built by
2524 if no explicit targets are given on the command line.
2528 and add to the list of default targets.
2530 Multiple targets should be specified as
2531 separate arguments to the
2533 method, or as a list.
2535 will also accept the Node returned by any
2536 of a construction environment's
2541 Default('foo', 'bar', 'baz')
2542 env.Default(['a', 'b', 'c'])
2543 hello = env.Program('hello', 'hello.c')
2551 will clear all default targets.
2554 will add to the (now empty) default-target list
2557 The current list of targets added using the
2559 function or method is available in the
2564 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2566 .RI DefaultEnvironment([ args ])
2567 Creates and returns a default construction environment object.
2568 This construction environment is used internally by SCons
2569 in order to execute many of the global functions in this list,
2570 and to fetch source files transparently
2571 from source code management systems.
2573 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2575 .RI Depends( target ", " dependency )
2577 .RI env.Depends( target ", " dependency )
2578 Specifies an explicit dependency;
2579 the target file(s) will be rebuilt
2580 whenever the dependency file(s) has changed.
2581 This should only be necessary
2582 for cases where the dependency
2583 is not caught by a Scanner
2587 env.Depends('foo', 'other-input-file-for-foo')
2590 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2592 .RI env.Dictionary([ vars ])
2593 Returns a dictionary object
2594 containing copies of all of the
2595 construction variables in the environment.
2596 If there are any variable names specified,
2597 only the specified construction
2598 variables are returned in the dictionary.
2601 dict = env.Dictionary()
2602 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2607 .RI Dir( name ", [" directory ])
2609 .RI env.Dir( name ", [" directory ])
2610 This returns a Directory Node,
2611 an object that represents the specified directory
2614 can be a relative or absolute path.
2616 is an optional directory that will be used as the parent directory.
2619 is specified, the current script's directory is used as the parent.
2621 Directory Nodes can be used anywhere you
2622 would supply a string as a directory name
2623 to a Builder method or function.
2624 Directory Nodes have attributes and methods
2625 that are useful in many situations;
2626 see "File and Directory Nodes," below.
2628 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2630 .RI EnsurePythonVersion( major ", " minor )
2632 .RI env.EnsurePythonVersion( major ", " minor )
2633 Ensure that the Python version is at least
2636 print out an error message and exit SCons with a non-zero exit code if the
2637 actual Python version is not late enough.
2640 EnsurePythonVersion(2,2)
2643 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2645 .RI EnsureSConsVersion( major ", " minor )
2647 .RI env.EnsureSConsVersion( major ", " minor )
2648 Ensure that the SCons version is at least
2651 print out an error message and exit SCons with a non-zero exit code if the
2652 actual SCons version is not late enough.
2655 EnsureSConsVersion(0,9)
2658 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2660 .RI Environment([ key = value ", ...])"
2662 .RI env.Environment([ key = value ", ...])"
2663 Return a new construction environment
2664 initialized with the specified
2668 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2670 .RI Execute( action ", [" strfunction ", " varlist ])
2672 .RI env.Execute( action ", [" strfunction ", " varlist ])
2673 Executes an Action object.
2676 may be an Action object
2677 (see the section "Action Objects,"
2678 below, for a complete explanation of the arguments and behavior),
2679 or it may be a command-line string,
2681 or executable Python function,
2682 each of which will be converted
2683 into an Action object
2685 The exit value of the command
2686 or return value of the Python function
2689 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2693 .RI env.Exit([ value ])
2699 A default exit value of
2702 is used if no value is specified.
2704 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2708 .RI env.Export( vars )
2711 to export a list of variables from the current
2712 SConscript file to all other SConscript files.
2713 The exported variables are kept in a global collection,
2714 so subsequent calls to
2716 will over-write previous exports that have the same name.
2717 Multiple variable names can be passed to
2719 as separate arguments or as a list. A dictionary can be used to map
2720 variables to a different name when exported. Both local variables and
2721 global variables can be exported.
2726 # Make env available for all SConscript files to Import().
2730 # Make env and package available for all SConscript files:.
2731 Export("env", "package")
2733 # Make env and package available for all SConscript files:
2734 Export(["env", "package"])
2736 # Make env available using the name debug:.
2737 Export({"debug":env})
2743 function supports an
2745 argument that makes it easier to to export a variable or
2746 set of variables to a single SConscript file.
2747 See the description of the
2751 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2753 .RI File( name ", [" directory ])
2755 .RI env.File( name ", [" directory ])
2758 an object that represents the specified file
2761 can be a relative or absolute path.
2763 is an optional directory that will be used as the parent directory.
2765 File Nodes can be used anywhere you
2766 would supply a string as a file name
2767 to a Builder method or function.
2768 File Nodes have attributes and methods
2769 that are useful in many situations;
2770 see "File and Directory Nodes," below.
2772 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2774 .RI FindFile( file ", " dirs )
2776 .RI env.FindFile( file ", " dirs )
2779 in the path specified by
2782 may be a list of file names or a single file name. In addition to searching
2783 for files that exist in the filesytem, this function also searches for
2784 derived files that have not yet been built.
2787 foo = env.FindFile('foo', ['dir1', 'dir2'])
2790 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2792 .RI Flatten( sequence )
2794 .RI env.Flatten( sequence )
2795 Takes a sequence (that is, a Python list or tuple)
2796 that may contain nested sequences
2797 and returns a flattened list containing
2798 all of the individual elements in any sequence.
2799 This can be helpful for collecting
2800 the lists returned by calls to Builders;
2801 other Builders will automatically
2802 flatten lists specified as input,
2803 but direct Python manipulation of
2804 these lists does not:
2807 foo = Object('foo.c')
2808 bar = Object('bar.c')
2810 # Because `foo' and `bar' are lists returned by the Object() Builder,
2811 # `objects' will be a list containing nested lists:
2812 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2814 # Passing such a list to another Builder is all right because
2815 # the Builder will flatten the list automatically:
2816 Program(source = objects)
2818 # If you need to manipulate the list directly using Python, you need to
2819 # call Flatten() yourself, or otherwise handle nested lists:
2820 for object in Flatten(objects):
2824 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2826 .RI GetBuildPath( file ", [" ... ])
2828 .RI env.GetBuildPath( file ", [" ... ])
2831 path name (or names) for the specified
2839 Nodes or strings representing path names.
2841 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2845 .RI env.GetLaunchDir()
2846 Returns the absolute path name of the directory from which
2849 was initially invoked.
2850 This can be useful when using the
2855 options, which internally
2856 change to the directory in which the
2860 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2862 .RI GetOption( name )
2864 .RI env.GetOption( name )
2865 This function provides a way to query a select subset of the scons command line
2866 options from a SConscript file. See
2868 for a description of the options available.
2870 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2872 '\".RI GlobalBuilders( flag )
2876 '\"adds the names of the default builders
2877 '\"(Program, Library, etc.)
2878 '\"to the global name space
2879 '\"so they can be called without an explicit construction environment.
2880 '\"(This is the default.)
2884 '\"the names of the default builders are removed
2885 '\"from the global name space
2886 '\"so that an explicit construction environment is required
2887 '\"to call all builders.
2889 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2893 .RI env.Help( text )
2894 This specifies help text to be printed if the
2896 argument is given to
2899 will exit after printing out the help text.
2901 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2903 .RI Ignore( target ", " dependency )
2905 .RI env.Ignore( target ", " dependency )
2906 The specified dependency file(s)
2907 will be ignored when deciding if
2908 the target file(s) need to be rebuilt.
2911 env.Ignore('foo', 'foo.c')
2912 env.Ignore('bar', ['bar1.h', 'bar2.h'])
2915 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2919 .RI env.Import( vars )
2922 to import a list of variables into the current SConscript file. This
2923 will import variables that were exported with
2929 Variables exported by
2932 Multiple variable names can be passed to
2934 as separate arguments or as a list. The variable "*" can be used
2935 to import all variables.
2940 Import("env", "variable")
2941 Import(["env", "variable"])
2945 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2947 .RI Install( dir ", " source )
2949 .RI env.Install( dir ", " source )
2950 Installs one or more files in a destination directory.
2951 The file names remain the same.
2954 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
2957 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2959 .RI InstallAs( target ", " source )
2961 .RI env.InstallAs( target ", " source )
2962 Installs one or more files as specific file names,
2963 allowing changing a file name as part of the
2965 It is an error if the target and source
2966 list different numbers of files.
2969 env.InstallAs(target = '/usr/local/bin/foo',
2970 source = 'foo_debug')
2971 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2972 source = ['libFOO.a', 'libBAR.a'])
2975 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2977 .RI Literal( string )
2979 .RI env.Literal( string )
2982 will be preserved as-is
2983 and not have construction variables expanded.
2985 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2987 .RI Local( targets )
2989 .RI env.Local( targets )
2992 will have copies made in the local tree,
2993 even if an already up-to-date copy
2994 exists in a repository.
2995 Returns a list of the target Node or Nodes.
2997 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2999 .RI env.ParseConfig( command ", [" function ])
3002 to modify the environment as specified by the output of
3006 expects the output of a typical
3010 and parses the returned
3031 option gets added to both the
3037 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3040 A factory function that
3041 returns a Builder object
3042 to be used to fetch source files
3043 from the Perforce source code management system.
3044 The returned Builder
3045 is intended to be passed to the
3050 env.SourceCode('.', env.Perforce())
3053 Perforce uses a number of external
3054 environment variables for its operation.
3055 Consequently, this function adds the
3056 following variables from the user's external environment
3057 to the construction environment's
3070 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3072 .RI Platform( string )
3073 Returns a callable object
3074 that can be used to initialize
3075 a construction environment using the
3076 platform keyword of the Environment() method:
3079 env = Environment(platform = Platform('win32'))
3082 .RI env.Platform( string )
3083 Applies the callable object for the specified platform
3085 to the environment through which the method was called.
3088 env.Platform('posix')
3095 variable from the user's external environment
3096 to the construction environment's
3099 This is so that any executed commands
3100 that use sockets to connect with other systems
3101 (such as fetching source files from
3102 external CVS repository specifications like
3103 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3104 will work on Win32 systems.
3106 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3108 .RI Precious( target ", ...)"
3110 .RI env.Precious( target ", ...)"
3113 as precious so it is not deleted before it is rebuilt. Normally
3115 deletes a target before building it.
3116 Multiple targets can be passed in to a single call to
3119 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3121 .RI env.Prepend( key = val ", [...])"
3122 Appends the specified keyword arguments
3123 to the beginning of construction variables in the environment.
3124 If the Environment does not have
3125 the specified construction variable,
3126 it is simply added to the environment.
3127 If the values of the construction variable
3128 and the keyword argument are the same type,
3129 then the two values will be simply added together.
3130 Otherwise, the construction variable
3131 and the value of the keyword argument
3132 are both coerced to lists,
3133 and the lists are added together.
3134 (See also the Append method, above.)
3137 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3140 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3142 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3143 This appends new path elements to the given path in the
3144 specified external environment
3148 any particular path once (leaving the first one it encounters and
3149 ignoring the rest, to preserve path order),
3150 and to help assure this,
3151 will normalize all paths (using
3154 .BR os.path.normcase ).
3155 This can also handle the
3156 case where the given old path variable is a list instead of a
3157 string, in which case a list will be returned instead of a string.
3161 print 'before:',env['ENV']['INCLUDE']
3162 include_path = '/foo/bar:/foo'
3163 env.PrependENVPath('INCLUDE', include_path)
3164 print 'after:',env['ENV']['INCLUDE']
3168 after: /foo/bar:/foo:/biz
3171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3173 .RI env.AppendUnique( key = val ", [...])"
3174 Appends the specified keyword arguments
3175 to the beginning of construction variables in the environment.
3176 If the Environment does not have
3177 the specified construction variable,
3178 it is simply added to the environment.
3179 If the construction variable being appended to is a list,
3180 then any value(s) that already exist in the
3181 construction variable will
3183 be added again to the list.
3186 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3189 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3192 A factory function that
3193 returns a Builder object
3194 to be used to fetch source files
3196 The returned Builder
3197 is intended to be passed to the
3202 env.SourceCode('.', env.RCS())
3207 will fetch source files
3208 from RCS subdirectories automatically,
3210 as demonstrated in the above example
3211 should only be necessary if
3212 you are fetching from
3215 directory as the source files,
3216 or if you need to explicitly specify RCS
3217 for a specific subdirectory.
3219 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3221 .RI env.Replace( key = val ", [...])"
3222 Replaces construction variables in the Environment
3223 with the specified keyword arguments.
3226 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3229 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3231 .RI Repository( directory )
3233 .RI env.Repository( directory )
3236 is a repository to be searched for files.
3240 and each one adds to the list of
3241 repositories that will be searched.
3245 a repository is a copy of the source tree,
3246 from the top-level directory on down,
3248 both source files and derived files
3249 that can be used to build targets in
3250 the local source tree.
3251 The canonical example would be an
3252 official source tree maintained by an integrator.
3253 If the repository contains derived files,
3254 then the derived files should have been built using
3256 so that the repository contains the necessary
3257 signature information to allow
3259 to figure out when it is appropriate to
3260 use the repository copy of a derived file,
3261 instead of building one locally.
3263 Note that if an up-to-date derived file
3264 already exists in a repository,
3268 make a copy in the local directory tree.
3269 In order to guarantee that a local copy
3275 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3280 what variable(s) to use as the return value(s) of the current SConscript
3281 file. These variables will be returned to the "calling" SConscript file
3282 as the return value(s) of
3284 Multiple variable names should be passed to
3290 Return(["foo", "bar"])
3293 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3295 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3297 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3298 Creates a Scanner object for
3301 See the section "Scanner Objects,"
3302 below, for a complete explanation of the arguments and behavior.
3304 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3307 A factory function that
3308 returns a Builder object
3309 to be used to fetch source files
3311 The returned Builder
3312 is intended to be passed to the
3317 env.SourceCode('.', env.SCCS())
3322 will fetch source files
3323 from SCCS subdirectories automatically,
3325 as demonstrated in the above example
3326 should only be necessary if
3327 you are fetching from
3330 directory as the source files,
3331 or if you need to explicitly specify SCCS
3332 for a specific subdirectory.
3334 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3336 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3338 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3340 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3342 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3346 one or more subsidiary SConscript (configuration) files.
3347 There are two ways to call the
3351 The first way you can call
3353 is to explicitly specify one or more
3355 as the first argument.
3356 A single script may be specified as a string;
3357 multiple scripts must be specified as a list
3358 (either explicitly or as created by
3362 The second way you can call
3364 is to specify a list of (sub)directory names
3371 execute a subsidiary configuration file named
3373 in each of the specified directories.
3374 You may specify a name other than
3376 by supplying an optional
3382 argument provides a list of variable names or a dictionary of
3383 named values to export to the
3385 These variables are locally exported only to the specified
3387 and do not affect the
3388 global pool of variables used by
3392 '\"If multiple dirs are provided,
3393 '\"each script gets a fresh export.
3398 function to import the variables.
3402 argument specifies that all of the target files
3403 (for example, object files and executables)
3404 that would normally be built in the subdirectory in which
3406 resides should actually
3410 is interpreted relative to the directory
3411 of the calling SConscript file.
3415 argument specifies that the
3416 source files from which
3417 the target files should be built
3421 is interpreted relative to the directory
3422 of the calling SConscript file.
3426 will link or copy (depending on the platform)
3427 all the source files into the build directory.
3428 This behavior may be disabled by
3429 setting the optional
3432 (it is set to 1 by default),
3435 will refer directly to
3436 the source files in their source directory
3437 when building target files.
3440 is usually safe, and always more efficient
3443 but it may cause build problems in certain end-cases,
3444 such as compiling from source files that
3445 are generated by the build.)
3447 Any variables returned by
3451 will be returned by the call to
3457 SConscript('subdir/SConscript')
3458 foo = SConscript('sub/SConscript', exports='env')
3459 SConscript('dir/SConscript', exports=['env', 'variable'])
3460 SConscript('src/SConscript', build_dir='build', duplicate=0)
3461 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3462 SConscript(dirs=['sub1', 'sub2'])
3463 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3468 .RI SConscriptChdir( value )
3470 .RI env.SConscriptChdir( value )
3473 changes its working directory
3474 to the directory in which each
3475 subsidiary SConscript file lives.
3476 This behavior may be disabled
3477 by specifying either:
3481 env.SConscriptChdir(0)
3486 will stay in the top-level directory
3487 while reading all SConscript files.
3488 (This may be necessary when building from repositories,
3489 when all the directories in which SConscript files may be found
3490 don't necessarily exist locally.)
3492 You may enable and disable
3493 this ability by calling
3500 SConscript('foo/SConscript') # will not chdir to foo
3501 env.SConscriptChdir(1)
3502 SConscript('bar/SConscript') # will chdir to bar
3505 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3507 .RI SConsignFile([ file , dbm_module ])
3509 .RI env.SConsignFile([ file , dbm_module ])
3512 to store all file signatures
3522 is not an absolute path name,
3523 the file is placed in the same directory as the top-level
3529 argument can be used to specify
3530 which Python database module
3531 The default is to use a custom
3533 module that uses pickled
3534 Python data structures,
3535 and which works on all Python versions from 1.5.2 on.
3540 # Stores signatures in ".sconsign.dbm"
3541 # in the top-level SConstruct directory.
3544 # Stores signatures in the file "etc/scons-signatures"
3545 # relative to the top-level SConstruct directory.
3546 SConsignFile("etc/scons-signatures")
3548 # Stores signatures in the specified absolute file name.
3549 SConsignFile("/home/me/SCons/signatures")
3552 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3554 .RI SetOption( name ", " value )
3556 .RI env.SetOption( name ", " value )
3557 This function provides a way to set a select subset of the scons command
3558 line options from a SConscript file. The options supported are:
3560 which corresponds to -c, --clean, and --remove;
3563 corresponds to --duplicate;
3565 which corresponds to --implicit-cache;
3567 which corresponds to --max-drift;
3569 which corresponds to -j and --jobs.
3570 See the documentation for the
3571 corresponding command line object for information about each specific
3575 SetOption('max_drift', 1)
3578 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3580 .RI SideEffect( side_effect ", " target )
3582 .RI env.SideEffect( side_effect ", " target )
3585 as a side effect of building
3591 can be a list, a file name, or a node.
3592 A side effect is a target that is created
3593 as a side effect of building other targets.
3594 For example, a Windows PDB
3595 file is created as a side effect of building the .obj
3596 files for a static library.
3597 If a target is a side effect of multiple build commands,
3599 will ensure that only one set of commands
3600 is executed at a time.
3601 Consequently, you only need to use this method
3602 for side-effect targets that are built as a result of
3603 multiple build commands.
3605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3607 .RI SourceCode( entries ", " builder )
3609 .RI env.SourceCode( entries ", " builder )
3610 Arrange for non-existent source files to
3611 be fetched from a source code management system
3616 may be a Node, string or list of both,
3617 and may represent either individual
3618 source files or directories in which
3619 source files can be found.
3621 For any non-existent source files,
3623 will search up the directory tree
3633 will not use a builder to fetch
3634 source files for the specified
3638 builder has been specified
3639 for a directory higher up the tree.
3643 fetch files from SCCS or RCS subdirectories
3644 without explicit configuration.
3645 This takes some extra processing time
3646 to search for the necessary
3647 source code management files on disk.
3648 You can avoid these extra searches
3649 and speed up your build a little
3650 by disabling these searches as follows:
3653 env.SourceCode('.', None)
3657 Note that if the specified
3659 is one you create by hand,
3660 it must have an associated
3661 construction environment to use
3662 when fetching a source file.
3665 provides a set of canned factory
3666 functions that return appropriate
3667 Builders for various popular
3668 source code management systems.
3669 Canonical examples of invocation include:
3672 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3673 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3674 env.SourceCode('/', env.RCS())
3675 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3676 env.SourceCode('no_source.c', None)
3678 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3680 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3682 '\".RI Subversion( repository ", " module )
3683 '\"A factory function that
3684 '\"returns a Builder object
3685 '\"to be used to fetch source files
3686 '\"from the specified Subversion
3688 '\"The returned Builder
3689 '\"is intended to be passed to the
3693 '\"The optional specified
3695 '\"will be added to the beginning
3696 '\"of all repository path names;
3697 '\"this can be used, in essence,
3698 '\"to strip initial directory names
3699 '\"from the repository path names,
3700 '\"so that you only have to
3701 '\"replicate part of the repository
3702 '\"directory hierarchy in your
3703 '\"local build directory:
3706 '\"# Will fetch foo/bar/src.c
3707 '\"# from /usr/local/Subversion/foo/bar/src.c.
3708 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3710 '\"# Will fetch bar/src.c
3711 '\"# from /usr/local/Subversion/foo/bar/src.c.
3712 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3714 '\"# Will fetch src.c
3715 '\"# from /usr/local/Subversion/foo/bar/src.c.
3716 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3721 .RI SourceSignatures( type )
3723 .RI env.SourceSignatures( type )
3724 This function tells SCons what type of signature to use for source files:
3728 If the environment method is used,
3729 the specified type of source signature
3730 is only used when deciding whether targets
3731 built with that environment are up-to-date or must be rebuilt.
3732 If the global function is used,
3733 the specified type of source signature becomes the default
3734 used for all decisions
3735 about whether targets are up-to-date.
3737 "MD5" means the signature of a source file
3738 is the MD5 checksum of its contents.
3739 "timestamp" means the signature of a source file
3740 is its timestamp (modification time).
3741 There is no different between the two behaviors
3745 "MD5" signatures take longer to compute,
3746 but are more accurate than "timestamp" signatures.
3747 The default is "MD5".
3749 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3753 .RI env.Split( arg )
3754 Returns a list of file names or other objects.
3756 it will be split on strings of white-space characters
3758 making it easier to write long lists of file names.
3759 If arg is already a list,
3760 the list will be returned untouched.
3761 If arg is any other type of object,
3762 it will be returned as a list
3763 containing just the object.
3766 files = Split("f1.c f2.c f3.c")
3767 files = env.Split("f4.c f5.c f6.c")
3775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3777 .RI TargetSignatures( type )
3779 .RI env.TargetSignatures( type )
3780 This function tells SCons what type of signatures to use
3785 If the environment method is used,
3786 the specified type of signature is only used
3787 for targets built with that environment.
3788 If the global function is used,
3789 the specified type of signature becomes the default
3790 used for all target files that
3791 don't have an explicit target signature type
3792 specified for their environments.
3794 "build" means the signature of a target file
3795 is made by concatenating all of the
3796 signatures of all its source files.
3797 "content" means the signature of a target
3798 file is an MD5 checksum of its contents.
3799 "build" signatures are usually faster to compute,
3800 but "content" signatures can prevent unnecessary rebuilds
3801 when a target file is rebuilt to the exact same contents
3802 as the previous build.
3803 The default is "build".
3805 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3807 .RI Tool( string, toolpath=[] )
3808 Returns a callable object
3809 that can be used to initialize
3810 a construction environment using the
3811 tools keyword of the Environment() method.
3812 The object may be called with a construction
3813 environment as an argument,
3814 in which case the object will be
3815 add the necessary variables
3816 to the construction environment
3817 and the name of the tool will be added to the
3819 construction variable.
3822 env = Environment(tools = [ Tool('msvc') ])
3826 t(env) # adds 'msvc' to the TOOLS variable
3827 u = Tool('opengl', toolpath = ['tools'])
3828 u(env) # adds 'opengl' to the TOOLS variable
3831 .RI env.Tool( string [, toolpath] )
3832 Applies the callable object for the specified tool
3834 to the environment through which the method was called.
3838 env.Tool('opengl', toolpath = ['build/tools'])
3841 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3845 .RI env.Value( value )
3846 Returns a Node object representing the specified Python value. Value
3847 nodes can be used as dependencies of targets. If the result of
3850 changes between SCons runs, any targets depending on
3852 will be rebuilt. When using timestamp source signatures, Value nodes'
3853 timestamps are equal to the system time when the node is created.
3856 def create(target, source, env):
3857 f = open(str(target[0]), 'wb')
3858 f.write('prefix=' + source[0].get_contents())
3860 prefix = ARGUMENTS.get('prefix', '/usr/local')
3862 env['BUILDERS']['Config'] = Builder(action = create)
3863 env.Config(target = 'package-config', source = Value(prefix))
3866 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3868 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
3870 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
3872 Searches for the specified executable
3874 returning the full path name to the program
3876 and returning None if not.
3877 Searches the specified
3879 the value of the calling environment's PATH
3880 (env['ENV']['PATH']),
3881 or the user's current external PATH
3882 (os.environ['PATH'])
3884 On Win32 systems, searches for executable
3885 programs with any of the file extensions
3886 listed in the specified
3888 the calling environment's PATHEXT
3889 (env['ENV']['PATHEXT'])
3890 or the user's current PATHEXT
3891 (os.environ['PATHEXT'])
3899 .SS SConscript Variables
3900 In addition to the global functions and methods,
3902 supports a number of Python variables
3903 that can be used in SConscript files
3904 to affect how you want the build to be performed.
3906 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3911 arguments specified on the command line.
3912 Each element in the list is a tuple
3914 .RI ( keyword , value )
3920 elements of the tuple
3922 subscripting for element
3926 of the tuple, respectively.
3929 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
3930 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
3931 third_tuple = ARGLIST[2]
3932 print "third keyword, value =", third_tuple[0], third_tuple[1]
3933 for key, value in ARGLIST:
3934 # process key and value
3937 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3940 A dictionary of all the
3942 arguments specified on the command line.
3943 The dictionary is not in order,
3944 and if a given keyword has
3945 more than one value assigned to it
3946 on the command line,
3947 the last (right-most) value is
3953 if ARGUMENTS.get('debug', 0):
3954 env = Environment(CCFLAGS = '-g')
3959 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3962 A list of the targets which
3964 will actually try to build,
3965 regardless of whether they were specified on
3966 the command line or via the
3969 The elements of this list may be strings
3971 nodes, so you should run the list through the Python
3973 function to make sure any Node path names
3974 are converted to strings.
3976 Because this list may be taken from the
3977 list of targets specified using the
3980 the contents of the list may change
3981 on each successive call to
3986 for additional information.
3989 if 'foo' in BUILD_TARGETS:
3990 print "Don't forget to test the `foo' program!"
3991 if 'special/program' in BUILD_TARGETS:
3992 SConscript('special')
3997 list only contains targets expected listed
3998 on the command line or via calls to the
4003 contain all dependent targets that will be built as
4004 a result of making the sure the explicitly-specified
4005 targets are up to date.
4007 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4009 COMMAND_LINE_TARGETS
4010 A list of the targets explicitly specified on
4012 If there are no targets specified on the command line,
4014 This can be used, for example,
4015 to take specific actions only
4016 when a certain target or targets
4017 is explicitly being built:
4020 if 'foo' in COMMAND_LINE_TARGETS:
4021 print "Don't forget to test the `foo' program!"
4022 if 'special/program' in COMMAND_LINE_TARGETS:
4023 SConscript('special')
4026 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4029 A list of the target
4031 that have been specified using the
4034 The elements of the list are nodes,
4035 so you need to run them through the Python
4037 function to get at the path name for each Node.
4040 print str(DEFAULT_TARGETS[0])
4041 if 'foo' in map(str, DEFAULT_TARGETS):
4042 print "Don't forget to test the `foo' program!"
4047 list change on on each successive call to the
4052 print map(str, DEFAULT_TARGETS) # originally []
4054 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4056 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4058 print map(str, DEFAULT_TARGETS) # back to []
4061 Consequently, be sure to use
4063 only after you've made all of your
4066 or else simply be careful of the order
4067 of these statements in your SConscript files
4068 so that you don't look for a specific
4069 default target before it's actually been added to the list.
4071 .SS Construction Variables
4072 .\" XXX From Gary Ruben, 23 April 2002:
4073 .\" I think it would be good to have an example with each construction
4074 .\" variable description in the documentation.
4076 .\" CC The C compiler
4077 .\" Example: env["CC"] = "c68x"
4078 .\" Default: env["CC"] = "cc"
4080 .\" CCCOM The command line ...
4082 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4083 .\" env["CC"] = "c68x"
4084 .\" env["CFLAGS"] = "-ps -qq -mr"
4085 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4087 .\" (I dunno what this is ;-)
4088 A construction environment has an associated dictionary of
4089 .I construction variables
4090 that are used by built-in or user-supplied build rules.
4091 Construction variables must follow the same rules for
4093 the initial character must be an underscore or letter,
4094 followed by any number of underscores, letters, or digits.
4096 A number of useful construction variables are automatically defined by
4097 scons for each supported platform, and additional construction variables
4098 can be defined by the user. The following is a list of the automatically
4099 defined construction variables:
4102 The static library archiver.
4105 The command line used to generate a static library from object files.
4108 General options passed to the static library archiver.
4114 The command line used to generate an object file
4115 from an assembly-language source file.
4118 General options passed to the assembler.
4121 The command line used to assemble an assembly-language
4122 source file into an object file
4123 after first running the file through the C preprocessor.
4124 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4125 are included on this command line.
4128 The bibliography generator for the TeX formatter and typesetter and the
4129 LaTeX structured formatter and typesetter.
4132 The command line used to call the bibliography generator for the
4133 TeX formatter and typesetter and the LaTeX structured formatter and
4137 General options passed to the bibliography generator for the TeX formatter
4138 and typesetter and the LaTeX structured formatter and typesetter.
4141 The BitKeeper executable.
4144 The command line for
4145 fetching source files using BitKEeper.
4148 The command ($BITKEEPER) and subcommand
4149 for fetching source files using BitKeeper.
4151 .IP BITKEEPERGETFLAGS
4152 Options that are passed to the BitKeeper
4157 A dictionary mapping the names of the builders
4158 available through this environment
4159 to underlying Builder objects.
4161 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4162 are available by default.
4163 If you initialize this variable when an
4164 Environment is created:
4167 env = Environment(BUILDERS = {'NewBuilder' : foo})
4170 the default Builders will no longer be available.
4171 To use a new Builder object in addition to the default Builders,
4172 add your new Builder object like this:
4176 env.Append(BUILDERS = {'NewBuilder' : foo})
4183 env['BUILDERS]['NewBuilder'] = foo
4190 The command line used to compile a C source file to a (static) object file.
4191 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4192 are included on this command line.
4195 General options that are passed to the C compiler.
4198 The suffix for C source files.
4199 This is used by the internal CFile builder
4200 when generating C files from Lex (.l) or YACC (.y) input files.
4201 The default suffix, of course, is
4204 On case-insensitive systems (like Win32),
4211 The version number of the C compiler.
4212 This may or may not be set,
4213 depending on the specific C compiler being used.
4216 A function used to produce variables like $_CPPINCFLAGS. It takes
4218 arguments: a prefix to concatenate onto each element, a list of
4219 elements, a suffix to concatenate onto each element, an environment
4220 for variable interpolation, and an optional function that will be
4221 called to transform the list before concatenation.
4224 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4228 A platform independent specification of C preprocessor definitions.
4229 The definitions will be added to command lines
4230 through the automatically-generated
4231 $_CPPDEFFLAGS construction variable (see below),
4232 which is constructed according to
4233 the type of value of $CPPDEFINES:
4236 If $CPPDEFINES is a string,
4238 $CPPDEFPREFIX and $CPPDEFSUFFIX
4239 construction variables
4240 will be added to the beginning and end.
4243 # Will add -Dxyz to POSIX compiler command lines,
4244 # and /Dxyz to Microsoft Visual C++ command lines.
4245 env = Environment(CPPDEFINES='xyz')
4249 If $CPPDEFINES is a list,
4251 $CPPDEFPREFIX and $CPPDEFSUFFIX
4252 construction variables
4253 will be appended to the beginning and end
4254 of each element in the list.
4255 If any element is a list or tuple,
4256 then the first item is the name being
4257 defined and the second item is its value:
4260 # Will add -DB=2 -DA to POSIX compiler command lines,
4261 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4262 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4266 If $CPPDEFINES is a dictionary,
4268 $CPPDEFPREFIX and $CPPDEFSUFFIX
4269 construction variables
4270 will be appended to the beginning and end
4271 of each item from the dictionary.
4272 The key of each dictionary item
4273 is a name being defined
4274 to the dictionary item's corresponding value;
4277 then the name is defined without an explicit value.
4278 Note that the resulting flags are sorted by keyword
4279 to ensure that the order of the options on the
4280 command line is consistent each time
4285 # Will add -DA -DB=2 to POSIX compiler command lines,
4286 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4287 env = Environment(CPPDEFINES={'B':2, 'A':None})
4291 An automatically-generated construction variable
4292 containing the C preprocessor command-line options
4294 The value of $_CPPDEFFLAGS is created
4295 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4296 to the beginning and end
4297 of each directory in $CPPDEFINES.
4300 The prefix used to specify preprocessor definitions
4301 on the C compiler command line.
4302 This will be appended to the beginning of each definition
4303 in the $CPPDEFINES construction variable
4304 when the $_CPPDEFFLAGS variable is automatically generated.
4307 The suffix used to specify preprocessor definitions
4308 on the C compiler command line.
4309 This will be appended to the end of each definition
4310 in the $CPPDEFINES construction variable
4311 when the $_CPPDEFFLAGS variable is automatically generated.
4314 User-specified C preprocessor options.
4315 These will be included in any command that uses the C preprocessor,
4316 including not just compilation of C and C++ source files
4317 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4318 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4319 $F77PPCOM and $SHF77PPCOM command lines
4320 used to compile a Fortran source file,
4321 and the $ASPPCOM command line
4322 used to assemble an assembly language source file,
4323 after first running each file through the C preprocessor.
4324 Note that this variable does
4328 (or similar) include search path options
4329 that scons generates automatically from $CPPPATH.
4333 for the variable that expands to those options.
4336 An automatically-generated construction variable
4337 containing the C preprocessor command-line options
4338 for specifying directories to be searched for include files.
4339 The value of $_CPPINCFLAGS is created
4340 by appending $INCPREFIX and $INCSUFFIX
4341 to the beginning and end
4342 of each directory in $CPPPATH.
4345 The list of directories that the C preprocessor will search for include
4346 directories. The C/C++ implicit dependency scanner will search these
4347 directories for include files. Don't explicitly put include directory
4348 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4349 and the directories will not be searched by the dependency scanner. Note:
4350 directory names in CPPPATH will be looked-up relative to the SConscript
4351 directory when they are used in a command. To force
4353 to look-up a directory relative to the root of the source tree use #:
4356 env = Environment(CPPPATH='#/include')
4360 The directory look-up can also be forced using the
4365 include = Dir('include')
4366 env = Environment(CPPPATH=include)
4370 The directory list will be added to command lines
4371 through the automatically-generated
4373 construction variable,
4374 which is constructed by
4375 appending the values of the
4376 $INCPREFIX and $INCSUFFIX
4377 construction variables
4378 to the beginning and end
4379 of each directory in $CPPPATH.
4380 Any command lines you define that need
4381 the CPPPATH directory list should
4382 include $_CPPINCFLAGS:
4385 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4389 The list of suffixes of files that will be scanned
4390 for C preprocessor implicit dependencies
4392 The default list is:
4395 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4396 ".h", ".H", ".hxx", ".hpp", ".hh",
4397 ".F", ".fpp", ".FPP",
4398 ".S", ".spp", ".SPP"]
4405 Options that are passed to the CVS checkout subcommand.
4408 The command line used to
4409 fetch source files from a CVS repository.
4412 General options that are passed to CVS.
4413 By default, this is set to
4415 to specify from where the files must be fetched.
4418 The path to the CVS repository.
4419 This is referenced in the default
4426 The suffix for C++ source files.
4427 This is used by the internal CXXFile builder
4428 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4429 The default suffix is
4431 SCons also treats files with the suffixes
4438 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4445 The command line used to compile a C++ source file to an object file.
4446 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4447 are included on this command line.
4450 General options that are passed to the C++ compiler.
4453 The version number of the C++ compiler.
4454 This may or may not be set,
4455 depending on the specific C++ compiler being used.
4458 A function that converts a file name into a Dir instance relative to the
4462 The list of suffixes of files that will be scanned
4463 for imported D package files.
4464 The default list is:
4471 The TeX DVI file to PDF file converter.
4474 General options passed to the TeX DVI file to PDF file converter.
4477 The command line used to convert TeX DVI files into a PDF file.
4480 The TeX DVI file to PostScript converter.
4483 General options passed to the TeX DVI file to PostScript converter.
4486 A dictionary of environment variables
4487 to use when invoking commands. When ENV is used in a command all list
4488 values will be joined using the path separator and any other non-string
4489 values will simply be coerced to a string.
4490 Note that, by default,
4494 propagate the environment in force when you
4497 to the commands used to build target files.
4498 This is so that builds will be guaranteed
4499 repeatable regardless of the environment
4500 variables set at the time
4504 If you want to propagate your
4505 environment variables
4506 to the commands executed
4507 to build target files,
4508 you must do so explicitly:
4512 env = Environment(ENV = os.environ)
4516 Note that you can choose only to propagate
4517 certain environment variables.
4521 environment variable,
4524 uses the same utilities
4525 as the invoking shell (or other process):
4530 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4534 A function that will be called to escape shell special characters in
4535 command lines. The function should take one argument: the command line
4536 string to escape; and should return the escaped command line.
4539 The Fortran 77 compiler.
4540 You should normally set the $FORTRAN variable,
4541 which specifies the default Fortran compiler
4542 for all Fortran versions.
4543 You only need to set $F77 if you need to use a specific compiler
4544 or compiler version for Fortran 77 files.
4547 The command line used to compile a Fortran 77 source file to an object file.
4548 You only need to set $F77COM if you need to use a specific
4549 command line for Fortran 77 files.
4550 You should normally set the $FORTRANCOM variable,
4551 which specifies the default command line
4552 for all Fortran versions.
4555 General user-specified options that are passed to the Fortran 77 compiler.
4556 Note that this variable does
4560 (or similar) include search path options
4561 that scons generates automatically from $F77PATH.
4565 for the variable that expands to those options.
4566 You only need to set $F77FLAGS if you need to define specific
4567 user options for Fortran 77 files.
4568 You should normally set the $FORTRANFLAGS variable,
4569 which specifies the user-specified options
4570 passed to the default Fortran compiler
4571 for all Fortran versions.
4574 An automatically-generated construction variable
4575 containing the Fortran 77 compiler command-line options
4576 for specifying directories to be searched for include files.
4577 The value of $_F77INCFLAGS is created
4578 by appending $INCPREFIX and $INCSUFFIX
4579 to the beginning and end
4580 of each directory in $F77PATH.
4583 The list of directories that the Fortran 77 compiler will search for include
4584 directories. The implicit dependency scanner will search these
4585 directories for include files. Don't explicitly put include directory
4586 arguments in $F77FLAGS because the result will be non-portable
4587 and the directories will not be searched by the dependency scanner. Note:
4588 directory names in $F77PATH will be looked-up relative to the SConscript
4589 directory when they are used in a command. To force
4591 to look-up a directory relative to the root of the source tree use #:
4592 You only need to set $F77PATH if you need to define a specific
4593 include path for Fortran 77 files.
4594 You should normally set the $FORTRANPATH variable,
4595 which specifies the include path
4596 for the default Fortran compiler
4597 for all Fortran versions.
4600 env = Environment(F77PATH='#/include')
4604 The directory look-up can also be forced using the
4609 include = Dir('include')
4610 env = Environment(F77PATH=include)
4614 The directory list will be added to command lines
4615 through the automatically-generated
4617 construction variable,
4618 which is constructed by
4619 appending the values of the
4620 $INCPREFIX and $INCSUFFIX
4621 construction variables
4622 to the beginning and end
4623 of each directory in $F77PATH.
4624 Any command lines you define that need
4625 the F77PATH directory list should
4626 include $_F77INCFLAGS:
4629 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4633 The command line used to compile a Fortran 77 source file to an object file
4634 after first running the file through the C preprocessor.
4635 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4636 are included on this command line.
4637 You only need to set $F77PPCOM if you need to use a specific
4638 C-preprocessor command line for Fortran 77 files.
4639 You should normally set the $FORTRANPPCOM variable,
4640 which specifies the default C-preprocessor command line
4641 for all Fortran versions.
4644 The Fortran 90 compiler.
4645 You should normally set the $FORTRAN variable,
4646 which specifies the default Fortran compiler
4647 for all Fortran versions.
4648 You only need to set $F90 if you need to use a specific compiler
4649 or compiler version for Fortran 90 files.
4652 The command line used to compile a Fortran 90 source file to an object file.
4653 You only need to set $F90COM if you need to use a specific
4654 command line for Fortran 90 files.
4655 You should normally set the $FORTRANCOM variable,
4656 which specifies the default command line
4657 for all Fortran versions.
4660 General user-specified options that are passed to the Fortran 90 compiler.
4661 Note that this variable does
4665 (or similar) include search path options
4666 that scons generates automatically from $F90PATH.
4670 for the variable that expands to those options.
4671 You only need to set $F90FLAGS if you need to define specific
4672 user options for Fortran 90 files.
4673 You should normally set the $FORTRANFLAGS variable,
4674 which specifies the user-specified options
4675 passed to the default Fortran compiler
4676 for all Fortran versions.
4679 An automatically-generated construction variable
4680 containing the Fortran 90 compiler command-line options
4681 for specifying directories to be searched for include files.
4682 The value of $_F90INCFLAGS is created
4683 by appending $INCPREFIX and $INCSUFFIX
4684 to the beginning and end
4685 of each directory in $F90PATH.
4688 The list of directories that the Fortran 90 compiler will search for include
4689 directories. The implicit dependency scanner will search these
4690 directories for include files. Don't explicitly put include directory
4691 arguments in $F90FLAGS because the result will be non-portable
4692 and the directories will not be searched by the dependency scanner. Note:
4693 directory names in $F90PATH will be looked-up relative to the SConscript
4694 directory when they are used in a command. To force
4696 to look-up a directory relative to the root of the source tree use #:
4697 You only need to set $F90PATH if you need to define a specific
4698 include path for Fortran 90 files.
4699 You should normally set the $FORTRANPATH variable,
4700 which specifies the include path
4701 for the default Fortran compiler
4702 for all Fortran versions.
4705 env = Environment(F90PATH='#/include')
4709 The directory look-up can also be forced using the
4714 include = Dir('include')
4715 env = Environment(F90PATH=include)
4719 The directory list will be added to command lines
4720 through the automatically-generated
4722 construction variable,
4723 which is constructed by
4724 appending the values of the
4725 $INCPREFIX and $INCSUFFIX
4726 construction variables
4727 to the beginning and end
4728 of each directory in $F90PATH.
4729 Any command lines you define that need
4730 the F90PATH directory list should
4731 include $_F90INCFLAGS:
4734 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
4738 The command line used to compile a Fortran 90 source file to an object file
4739 after first running the file through the C preprocessor.
4740 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
4741 are included on this command line.
4742 You only need to set $F90PPCOM if you need to use a specific
4743 C-preprocessor command line for Fortran 90 files.
4744 You should normally set the $FORTRANPPCOM variable,
4745 which specifies the default C-preprocessor command line
4746 for all Fortran versions.
4749 The Fortran 95 compiler.
4750 You should normally set the $FORTRAN variable,
4751 which specifies the default Fortran compiler
4752 for all Fortran versions.
4753 You only need to set $F95 if you need to use a specific compiler
4754 or compiler version for Fortran 95 files.
4757 The command line used to compile a Fortran 95 source file to an object file.
4758 You only need to set $F95COM if you need to use a specific
4759 command line for Fortran 95 files.
4760 You should normally set the $FORTRANCOM variable,
4761 which specifies the default command line
4762 for all Fortran versions.
4765 General user-specified options that are passed to the Fortran 95 compiler.
4766 Note that this variable does
4770 (or similar) include search path options
4771 that scons generates automatically from $F95PATH.
4775 for the variable that expands to those options.
4776 You only need to set $F95FLAGS if you need to define specific
4777 user options for Fortran 95 files.
4778 You should normally set the $FORTRANFLAGS variable,
4779 which specifies the user-specified options
4780 passed to the default Fortran compiler
4781 for all Fortran versions.
4784 An automatically-generated construction variable
4785 containing the Fortran 95 compiler command-line options
4786 for specifying directories to be searched for include files.
4787 The value of $_F95INCFLAGS is created
4788 by appending $INCPREFIX and $INCSUFFIX
4789 to the beginning and end
4790 of each directory in $F95PATH.
4793 The list of directories that the Fortran 95 compiler will search for include
4794 directories. The implicit dependency scanner will search these
4795 directories for include files. Don't explicitly put include directory
4796 arguments in $F95FLAGS because the result will be non-portable
4797 and the directories will not be searched by the dependency scanner. Note:
4798 directory names in $F95PATH will be looked-up relative to the SConscript
4799 directory when they are used in a command. To force
4801 to look-up a directory relative to the root of the source tree use #:
4802 You only need to set $F95PATH if you need to define a specific
4803 include path for Fortran 95 files.
4804 You should normally set the $FORTRANPATH variable,
4805 which specifies the include path
4806 for the default Fortran compiler
4807 for all Fortran versions.
4810 env = Environment(F95PATH='#/include')
4814 The directory look-up can also be forced using the
4819 include = Dir('include')
4820 env = Environment(F95PATH=include)
4824 The directory list will be added to command lines
4825 through the automatically-generated
4827 construction variable,
4828 which is constructed by
4829 appending the values of the
4830 $INCPREFIX and $INCSUFFIX
4831 construction variables
4832 to the beginning and end
4833 of each directory in $F95PATH.
4834 Any command lines you define that need
4835 the F95PATH directory list should
4836 include $_F95INCFLAGS:
4839 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
4843 The command line used to compile a Fortran 95 source file to an object file
4844 after first running the file through the C preprocessor.
4845 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
4846 are included on this command line.
4847 You only need to set $F95PPCOM if you need to use a specific
4848 C-preprocessor command line for Fortran 95 files.
4849 You should normally set the $FORTRANPPCOM variable,
4850 which specifies the default C-preprocessor command line
4851 for all Fortran versions.
4854 The default Fortran compiler
4855 for all versions of Fortran.
4858 The command line used to compile a Fortran source file to an object file.
4859 By default, any options specified
4860 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
4861 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
4862 are included on this command line.
4865 General user-specified options that are passed to the Fortran compiler.
4866 Note that this variable does
4870 (or similar) include or module search path options
4871 that scons generates automatically from $FORTRANPATH.
4873 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
4875 for the variables that expand those options.
4877 .IP _FORTRANINCFLAGS
4878 An automatically-generated construction variable
4879 containing the Fortran compiler command-line options
4880 for specifying directories to be searched for include
4881 files and module files.
4882 The value of $_FORTRANINCFLAGS is created
4883 by prepending/appending $INCPREFIX and $INCSUFFIX
4884 to the beginning and end
4885 of each directory in $FORTRANPATH.
4888 Directory location where the Fortran compiler should place
4889 any module files it generates. This variable is empty, by default. Some
4890 Fortran compilers will internally append this directory in the search path
4891 for module files, as well
4893 .IP FORTRANMODDIRPREFIX
4894 The prefix used to specify a module directory on the Fortran compiler command
4896 This will be appended to the beginning of the directory
4897 in the $FORTRANMODDIR construction variables
4898 when the $_FORTRANMODFLAG variables is automatically generated.
4900 .IP FORTRANMODDIRSUFFIX
4901 The suffix used to specify a module directory on the Fortran compiler command
4903 This will be appended to the beginning of the directory
4904 in the $FORTRANMODDIR construction variables
4905 when the $_FORTRANMODFLAG variables is automatically generated.
4908 An automatically-generated construction variable
4909 containing the Fortran compiler command-line option
4910 for specifying the directory location where the Fortran
4911 compiler should place any module files that happen to get
4912 generated during compilation.
4913 The value of $_FORTRANMODFLAG is created
4914 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
4915 to the beginning and end of the directory in $FORTRANMODDIR.
4917 .IP FORTRANMODPREFIX
4918 The module file prefix used by the Fortran compiler. SCons assumes that
4919 the Fortran compiler follows the quasi-standard naming convention for
4921 .I <module_name>.mod.
4922 As a result, this variable is left empty, by default. For situations in
4923 which the compiler does not necessarily follow the normal convention,
4924 the user may use this variable. Its value will be appended to every
4925 module file name as scons attempts to resolve dependencies.
4927 .IP FORTRANMODSUFFIX
4928 The module file suffix used by the Fortran compiler. SCons assumes that
4929 the Fortran compiler follows the quasi-standard naming convention for
4931 .I <module_name>.mod.
4932 As a result, this variable is set to ".mod", by default. For situations
4933 in which the compiler does not necessarily follow the normal convention,
4934 the user may use this variable. Its value will be appended to every
4935 module file name as scons attempts to resolve dependencies.
4938 The list of directories that the Fortran compiler will search for
4939 include files and (for some compilers) module files. The Fortran implicit
4940 dependency scanner will search these directories for include files (but
4941 not module files since they are autogenerated and, as such, may not
4942 actually exist at the time the scan takes place). Don't explicitly put
4943 include directory arguments in FORTRANFLAGS because the result will be
4944 non-portable and the directories will not be searched by the dependency
4945 scanner. Note: directory names in FORTRANPATH will be looked-up relative
4946 to the SConscript directory when they are used in a command. To force
4948 to look-up a directory relative to the root of the source tree use #:
4951 env = Environment(FORTRANPATH='#/include')
4955 The directory look-up can also be forced using the
4960 include = Dir('include')
4961 env = Environment(FORTRANPATH=include)
4965 The directory list will be added to command lines
4966 through the automatically-generated
4968 construction variable,
4969 which is constructed by
4970 appending the values of the
4971 $INCPREFIX and $INCSUFFIX
4972 construction variables
4973 to the beginning and end
4974 of each directory in $FORTRANPATH.
4975 Any command lines you define that need
4976 the FORTRANPATH directory list should
4977 include $_FORTRANINCFLAGS:
4980 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
4984 The command line used to compile a Fortran source file to an object file
4985 after first running the file through the C preprocessor.
4986 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
4987 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
4988 construction variables are included on this command line.
4991 The list of suffixes of files that will be scanned
4992 for Fortran implicit dependencies
4993 (INCLUDE lines & USE statements).
4994 The default list is:
4997 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
4998 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5002 A function that converts a file name into a File instance relative to the
5006 The Ghostscript program used to convert PostScript to PDF files.
5009 General options passed to the Ghostscript program
5010 when converting PostScript to PDF files.
5013 The Ghostscript command line used to convert PostScript to PDF files.
5016 The list of suffixes of files that will be scanned
5017 for IDL implicit dependencies
5018 (#include or import lines).
5019 The default list is:
5026 The prefix used to specify an include directory on the C compiler command
5028 This will be appended to the beginning of each directory
5029 in the $CPPPATH and $FORTRANPATH construction variables
5030 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5031 variables are automatically generated.
5034 The suffix used to specify an include directory on the C compiler command
5036 This will be appended to the end of each directory
5037 in the $CPPPATH and $FORTRANPATH construction variables
5038 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5039 variables are automatically generated.
5042 A function to be called to install a file into a
5043 destination file name.
5044 The default function copies the file into the destination
5045 (and sets the destination file's mode and permission bits
5046 to match the source file's).
5047 The function takes the following arguments:
5050 def install(dest, source, env):
5054 is the path name of the destination file.
5056 is the path name of the source file.
5058 is the construction environment
5059 (a dictionary of construction values)
5060 in force for this file installation.
5063 The Java archive tool.
5066 The directory to which the Java archive tool should change
5072 The command line used to call the Java archive tool.
5075 General options passed to the Java archive tool.
5076 By default this is set to
5078 to create the necessary
5083 The suffix for Java archives:
5091 The command line used to compile a directory tree containing
5092 Java source files to
5093 corresponding Java class files.
5094 Any options specified in the $JAVACFLAGS construction variable
5095 are included on this command line.
5098 General options that are passed to the Java compiler.
5101 The directory in which Java class files may be found.
5102 This is stripped from the beginning of any Java .class
5103 file names supplied to the
5108 The suffix for Java class files;
5113 The Java generator for C header and stub files.
5116 The command line used to generate C header and stub files
5118 Any options specified in the $JAVAHFLAGS construction variable
5119 are included on this command line.
5122 General options passed to the C header and stub file generator
5126 The suffix for Java files;
5131 The LaTeX structured formatter and typesetter.
5134 The command line used to call the LaTeX structured formatter and typesetter.
5137 General options passed to the LaTeX structured formatter and typesetter.
5140 The lexical analyzer generator.
5143 General options passed to the lexical analyzer generator.
5146 The command line used to call the lexical analyzer generator
5147 to generate a source file.
5150 An automatically-generated construction variable
5151 containing the linker command-line options
5152 for specifying directories to be searched for library.
5153 The value of $_LIBDIRFLAGS is created
5154 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5155 to the beginning and end
5156 of each directory in $LIBPATH.
5159 The prefix used to specify a library directory on the linker command line.
5160 This will be appended to the beginning of each directory
5161 in the $LIBPATH construction variable
5162 when the $_LIBDIRFLAGS variable is automatically generated.
5165 The suffix used to specify a library directory on the linker command line.
5166 This will be appended to the end of each directory
5167 in the $LIBPATH construction variable
5168 when the $_LIBDIRFLAGS variable is automatically generated.
5171 An automatically-generated construction variable
5172 containing the linker command-line options
5173 for specifying libraries to be linked with the resulting target.
5174 The value of $_LIBFLAGS is created
5175 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5176 to the beginning and end
5177 of each directory in $LIBS.
5180 The prefix used to specify a library to link on the linker command line.
5181 This will be appended to the beginning of each library
5182 in the $LIBS construction variable
5183 when the $_LIBFLAGS variable is automatically generated.
5186 The suffix used to specify a library to link on the linker command line.
5187 This will be appended to the end of each library
5188 in the $LIBS construction variable
5189 when the $_LIBFLAGS variable is automatically generated.
5192 The list of directories that will be searched for libraries.
5193 The implicit dependency scanner will search these
5194 directories for include files. Don't explicitly put include directory
5195 arguments in $LINKFLAGS or $SHLINKFLAGS
5196 because the result will be non-portable
5197 and the directories will not be searched by the dependency scanner. Note:
5198 directory names in LIBPATH will be looked-up relative to the SConscript
5199 directory when they are used in a command. To force
5201 to look-up a directory relative to the root of the source tree use #:
5204 env = Environment(LIBPATH='#/libs')
5208 The directory look-up can also be forced using the
5214 env = Environment(LIBPATH=libs)
5218 The directory list will be added to command lines
5219 through the automatically-generated
5221 construction variable,
5222 which is constructed by
5223 appending the values of the
5224 $LIBDIRPREFIX and $LIBDIRSUFFIX
5225 construction variables
5226 to the beginning and end
5227 of each directory in $LIBPATH.
5228 Any command lines you define that need
5229 the LIBPATH directory list should
5230 include $_LIBDIRFLAGS:
5233 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5237 The prefix used for (static) library file names.
5238 A default value is set for each platform
5239 (posix, win32, os2, etc.),
5240 but the value is overridden by individual tools
5241 (ar, mslib, sgiar, sunar, tlib, etc.)
5242 to reflect the names of the libraries they create.
5245 An array of legal prefixes for library file names.
5248 A list of one or more libraries
5249 that will be linked with
5250 any executable programs
5251 created by this environment.
5254 The library list will be added to command lines
5255 through the automatically-generated
5257 construction variable,
5258 which is constructed by
5259 appending the values of the
5260 $LIBLINKPREFIX and $LIBLINKSUFFIX
5261 construction variables
5262 to the beginning and end
5263 of each directory in $LIBS.
5264 Any command lines you define that need
5265 the LIBS library list should
5269 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5273 The suffix used for (static) library file names.
5274 A default value is set for each platform
5275 (posix, win32, os2, etc.),
5276 but the value is overridden by individual tools
5277 (ar, mslib, sgiar, sunar, tlib, etc.)
5278 to reflect the names of the libraries they create.
5281 An array of legal suffixes for library file names.
5287 General user options passed to the linker.
5288 Note that this variable should
5292 (or similar) options for linking with the libraries listed in $LIBS,
5295 (or similar) library search path options
5296 that scons generates automatically from $LIBPATH.
5300 for the variable that expands to library-link options,
5304 for the variable that expands to library search path options.
5307 The command line used to link object files into an executable.
5310 The M4 macro preprocessor.
5313 General options passed to the M4 macro preprocessor.
5316 The command line used to pass files through the macro preprocessor.
5319 The maximum number of characters allowed on an external command line.
5321 link lines longer than this many characters
5322 are linke via a temporary file name.
5325 When the Microsoft Visual Studio tools are initialized, they set up
5326 this dictionary with the following keys:
5329 the version of MSVS being used (can be set via
5333 the available versions of MSVS installed
5336 installed directory of Visual C++
5339 installed directory of Visual Studio
5342 installed directory of the .NET framework
5344 .B FRAMEWORKVERSIONS:
5345 list of installed versions of the .NET framework, sorted latest to oldest.
5347 .B FRAMEWORKVERSION:
5348 latest installed version of the .NET framework
5351 installed location of the .NET SDK.
5354 installed location of the Platform SDK.
5356 .B PLATFORMSDK_MODULES:
5357 dictionary of installed Platform SDK modules,
5358 where the dictionary keys are keywords for the various modules, and
5359 the values are 2-tuples where the first is the release date, and the
5360 second is the version number.
5362 If a value isn't set, it wasn't available in the registry.
5364 .IP MSVS_IGNORE_IDE_PATHS
5365 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5366 instead of the settings from the IDE.
5368 For Visual Studio, SCons will (by default) automatically determine
5369 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5370 set by the IDE. You can override this behavior by setting these
5371 variables after Environment initialization, or by setting
5372 .B MSVS_IGNORE_IDE_PATHS = 1
5373 in the Environment initialization.
5374 Specifying this will not leave these unset, but will set them to a
5375 minimal set of paths needed to run the tools successfully.
5378 For VS6, the mininimal set is:
5379 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5380 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5381 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5383 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5384 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5385 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5389 Where '<VSDir>' is the installed location of Visual Studio.
5391 .IP MSVS_USE_MFC_DIRS
5392 Tells the MS Visual Studio tool(s) to use
5393 the MFC directories in its default paths
5394 for compiling and linking.
5395 Under MSVS version 6,
5397 .B MSVS_USE_MFC_DIRS
5406 external environment variable,
5412 external environment variable.
5413 Under MSVS version 7,
5415 .B MSVS_USE_MFC_DIRS
5418 .B "atlmfc\\\\include"
5419 directory to the default
5421 external environment variable,
5424 directory to the default
5426 external environment variable.
5427 The current default value is
5429 which means these directories
5430 are added to the paths by default.
5431 This default value is likely to change
5432 in a future release,
5433 so users who want the ATL and MFC
5434 values included in their paths
5435 are encouraged to enable the
5436 .B MSVS_USE_MFC_DIRS
5438 to avoid future incompatibility.
5439 This variable has no effect if the
5443 environment variables are set explictly.
5446 Sets the preferred version of MSVS to use.
5448 SCons will (by default) select the latest version of MSVS
5449 installed on your machine. So, if you have version 6 and version 7
5450 (MSVS .NET) installed, it will prefer version 7. You can override this by
5453 variable in the Environment initialization, setting it to the
5454 appropriate version ('6.0' or '7.0', for example).
5455 If the given version isn't installed, tool initialization will fail.
5458 The action used to generate Microsoft Visual Studio
5459 project and solution files.
5461 .IP MSVSPROJECTSUFFIX
5462 The suffix used for Microsoft Visual Studio project (DSP) files.
5463 The default value is
5465 when using Visual Studio version 7.x (.NET),
5468 when using earlier versions of Visual Studio.
5470 .IP MSVSSOLUTIONSUFFIX
5471 The suffix used for Microsoft Visual Studio solution (DSW) files.
5472 The default value is
5474 when using Visual Studio version 7.x (.NET),
5477 when using earlier versions of Visual Studio.
5480 When set to non-zero,
5481 suppresses creation of a corresponding Win32 static import lib by the
5483 builder when used with
5484 MinGW or Microsoft Visual Studio.
5485 This also suppresses creation
5486 of an export (.exp) file
5487 when using Microsoft Visual Studio.
5490 The prefix used for (static) object file names.
5493 The suffix used for (static) object file names.
5496 The Perforce executable.
5499 The command line used to
5500 fetch source files from Perforce.
5503 General options that are passed to Perforce.
5506 The Microsoft Visual C++ precompiled header that will be used when compiling
5507 object files. This variable is ignored by tools other than Microsoft Visual C++.
5508 When this variable is
5509 defined SCons will add options to the compiler command line to
5510 cause it to use the precompiled header, and will also set up the
5511 dependencies for the PCH file. Example:
5514 env['PCH'] = 'StdAfx.pch'
5518 This variable specifies how much of a source file is precompiled. This
5519 variable is ignored by tools other than Microsoft Visual C++, or when
5520 the PCH variable is not being used. When this variable is define it
5521 must be a string that is the name of the header that
5522 is included at the end of the precompiled portion of the source files, or
5523 the empty string if the "#pragma hrdstop" construct is being used:
5526 env['PCHSTOP'] = 'StdAfx.h'
5530 The Microsoft Visual C++ PDB file that will store debugging information for
5531 object files, shared libraries, and programs. This variable is ignored by
5532 tools other than Microsoft Visual C++.
5533 When this variable is
5534 defined SCons will add options to the compiler and linker command line to
5535 cause them to generate external debugging information, and will also set up the
5536 dependencies for the PDB file. Example:
5539 env['PDB'] = 'hello.pdb'
5543 A deprecated synonym for $DVIPDFCOM.
5546 The prefix used for PDF file names.
5549 The suffix used for PDF file names.
5552 The name of the platform used to create the Environment. If no platform is
5553 specified when the Environment is created,
5555 autodetects the platform.
5558 env = Environment(tools = [])
5559 if env['PLATFORM'] == 'cygwin':
5566 The prefix used for executable file names.
5569 The suffix used for executable file names.
5572 The command line used to convert TeX DVI files into a PostScript file.
5575 The prefix used for PostScript file names.
5578 The prefix used for PostScript file names.
5581 The qt tool tries to take this from os.environ.
5582 It also initializes all QT_*
5583 construction variables listed below.
5584 (Note that all paths are constructed
5585 with python's os.path.join() method,
5586 but are listed here with the '/' separator
5587 for easier reading.)
5588 In addition, the construction environment
5589 variables CPPPATH, LIBPATH, LIBS, PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5590 are modified. Because the build-performance is affected when using this tool,
5591 you have to explicitly specify it at Environment creation:
5594 Environment(tools=['default','qt'])
5597 The qt tool supports the following operations:
5599 .B Automatic moc file generation from header files.
5600 You do not have to specify moc files explicitly, the tool does it for you.
5601 However, there are a few preconditions to do so: Your header file must have
5602 the same filebase as your implementation file and must stay in the same
5603 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
5604 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
5605 See also the corresponding builder method
5608 .B Automatic moc file generation from cxx files.
5609 As stated in the qt documentation, include the moc file at the end of
5610 the cxx file. Note that you have to include the file, which is generated
5611 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
5612 <basename>.moc. A warning is generated after building the moc file, if you
5613 do not include the correct file. If you are using BuildDir, you may
5614 need to specify duplicate=1. You can turn off automatic moc file generation
5615 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
5618 .B Automatic handling of .ui files.
5619 The implementation files generated from .ui files are handled much the same
5620 as yacc or lex files. Each .ui file given as a source of Program, Library or
5621 SharedLibrary will generate three files, the declaration file, the
5622 implementation file and a moc file. Because there are also generated headers,
5623 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
5627 Turn off scanning for mocable files. Use the Moc Builder to explicitely
5628 specify files to run moc on.
5631 Prints lots of debugging information while scanning for moc files.
5634 Default value is 'qt'. You may want to set this to 'qt-mt'.
5637 Default value is '$QTDIR/bin/moc'.
5640 Default value is ''. Prefix for moc output files, when source is a cxx file.
5643 Default value is '.moc'. Suffix for moc output files, when source is a cxx
5646 .IP QT_MOCFROMCPPFLAGS
5647 Default value is '-i'. These flags are passed to moc, when moccing a
5650 .IP QT_MOCFROMCXXCOM
5651 Command to generate a moc file from a cpp file.
5654 Command to generate a moc file from a header.
5656 .IP QT_MOCFROMHFLAGS
5657 Default value is ''. These flags are passed to moc, when moccing a header
5661 Default value is 'moc_'. Prefix for moc output files, when source is a header.
5664 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
5668 Default value is '$QTDIR/bin/uic'.
5671 Command to generate header files from .ui files.
5674 Default value is ''. These flags are passed to uic, when creating a a h
5675 file from a .ui file.
5677 .IP QT_UICDECLPREFIX
5678 Default value is ''. Prefix for uic generated header files.
5680 .IP QT_UICDECLSUFFIX
5681 Default value is '.h'. Suffix for uic generated header files.
5684 Command to generate cxx files from .ui files.
5687 Default value is ''. These flags are passed to uic, when creating a cxx
5688 file from a .ui file.
5690 .IP QT_UICIMPLPREFIX
5691 Default value is 'uic_'. Prefix for uic generated implementation files.
5693 .IP QT_UICIMPLSUFFIX
5694 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
5698 Default value is '.ui'. Suffix of designer input files.
5701 The archive indexer.
5704 General options passed to the archive indexer.
5707 The resource compiler used by the RES builder.
5710 The command line used by the RES builder.
5713 The flags passed to the resource compiler by the RES builder.
5717 Note that this variable is not actually used
5718 for the command to fetch source files from RCS;
5721 construction variable, below.
5724 The RCS "checkout" executable,
5725 used to fetch source files from RCS.
5728 The command line used to
5729 fetch (checkout) source files from RCS.
5732 Options that are passed to the $RCS_CO command.
5735 A function that converts a file name into a list of Dir instances by
5736 searching the repositories.
5739 The Java RMI stub compiler.
5742 The command line used to compile stub
5743 and skeleton class files
5744 from Java classes that contain RMI implementations.
5745 Any options specified in the $RMICFLAGS construction variable
5746 are included on this command line.
5749 General options passed to the Java RMI stub compiler.
5752 A list of paths to search for shared libraries when running programs.
5753 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
5754 Ignored on platforms and toolchains that don't support it.
5755 Note that the paths added to RPATH
5756 are not transformed by
5758 in any way: if you want an absolute
5759 path, you must make it absolute yourself.
5762 A list of the available implicit dependency scanners.
5763 New file scanners may be added by
5764 appending to this list,
5765 although the more flexible approach
5766 is to associate scanners
5767 with a specific Builder.
5768 See the sections "Builder Objects"
5769 and "Scanner Objects,"
5770 below, for more information.
5773 The SCCS executable.
5776 The command line used to
5777 fetch source files from SCCS.
5780 General options that are passed to SCCS.
5783 Options that are passed specifically to the SCCS "get" subcommand.
5784 This can be set, for example, to
5786 to check out editable files from SCCS.
5789 The C compiler used for generating shared-library objects.
5792 The command line used to compile a C source file
5793 to a shared-library object file.
5794 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
5795 are included on this command line.
5798 Options that are passed to the C compiler
5799 to generate shared-library objects.
5802 The C++ compiler used for generating shared-library objects.
5805 The command line used to compile a C++ source file
5806 to a shared-library object file.
5807 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
5808 are included on this command line.
5811 Options that are passed to the C++ compiler
5812 to generate shared-library objects.
5815 A string naming the shell program that will be passed to the
5820 construction variable for more information.
5823 The Fortran 77 compiler used for generating shared-library objects.
5824 You should normally set the $SHFORTRANC variable,
5825 which specifies the default Fortran compiler
5826 for all Fortran versions.
5827 You only need to set $SHF77 if you need to use a specific compiler
5828 or compiler version for Fortran 77 files.
5831 The command line used to compile a Fortran 77 source file
5832 to a shared-library object file.
5833 You only need to set $SHF77COM if you need to use a specific
5834 command line for Fortran 77 files.
5835 You should normally set the $SHFORTRANCOM variable,
5836 which specifies the default command line
5837 for all Fortran versions.
5840 Options that are passed to the Fortran 77 compiler
5841 to generated shared-library objects.
5842 You only need to set $SHF77FLAGS if you need to define specific
5843 user options for Fortran 77 files.
5844 You should normally set the $SHFORTRANFLAGS variable,
5845 which specifies the user-specified options
5846 passed to the default Fortran compiler
5847 for all Fortran versions.
5850 The command line used to compile a Fortran 77 source file to a
5851 shared-library object file
5852 after first running the file through the C preprocessor.
5853 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
5854 are included on this command line.
5855 You only need to set $SHF77PPCOM if you need to use a specific
5856 C-preprocessor command line for Fortran 77 files.
5857 You should normally set the $SHFORTRANPPCOM variable,
5858 which specifies the default C-preprocessor command line
5859 for all Fortran versions.
5862 The Fortran 90 compiler used for generating shared-library objects.
5863 You should normally set the $SHFORTRANC variable,
5864 which specifies the default Fortran compiler
5865 for all Fortran versions.
5866 You only need to set $SHF90 if you need to use a specific compiler
5867 or compiler version for Fortran 90 files.
5870 The command line used to compile a Fortran 90 source file
5871 to a shared-library object file.
5872 You only need to set $SHF90COM if you need to use a specific
5873 command line for Fortran 90 files.
5874 You should normally set the $SHFORTRANCOM variable,
5875 which specifies the default command line
5876 for all Fortran versions.
5879 Options that are passed to the Fortran 90 compiler
5880 to generated shared-library objects.
5881 You only need to set $SHF90FLAGS if you need to define specific
5882 user options for Fortran 90 files.
5883 You should normally set the $SHFORTRANFLAGS variable,
5884 which specifies the user-specified options
5885 passed to the default Fortran compiler
5886 for all Fortran versions.
5889 The command line used to compile a Fortran 90 source file to a
5890 shared-library object file
5891 after first running the file through the C preprocessor.
5892 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
5893 are included on this command line.
5894 You only need to set $SHF90PPCOM if you need to use a specific
5895 C-preprocessor command line for Fortran 90 files.
5896 You should normally set the $SHFORTRANPPCOM variable,
5897 which specifies the default C-preprocessor command line
5898 for all Fortran versions.
5901 The Fortran 95 compiler used for generating shared-library objects.
5902 You should normally set the $SHFORTRANC variable,
5903 which specifies the default Fortran compiler
5904 for all Fortran versions.
5905 You only need to set $SHF95 if you need to use a specific compiler
5906 or compiler version for Fortran 95 files.
5909 The command line used to compile a Fortran 95 source file
5910 to a shared-library object file.
5911 You only need to set $SHF95COM if you need to use a specific
5912 command line for Fortran 95 files.
5913 You should normally set the $SHFORTRANCOM variable,
5914 which specifies the default command line
5915 for all Fortran versions.
5918 Options that are passed to the Fortran 95 compiler
5919 to generated shared-library objects.
5920 You only need to set $SHF95FLAGS if you need to define specific
5921 user options for Fortran 95 files.
5922 You should normally set the $SHFORTRANFLAGS variable,
5923 which specifies the user-specified options
5924 passed to the default Fortran compiler
5925 for all Fortran versions.
5928 The command line used to compile a Fortran 95 source file to a
5929 shared-library object file
5930 after first running the file through the C preprocessor.
5931 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
5932 are included on this command line.
5933 You only need to set $SHF95PPCOM if you need to use a specific
5934 C-preprocessor command line for Fortran 95 files.
5935 You should normally set the $SHFORTRANPPCOM variable,
5936 which specifies the default C-preprocessor command line
5937 for all Fortran versions.
5940 The default Fortran compiler used for generating shared-library objects.
5943 The command line used to compile a Fortran source file
5944 to a shared-library object file.
5947 Options that are passed to the Fortran compiler
5948 to generate shared-library objects.
5951 The command line used to compile a Fortran source file to a
5952 shared-library object file
5953 after first running the file through the C preprocessor.
5954 Any options specified
5955 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
5956 are included on this command line.
5959 The prefix used for shared library file names.
5962 The suffix used for shared library file names.
5965 The linker for programs that use shared libraries.
5968 General user options passed to the linker for programs using shared libraries.
5969 Note that this variable should
5973 (or similar) options for linking with the libraries listed in $LIBS,
5976 (or similar) include search path options
5977 that scons generates automatically from $LIBPATH.
5981 for the variable that expands to library-link options,
5985 for the variable that expands to library search path options.
5988 The prefix used for shared object file names.
5991 The suffix used for shared object file names.
5994 A reserved variable name
5995 that may not be set or used in a construction environment.
5996 (See "Variable Substitution," below.)
5999 A reserved variable name
6000 that may not be set or used in a construction environment.
6001 (See "Variable Substitution," below.)
6004 A command interpreter function that will be called to execute command line
6005 strings. The function must expect 4 arguments:
6008 def spawn(shell, escape, cmd, args, env):
6012 is a string naming the shell program to use.
6014 is a function that can be called to escape shell special characters in
6017 is the path to the command to be executed.
6019 is that arguments to the command.
6021 is a dictionary of the environment variables
6022 in which the command should be executed.
6025 '\"The Subversion executable (usually named
6029 '\"The command line used to
6030 '\"fetch source files from a Subversion repository.
6033 '\"General options that are passed to Subversion.
6036 The scripting language wrapper and interface generator.
6039 The suffix that will be used for intermediate C
6040 source files generated by
6041 the scripting language wrapper and interface generator.
6042 The default value is
6043 .BR _wrap$CFILESUFFIX .
6044 By default, this value is used whenever the
6048 specified as part of the
6050 construction variable.
6053 The command line used to call
6054 the scripting language wrapper and interface generator.
6056 .IP SWIGCXXFILESUFFIX
6057 The suffix that will be used for intermediate C++
6058 source files generated by
6059 the scripting language wrapper and interface generator.
6060 The default value is
6061 .BR _wrap$CFILESUFFIX .
6062 By default, this value is used whenever the
6064 option is specified as part of the
6066 construction variable.
6069 General options passed to
6070 the scripting language wrapper and interface generator.
6071 This is where you should set
6075 or whatever other options you want to specify to SWIG.
6078 option in this variable,
6081 generate a C++ intermediate source file
6082 with the extension that is specified as the
6090 The command line used to call the tar archiver.
6093 General options passed to the tar archiver.
6096 A reserved variable name
6097 that may not be set or used in a construction environment.
6098 (See "Variable Substitution," below.)
6101 A reserved variable name
6102 that may not be set or used in a construction environment.
6103 (See "Variable Substitution," below.)
6106 The suffix used for tar file names.
6109 The TeX formatter and typesetter.
6112 The command line used to call the TeX formatter and typesetter.
6115 General options passed to the TeX formatter and typesetter.
6118 A list of the names of the Tool specifications
6119 that are part of this construction environment.
6121 .IP WIN32_INSERT_DEF
6122 When this is set to true,
6123 a library build of a WIN32 shared library (.dll file)
6124 will also build a corresponding .def file at the same time,
6125 if a .def file is not already listed as a build target.
6126 The default is 0 (do not build a .def file).
6129 The prefix used for WIN32 .def file names.
6132 The suffix used for WIN32 .def file names.
6135 The parser generator.
6138 The command line used to call the parser generator
6139 to generate a source file.
6142 General options passed to the parser generator.
6143 If $YACCFLAGS contains a \-d option,
6144 SCons assumes that the call will also create a .h file
6145 (if the yacc source file ends in a .y suffix)
6147 (if the yacc source file ends in a .yy suffix)
6150 The zip compression and file packaging utility.
6153 The command line used to call the zip utility,
6154 or the internal Python function used to create a
6163 module used by the internal Python function
6164 to control whether the zip archive
6165 is compressed or not.
6166 The default value is
6167 .BR zipfile.ZIP_DEFLATED ,
6168 which creates a compressed zip archive.
6169 This value has no effect when using Python 1.5.2
6172 module is otherwise unavailable.
6175 General options passed to the zip utility.
6178 Construction variables can be retrieved and set using the
6180 method of the construction environment:
6183 dict = env.Dictionary()
6187 or using the [] operator:
6193 Construction variables can also be passed to the construction environment
6197 env = Environment(CC="cc")
6200 or when copying a construction environment using the
6205 env2 = env.Copy(CC="cl.exe")
6208 .SS Configure Contexts
6212 .I configure contexts,
6213 an integrated mechanism similar to the
6214 various AC_CHECK macros in GNU autoconf
6215 for testing for the existence of C header
6216 files, libraries, etc.
6217 In contrast to autoconf,
6219 does not maintain an explicit cache of the tested values,
6220 but uses its normal dependency tracking to keep the checked values
6222 The following methods can be used to perform checks:
6225 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
6227 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ])
6228 This creates a configure context, which can be used to perform checks.
6230 specifies the environment for building the tests.
6231 This environment may be modified when performing checks.
6233 is a dictionary containing custom tests.
6234 See also the section about custom tests below.
6235 By default, no custom tests are added to the configure context.
6237 specifies a directory where the test cases are built.
6238 Note that this directory is not used for building
6240 The default value is the directory
6243 specifies a file which collects the output from commands
6244 that are executed to check for the existence of header files, libraries, etc.
6245 The default is the file #/config.log.
6246 If you are using the
6249 you may want to specify a subdirectory under your build directory.
6254 instance has the following associated methods:
6257 .RI Configure.Finish( self )
6258 This method should be called after configuration is done.
6259 It returns the environment as modified
6260 by the configuration checks performed.
6261 After this method is called, no further checks can be performed
6262 with this configuration context.
6263 However, you can create a new
6265 context to perform additional checks.
6266 Only one context should be active at a time.
6268 The following Checks are predefined.
6269 (This list will likely grow larger as time
6270 goes by and developers contribute new useful tests.)
6273 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6276 is usable in the specified language.
6279 in which case the last item in the list
6280 is the header file to be checked,
6281 and the previous list items are
6284 lines should precede the
6285 header line being checked for.
6286 The optional argument
6289 a two character string, where the first character denotes the opening
6290 quote and the second character denotes the closing quote.
6291 By default, both characters are " (double quote).
6292 The optional argument
6298 and selects the compiler to be used for the check.
6299 Returns 1 on success and 0 on failure.
6302 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6303 This is a wrapper around
6304 .B Configure.CheckHeader
6307 is usable in the C language.
6310 in which case the last item in the list
6311 is the header file to be checked,
6312 and the previous list items are
6315 lines should precede the
6316 header line being checked for.
6317 The optional argument
6320 a two character string, where the first character denotes the opening
6321 quote and the second character denotes the closing quote (both default
6323 Returns 1 on success and 0 on failure.
6326 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6327 This is a wrapper around
6328 .B Configure.CheckHeader
6331 is usable in the C++ language.
6334 in which case the last item in the list
6335 is the header file to be checked,
6336 and the previous list items are
6339 lines should precede the
6340 header line being checked for.
6341 The optional argument
6344 a two character string, where the first character denotes the opening
6345 quote and the second character denotes the closing quote (both default
6347 Returns 1 on success and 0 on failure.
6350 .RI Configure.CheckFunc( self ", " function_name ", [" language ])
6351 Checks if the specified
6352 C or C++ function is available.
6354 is the name of the function to check for.
6361 and selects the compiler to be used for the check;
6365 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
6372 is 1 and the library provides the specified
6374 appends the library to the LIBS construction environment variable.
6376 may also be None (the default),
6379 is checked with the current LIBS variable,
6380 or a list of library names,
6381 in which case each library in the list
6388 you can link against the specified
6396 and selects the compiler to be used for the check;
6398 The default value for
6401 It is assumed, that the C-language is used.
6402 This method returns 1 on success and 0 on error.
6405 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
6408 .RI Configure.CheckLib
6409 call, this call provides a more sophisticated way to check against libraries.
6412 specifies the library or a list of libraries to check.
6414 specifies a header to check for.
6417 in which case the last item in the list
6418 is the header file to be checked,
6419 and the previous list items are
6422 lines should precede the
6423 header line being checked for.
6425 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6427 can be any valid expression (with a trailing ';'). The default is 'main();'.
6429 specifies whether to add the library to the environment (only if the check
6430 succeeds). This method returns 1 on success and 0 on error.
6433 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
6434 Checks for the existence of a type defined by
6437 specifies the typedef name to check for.
6439 is a string containing one or more
6441 lines that will be inserted into the program
6442 that will be run to test for the existence of the type.
6449 and selects the compiler to be used for the check;
6453 Example of a typical Configure usage:
6457 conf = Configure( env )
6458 if not conf.CheckCHeader( 'math.h' ):
6459 print 'We really need math.h!'
6461 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6462 # do stuff for qt - usage, e.g.
6463 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6468 You can define your own custom checks.
6469 in addition to the predefined checks.
6470 These are passed in a dictionary to the Configure function.
6471 This dictionary maps the names of the checks
6472 to user defined Python callables
6473 (either Python functions or class instances implementing the
6476 The first argument of the call is always a
6478 instance followed by the arguments,
6479 which must be supplied by the user of the check.
6480 These CheckContext instances define the following methods:
6483 .RI CheckContext.Message( self ", " text )
6485 Usually called before the check is started.
6487 will be displayed to the user, e.g. 'Checking for library X...'
6490 .RI CheckContext.Result( self, ", " res )
6492 Usually called after the check is done.
6494 can be either an integer or a string. In the former case, 'ok' (res != 0)
6495 or 'failed' (res == 0) is displayed to the user, in the latter case the
6496 given string is displayed.
6499 .RI CheckContext.TryCompile( self ", " text ", " extension )
6500 Checks if a file with the specified
6502 (e.g. '.c') containing
6504 can be compiled using the environment's
6506 builder. Returns 1 on success and 0 on failure.
6509 .RI CheckContext.TryLink( self ", " text ", " extension )
6510 Checks, if a file with the specified
6512 (e.g. '.c') containing
6514 can be compiled using the environment's
6516 builder. Returns 1 on success and 0 on failure.
6519 .RI CheckContext.TryRun( self ", " text ", " extension )
6520 Checks, if a file with the specified
6522 (e.g. '.c') containing
6524 can be compiled using the environment's
6526 builder. On success, the program is run. If the program
6527 executes successfully
6528 (that is, its return status is 0),
6533 is the standard output of the
6535 If the program fails execution
6536 (its return status is non-zero),
6537 then (0, '') is returned.
6540 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
6541 Checks if the specified
6543 with an optional source file (contents
6550 may be anything which can be converted to a
6557 is the content of the target file.
6563 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
6564 Low level implementation for testing specific builds;
6565 the methods above are based on this method.
6566 Given the Builder instance
6570 of a source file with optional
6572 this method returns 1 on success and 0 on failure. In addition,
6574 is set to the build target node, if the build was successful.
6577 Example for implementing and using custom tests:
6580 def CheckQt(context, qtdir):
6581 context.Message( 'Checking for qt ...' )
6582 lastLIBS = context.env['LIBS']
6583 lastLIBPATH = context.env['LIBPATH']
6584 lastCPPPATH= context.env['CPPPATH']
6585 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
6586 ret = context.TryLink("""
6588 int main(int argc, char **argv) {
6589 QApplication qapp(argc, argv);
6594 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
6595 context.Result( ret )
6599 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
6600 if not conf.CheckQt('/usr/lib/qt'):
6601 print 'We really need qt!'
6606 .SS Construction Variable Options
6608 Often when building software, various options need to be specified at build
6609 time that are not known when the SConstruct/SConscript files are
6610 written. For example, libraries needed for the build may be in non-standard
6611 locations, or site-specific compiler options may need to be passed to the
6614 provides a mechanism for overridding construction variables from the
6615 command line or a text-based SConscript file through an Options
6616 object. To create an Options object, call the Options() function:
6619 .RI Options([ files "], [" args ])
6620 This creates an Options object that will read construction variables from
6621 the file or list of filenames specified in
6623 If no files are specified,
6628 then no files will be read.
6629 The optional argument
6632 values that will override anything read from the specified files;
6633 it is primarily intended to be passed the
6635 dictionary that holds variables
6636 specified on the command line.
6640 opts = Options('custom.py')
6641 opts = Options('overrides.py', ARGUMENTS)
6642 opts = Options(None, {FOO:'expansion', BAR:7})
6645 Options objects have the following methods:
6648 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
6649 This adds a customizable construction variable to the Options object.
6651 is the name of the variable.
6653 is the help text for the variable.
6655 is the default value of the variable.
6657 is called to validate the value of the variable, and should take three
6658 arguments: key, value, and environment
6660 is called to convert the value before putting it in the environment, and
6661 should take a single argument: value. Example:
6664 opts.Add('CC', 'The C compiler')
6668 .RI AddOptions( list )
6669 A wrapper script that adds
6670 multiple customizable construction variables
6671 to an Options object.
6673 is a list of tuple or list objects
6674 that contain the arguments
6675 for an individual call to the
6682 ('CC', 'The C compiler'),
6683 ('VALIDATE', 'An option for testing validation',
6684 'notset', validator, None),
6689 .RI Update( env ", [" args ])
6690 This updates a construction environment
6692 with the customized construction variables. Normally this method is not
6693 called directly, but is called indirectly by passing the Options object to
6694 the Environment() function:
6697 env = Environment(options=opts)
6701 .RI Save( filename ", " env )
6702 This saves the currently set options into a script file named
6704 that can be used on the next invocation to automatically load the current
6705 settings. This method combined with the Options method can be used to
6706 support caching of options between runs.
6710 opts = Options(['options.cache', 'custom.py'])
6713 opts.Save('options.cache', env)
6717 .RI GenerateHelpText( env ", [" sort ])
6718 This generates help text documenting the customizable construction
6719 variables suitable to passing in to the Help() function.
6721 is the construction environment that will be used to get the actual values
6722 of customizable variables. Calling with
6726 will cause the output to be sorted
6727 by the specified argument.
6731 should take two arguments
6734 (like the standard Python
6739 Help(opts.GenerateHelpText(env))
6740 Help(opts.GenerateHelpText(env, sort=cmp))
6743 The text based SConscript file is executed as a Python script, and the
6744 global variables are queried for customizable construction
6751 To make it more convenient to work with customizable Options,
6753 provides a number of functions
6754 that make it easy to set up
6755 various types of Options:
6758 .RI BoolOption( key ", " help ", " default )
6759 Return a tuple of arguments
6760 to set up a Boolean option.
6764 have a default value of
6766 and display the specified
6769 The option will interpret the values
6791 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
6792 Return a tuple of arguments
6794 whose value may be one
6795 of a specified list of legal enumerated values.
6799 have a default value of
6801 and display the specified
6804 The option will only support those
6810 argument is a dictionary
6811 that can be used to convert
6812 input values into specific legal values
6821 then the values are case-sensitive.
6826 then values will be matched
6832 then values will be matched
6834 and all input values will be
6835 converted to lower case.
6838 .RI ListOption( key ", " help ", " default ", " names )
6839 Return a tuple of arguments
6841 whose value may be one or more
6842 of a specified list of legal enumerated values.
6846 have a default value of
6848 and display the specified
6851 The option will only support the values
6854 or the values in the
6857 More than one value may be specified,
6858 with all values separated by commas.
6861 .RI PackageOption( key ", " help ", " default )
6862 Return a tuple of arguments
6864 whose value is a path name
6865 of a package that may be
6866 enabled, disabled or
6867 given an explicit path name.
6871 have a default value of
6873 and display the specified
6876 The option will support the values
6883 in which case the specified
6886 or the option may be set to an
6888 (typically the path name to a package
6889 that is being enabled).
6890 The option will also support the values
6896 to disable use of the specified option.
6899 .RI PathOption( key ", " help ", " default )
6900 Return a tuple of arguments
6902 whose value is expected to be a path name.
6906 have a default value of
6908 and display the specified
6913 These functions make it
6914 convenient to create a number
6915 of options with consistent behavior
6916 in a single call to the
6922 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
6923 EnumOption('debug', 'debug output and symbols', 'no'
6924 allowed_values=('yes', 'no', 'full'),
6925 map={}, ignorecase=0), # case sensitive
6926 ListOption('shared',
6927 'libraries to build as shared libraries',
6929 names = list_of_libs),
6930 PackageOption('x11',
6931 'use X11 installed here (yes = search some places)',
6933 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
6937 .SS File and Directory Nodes
6947 Nodes, respectively.
6948 python objects, respectively.
6949 Those objects have several user-visible attributes
6950 and methods that are often useful:
6956 This path is relative to the top-level directory
6960 The build path is the same as the source path if
6965 The absolute build path of the given file or directory.
6975 object representing the
6984 # Get the current build dir's path, relative to top.
6986 # Current dir's absolute path
6988 # Next line is always '.', because it is the top dir's path relative to itself.
6990 File('foo.c').srcnode().path # source path of the given source file.
6992 # Builders also return File objects:
6993 foo = env.Program('foo.c')
6994 print "foo will be built in %s"%foo.path
7000 can be extended to build different types of targets
7001 by adding new Builder objects
7002 to a construction environment.
7004 you should only need to add a new Builder object
7005 when you want to build a new type of file or other external target.
7006 If you just want to invoke a different compiler or other tool
7007 to build a Program, Object, Library, or any other
7008 type of output file for which
7010 already has an existing Builder,
7011 it is generally much easier to
7012 use those existing Builders
7013 in a construction environment
7014 that sets the appropriate construction variables
7017 Builder objects are created
7023 function accepts the following arguments:
7026 The command line string used to build the target from the source.
7029 a list of strings representing the command
7030 to be executed and its arguments
7031 (suitable for enclosing white space in an argument),
7033 mapping source file name suffixes to
7034 any combination of command line strings
7035 (if the builder should accept multiple source file extensions),
7038 (see the next section);
7039 or a list of any of the above.
7042 takes three arguments:
7044 - a list of source nodes,
7046 - a list of target nodes,
7048 - the construction environment.
7051 The prefix that will be prepended to the target file name.
7052 This may be a simple string, or a callable object that takes
7053 two arguments, a construction environment and a list of sources,
7054 and returns a prefix.
7057 b = Builder("build_it < $SOURCE > $TARGET"
7060 def gen_prefix(env, sources):
7061 return "file-" + env['PLATFORM'] + '-'
7062 b = Builder("build_it < $SOURCE > $TARGET"
7063 prefix = gen_prefix)
7067 The suffix that will be appended to the target file name.
7068 This may be a simple string, or a callable object that takes
7069 two arguments, a construction environment and a list of sources,
7070 and returns a suffix.
7071 If the suffix is a string, then
7073 will append a '.' to the beginning of the
7074 suffix if it's not already there.
7075 The string returned by callable object
7076 is untouched and must append its own '.'
7077 to the beginning if one is desired.
7080 b = Builder("build_it < $SOURCE > $TARGET"
7083 def gen_suffix(env, sources):
7084 return "." + env['PLATFORM'] + "-file"
7085 b = Builder("build_it < $SOURCE > $TARGET"
7086 suffix = gen_suffix)
7090 The expected source file name suffix.
7093 A Scanner object that
7094 will be invoked to find
7095 implicit dependencies for this target file.
7096 This keyword argument should be used
7097 for Scanner objects that find
7098 implicit dependencies
7099 based only on the target file
7100 and the construction environment,
7103 (See the section "Scanner Objects," below,
7104 for information about creating Scanner objects.)
7107 A Scanner object that
7109 find implicit dependences in
7111 used to build this target file.
7112 This is where you would
7113 specify a scanner to
7116 lines in source files.
7117 (See the section "Scanner Objects," below,
7118 for information about creating Scanner objects.)
7121 A factory function that the Builder will use
7122 to turn any targets specified as strings into SCons Nodes.
7124 SCons assumes that all targets are files.
7125 Other useful target_factory
7128 for when a Builder creates a directory target,
7131 for when a Builder can create either a file
7132 or directory target.
7137 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7139 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7140 env.MakeDirectory('new_directory')
7144 A factory function that the Builder will use
7145 to turn any sources specified as strings into SCons Nodes.
7147 SCons assumes that all source are files.
7148 Other useful source_factory
7151 for when a Builder uses a directory as a source,
7154 for when a Builder can use files
7155 or directories (or both) as sources.
7160 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7162 env.Append(BUILDERS = {'Collect':CollectBuilder})
7163 env.Collect('archive', ['directory_name', 'file_name'])
7167 A function or list of functions to manipulate the target and source
7168 lists before dependencies are established
7169 and the target(s) are actually built.
7171 can also be a string containing a construction variable to expand
7172 to an emitter function or list of functions,
7173 or a dictionary mapping source file suffixes
7174 to emitter functions.
7175 (Only the suffix of the first source file
7176 is used to select the actual emitter function
7177 from an emitter dictionary.)
7180 takes three arguments:
7182 - a list of source nodes,
7184 - a list of target nodes,
7186 - the construction environment.
7187 An emitter must return a tuple containing two lists,
7188 the list of targets to be built by this builder,
7189 and the list of sources for this builder.
7194 def e(target, source, env):
7195 return (target + ['foo.foo'], source + ['foo.src'])
7197 # Simple association of an emitter function with a Builder.
7198 b = Builder("my_build < $TARGET > $SOURCE",
7201 def e2(target, source, env):
7202 return (target + ['bar.foo'], source + ['bar.src'])
7204 # Simple association of a list of emitter functions with a Builder.
7205 b = Builder("my_build < $TARGET > $SOURCE",
7208 # Calling an emitter function through a construction variable.
7209 env = Environment(MY_EMITTER = e)
7210 b = Builder("my_build < $TARGET > $SOURCE",
7211 emitter = '$MY_EMITTER')
7213 # Calling a list of emitter functions through a construction variable.
7214 env = Environment(EMITTER_LIST = [e, e2])
7215 b = Builder("my_build < $TARGET > $SOURCE",
7216 emitter = '$EMITTER_LIST')
7218 # Associating multiple emitters with different file
7219 # suffixes using a dictionary.
7220 def e_suf1(target, source, env):
7221 return (target + ['another_target_file'], source)
7222 def e_suf2(target, source, env):
7223 return (target, source + ['another_source_file'])
7224 b = Builder("my_build < $TARGET > $SOURCE",
7225 emitter = {'.suf1' : e_suf1,
7233 arguments must not both be used for the same Builder.
7236 Specifies whether this builder is allowed to be called multiple times for
7237 the same target file(s). The default is 0, which means the builder
7238 can not be called multiple times for the same target file(s). Calling a
7239 builder multiple times for the same target simply adds additional source
7240 files to the target; it is not allowed to change the environment associated
7241 with the target, specify addition environment overrides, or associate a different
7242 builder with the target.
7245 A construction environment that can be used
7246 to fetch source code using this Builder.
7247 (Note that this environment is
7249 used for normal builds of normal target files,
7250 which use the environment that was
7251 used to call the Builder for the target file.)
7254 A function that returns a list of actions that will be executed to build
7255 the target(s) from the source(s).
7256 The returned action(s) may be
7257 an Action object, or anything that
7258 can be converted into an Action object
7259 (see the next section).
7261 The generator function
7262 takes four arguments:
7264 - a list of source nodes,
7266 - a list of target nodes,
7268 - the construction environment,
7270 - a Boolean value that specifies
7271 whether the generator is being called
7272 for generating a build signature
7273 (as opposed to actually executing the command).
7277 def g(source, target, env, for_signature):
7278 return [["gcc", "-c", "-o"] + target + source]
7280 b = Builder(generator=g)
7284 Specifies a builder to use when a source file name suffix does not match
7285 any of the suffixes of the builder. Using this argument produces a
7286 multi-stage builder.
7289 Specifies that this builder expects exactly one source file per call. Giving
7290 more than one source files without target files results in implicitely calling
7291 the builder multiple times (once for each source given). Giving multiple
7292 source files together with target files results in a UserError exception.
7300 arguments must not both be used for the same Builder.
7303 A construction environment that can be used
7304 to fetch source code using this Builder.
7305 (Note that this environment is
7307 used for normal builds of normal target files,
7308 which use the environment that was
7309 used to call the Builder for the target file.)
7312 b = Builder(action="build < $SOURCE > $TARGET")
7313 env = Environment(BUILDERS = {'MyBuild' : b})
7314 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
7318 Any additional keyword arguments supplied
7319 when a Builder object is created
7320 (that is, when the Builder() function is called)
7321 will be set in the executing construction
7322 environment when the Builder object is called.
7323 The canonical example here would be
7324 to set a construction variable to
7325 the repository of a source code system.
7327 Any additional keyword arguments supplied
7331 will only be associated with the target
7332 created by that particular Builder call
7333 (and any other files built as a
7334 result of the call).
7336 These extra keyword arguments are passed to the
7337 following functions:
7338 command generator functions,
7340 and emitter functions.
7346 function will turn its
7348 keyword argument into an appropriate
7349 internal Action object.
7350 You can also explicity create Action objects
7354 which can then be passed to the
7357 This can be used to configure
7358 an Action object more flexibly,
7359 or it may simply be more efficient
7360 than letting each separate Builder object
7361 create a separate Action
7363 Builder objects need to do the same thing.
7368 returns an appropriate object for the action
7369 represented by the type of the first argument:
7372 If the first argument is already an Action object,
7373 the object is simply returned.
7376 If the first argument is a string,
7377 a command-line Action is returned.
7380 Action('$CC -c -o $TARGET $SOURCES')
7383 .\" XXX From Gary Ruben, 23 April 2002:
7384 .\" What would be useful is a discussion of how you execute command
7385 .\" shell commands ie. what is the process used to spawn the shell, pass
7386 .\" environment variables to it etc., whether there is one shell per
7387 .\" environment or one per command etc. It might help to look at the Gnu
7388 .\" make documentation to see what they think is important to discuss about
7389 .\" a build system. I'm sure you can do a better job of organising the
7390 .\" documentation than they have :-)
7394 If the first argument is a list,
7395 then a list of Action objects is returned.
7396 An Action object is created as necessary
7397 for each element in the list.
7400 the list is itself a list,
7401 the internal list is the
7402 command and arguments to be executed via
7404 This allows white space to be enclosed
7405 in an argument by defining
7406 a command in a list within a list:
7409 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7413 If the first argument is a Python function,
7414 a function Action is returned.
7415 The Python function takes three keyword arguments,
7417 (a Node object representing the target file),
7419 (a Node object representing the source file)
7422 (the construction environment
7423 used for building the target file).
7428 arguments may be lists of Node objects if there is
7429 more than one target file or source file.
7430 The actual target and source file name(s) may
7431 be retrieved from their Node objects
7432 via the built-in Python str() function:
7435 target_file_name = str(target)
7436 source_file_names = map(lambda x: str(x), source)
7439 The function should return
7443 to indicate a successful build of the target file(s).
7444 The function may raise an exception
7445 or return a non-zero exit status
7446 to indicate an unsuccessful build.
7449 def build_it(target = None, source = None, env = None):
7450 # build the target from the source
7453 a = Action(build_it)
7456 The second, optional argument
7457 is a Python function that returns
7458 a string to be printed to describe the action being executed.
7459 Like a function to build a file,
7460 this function takes three arguments:
7462 (a Node object representing the target file),
7464 (a Node object representing the source file)
7467 (a construction environment).
7472 arguments may be lists of Node objects if there is
7473 more than one target file or source file.
7477 def build_it(target, source, env):
7478 # build the target from the source
7481 def string_it(target, source, env):
7482 return "building '%s' from '%s'" % (target[0], source[0])
7484 # Use a positional argument.
7485 a = Action(build_it, string_it)
7487 # Alternatively, use a keyword argument.
7488 a = Action(build_it, strfunction=string_it)
7491 The third, also optional argument
7492 is a list of construction variables
7493 whose values will be included
7494 in the signature of the Action
7495 when deciding whether a target should
7496 be rebuilt because the action changed.
7497 This is necessary whenever you want a target to
7498 be rebuilt when a specific
7499 construction variable changes,
7500 because the underlying Python code for a function
7501 will not change when the value of the construction variable does.
7504 def build_it(target, source, env):
7505 # build the target from the 'XXX' construction variable
7506 open(target[0], 'w').write(env['XXX'])
7509 def string_it(target, source):
7510 return "building '%s' from '%s'" % (target[0], source[0])
7512 # Use positional arguments.
7513 a = Action(build_it, string_it, ['XXX'])
7515 # Alternatively, use a keyword argument.
7516 a = Action(build_it, varlist=['XXX'])
7519 If the action argument is not one of the above,
7522 .SS Miscellaneous Action Functions
7525 supplies a number of functions
7526 that arrange for various common
7527 file and directory manipulations
7529 These are similar in concept to "tasks" in the
7531 although the implementation is slightly different.
7532 These functions do not actually
7533 perform the specified action
7534 at the time the function is called,
7535 but instead return an Action object
7536 that can be executed at the
7538 (In Object-Oriented terminology,
7543 that return Action objects.)
7546 there are two natural ways
7549 are intended to be used.
7553 to perform the action
7554 at the time the SConscript
7558 global function to do so:
7560 Execute(Touch('file'))
7564 you can use these functions
7565 to supply Actions in a list
7569 This can allow you to
7570 perform more complicated
7571 sequences of file manipulation
7573 on platform-specific
7577 env = Environment(TMPBUILD = '/tmp/builddir')
7578 env.Command('foo.out', 'foo.in',
7579 [Mkdir('$TMPBUILD'),
7580 Copy('${SOURCE.dir}', '$TMPBUILD')
7581 "cd $TMPBUILD && make",
7582 Delete('$TMPBUILD')])
7586 .RI Chmod( dest ", " mode )
7587 Returns an Action object that
7588 changes the permissions on the specified
7590 file or directory to the specified
7595 Execute(Chmod('file', 0755))
7597 env.Command('foo.out', 'foo.in',
7598 [Copy('$TARGET', '$SOURCE'),
7599 Chmod('$TARGET', 0755)])
7603 .RI Copy( dest ", " src )
7604 Returns an Action object
7607 source file or directory to the
7609 destination file or directory.
7613 Execute(Copy('foo.output', 'foo.input'))
7615 env.Command('bar.out', 'bar.in',
7616 Copy('$TARGET', '$SOURCE'))
7621 Returns an Action that
7622 deletes the specified
7624 which may be a file or a directory tree.
7625 If a directory is specified,
7626 the entire directory tree
7631 Execute(Delete('/tmp/buildroot'))
7633 env.Command('foo.out', 'foo.in',
7634 [Delete('${TARGET.dir}'),
7641 that creates the specified
7647 Execute(Mkdir('/tmp/outputdir'))
7649 env.Command('foo.out', 'foo.in',
7650 [Mkdir('/tmp/builddir',
7651 Copy('$SOURCE', '/tmp/builddir')
7652 "cd /tmp/builddir && ])
7657 .RI Move( dest ", " src )
7659 that moves the specified
7661 file or directory to
7668 Execute(Move('file.destination', 'file.source'))
7670 env.Command('output_file', 'input_file',
7672 Move('$TARGET', 'file_created_by_MyBuildAction')])
7678 that updates the modification time
7684 Execute(Touch('file_to_be_touched'))
7686 env.Command('marker', 'input_file',
7691 .SS Variable Substitution
7693 Before executing a command,
7695 performs construction variable interpolation on the strings that make up
7696 the command line of builders.
7697 Variables are introduced by a
7700 Besides construction variables, scons provides the following
7701 variables for each command execution:
7704 The file name of the target being built, or the file name of the first
7705 target if multiple targets are being built.
7708 The file names of all targets being built.
7711 The file name of the source of the build command, or the file name of the
7712 first source if multiple sources are being built.
7715 The file names of the sources of the build command.
7717 (Note that the above variables are reserved
7718 and may not be set in a construction environment.)
7721 For example, given the construction variable CC='cc', targets=['foo'], and
7722 sources=['foo.c', 'bar.c']:
7725 action='$CC -c -o $TARGET $SOURCES'
7728 would produce the command line:
7731 cc -c -o foo foo.c bar.c
7734 Variable names may be surrounded by curly braces ({})
7735 to separate the name from the trailing characters.
7736 Within the curly braces, a variable name may have
7737 a Python slice subscript appended to select one
7738 or more items from a list.
7739 In the previous example, the string:
7751 Additionally, a variable name may
7752 have the following special
7753 modifiers appended within the enclosing curly braces
7754 to modify the interpolated string:
7757 The base path of the file name,
7758 including the directory path
7759 but excluding any suffix.
7762 The name of the directory in which the file exists.
7766 minus any directory portion.
7769 Just the basename of the file,
7771 and minus the directory.
7774 Just the file suffix.
7777 The absolute path name of the file.
7780 The POSIX form of the path,
7781 with directories separated by
7785 This is sometimes necessary on Win32 systems
7786 when a path references a file on other (POSIX) systems.
7789 The directory and file name to the source file linked to this file
7790 through BuildDir. If this file isn't linked, it just returns the
7791 directory and filename unchanged.
7794 The directory containing the source file linked to this file
7795 through BuildDir. If this file isn't linked, it just returns the
7796 directory part of the filename.
7799 The directory and file name to the source file linked to this file
7800 through BuildDir. If the file does not exist locally but exists in
7801 a Repository, the path in the Repository is returned.
7802 If this file isn't linked, it just returns the
7803 directory and filename unchanged.
7806 The Repository directory containing the source file linked to this file
7807 through BuildDir. If this file isn't linked, it just returns the
7808 directory part of the filename.
7811 For example, the specified target will
7812 expand as follows for the corresponding modifiers:
7815 $TARGET => sub/dir/file.x
7816 ${TARGET.base} => sub/dir/file
7817 ${TARGET.dir} => sub/dir
7818 ${TARGET.file} => file.x
7819 ${TARGET.filebase} => file
7820 ${TARGET.suffix} => .x
7821 ${TARGET.abspath} => /top/dir/sub/dir/file.x
7823 BuildDir('sub/dir','src')
7824 $SOURCE => sub/dir/file.x
7825 ${SOURCE.srcpath} => src/file.x
7826 ${SOURCE.srcdir} => src
7828 Repository('/usr/repository')
7829 $SOURCE => sub/dir/file.x
7830 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
7831 ${SOURCE.rsrcdir} => /usr/repository/src
7834 Lastly, a variable name
7835 may be a callable Python function
7837 construction variable in the environment.
7839 take four arguments:
7841 - a list of target nodes,
7843 - a list of source nodes,
7845 - the construction environment,
7847 - a Boolean value that specifies
7848 whether the function is being called
7849 for generating a build signature.
7850 SCons will insert whatever
7851 the called function returns
7852 into the expanded string:
7855 def foo(target, source, env, for_signature):
7858 # Will expand $BAR to "bar baz"
7859 env=Environment(FOO=foo, BAR="$FOO baz")
7862 You can use this feature to pass arguments to a
7863 Python function by creating a callable class
7864 that stores one or more arguments in an object,
7865 and then uses them when the
7868 Note that in this case,
7869 the entire variable expansion must
7870 be enclosed by curly braces
7871 so that the arguments will
7872 be associated with the
7873 instantiation of the class:
7877 def __init__(self, arg):
7880 def __call__(self, target, source, env, for_signature):
7883 # Will expand $BAR to "my argument bar baz"
7884 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
7888 The special pseudo-variables
7892 may be used to surround parts of a command line
7895 causing a rebuild--that is,
7896 which are not included in the signature
7897 of target files built with this command.
7902 will be removed from the command line
7903 before it is added to file signatures,
7908 will be removed before the command is executed.
7909 For example, the command line:
7912 echo Last build occurred $( $TODAY $). > $TARGET
7916 would execute the command:
7919 echo Last build occurred $TODAY. > $TARGET
7923 but the command signature added to any target files would be:
7926 echo Last build occurred . > $TARGET
7929 SCons uses the following rules when converting construction variables into
7933 When the value is a string it is interpreted as a space delimited list of
7934 command line arguments.
7937 When the value is a list it is interpreted as a list of command line
7938 arguments. Each element of the list is converted to a string.
7941 Anything that is not a list or string is converted to a string and
7942 interpreted as a single command line argument.
7945 Newline characters (\\n) delimit lines. The newline parsing is done after
7946 all other parsing, so it is not possible for arguments (e.g. file names) to
7947 contain embedded newline characters. This limitation will likely go away in
7948 a future version of SCons.
7956 new file types for implicit dependencies.
7957 Scanner accepts the following arguments:
7960 A Python function that will process
7962 and return a list of strings (file names)
7963 representing the implicit
7964 dependencies found in the contents.
7965 The function takes three or four arguments:
7967 def scanner_function(node, env, path):
7969 def scanner_function(node, env, path, arg):
7973 argument is the internal
7974 SCons node representing the file.
7977 to fetch the name of the file, and
7978 .B node.get_contents()
7979 to fetch contents of the file.
7983 argument is the construction environment for the scan.
7984 Fetch values from it using the
7990 argument is a tuple (or list)
7991 of directories that can be searched
7993 This will usually be the tuple returned by the
7995 argument (see below).
7999 argument is the argument supplied
8000 when the scanner was created, if any.
8003 The name of the Scanner.
8005 to identify the Scanner internally.
8008 An optional argument that, if specified,
8009 will be passed to the scanner function
8011 and the path function
8015 An optional list that can be used to
8016 determine which scanner should be used for
8018 In the usual case of scanning for file names,
8019 this argument will be a list of suffixes
8020 for the different file types that this
8021 Scanner knows how to scan.
8022 If the argument is a string,
8023 then it will be expanded
8024 into a list by the current environment.
8027 A Python function that takes
8028 two or three arguments:
8029 a construction environment, directory Node,
8030 and optional argument supplied
8031 when the scanner was created.
8034 returns a tuple of directories
8035 that can be searched for files to be returned
8036 by this Scanner object.
8039 The class of Node that should be returned
8040 by this Scanner object.
8041 Any strings or other objects returned
8042 by the scanner function
8043 that are not of this class
8044 will be run through the
8049 A Python function that will take a string
8051 and turn it into the appropriate class of Node
8052 to be returned by this Scanner object.
8055 An optional Python function that takes two arguments,
8056 a Node (file) and a construction environment,
8057 and returns whether the
8058 Node should, in fact,
8059 be scanned for dependencies.
8060 This check can be used to eliminate unnecessary
8061 calls to the scanner function when,
8062 for example, the underlying file
8063 represented by a Node does not yet exist.
8066 An optional flag that
8067 specifies whether this scanner should be re-invoked
8068 on the dependency files returned by the scanner.
8069 When this flag is not set,
8070 the Node subsystem will
8071 only invoke the scanner on the file being scanned,
8072 and not (for example) also on the files
8073 specified by the #include lines
8074 in the file being scanned.
8076 .SH SYSTEM-SPECIFIC BEHAVIOR
8077 SCons and its configuration files are very portable,
8078 due largely to its implementation in Python.
8079 There are, however, a few portability
8080 issues waiting to trap the unwary.
8082 SCons handles the upper-case
8084 file suffix differently,
8085 depending on the capabilities of
8086 the underlying system.
8087 On a case-sensitive system
8088 such as Linux or UNIX,
8089 SCons treats a file with a
8091 suffix as a C++ source file.
8092 On a case-insensitive system
8094 SCons treats a file with a
8096 suffix as a C source file.
8098 SCons handles the upper-case
8100 file suffix differently,
8101 depending on the capabilities of
8102 the underlying system.
8103 On a case-sensitive system
8104 such as Linux or UNIX,
8105 SCons treats a file with a
8107 suffix as a Fortran source file
8108 that is to be first run through
8109 the standard C preprocessor.
8110 On a case-insensitive system
8112 SCons treats a file with a
8114 suffix as a Fortran source file that should
8116 be run through the C preprocessor.
8117 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
8118 Cygwin supplies a set of tools and utilities
8119 that let users work on a
8120 Windows system using a more POSIX-like environment.
8121 The Cygwin tools, including Cygwin Python,
8123 by sharing an ability to interpret UNIX-like path names.
8124 For example, the Cygwin tools
8125 will internally translate a Cygwin path name
8126 like /cygdrive/c/mydir
8127 to an equivalent Windows pathname
8128 of C:/mydir (equivalent to C:\\mydir).
8131 that are built for native Windows execution,
8132 such as the python.org and ActiveState versions,
8133 do not have the Cygwin path name semantics.
8134 This means that using a native Windows version of Python
8135 to build compiled programs using Cygwin tools
8136 (such as gcc, bison, and flex)
8137 may yield unpredictable results.
8138 "Mixing and matching" in this way
8139 can be made to work,
8140 but it requires careful attention to the use of path names
8141 in your SConscript files.
8143 In practice, users can sidestep
8144 the issue by adopting the following rules:
8146 use the Cygwin-supplied Python interpreter
8148 when using Microsoft Visual C/C++
8149 (or some other Windows compiler)
8150 use the python.org or ActiveState version of Python
8152 .SS WIN32: scons.bat file
8154 SCons is executed via a wrapper
8157 This has (at least) two ramifications:
8159 First, Windows command-line users
8160 that want to use variable assignment
8162 may have to put double quotes
8163 around the assignments:
8166 scons "FOO=BAR" "BAZ=BLEH"
8169 Second, the Cygwin shell does not
8170 recognize this file as being the same
8173 command issued at the command-line prompt.
8174 You can work around this either by
8177 from the Cygwin command line,
8178 or by creating a wrapper shell
8184 The MinGW bin directory must be in your PATH environment variable or the
8185 PATH variable under the ENV construction variable for SCons
8186 to detect and use the MinGW tools. When running under the native Windows
8187 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8188 tools, if they are both installed, regardless of the order of the bin
8189 directories in the PATH variable. If you have both MSVC and MinGW
8190 installed and you want to use MinGW instead of MSVC,
8191 then you must explictly tell SCons to use MinGW by passing
8197 to the Environment() function, because SCons will prefer the MSVC tools
8198 over the MinGW tools.
8202 To help you get started using SCons,
8203 this section contains a brief overview of some common tasks.
8205 .SS Basic Compilation From a Single Source File
8209 env.Program(target = 'foo', source = 'foo.c')
8212 Note: Build the file by specifying
8213 the target as an argument
8214 ("scons foo" or "scons foo.exe").
8215 or by specifying a dot ("scons .").
8217 .SS Basic Compilation From Multiple Source Files
8221 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8224 .SS Setting a Compilation Flag
8227 env = Environment(CCFLAGS = '-g')
8228 env.Program(target = 'foo', source = 'foo.c')
8231 .SS Search The Local Directory For .h Files
8235 need to set CCFLAGS to specify -I options by hand.
8236 SCons will construct the right -I options from CPPPATH.
8239 env = Environment(CPPPATH = ['.'])
8240 env.Program(target = 'foo', source = 'foo.c')
8243 .SS Search Multiple Directories For .h Files
8246 env = Environment(CPPPATH = ['include1', 'include2'])
8247 env.Program(target = 'foo', source = 'foo.c')
8250 .SS Building a Static Library
8254 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8255 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8258 .SS Building a Shared Library
8262 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8263 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8266 .SS Linking a Local Library Into a Program
8269 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8270 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8271 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8274 .SS Defining Your Own Builder Object
8276 Notice that when you invoke the Builder,
8277 you can leave off the target file suffix,
8278 and SCons will add it automatically.
8281 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8283 src_suffix = '.tex')
8284 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8285 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8287 # The following creates "bar.pdf" from "bar.tex"
8288 env.PDFBuilder(target = 'bar', source = 'bar')
8291 Note also that the above initialization
8292 overwrites the default Builder objects,
8293 so the Environment created above
8294 can not be used call Builders like env.Program(),
8295 env.Object(), env.StaticLibrary(), etc.
8297 .SS Adding Your Own Builder Object to an Environment
8300 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8302 src_suffix = '.tex')
8304 env.Append(BUILDERS = {'PDFBuilder' : bld})
8305 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8306 env.Program(target = 'bar', source = 'bar.c')
8309 You also can use other Pythonic techniques to add
8310 to the BUILDERS construction variable, such as:
8314 env['BUILDERS]['PDFBuilder'] = bld
8317 .SS Defining Your Own Scanner Object
8322 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8324 def kfile_scan(node, env, path, arg):
8325 contents = node.get_contents()
8326 includes = include_re.findall(contents)
8329 kscan = Scanner(name = 'kfile',
8330 function = kfile_scan,
8333 scanners = Environment().Dictionary('SCANNERS')
8334 env = Environment(SCANNERS = scanners + [kscan])
8336 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8338 bar_in = File('bar.in')
8339 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8340 bar_in.target_scanner = kscan
8343 .SS Creating a Hierarchical Build
8345 Notice that the file names specified in a subdirectory's
8347 file are relative to that subdirectory.
8353 env.Program(target = 'foo', source = 'foo.c')
8355 SConscript('sub/SConscript')
8360 # Builds sub/foo from sub/foo.c
8361 env.Program(target = 'foo', source = 'foo.c')
8363 SConscript('dir/SConscript')
8368 # Builds sub/dir/foo from sub/dir/foo.c
8369 env.Program(target = 'foo', source = 'foo.c')
8372 .SS Sharing Variables Between SConscript Files
8374 You must explicitly Export() and Import() variables that
8375 you want to share between SConscript files.
8381 env.Program(target = 'foo', source = 'foo.c')
8384 SConscript('subdirectory/SConscript')
8386 subdirectory/SConscript:
8389 env.Program(target = 'foo', source = 'foo.c')
8392 .SS Building Multiple Variants From the Same Source
8394 Use the BuildDir() method to establish
8395 one or more separate build directories for
8396 a given source directory,
8397 then use the SConscript() method
8398 to specify the SConscript files
8399 in the build directories:
8406 BuildDir('foo', 'src')
8407 SConscript('foo/SConscript')
8411 BuildDir('bar', 'src')
8412 SConscript('bar/SConscript')
8417 env = Environment(CCFLAGS = ccflags)
8418 env.Program(target = 'src', source = 'src.c')
8421 Note the use of the Export() method
8422 to set the "ccflags" variable to a different
8423 value for each variant build.
8425 .SS Hierarchical Build of Two Libraries Linked With a Program
8430 env = Environment(LIBPATH = ['#libA', '#libB'])
8432 SConscript('libA/SConscript')
8433 SConscript('libB/SConscript')
8434 SConscript('Main/SConscript')
8439 env.Library('a', Split('a1.c a2.c a3.c'))
8444 env.Library('b', Split('b1.c b2.c b3.c'))
8449 e = env.Copy(LIBS = ['a', 'b'])
8450 e.Program('foo', Split('m1.c m2.c m3.c'))
8453 The '#' in the LIBPATH directories specify that they're relative to the
8454 top-level directory, so they don't turn into "Main/libA" when they're
8455 used in Main/SConscript.
8457 Specifying only 'a' and 'b' for the library names
8458 allows SCons to append the appropriate library
8459 prefix and suffix for the current platform
8460 (for example, 'liba.a' on POSIX systems,
8461 'a.lib' on Windows).
8463 .SS Customizing contruction variables from the command line.
8465 The following would allow the C compiler to be specified on the command
8466 line or in the file custom.py.
8469 opts = Options('custom.py')
8470 opts.Add('CC', 'The C compiler.')
8471 env = Environment(options=opts)
8472 Help(opts.GenerateHelpText(env))
8475 The user could specify the C compiler on the command line:
8481 or in the custom.py file:
8487 or get documentation on the options:
8498 .SS Using Microsoft Visual C++ precompiled headers
8500 Since windows.h includes everything and the kitchen sink, it can take quite
8501 some time to compile it over and over again for a bunch of object files, so
8502 Microsoft provides a mechanism to compile a set of headers once and then
8503 include the previously compiled headers in any object file. This
8504 technology is called precompiled headers. The general recipe is to create a
8505 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
8506 then include every header you want to precompile in "StdAfx.h", and finally
8507 include "StdAfx.h" as the first header in all the source files you are
8508 compiling to object files. For example:
8512 #include <windows.h>
8513 #include <my_big_header.h>
8532 /* do some other stuff */
8538 env['PCHSTOP'] = 'StdAfx.h'
8539 env['PCH'] = env.PCH('StdAfx.cpp')[0]
8540 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8543 For more information see the document for the PCH builder, and the PCH and
8544 PCHSTOP construction variables. To learn about the details of precompiled
8545 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
8547 .SS Using Microsoft Visual C++ external debugging information
8549 Since including debugging information in programs and shared libraries can
8550 cause their size to increase significantly, Microsoft provides a mechanism
8551 for including the debugging information in an external file called a PDB
8552 file. SCons supports PDB files through the PDB construction
8558 env['PDB'] = 'MyApp.pdb'
8559 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8562 For more information see the document for the PDB construction variable.
8567 Specifies the directory that contains the SCons Python module directory
8568 (e.g. /home/aroach/scons-src-0.01/src/engine).
8571 A string of options that will be used by scons in addition to those passed
8572 on the command line.
8583 Steven Knight <knight@baldmt.com>
8585 Anthony Roach <aroach@electriceyeball.com>