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.
426 This specifies how the
428 call should use or generate the
429 results of configuration tests.
430 The option should be specified from
431 among the following choices:
435 scons will use its normal dependency mechanisms
436 to decide if a test must be rebuilt or not.
437 This saves time by not running the same configuration tests
438 every time you invoke scons,
439 but will overlook changes in system header files
440 or external commands (such as compilers)
441 if you don't specify those dependecies explicitly.
442 This is the default behavior.
446 If this option is specified,
447 all configuration tests will be re-run
448 regardless of whether the
449 cached results are out of date.
450 This can be used to explicitly
451 force the configuration tests to be updated
452 in response to an otherwise unconfigured change
453 in a system header file or compiler.
457 If this option is specified,
458 no configuration tests will be rerun
459 and all results will be taken from cache.
460 Note that scons will still consider it an error
461 if --config=cache is specified
462 and a necessary test does not
463 yet have any results in the cache.
466 .RI "-C" " directory" ", --directory=" directory
467 Change to the specified
469 before searching for the
474 file, or doing anything
477 options are interpreted
478 relative to the previous one, and the right-most
480 option wins. (This option is nearly
482 .BR "-f directory/SConstruct" ,
483 except that it will search for
488 in the specified directory.)
492 .\" Display dependencies while building target files. Useful for
493 .\" figuring out why a specific file is being rebuilt, as well as
494 .\" general debugging of the build process.
498 Works exactly the same way as the
500 option except for the way default targets are handled.
501 When this option is used and no targets are specified on the command line,
502 all default targets are built, whether or not they are below the current
507 Debug the build process.
509 specifies what type of debugging:
513 Print a count of how many objects are created
514 of the various classes used internally by SCons.
515 This only works when run under Python 2.1 or later.
519 Print the dependency tree
520 after each top-level target is built. This prints out only derived files.
524 Print the include tree after each top-level target is built.
525 This is generally used to find out what files are included by the sources
526 of a given derived file:
529 $ scons --debug=includes foo.o
534 Prints how much memory SCons uses
535 before and after reading the SConscript files
536 and before and after building.
540 Prints a list of the various objects
541 of the various classes used internally by SCons.
542 This only works when run under Python 2.1 or later.
546 Re-run SCons under the control of the
553 Print the raw command line used to build each target
554 before the construction environment variables are substituted.
555 Also shows which targets are being built by this command.
556 Output looks something like this:
558 $ scons --debug=presub
559 Building myprog.o with action(s):
560 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
566 Prints an internal Python stack trace
567 when encountering an otherwise unexplained error.
571 Prints various time profiling information: the time spent
572 executing each build command, the total build time, the total time spent
573 executing build commands, the total time spent executing SConstruct and
574 SConscript files, and the total time spent executing SCons itself.
578 Print the dependency tree
579 after each top-level target is built. This prints out the complete
580 dependency tree including implicit dependencies and ignored
584 .\" -e, --environment-overrides
585 .\" Variables from the execution environment override construction
586 .\" variables from the SConscript files.
589 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
592 as the initial SConscript file.
596 Print a local help message for this build, if one is defined in
597 the SConscript file(s), plus a line that describes the
599 option for command-line option help. If no local help message
600 is defined, prints the standard help message about command-line
601 options. Exits after displaying the appropriate message.
605 Print the standard help message about command-line options and
610 Ignore all errors from commands executed to rebuild files.
613 .RI -I " directory" ", --include-dir=" directory
617 imported Python modules. If several
620 are used, the directories are searched in the order specified.
624 Cache implicit dependencies. This can cause
626 to miss changes in the implicit dependencies in cases where a new implicit
627 dependency is added earlier in the implicit dependency search path
628 (e.g. CPPPATH) than a current implicit dependency with the same name.
631 --implicit-deps-changed
632 Force SCons to ignore the cached implicit dependencies. This causes the
633 implicit dependencies to be rescanned and recached. This implies
634 .BR --implicit-cache .
637 --implicit-deps-unchanged
638 Force SCons to ignore changes in the implicit dependencies.
639 This causes cached implicit dependencies to always be used.
641 .BR --implicit-cache .
644 .RI -j " N" ", --jobs=" N
645 Specifies the number of jobs (commands) to run simultaneously.
646 If there is more than one
648 option, the last one is effective.
652 .\" is specified without an argument,
654 .\" will not limit the number of
655 .\" simultaneous jobs.
659 Continue as much as possible after an error. The target that
660 failed and those that depend on it will not be remade, but other
661 targets specified on the command line will still be processed.
664 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
665 .\" No new jobs (commands) will be started if
666 .\" there are other jobs running and the system load
667 .\" average is at least
669 .\" (a floating-point number).
672 .RI --duplicate= ORDER
673 There are three ways to duplicate files in a build tree: hard links,
674 soft (symbolic) links and copies. The default behaviour of SCons is to
675 prefer hard links to soft links to copies. You can specify different
676 behaviours with this option.
686 SCons will attempt to duplicate files using
687 the mechanisms in the specified order.
692 .\" List derived files (targets, dependencies) that would be built,
693 .\" but do not build them.
694 .\" [XXX This can probably go away with the right
695 .\" combination of other options. Revisit this issue.]
699 .\" List derived files that would be built, with the actions
700 .\" (commands) that build them. Does not build the files.
701 .\" [XXX This can probably go away with the right
702 .\" combination of other options. Revisit this issue.]
706 .\" List derived files that would be built, plus where the file is
707 .\" defined (file name and line number). Does not build the files.
708 .\" [XXX This can probably go away with the right
709 .\" combination of other options. Revisit this issue.]
713 Ignored for compatibility with non-GNU versions of
717 .RI --max-drift= SECONDS
718 Set the maximum expected drift in the modification time of files to
720 This value determines how old a file must be before its content signature
721 is cached. The default value is 2 days, which means a file must have a
722 modification time of at least two days ago in order to have its content
723 signature cached. A negative value means to never cache the content
724 signature and to ignore the cached value if there already is one. A value
725 of 0 means to always cache the signature, no matter how old the file is.
728 -n, --just-print, --dry-run, --recon
729 No execute. Print the commands that would be executed to build
730 any out-of-date target files, but do not execute the commands.
733 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
737 .\" not rebuild anything due to changes in the contents of
740 .\" .RI --override " file"
741 .\" Read values to override specific build environment variables
742 .\" from the specified
746 .\" Print the data base (construction environments,
747 .\" Builder and Scanner objects) that are defined
748 .\" after reading the SConscript files.
749 .\" After printing, a normal build is performed
750 .\" as usual, as specified by other command-line options.
751 .\" This also prints version information
756 .\" To print the database without performing a build do:
764 Run SCons under the Python profiler
765 and save the results in the specified
767 The results may be analyzed using the Python
771 Do not run any commands, or print anything. Just return an exit
772 status that is zero if the specified targets are already up to
773 date, non-zero otherwise.
776 Quiets SCons status messages about
777 reading SConscript files,
779 and entering directories.
780 Commands that are executed
781 to rebuild target files are still printed.
784 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
785 .\" Clear the default construction variables. Construction
786 .\" environments that are created will be completely empty.
790 Build dependencies in a random order. This is useful when
791 building multiple trees simultaneously with caching enabled,
792 to prevent multiple builds from simultaneously trying to build
793 or retrieve the same target files.
796 -s, --silent, --quiet
797 Silent. Do not print commands that are executed to rebuild
799 Also suppresses SCons status messages.
802 -S, --no-keep-going, --stop
803 Ignored for compatibility with GNU
808 Ignored for compatibility with GNU
810 (Touching a file to make it
811 appear up-to-date is unnecessary when using
815 -u, --up, --search-up
816 Walks up the directory structure until an
821 file is found, and uses that
822 as the top of the directory tree.
823 If no targets are specified on the command line,
824 only targets at or below the
825 current directory will be built.
829 Works exactly the same way as the
831 option except for the way default targets are handled.
832 When this option is used and no targets are specified on the command line,
833 all default targets that are defined in the SConscript(s) in the current
834 directory are built, regardless of what directory the resultant targets end
841 version, copyright information,
842 list of authors, and any other relevant information.
846 -w, --print-directory
847 Print a message containing the working directory before and
848 after other processing.
851 .RI --warn= type ", --warn=no-" type
852 Enable or disable warnings.
854 specifies the type of warnings to be enabled or disabled:
857 --warn=all, --warn=no-all
858 Enables or disables all warnings.
861 --warn=dependency, --warn=no-dependency
862 Enables or disables warnings about dependencies.
863 These warnings are disabled by default.
866 --warn=deprecated, --warn=no-deprecated
867 Enables or disables warnings about use of deprecated features.
868 These warnings are enabled by default.
871 --warn=missing-sconscript, --warn=no-missing-sconscript
872 Enables or disables warnings about missing SConscript files.
873 These warnings are enabled by default.
877 Turn off -w, even if it was turned on implicitly.
880 .\" .RI --write-filenames= file
881 .\" Write all filenames considered into
885 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
886 .\" Pretend that the target
889 .\" modified. When used with the
892 .\" show you what would be rebuilt if you were to modify that file.
898 .\" --warn-undefined-variables
899 .\" Warn when an undefined variable is referenced.
902 .RI -Y " repository" ", --repository=" repository
903 Search the specified repository for any input and target
904 files not found in the local directory hierarchy. Multiple
906 options may specified, in which case the
907 repositories are searched in the order specified.
909 .SH CONFIGURATION FILE REFERENCE
910 .\" .SS Python Basics
911 .\" XXX Adding this in the future would be a help.
912 .SS Construction Environments
913 A construction environment is the basic means by which the SConscript
914 files communicate build information to
916 A new construction environment is created using the
924 By default, a new construction environment is
925 initialized with a set of builder methods
926 and construction variables that are appropriate
927 for the current platform.
928 An optional platform keyword argument may be
929 used to specify that an environment should
930 be initialized for a different platform:
933 env = Environment(platform = 'cygwin')
934 env = Environment(platform = 'os2')
935 env = Environment(platform = 'posix')
936 env = Environment(platform = 'win32')
939 Specifying a platform initializes the appropriate
940 construction variables in the environment
941 to use and generate file names with prefixes
942 and suffixes appropriate for the platform.
948 variable from the user's external environment
949 to the construction environment's
952 This is so that any executed commands
953 that use sockets to connect with other systems
954 (such as fetching source files from
955 external CVS repository specifications like
956 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
957 will work on Win32 systems.
959 The platform argument may be function or callable object,
960 in which case the Environment() method
961 will call the specified argument to update
962 the new construction environment:
965 def my_platform(env):
968 env = Environment(platform = my_platform)
971 Additionally, a specific set of tools
972 with which to initialize the environment
973 may specified as an optional keyword argument:
976 env = Environment(tools = ['msvc', 'lex'])
979 Non-built-in tools may be specified using the toolpath argument:
982 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
985 This looks for a tool specification in tools/foo.py (as well as
986 using the ordinary default tools for the platform). foo.py should
987 have two functions: generate(env) and exists(env). generate()
988 modifies the passed in environment and exists() should return a true
989 value if the tool is available. Tools in the toolpath are used before
990 any of the built-in ones. For example, adding gcc.py to the toolpath
991 would override the built-in gcc tool.
993 The elements of the tools list may also
994 be functions or callable objects,
995 in which case the Environment() method
996 will call the specified elements
997 to update the new construction environment:
1001 env['XYZZY'] = 'xyzzy'
1003 env = Environment(tools = [my_tool])
1006 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1007 the environment it receives to customize the tool for different platforms.
1009 If no tool list is specified, then SCons will auto-detect the installed
1010 tools using the PATH variable in the ENV construction variable and the
1011 platform name when the Environment is constructed. Changing the PATH
1012 variable after the Environment is constructed will not cause the tools to
1015 SCons supports the following tool specifications out of the box:
1088 Additionally, there is a "tool" named
1090 which configures the
1091 environment with a default set of tools for the current platform.
1093 On posix and cygwin platforms
1094 the GNU tools (e.g. gcc) are preferred by SCons,
1095 on win32 the Microsoft tools (e.g. msvc)
1096 followed by MinGW are preferred by SCons,
1097 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1101 Build rules are specified by calling a construction
1102 environment's builder methods.
1103 The arguments to the builder methods are
1105 (a list of target files)
1108 (a list of source files).
1110 Because long lists of file names
1111 can lead to a lot of quoting,
1116 and a same-named environment method
1117 that split a single string
1118 into a list, separated on
1119 strings of white-space characters.
1120 (These are similar to the
1121 string.split() method
1122 from the standard Python library,
1123 but work even if the input isn't a string.)
1125 Like all Python arguments,
1126 the target and source arguments to a builder method
1127 can be specified either with or without
1128 the "target" and "source" keywords.
1129 When the keywords are omitted,
1130 the target is first,
1131 followed by the source.
1132 The following are equivalent examples of calling the Program builder method:
1135 env.Program('bar', ['bar.c', 'foo.c'])
1136 env.Program('bar', Split('bar.c foo.c'))
1137 env.Program('bar', env.Split('bar.c foo.c'))
1138 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1139 env.Program(target = 'bar', Split('bar.c foo.c'))
1140 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1141 env.Program('bar', source = string.split('bar.c foo.c'))
1144 When the target shares the same base name
1145 as the source and only the suffix varies,
1146 and if the builder method has a suffix defined for the target file type,
1147 then the target argument may be omitted completely,
1150 will deduce the target file name from
1151 the source file name.
1152 The following examples all build the
1158 (on Windows systems)
1159 from the bar.c source file:
1162 env.Program(target = 'bar', source = 'bar.c')
1163 env.Program('bar', source = 'bar.c')
1164 env.Program(source = 'bar.c')
1165 env.Program('bar.c')
1168 It is possible to override or add construction variables when calling a
1169 builder method by passing additional keyword arguments.
1170 These overridden or added
1171 variables will only be in effect when building the target, so they will not
1172 affect other parts of the build. For example, if you want to add additional
1173 libraries for just one program:
1176 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1179 or generate a shared library with a nonstandard suffix:
1182 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1185 Although the builder methods defined by
1188 methods of a construction environment object,
1189 they may also be called without an explicit environment:
1192 Program('hello', 'hello.c')
1193 SharedLibrary('word', 'word.cpp')
1197 the methods are called internally using a default construction
1198 environment that consists of the tools and values that
1200 has determined are appropriate for the local system.
1202 All builder methods return a list of Nodes
1203 that represent the target or targets that will be built.
1206 is an internal SCons object
1208 build targets or sources.
1210 The returned Node(s)
1211 can be passed to other builder methods as source(s)
1212 or passed to any SCons function or method
1213 where a filename would normally be accepted.
1214 For example, if it were necessary
1217 flag when compiling one specific object file:
1220 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1221 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1224 Using a Node in this way
1225 makes for a more portable build
1226 by avoiding having to specify
1227 a platform-specific object suffix
1228 when calling the Program() builder method.
1230 Note that Builder calls will automatically "flatten"
1231 the source and target file lists,
1232 so it's all right to have the bar_obj list
1233 return by the StaticObject() call
1234 in the middle of the source file list.
1235 If you need to manipulate a list of lists returned by Builders
1236 directly using Python,
1237 you can either build the list by hand:
1240 foo = Object('foo.c')
1241 bar = Object('bar.c')
1242 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1243 for object in objects:
1250 to create a list containing just the Nodes,
1251 which may be more convenient:
1254 foo = Object('foo.c')
1255 bar = Object('bar.c')
1256 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1257 for object in objects:
1261 The path name for a Node's file may be used
1262 by passing the Node to the Python-builtin
1267 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1268 print "The path to bar_obj is:", str(bar_obj_list[0])
1271 Note again that because the Builder call returns a list,
1272 we have to access the first element in the list
1273 .B (bar_obj_list[0])
1274 to get at the Node that actually represents
1278 provides the following builder methods:
1280 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1283 Builds a C source file given a lex (.l) or yacc (.y) input file.
1284 The suffix specified by the $CFILESUFFIX construction variable
1286 is automatically added to the target
1287 if it is not already present. Example:
1291 env.CFile(target = 'foo.c', source = 'foo.l')
1293 env.CFile(target = 'bar', source = 'bar.y')
1296 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1299 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1301 The suffix specified by the $CXXFILESUFFIX construction variable
1303 is automatically added to the target
1304 if it is not already present. Example:
1308 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1310 env.CXXFile(target = 'bar', source = 'bar.yy')
1313 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1316 Builds a .dvi file from a .tex, .ltx or .latex input file.
1317 If the source file suffix is .tex,
1319 will examine the contents of the file;
1324 is found, the file is assumed to be a LaTeX file and
1325 the target is built by invoking the $LATEXCOM command line;
1326 otherwise, the $TEXCOM command line is used.
1327 If the file is a LaTeX file,
1330 builder method will also examine the contents
1333 and invoke the $BIBTEX command line
1337 and will examine the contents
1339 file and re-run the $LATEXCOM command
1340 if the log file says it is necessary.
1343 (hard-coded within TeX itself)
1344 is automatically added to the target
1345 if it is not already present. Examples:
1348 # builds from aaa.tex
1349 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1351 env.DVI(target = 'bbb', source = 'bbb.ltx')
1352 # builds from ccc.latex
1353 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1356 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1359 Builds a Java archive (.jar) file
1360 from a source tree of .class files.
1361 If the $JARCHDIR value is set, the
1363 command will change to the specified directory using the
1366 If the contents any of the source files begin with the string
1367 .BR Manifest-Version ,
1368 the file is assumed to be a manifest
1369 and is passed to the
1376 env.Jar(target = 'foo.jar', source = 'classes')
1379 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1382 Builds one or more Java class files
1383 from one or more source trees of .java files.
1384 The class files will be placed underneath
1385 the specified target directory.
1386 SCons will parse each source .java file
1388 (including inner classes)
1389 defined within that file,
1390 and from that figure out the
1391 target .class files that will be created.
1392 SCons will also search each Java file
1393 for the Java package name,
1394 which it assumes can be found on a line
1395 beginning with the string
1397 in the first column;
1398 the resulting .class files
1399 will be placed in a directory reflecting
1400 the specified package name.
1404 defining a single public
1407 containing a package name of
1409 will generate a corresponding
1410 .IR sub/dir/Foo.class
1416 env.Java(target = 'classes', source = 'src')
1417 env.Java(target = 'classes', source = ['src1', 'src2'])
1420 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1423 Builds C header and source files for
1424 implementing Java native methods.
1425 The target can be either a directory
1426 in which the header files will be written,
1427 or a header file name which
1428 will contain all of the definitions.
1429 The source can be either the names of .class files,
1430 or the objects returned from the
1434 If the construction variable
1436 is set, either in the environment
1437 or in the call to the
1439 builder method itself,
1440 then the value of the variable
1441 will be stripped from the
1442 beginning of any .class file names.
1447 # builds java_native.h
1448 classes = env.Java(target = 'classdir', source = 'src')
1449 env.JavaH(target = 'java_native.h', source = classes)
1451 # builds include/package_foo.h and include/package_bar.h
1452 env.JavaH(target = 'include',
1453 source = ['package/foo.class', 'package/bar.class'])
1455 # builds export/foo.h and export/bar.h
1456 env.JavaH(target = 'export',
1457 source = ['classes/foo.class', 'classes/bar.class'],
1458 JAVACLASSDIR = 'classes')
1461 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1468 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1471 Builds an output file from an M4 input file.
1472 This uses a default $M4FLAGS value of
1474 which considers all warnings to be fatal
1475 and stops on the first warning
1476 when using the GNU version of m4.
1480 env.M4(target = 'foo.c', source = 'foo.c.m4')
1483 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1486 Builds an output file from a moc input file. Moc input files are either
1487 header files or cxx files. This builder is only available after using the
1488 tool 'qt'. See the QTDIR variable for more information.
1492 env.Moc('foo.h') # generates moc_foo.cc
1493 env.Moc('foo.cpp') # generates foo.moc
1496 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1498 .IP env.MSVSProject()
1499 Builds Microsoft Visual Studio project files.
1500 This builds a Visual Studio project file, based on the version of
1501 Visual Studio that is configured (either the latest installed version,
1502 or the version set by
1504 in the Environment constructor).
1505 For VS 6, it will generate
1509 files, for VS 7, it will
1516 It takes several lists of filenames to be placed into the project
1517 file, currently these are limited to
1518 .B srcs, incs, localincs, resources,
1521 These are pretty self explanatory, but it
1522 should be noted that the 'srcs' list is NOT added to the $SOURCES
1523 environment variable. This is because it represents a list of files
1524 to be added to the project file, not the source used to build the
1525 project file (in this case, the 'source' is the SConscript file used
1526 to call MSVSProject).
1528 In addition to these values (which are all optional, although not
1529 specifying any of them results in an empty project file), the
1530 following values must be specified:
1532 target: The name of the target .dsp or .vcproj file. The correct
1533 suffix for the version of Visual Studio must be used, but the value
1535 env['MSVSPROJECTSUFFIX']
1537 will be defined to the correct value (see example below).
1539 variant: The name of this particular variant. These are typically
1540 things like "Debug" or "Release", but really can be anything you want.
1541 Multiple calls to MSVSProject with different variants are allowed: all
1542 variants will be added to the project file with their appropriate
1543 build targets and sources.
1545 buildtarget: A list of SCons.Node.FS objects which is returned from
1546 the command which builds the target. This is used to tell SCons what
1547 to build when the 'build' button is pressed inside of the IDE.
1552 barsrcs = ['bar.cpp'],
1553 barincs = ['bar.h'],
1554 barlocalincs = ['StdAfx.h']
1555 barresources = ['bar.rc','resource.h']
1556 barmisc = ['bar_readme.txt']
1558 dll = local.SharedLibrary(target = 'bar.dll',
1561 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1564 localincs = barlocalincs,
1565 resources = barresources,
1568 variant = 'Release')
1571 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1578 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1581 Builds a Microsoft Visual C++ precompiled header.
1582 Calling this builder method
1583 returns a list of two targets: the PCH as the first element, and the object
1584 file as the second element. Normally the object file is ignored.
1585 This builder method is only
1586 provided when Microsoft Visual C++ is being used as the compiler.
1587 The PCH builder method is generally used in
1588 conjuction with the PCH construction variable to force object files to use
1589 the precompiled header:
1592 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1598 Builds a .pdf file from a .dvi input file
1599 (or, by extension, a .tex, .ltx, or .latex input file).
1600 The suffix specified by the $PDFSUFFIX construction variable
1602 is added automatically to the target
1603 if it is not already present. Example:
1606 # builds from aaa.tex
1607 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1608 # builds bbb.pdf from bbb.dvi
1609 env.PDF(target = 'bbb', source = 'bbb.dvi')
1612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1614 .IP env.PostScript()
1615 Builds a .ps file from a .dvi input file
1616 (or, by extension, a .tex, .ltx, or .latex input file).
1617 The suffix specified by the $PSSUFFIX construction variable
1619 is added automatically to the target
1620 if it is not already present. Example:
1623 # builds from aaa.tex
1624 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1625 # builds bbb.ps from bbb.dvi
1626 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1629 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1632 Builds an executable given one or more object files
1633 or C, C++, D, or Fortran source files.
1634 If any C, C++, D or Fortran source files are specified,
1635 then they will be automatically
1636 compiled to object files using the
1639 see that builder method's description for
1640 a list of legal source file suffixes
1641 and how they are interpreted.
1642 The target executable file prefix
1643 (specified by the $PROGPREFIX construction variable; nothing by default)
1645 (specified by the $PROGSUFFIX construction variable;
1646 by default, .exe on Windows systems, nothing on POSIX systems)
1647 are automatically added to the target if not already present.
1651 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1654 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1657 Builds a Microsoft Visual C++ resource file.
1658 This builder method is only provided
1659 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1663 for MinGW) suffix is added to the target name if no other suffix is given. The source
1664 file is scanned for implicit dependencies as though it were a C file. Example:
1667 env.RES('resource.rc')
1670 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1673 Builds stub and skeleton class files
1675 from Java .class files.
1676 The target is a directory
1677 relative to which the stub
1678 and skeleton class files will be written.
1679 The source can be the names of .class files,
1680 or the objects return from the
1684 If the construction variable
1686 is set, either in the environment
1687 or in the call to the
1689 builder method itself,
1690 then the value of the variable
1691 will be stripped from the
1692 beginning of any .class file names.
1695 classes = env.Java(target = 'classdir', source = 'src')
1696 env.RMIC(target = 'outdir1', source = classes)
1698 env.RMIC(target = 'outdir2',
1699 source = ['package/foo.class', 'package/bar.class'])
1701 env.RMIC(target = 'outdir3',
1702 source = ['classes/foo.class', 'classes/bar.class'],
1703 JAVACLASSDIR = 'classes')
1706 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1708 .IP env.RPCGenClient()
1709 Generates an RPC client stub (_clnt.c) file
1710 from a specified RPC (.x) source file.
1711 Because rpcgen only builds output files
1712 in the local directory,
1713 the command will be executed
1714 in the source file's directory by default.
1717 # Builds src/rpcif_clnt.c
1718 env.RPCGenClient('src/rpcif.x')
1721 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1723 .IP env.RPCGenHeader()
1724 Generates an RPC header (.h) file
1725 from a specified RPC (.x) source file.
1726 Because rpcgen only builds output files
1727 in the local directory,
1728 the command will be executed
1729 in the source file's directory by default.
1732 # Builds src/rpcif.h
1733 env.RPCGenHeader('src/rpcif.x')
1736 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1738 .IP env.RPCGenService()
1739 Generates an RPC server-skeleton (_svc.c) file
1740 from a specified RPC (.x) source file.
1741 Because rpcgen only builds output files
1742 in the local directory,
1743 the command will be executed
1744 in the source file's directory by default.
1747 # Builds src/rpcif_svc.c
1748 env.RPCGenClient('src/rpcif.x')
1751 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1754 Generates an RPC XDR routine (_xdr.c) file
1755 from a specified RPC (.x) source file.
1756 Because rpcgen only builds output files
1757 in the local directory,
1758 the command will be executed
1759 in the source file's directory by default.
1762 # Builds src/rpcif_xdr.c
1763 env.RPCGenClient('src/rpcif.x')
1766 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1768 .IP env.SharedLibrary()
1769 Builds a shared library
1770 (.so on a POSIX system, .dll on WIN32)
1771 given one or more object files
1772 or C, C++, D or Fortran source files.
1773 If any source files are given,
1774 then they will be automatically
1775 compiled to object files.
1776 The static library prefix and suffix (if any)
1777 are automatically added to the target.
1778 The target library file prefix
1779 (specified by the $SHLIBPREFIX construction variable;
1780 by default, lib on POSIX systems, nothing on Windows systems)
1782 (specified by the $SHLIBSUFFIX construction variable;
1783 by default, .dll on Windows systems, .so on POSIX systems)
1784 are automatically added to the target if not already present.
1788 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1791 On WIN32 systems, the
1793 builder method will always build an import (.lib) library
1794 in addition to the shared (.dll) library,
1795 adding a .lib library with the same basename
1796 if there is not already a .lib file explicitly
1797 listed in the targets.
1799 Any object files listed in the
1801 must have been built for a shared library
1806 will raise an error if there is any mismatch.
1808 On WIN32 systems, specifying "register=1" will cause the dll to be
1809 registered after it is built using REGSVR32. The command that is run
1810 ("regsvr32" by default) is determined by $REGSVR construction
1811 variable, and the flags passed are determined by $REGSVRFLAGS. By
1812 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1813 up and requiring user attention when it is run. If you change
1814 $REGSVRFLAGS, be sure to include "/s". For example,
1817 env.SharedLibrary(target = 'bar',
1818 source = ['bar.cxx', 'foo.obj'],
1823 will register "bar.dll" as a COM object when it is done linking it.
1825 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1827 .IP env.SharedObject()
1828 Builds an object file for
1829 inclusion in a shared library.
1830 Source files must have one of the same set of extensions
1831 specified above for the
1834 On some platforms building a shared object requires additional
1835 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1836 normal (static) object, but on some platforms there is no difference between a
1837 shared object and a normal (static) one. When there is a difference, SCons
1838 will only allow shared objects to be linked into a shared library, and will
1839 use a different suffix for shared objects. On platforms where there is no
1840 difference, SCons will allow both normal (static)
1841 and shared objects to be linked into a
1842 shared library, and will use the same suffix for shared and normal
1844 The target object file prefix
1845 (specified by the $SHOBJPREFIX construction variable;
1846 by default, the same as $OBJPREFIX)
1848 (specified by the $SHOBJSUFFIX construction variable)
1849 are automatically added to the target if not already present.
1853 env.SharedObject(target = 'ddd', source = 'ddd.c')
1854 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1855 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1858 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1860 .IP env.StaticLibrary()
1861 Builds a static library given one or more object files
1862 or C, C++, D or Fortran source files.
1863 If any source files are given,
1864 then they will be automatically
1865 compiled to object files.
1866 The static library prefix and suffix (if any)
1867 are automatically added to the target.
1868 The target library file prefix
1869 (specified by the $LIBPREFIX construction variable;
1870 by default, lib on POSIX systems, nothing on Windows systems)
1872 (specified by the $LIBSUFFIX construction variable;
1873 by default, .lib on Windows systems, .a on POSIX systems)
1874 are automatically added to the target if not already present.
1878 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1882 Any object files listed in the
1884 must have been built for a static library
1889 will raise an error if there is any mismatch.
1891 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1893 .IP env.StaticObject()
1894 Builds a static object file
1895 from one or more C, C++, D, or Fortran source files.
1896 Source files must have one of the following extensions:
1899 .asm assembly language file
1900 .ASM assembly language file
1912 .F WIN32: Fortran file
1913 POSIX: Fortran file + C pre-processor
1916 .fpp Fortran file + C pre-processor
1917 .FPP Fortran file + C pre-processor
1918 .s assembly language file
1919 .S WIN32: assembly language file
1920 POSIX: assembly language file + C pre-processor
1921 .spp assembly language file + C pre-processor
1922 .SPP assembly language file + C pre-processor
1925 The target object file prefix
1926 (specified by the $OBJPREFIX construction variable; nothing by default)
1928 (specified by the $OBJSUFFIX construction variable;
1929 \.obj on Windows systems, .o on POSIX systems)
1930 are automatically added to the target if not already present.
1934 env.StaticObject(target = 'aaa', source = 'aaa.c')
1935 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1936 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1939 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1942 Builds a tar archive of the specified files
1944 Unlike most builder methods,
1947 builder method may be called multiple times
1949 each additional call
1950 adds to the list of entries
1951 that will be built into the archive.
1954 env.Tar('src.tar', 'src')
1956 # Create the stuff.tar file.
1957 env.Tar('stuff', ['subdir1', 'subdir2'])
1958 # Also add "another" to the stuff.tar file.
1959 env.Tar('stuff', 'another')
1961 # Set TARFLAGS to create a gzip-filtered archive.
1962 env = Environment(TARFLAGS = '-c -z')
1963 env.Tar('foo.tar.gz', 'foo')
1965 # Also set the suffix to .tgz.
1966 env = Environment(TARFLAGS = '-c -z',
1971 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1973 .IP env.TypeLibrary()
1974 Builds a Windows type library (.tlb) file from and input IDL file
1975 (.idl). In addition, it will build the associated inteface stub and
1976 proxy source files. It names them according to the base name of the .idl file.
1981 env.TypeLibrary(source="foo.idl")
1984 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1986 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1989 Builds a header file, an implementation file and a moc file from an ui file.
1990 and returns the corresponding nodes in the above order.
1991 This builder is only available after using the tool 'qt'. Note: you can
1992 specify .ui files directly as inputs for Program, Library and SharedLibrary
1993 without using this builder. Using the builder lets you override the standard
1994 naming conventions (be careful: prefixes are always prepended to names of
1995 built files; if you don't want prefixes, you may set them to ``).
1996 See the QTDIR variable for more information.
2000 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2001 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2002 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2005 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2008 Builds a zip archive of the specified files
2010 Unlike most builder methods,
2013 builder method may be called multiple times
2015 each additional call
2016 adds to the list of entries
2017 that will be built into the archive.
2020 env.Zip('src.zip', 'src')
2022 # Create the stuff.zip file.
2023 env.Zip('stuff', ['subdir1', 'subdir2'])
2024 # Also add "another" to the stuff.tar file.
2025 env.Zip('stuff', 'another')
2030 C source files, C++ source files,
2031 Fortran source files with
2033 (POSIX systems only),
2038 and assembly language files with
2040 (POSIX systems only),
2045 for C preprocessor dependencies,
2046 so the dependencies do not need to be specified explicitly.
2048 targets of builder methods automatically depend on their sources.
2049 An explicit dependency can
2050 be specified using the
2052 method of a construction environment (see below).
2054 .SS Methods and Functions to Do Things
2055 In addition to Builder methods,
2057 provides a number of other construction environment methods
2058 and global functions to
2059 manipulate the build configuration.
2061 Usually, a construction environment method
2062 and global function with the same name both exist
2063 so that you don't have to remember whether
2064 to a specific bit of functionality
2065 must be called with or without a construction environment.
2066 In the following list,
2067 if you call something as a global function
2070 .RI Function( arguments )
2072 and if you call something through a construction
2073 environment it looks like:
2075 .RI env.Function( arguments )
2077 If you can call the functionality in both ways,
2078 then both forms are listed.
2080 Except where otherwise noted,
2082 construction environment method
2084 provide the exact same functionality.
2085 The only difference is that,
2087 calling the functionality through a construction environment will
2088 substitute construction variables into
2089 any supplied strings.
2092 env = Environment(FOO = 'foo')
2096 the first call to the global
2098 function will actually add a target named
2100 to the list of default targets,
2101 while the second call to the
2103 construction environment method
2104 will expand the value
2105 and add a target named
2107 to the list of default targets.
2108 For more on construction variable expansion,
2109 see the next section on
2110 construction variables.
2112 Construction environment methods
2113 and global functions supported by
2117 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2119 .RI Action( action ", [" strfunction ", " varlist ])
2121 .RI env.Action( action ", [" strfunction ", " varlist ])
2122 Creates an Action object for
2125 See the section "Action Objects,"
2126 below, for a complete explanation of the arguments and behavior.
2128 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2130 .RI AddPostAction( target ", " action )
2132 .RI env.AddPostAction( target ", " action )
2133 Arranges for the specified
2139 The specified action(s) may be
2140 an Action object, or anything that
2141 can be converted into an Action object
2144 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2146 .RI AddPreAction( target ", " action )
2148 .RI env.AddPreAction( target ", " action )
2149 Arranges for the specified
2152 before the specified
2155 The specified action(s) may be
2156 an Action object, or anything that
2157 can be converted into an Action object
2160 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2162 .RI Alias( alias ", [" targets ])
2164 .RI env.Alias( alias ", [" targets ])
2165 Creates one or more phony targets that
2166 expand to one or more other targets.
2167 Returns the Node object representing the alias,
2168 which exists outside of any file system.
2169 This Node object, or the alias name,
2170 may be used as a dependency of any other target,
2171 including another alias.
2173 can be called multiple times for the same
2174 alias to add additional targets to the alias.
2178 Alias('install', '/usr/bin')
2179 Alias(['install', 'install-lib'], '/usr/local/lib')
2181 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2182 env.Alias('install', ['/usr/local/man'])
2185 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2187 .RI AlwaysBuild( target ", ...)"
2189 .RI env.AlwaysBuild( target ", ...)"
2192 so that it is always assumed to be out of date,
2193 and will always be rebuilt if needed.
2196 does not add its target(s) to the default target list,
2197 so the targets will only be built
2198 if they are specified on the command line,
2199 or are a dependent of a target specified on the command line--but
2202 be built if so specified.
2203 Multiple targets can be passed in to a single call to
2206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2208 .RI env.Append( key = val ", [...])"
2209 Appends the specified keyword arguments
2210 to the end of construction variables in the environment.
2211 If the Environment does not have
2212 the specified construction variable,
2213 it is simply added to the environment.
2214 If the values of the construction variable
2215 and the keyword argument are the same type,
2216 then the two values will be simply added together.
2217 Otherwise, the construction variable
2218 and the value of the keyword argument
2219 are both coerced to lists,
2220 and the lists are added together.
2221 (See also the Prepend method, below.)
2224 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2227 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2229 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2230 This appends new path elements to the given path in the
2231 specified external environment
2235 any particular path once (leaving the last one it encounters and
2236 ignoring the rest, to preserve path order),
2237 and to help assure this,
2238 will normalize all paths (using
2241 .BR os.path.normcase ).
2242 This can also handle the
2243 case where the given old path variable is a list instead of a
2244 string, in which case a list will be returned instead of a string.
2248 print 'before:',env['ENV']['INCLUDE']
2249 include_path = '/foo/bar:/foo'
2250 env.PrependENVPath('INCLUDE', include_path)
2251 print 'after:',env['ENV']['INCLUDE']
2255 after: /biz:/foo/bar:/foo
2258 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2260 .RI env.AppendUnique( key = val ", [...])"
2261 Appends the specified keyword arguments
2262 to the end of construction variables in the environment.
2263 If the Environment does not have
2264 the specified construction variable,
2265 it is simply added to the environment.
2266 If the construction variable being appended to is a list,
2267 then any value(s) that already exist in the
2268 construction variable will
2270 be added again to the list.
2273 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2276 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2279 A factory function that
2280 returns a Builder object
2281 to be used to fetch source files
2283 The returned Builder
2284 is intended to be passed to the
2289 env.SourceCode('.', env.BitKeeper())
2292 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2294 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2296 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2297 This specifies a build directory
2299 in which to build all derived files
2300 that would normally be built under
2302 Multiple build directories can be set up for multiple build variants, for
2305 must be underneath the SConstruct file's directory,
2308 may not be underneath the
2311 The default behavior is for
2313 to duplicate all of the files in the tree underneath
2317 and then build the derived files within the copied tree.
2318 (The duplication is performed by
2320 depending on the platform; see also the
2323 This guarantees correct builds
2324 regardless of whether intermediate source files
2325 are generated during the build,
2326 where preprocessors or other scanners search
2328 or whether individual compilers or other invoked tools
2329 are hard-coded to put derived files in the same directory as source files.
2331 This behavior of making a complete copy of the source tree
2332 may be disabled by setting
2337 to invoke Builders using the
2338 path names of source files in
2340 and the path names of derived files within
2342 This is always more efficient than
2344 and is usually safe for most builds.
2348 may cause build problems
2349 if source files are generated during the build,
2350 if any invoked tools are hard-coded to
2351 put derived files in the same directory as the source files.
2353 Note that specifying a
2355 works most naturally
2356 with a subsidiary SConscript file
2357 in the source directory.
2359 you would then call the subsidiary SConscript file
2360 not in the source directory,
2365 had made a virtual copy of the source tree
2366 regardless of the value of
2368 This is how you tell
2370 which variant of a source tree to build.
2374 BuildDir('build-variant1', 'src')
2375 SConscript('build-variant1/SConscript')
2376 BuildDir('build-variant2', 'src')
2377 SConscript('build-variant2/SConscript')
2383 function, described below,
2385 specify a build directory
2386 in conjunction with calling a subsidiary
2389 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2391 .RI Builder( action ", [" arguments ])
2393 .RI env.Builder( action ", [" arguments ])
2394 Creates a Builder object for
2397 See the section "Builder Objects,"
2398 below, for a complete explanation of the arguments and behavior.
2400 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2402 .RI CacheDir( cache_dir )
2404 .RI env.CacheDir( cache_dir )
2407 will maintain a cache of derived files in
2409 The derived files in the cache will be shared
2410 among all the builds using the same
2418 finds a derived file that needs to be rebuilt,
2419 it will first look in the cache to see if a
2420 derived file has already been built
2421 from identical input files and an identical build action
2422 (as incorporated into the MD5 build signature).
2425 will retrieve the file from the cache.
2426 If the derived file is not present in the cache,
2429 then place a copy of the built file in the cache
2430 (identified by its MD5 build signature),
2431 so that it may be retrieved by other
2432 builds that need to build the same derived file
2433 from identical inputs.
2437 may be disabled for any invocation
2446 will place a copy of
2448 derived files in the cache,
2449 even if they already existed
2450 and were not built by this invocation.
2451 This is useful to populate a cache
2454 is added to a build,
2463 "Retrieved `file' from cache,"
2466 option is being used.
2471 will print the action that
2473 have been used to build the file,
2474 without any indication that
2475 the file was actually retrieved from the cache.
2476 This is useful to generate build logs
2477 that are equivalent regardless of whether
2478 a given derived file has been built in-place
2479 or retrieved from the cache.
2481 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2483 .RI Clean( targets ", " files_or_dirs )
2485 .RI env.Clean( targets ", " files_or_dirs )
2486 This specifies a list of files or directories which should be removed
2487 whenever the targets are specified with the
2489 command line option.
2490 The specified targets may be a list
2491 or an individual target.
2495 and create new targets or add files and directories to the
2496 clean list for the specified targets.
2498 Multiple files or directories should be specified
2499 either as separate arguments to the
2501 method, or as a list.
2503 will also accept the return value of any of the construction environment
2508 Clean('foo', ['bar', 'baz'])
2509 Clean('dist', env.Program('hello', 'hello.c'))
2510 Clean(['foo', 'bar'], 'something_else_to_clean')
2513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2515 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2517 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2518 Executes a specific action
2519 (or list of actions)
2520 to build a target file or files.
2521 This is more convenient
2522 than defining a separate Builder object
2523 for a single special-case build.
2524 Any keyword arguments specified override any
2525 same-named existing construction variables.
2527 Note that an action can be an external command,
2528 specified as a string,
2529 or a callable Python object;
2530 see "Action Objects," below.
2534 env.Command('foo.out', 'foo.in',
2535 "$FOO_BUILD < $SOURCES > $TARGET")
2537 env.Command('bar.out', 'bar.in',
2539 "$BAR_BUILD < $SOURCES > $TARGET"],
2540 ENV = {'PATH' : '/usr/local/bin/'})
2542 def rename(env, target, source):
2544 os.rename('.tmp', str(target[0]))
2546 env.Command('baz.out', 'baz.in',
2547 ["$BAZ_BUILD < $SOURCES > .tmp",
2551 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2553 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2555 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2556 Creates a Configure object for integrated
2557 functionality similar to GNU autoconf.
2558 See the section "Configure Contexts,"
2559 below, for a complete explanation of the arguments and behavior.
2561 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2563 .RI env.Copy([ key = val ", ...])"
2564 Return a separate copy of a construction environment.
2565 If there are any keyword arguments specified,
2566 they are added to the returned copy,
2567 overwriting any existing values
2572 env3 = env.Copy(CCFLAGS = '-g')
2575 Additionally, a list of tools and a toolpath may be specified, as in
2576 the Environment constructor:
2579 def MyTool(env): env['FOO'] = 'bar'
2580 env4 = env.Copy(tools = ['msvc', MyTool])
2583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2585 .RI env.CVS( repository ", " module )
2586 A factory function that
2587 returns a Builder object
2588 to be used to fetch source files
2592 The returned Builder
2593 is intended to be passed to the
2597 The optional specified
2599 will be added to the beginning
2600 of all repository path names;
2601 this can be used, in essence,
2602 to strip initial directory names
2603 from the repository path names,
2604 so that you only have to
2605 replicate part of the repository
2606 directory hierarchy in your
2607 local build directory:
2610 # Will fetch foo/bar/src.c
2611 # from /usr/local/CVSROOT/foo/bar/src.c.
2612 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2614 # Will fetch bar/src.c
2615 # from /usr/local/CVSROOT/foo/bar/src.c.
2616 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2619 # from /usr/local/CVSROOT/foo/bar/src.c.
2620 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2623 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2625 .RI Default( targets )
2627 .RI env.Default( targets )
2628 This specifies a list of default targets,
2629 which will be built by
2631 if no explicit targets are given on the command line.
2635 and add to the list of default targets.
2637 Multiple targets should be specified as
2638 separate arguments to the
2640 method, or as a list.
2642 will also accept the Node returned by any
2643 of a construction environment's
2648 Default('foo', 'bar', 'baz')
2649 env.Default(['a', 'b', 'c'])
2650 hello = env.Program('hello', 'hello.c')
2658 will clear all default targets.
2661 will add to the (now empty) default-target list
2664 The current list of targets added using the
2666 function or method is available in the
2671 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2673 .RI DefaultEnvironment([ args ])
2674 Creates and returns a default construction environment object.
2675 This construction environment is used internally by SCons
2676 in order to execute many of the global functions in this list,
2677 and to fetch source files transparently
2678 from source code management systems.
2680 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2682 .RI Depends( target ", " dependency )
2684 .RI env.Depends( target ", " dependency )
2685 Specifies an explicit dependency;
2686 the target file(s) will be rebuilt
2687 whenever the dependency file(s) has changed.
2688 This should only be necessary
2689 for cases where the dependency
2690 is not caught by a Scanner
2694 env.Depends('foo', 'other-input-file-for-foo')
2697 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2699 .RI env.Dictionary([ vars ])
2700 Returns a dictionary object
2701 containing copies of all of the
2702 construction variables in the environment.
2703 If there are any variable names specified,
2704 only the specified construction
2705 variables are returned in the dictionary.
2708 dict = env.Dictionary()
2709 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2712 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2714 .RI Dir( name ", [" directory ])
2716 .RI env.Dir( name ", [" directory ])
2717 This returns a Directory Node,
2718 an object that represents the specified directory
2721 can be a relative or absolute path.
2723 is an optional directory that will be used as the parent directory.
2726 is specified, the current script's directory is used as the parent.
2728 Directory Nodes can be used anywhere you
2729 would supply a string as a directory name
2730 to a Builder method or function.
2731 Directory Nodes have attributes and methods
2732 that are useful in many situations;
2733 see "File and Directory Nodes," below.
2735 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2737 .RI env.Dump([ key ])
2738 Returns a pretty printable representation of the environment.
2742 should be a string containing the name of the variable of interest.
2747 print env.Dump('CCCOM')
2751 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2761 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2764 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2769 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2771 .RI EnsurePythonVersion( major ", " minor )
2773 .RI env.EnsurePythonVersion( major ", " minor )
2774 Ensure that the Python version is at least
2777 print out an error message and exit SCons with a non-zero exit code if the
2778 actual Python version is not late enough.
2781 EnsurePythonVersion(2,2)
2784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2786 .RI EnsureSConsVersion( major ", " minor )
2788 .RI env.EnsureSConsVersion( major ", " minor )
2789 Ensure that the SCons version is at least
2792 print out an error message and exit SCons with a non-zero exit code if the
2793 actual SCons version is not late enough.
2796 EnsureSConsVersion(0,9)
2799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2801 .RI Environment([ key = value ", ...])"
2803 .RI env.Environment([ key = value ", ...])"
2804 Return a new construction environment
2805 initialized with the specified
2809 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2811 .RI Execute( action ", [" strfunction ", " varlist ])
2813 .RI env.Execute( action ", [" strfunction ", " varlist ])
2814 Executes an Action object.
2817 may be an Action object
2818 (see the section "Action Objects,"
2819 below, for a complete explanation of the arguments and behavior),
2820 or it may be a command-line string,
2822 or executable Python function,
2823 each of which will be converted
2824 into an Action object
2826 The exit value of the command
2827 or return value of the Python function
2830 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2834 .RI env.Exit([ value ])
2840 A default exit value of
2843 is used if no value is specified.
2845 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2849 .RI env.Export( vars )
2852 to export a list of variables from the current
2853 SConscript file to all other SConscript files.
2854 The exported variables are kept in a global collection,
2855 so subsequent calls to
2857 will over-write previous exports that have the same name.
2858 Multiple variable names can be passed to
2860 as separate arguments or as a list. A dictionary can be used to map
2861 variables to a different name when exported. Both local variables and
2862 global variables can be exported.
2867 # Make env available for all SConscript files to Import().
2871 # Make env and package available for all SConscript files:.
2872 Export("env", "package")
2874 # Make env and package available for all SConscript files:
2875 Export(["env", "package"])
2877 # Make env available using the name debug:.
2878 Export({"debug":env})
2884 function supports an
2886 argument that makes it easier to to export a variable or
2887 set of variables to a single SConscript file.
2888 See the description of the
2892 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2894 .RI File( name ", [" directory ])
2896 .RI env.File( name ", [" directory ])
2899 an object that represents the specified file
2902 can be a relative or absolute path.
2904 is an optional directory that will be used as the parent directory.
2906 File Nodes can be used anywhere you
2907 would supply a string as a file name
2908 to a Builder method or function.
2909 File Nodes have attributes and methods
2910 that are useful in many situations;
2911 see "File and Directory Nodes," below.
2913 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2915 .RI FindFile( file ", " dirs )
2917 .RI env.FindFile( file ", " dirs )
2920 in the path specified by
2923 may be a list of file names or a single file name. In addition to searching
2924 for files that exist in the filesytem, this function also searches for
2925 derived files that have not yet been built.
2928 foo = env.FindFile('foo', ['dir1', 'dir2'])
2931 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2933 .RI Flatten( sequence )
2935 .RI env.Flatten( sequence )
2936 Takes a sequence (that is, a Python list or tuple)
2937 that may contain nested sequences
2938 and returns a flattened list containing
2939 all of the individual elements in any sequence.
2940 This can be helpful for collecting
2941 the lists returned by calls to Builders;
2942 other Builders will automatically
2943 flatten lists specified as input,
2944 but direct Python manipulation of
2945 these lists does not:
2948 foo = Object('foo.c')
2949 bar = Object('bar.c')
2951 # Because `foo' and `bar' are lists returned by the Object() Builder,
2952 # `objects' will be a list containing nested lists:
2953 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
2955 # Passing such a list to another Builder is all right because
2956 # the Builder will flatten the list automatically:
2957 Program(source = objects)
2959 # If you need to manipulate the list directly using Python, you need to
2960 # call Flatten() yourself, or otherwise handle nested lists:
2961 for object in Flatten(objects):
2965 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2967 .RI GetBuildPath( file ", [" ... ])
2969 .RI env.GetBuildPath( file ", [" ... ])
2972 path name (or names) for the specified
2980 Nodes or strings representing path names.
2982 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2986 .RI env.GetLaunchDir()
2987 Returns the absolute path name of the directory from which
2990 was initially invoked.
2991 This can be useful when using the
2996 options, which internally
2997 change to the directory in which the
3001 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3003 .RI GetOption( name )
3005 .RI env.GetOption( name )
3006 This function provides a way to query a select subset of the scons command line
3007 options from a SConscript file. See
3009 for a description of the options available.
3011 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3013 '\".RI GlobalBuilders( flag )
3017 '\"adds the names of the default builders
3018 '\"(Program, Library, etc.)
3019 '\"to the global name space
3020 '\"so they can be called without an explicit construction environment.
3021 '\"(This is the default.)
3025 '\"the names of the default builders are removed
3026 '\"from the global name space
3027 '\"so that an explicit construction environment is required
3028 '\"to call all builders.
3030 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3034 .RI env.Help( text )
3035 This specifies help text to be printed if the
3037 argument is given to
3041 is called multiple times, the text is appended together in the order
3046 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3048 .RI Ignore( target ", " dependency )
3050 .RI env.Ignore( target ", " dependency )
3051 The specified dependency file(s)
3052 will be ignored when deciding if
3053 the target file(s) need to be rebuilt.
3056 env.Ignore('foo', 'foo.c')
3057 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3060 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3064 .RI env.Import( vars )
3067 to import a list of variables into the current SConscript file. This
3068 will import variables that were exported with
3074 Variables exported by
3077 Multiple variable names can be passed to
3079 as separate arguments or as a list. The variable "*" can be used
3080 to import all variables.
3085 Import("env", "variable")
3086 Import(["env", "variable"])
3090 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3092 .RI Install( dir ", " source )
3094 .RI env.Install( dir ", " source )
3095 Installs one or more files in a destination directory.
3096 The file names remain the same.
3099 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3102 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3104 .RI InstallAs( target ", " source )
3106 .RI env.InstallAs( target ", " source )
3107 Installs one or more files as specific file names,
3108 allowing changing a file name as part of the
3110 It is an error if the target and source
3111 list different numbers of files.
3114 env.InstallAs(target = '/usr/local/bin/foo',
3115 source = 'foo_debug')
3116 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3117 source = ['libFOO.a', 'libBAR.a'])
3120 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3122 .RI Literal( string )
3124 .RI env.Literal( string )
3127 will be preserved as-is
3128 and not have construction variables expanded.
3130 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3132 .RI Local( targets )
3134 .RI env.Local( targets )
3137 will have copies made in the local tree,
3138 even if an already up-to-date copy
3139 exists in a repository.
3140 Returns a list of the target Node or Nodes.
3142 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3144 .RI env.ParseConfig( command ", [" function ])
3147 to modify the environment as specified by the output of
3151 expects the output of a typical
3155 and parses the returned
3176 option gets added to both the
3183 option gets added to the
3186 Any other strings not associated with options
3187 are assumed to be the names of libraries
3190 construction variable.
3192 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3195 A factory function that
3196 returns a Builder object
3197 to be used to fetch source files
3198 from the Perforce source code management system.
3199 The returned Builder
3200 is intended to be passed to the
3205 env.SourceCode('.', env.Perforce())
3208 Perforce uses a number of external
3209 environment variables for its operation.
3210 Consequently, this function adds the
3211 following variables from the user's external environment
3212 to the construction environment's
3225 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3227 .RI Platform( string )
3228 Returns a callable object
3229 that can be used to initialize
3230 a construction environment using the
3231 platform keyword of the Environment() method:
3234 env = Environment(platform = Platform('win32'))
3237 .RI env.Platform( string )
3238 Applies the callable object for the specified platform
3240 to the environment through which the method was called.
3243 env.Platform('posix')
3250 variable from the user's external environment
3251 to the construction environment's
3254 This is so that any executed commands
3255 that use sockets to connect with other systems
3256 (such as fetching source files from
3257 external CVS repository specifications like
3258 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3259 will work on Win32 systems.
3261 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3263 .RI Precious( target ", ...)"
3265 .RI env.Precious( target ", ...)"
3268 as precious so it is not deleted before it is rebuilt. Normally
3270 deletes a target before building it.
3271 Multiple targets can be passed in to a single call to
3274 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3276 .RI env.Prepend( key = val ", [...])"
3277 Appends the specified keyword arguments
3278 to the beginning of construction variables in the environment.
3279 If the Environment does not have
3280 the specified construction variable,
3281 it is simply added to the environment.
3282 If the values of the construction variable
3283 and the keyword argument are the same type,
3284 then the two values will be simply added together.
3285 Otherwise, the construction variable
3286 and the value of the keyword argument
3287 are both coerced to lists,
3288 and the lists are added together.
3289 (See also the Append method, above.)
3292 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3295 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3297 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3298 This appends new path elements to the given path in the
3299 specified external environment
3303 any particular path once (leaving the first one it encounters and
3304 ignoring the rest, to preserve path order),
3305 and to help assure this,
3306 will normalize all paths (using
3309 .BR os.path.normcase ).
3310 This can also handle the
3311 case where the given old path variable is a list instead of a
3312 string, in which case a list will be returned instead of a string.
3316 print 'before:',env['ENV']['INCLUDE']
3317 include_path = '/foo/bar:/foo'
3318 env.PrependENVPath('INCLUDE', include_path)
3319 print 'after:',env['ENV']['INCLUDE']
3323 after: /foo/bar:/foo:/biz
3326 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3328 .RI env.AppendUnique( key = val ", [...])"
3329 Appends the specified keyword arguments
3330 to the beginning of construction variables in the environment.
3331 If the Environment does not have
3332 the specified construction variable,
3333 it is simply added to the environment.
3334 If the construction variable being appended to is a list,
3335 then any value(s) that already exist in the
3336 construction variable will
3338 be added again to the list.
3341 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3344 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3347 A factory function that
3348 returns a Builder object
3349 to be used to fetch source files
3351 The returned Builder
3352 is intended to be passed to the
3357 env.SourceCode('.', env.RCS())
3362 will fetch source files
3363 from RCS subdirectories automatically,
3365 as demonstrated in the above example
3366 should only be necessary if
3367 you are fetching from
3370 directory as the source files,
3371 or if you need to explicitly specify RCS
3372 for a specific subdirectory.
3374 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3376 .RI env.Replace( key = val ", [...])"
3377 Replaces construction variables in the Environment
3378 with the specified keyword arguments.
3381 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3384 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3386 .RI Repository( directory )
3388 .RI env.Repository( directory )
3391 is a repository to be searched for files.
3395 and each one adds to the list of
3396 repositories that will be searched.
3400 a repository is a copy of the source tree,
3401 from the top-level directory on down,
3403 both source files and derived files
3404 that can be used to build targets in
3405 the local source tree.
3406 The canonical example would be an
3407 official source tree maintained by an integrator.
3408 If the repository contains derived files,
3409 then the derived files should have been built using
3411 so that the repository contains the necessary
3412 signature information to allow
3414 to figure out when it is appropriate to
3415 use the repository copy of a derived file,
3416 instead of building one locally.
3418 Note that if an up-to-date derived file
3419 already exists in a repository,
3423 make a copy in the local directory tree.
3424 In order to guarantee that a local copy
3430 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3435 what variable(s) to use as the return value(s) of the current SConscript
3436 file. These variables will be returned to the "calling" SConscript file
3437 as the return value(s) of
3439 Multiple variable names should be passed to
3445 Return(["foo", "bar"])
3448 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3450 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3452 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3453 Creates a Scanner object for
3456 See the section "Scanner Objects,"
3457 below, for a complete explanation of the arguments and behavior.
3459 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3462 A factory function that
3463 returns a Builder object
3464 to be used to fetch source files
3466 The returned Builder
3467 is intended to be passed to the
3472 env.SourceCode('.', env.SCCS())
3477 will fetch source files
3478 from SCCS subdirectories automatically,
3480 as demonstrated in the above example
3481 should only be necessary if
3482 you are fetching from
3485 directory as the source files,
3486 or if you need to explicitly specify SCCS
3487 for a specific subdirectory.
3489 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3491 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3493 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3495 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3497 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3501 one or more subsidiary SConscript (configuration) files.
3502 There are two ways to call the
3506 The first way you can call
3508 is to explicitly specify one or more
3510 as the first argument.
3511 A single script may be specified as a string;
3512 multiple scripts must be specified as a list
3513 (either explicitly or as created by
3517 The second way you can call
3519 is to specify a list of (sub)directory names
3526 execute a subsidiary configuration file named
3528 in each of the specified directories.
3529 You may specify a name other than
3531 by supplying an optional
3537 argument provides a list of variable names or a dictionary of
3538 named values to export to the
3540 These variables are locally exported only to the specified
3542 and do not affect the
3543 global pool of variables used by
3547 '\"If multiple dirs are provided,
3548 '\"each script gets a fresh export.
3553 function to import the variables.
3557 argument specifies that all of the target files
3558 (for example, object files and executables)
3559 that would normally be built in the subdirectory in which
3561 resides should actually
3565 is interpreted relative to the directory
3566 of the calling SConscript file.
3570 argument specifies that the
3571 source files from which
3572 the target files should be built
3576 is interpreted relative to the directory
3577 of the calling SConscript file.
3581 will link or copy (depending on the platform)
3582 all the source files into the build directory.
3583 This behavior may be disabled by
3584 setting the optional
3587 (it is set to 1 by default),
3590 will refer directly to
3591 the source files in their source directory
3592 when building target files.
3595 is usually safe, and always more efficient
3598 but it may cause build problems in certain end-cases,
3599 such as compiling from source files that
3600 are generated by the build.)
3602 Any variables returned by
3606 will be returned by the call to
3612 SConscript('subdir/SConscript')
3613 foo = SConscript('sub/SConscript', exports='env')
3614 SConscript('dir/SConscript', exports=['env', 'variable'])
3615 SConscript('src/SConscript', build_dir='build', duplicate=0)
3616 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3617 SConscript(dirs=['sub1', 'sub2'])
3618 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3621 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3623 .RI SConscriptChdir( value )
3625 .RI env.SConscriptChdir( value )
3628 changes its working directory
3629 to the directory in which each
3630 subsidiary SConscript file lives.
3631 This behavior may be disabled
3632 by specifying either:
3636 env.SConscriptChdir(0)
3641 will stay in the top-level directory
3642 while reading all SConscript files.
3643 (This may be necessary when building from repositories,
3644 when all the directories in which SConscript files may be found
3645 don't necessarily exist locally.)
3647 You may enable and disable
3648 this ability by calling
3655 SConscript('foo/SConscript') # will not chdir to foo
3656 env.SConscriptChdir(1)
3657 SConscript('bar/SConscript') # will chdir to bar
3660 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3662 .RI SConsignFile([ file , dbm_module ])
3664 .RI env.SConsignFile([ file , dbm_module ])
3667 to store all file signatures
3677 is not an absolute path name,
3678 the file is placed in the same directory as the top-level
3684 argument can be used to specify
3685 which Python database module
3686 The default is to use a custom
3688 module that uses pickled
3689 Python data structures,
3690 and which works on all Python versions from 1.5.2 on.
3695 # Stores signatures in ".sconsign.dbm"
3696 # in the top-level SConstruct directory.
3699 # Stores signatures in the file "etc/scons-signatures"
3700 # relative to the top-level SConstruct directory.
3701 SConsignFile("etc/scons-signatures")
3703 # Stores signatures in the specified absolute file name.
3704 SConsignFile("/home/me/SCons/signatures")
3707 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3709 .RI env.SetDefault(key = val ", [...])"
3710 Sets construction variables to default values specified with the keyword
3711 arguments if (and only if) the variables are not already set.
3712 The following statements are equivalent:
3715 env.SetDefault(FOO = 'foo')
3717 if not env.has_key('FOO'): env['FOO'] = 'foo'
3720 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3722 .RI SetOption( name ", " value )
3724 .RI env.SetOption( name ", " value )
3725 This function provides a way to set a select subset of the scons command
3726 line options from a SConscript file. The options supported are:
3728 which corresponds to -c, --clean, and --remove;
3731 corresponds to --duplicate;
3733 which corresponds to --implicit-cache;
3735 which corresponds to --max-drift;
3737 which corresponds to -j and --jobs.
3738 See the documentation for the
3739 corresponding command line object for information about each specific
3743 SetOption('max_drift', 1)
3746 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3748 .RI SideEffect( side_effect ", " target )
3750 .RI env.SideEffect( side_effect ", " target )
3753 as a side effect of building
3759 can be a list, a file name, or a node.
3760 A side effect is a target that is created
3761 as a side effect of building other targets.
3762 For example, a Windows PDB
3763 file is created as a side effect of building the .obj
3764 files for a static library.
3765 If a target is a side effect of multiple build commands,
3767 will ensure that only one set of commands
3768 is executed at a time.
3769 Consequently, you only need to use this method
3770 for side-effect targets that are built as a result of
3771 multiple build commands.
3773 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3775 .RI SourceCode( entries ", " builder )
3777 .RI env.SourceCode( entries ", " builder )
3778 Arrange for non-existent source files to
3779 be fetched from a source code management system
3784 may be a Node, string or list of both,
3785 and may represent either individual
3786 source files or directories in which
3787 source files can be found.
3789 For any non-existent source files,
3791 will search up the directory tree
3801 will not use a builder to fetch
3802 source files for the specified
3806 builder has been specified
3807 for a directory higher up the tree.
3811 fetch files from SCCS or RCS subdirectories
3812 without explicit configuration.
3813 This takes some extra processing time
3814 to search for the necessary
3815 source code management files on disk.
3816 You can avoid these extra searches
3817 and speed up your build a little
3818 by disabling these searches as follows:
3821 env.SourceCode('.', None)
3825 Note that if the specified
3827 is one you create by hand,
3828 it must have an associated
3829 construction environment to use
3830 when fetching a source file.
3833 provides a set of canned factory
3834 functions that return appropriate
3835 Builders for various popular
3836 source code management systems.
3837 Canonical examples of invocation include:
3840 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
3841 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
3842 env.SourceCode('/', env.RCS())
3843 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
3844 env.SourceCode('no_source.c', None)
3846 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3848 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3850 '\".RI Subversion( repository ", " module )
3851 '\"A factory function that
3852 '\"returns a Builder object
3853 '\"to be used to fetch source files
3854 '\"from the specified Subversion
3856 '\"The returned Builder
3857 '\"is intended to be passed to the
3861 '\"The optional specified
3863 '\"will be added to the beginning
3864 '\"of all repository path names;
3865 '\"this can be used, in essence,
3866 '\"to strip initial directory names
3867 '\"from the repository path names,
3868 '\"so that you only have to
3869 '\"replicate part of the repository
3870 '\"directory hierarchy in your
3871 '\"local build directory:
3874 '\"# Will fetch foo/bar/src.c
3875 '\"# from /usr/local/Subversion/foo/bar/src.c.
3876 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
3878 '\"# Will fetch bar/src.c
3879 '\"# from /usr/local/Subversion/foo/bar/src.c.
3880 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
3882 '\"# Will fetch src.c
3883 '\"# from /usr/local/Subversion/foo/bar/src.c.
3884 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
3887 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3889 .RI SourceSignatures( type )
3891 .RI env.SourceSignatures( type )
3892 This function tells SCons what type of signature to use for source files:
3896 If the environment method is used,
3897 the specified type of source signature
3898 is only used when deciding whether targets
3899 built with that environment are up-to-date or must be rebuilt.
3900 If the global function is used,
3901 the specified type of source signature becomes the default
3902 used for all decisions
3903 about whether targets are up-to-date.
3905 "MD5" means the signature of a source file
3906 is the MD5 checksum of its contents.
3907 "timestamp" means the signature of a source file
3908 is its timestamp (modification time).
3909 There is no different between the two behaviors
3913 "MD5" signatures take longer to compute,
3914 but are more accurate than "timestamp" signatures.
3915 The default is "MD5".
3917 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3921 .RI env.Split( arg )
3922 Returns a list of file names or other objects.
3924 it will be split on strings of white-space characters
3926 making it easier to write long lists of file names.
3927 If arg is already a list,
3928 the list will be returned untouched.
3929 If arg is any other type of object,
3930 it will be returned as a list
3931 containing just the object.
3934 files = Split("f1.c f2.c f3.c")
3935 files = env.Split("f4.c f5.c f6.c")
3943 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3945 .RI TargetSignatures( type )
3947 .RI env.TargetSignatures( type )
3948 This function tells SCons what type of signatures to use
3953 If the environment method is used,
3954 the specified type of signature is only used
3955 for targets built with that environment.
3956 If the global function is used,
3957 the specified type of signature becomes the default
3958 used for all target files that
3959 don't have an explicit target signature type
3960 specified for their environments.
3962 "build" means the signature of a target file
3963 is made by concatenating all of the
3964 signatures of all its source files.
3965 "content" means the signature of a target
3966 file is an MD5 checksum of its contents.
3967 "build" signatures are usually faster to compute,
3968 but "content" signatures can prevent unnecessary rebuilds
3969 when a target file is rebuilt to the exact same contents
3970 as the previous build.
3971 The default is "build".
3973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3975 .RI Tool( string, toolpath=[] )
3976 Returns a callable object
3977 that can be used to initialize
3978 a construction environment using the
3979 tools keyword of the Environment() method.
3980 The object may be called with a construction
3981 environment as an argument,
3982 in which case the object will be
3983 add the necessary variables
3984 to the construction environment
3985 and the name of the tool will be added to the
3987 construction variable.
3990 env = Environment(tools = [ Tool('msvc') ])
3994 t(env) # adds 'msvc' to the TOOLS variable
3995 u = Tool('opengl', toolpath = ['tools'])
3996 u(env) # adds 'opengl' to the TOOLS variable
3999 .RI env.Tool( string [, toolpath] )
4000 Applies the callable object for the specified tool
4002 to the environment through which the method was called.
4006 env.Tool('opengl', toolpath = ['build/tools'])
4009 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4013 .RI env.Value( value )
4014 Returns a Node object representing the specified Python value. Value
4015 nodes can be used as dependencies of targets. If the result of
4018 changes between SCons runs, any targets depending on
4020 will be rebuilt. When using timestamp source signatures, Value nodes'
4021 timestamps are equal to the system time when the node is created.
4024 def create(target, source, env):
4025 f = open(str(target[0]), 'wb')
4026 f.write('prefix=' + source[0].get_contents())
4028 prefix = ARGUMENTS.get('prefix', '/usr/local')
4030 env['BUILDERS']['Config'] = Builder(action = create)
4031 env.Config(target = 'package-config', source = Value(prefix))
4034 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4036 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4038 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4040 Searches for the specified executable
4042 returning the full path name to the program
4044 and returning None if not.
4045 Searches the specified
4047 the value of the calling environment's PATH
4048 (env['ENV']['PATH']),
4049 or the user's current external PATH
4050 (os.environ['PATH'])
4052 On Win32 systems, searches for executable
4053 programs with any of the file extensions
4054 listed in the specified
4056 the calling environment's PATHEXT
4057 (env['ENV']['PATHEXT'])
4058 or the user's current PATHEXT
4059 (os.environ['PATHEXT'])
4067 .SS SConscript Variables
4068 In addition to the global functions and methods,
4070 supports a number of Python variables
4071 that can be used in SConscript files
4072 to affect how you want the build to be performed.
4074 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4079 arguments specified on the command line.
4080 Each element in the list is a tuple
4082 .RI ( keyword , value )
4088 elements of the tuple
4090 subscripting for element
4094 of the tuple, respectively.
4097 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4098 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4099 third_tuple = ARGLIST[2]
4100 print "third keyword, value =", third_tuple[0], third_tuple[1]
4101 for key, value in ARGLIST:
4102 # process key and value
4105 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4108 A dictionary of all the
4110 arguments specified on the command line.
4111 The dictionary is not in order,
4112 and if a given keyword has
4113 more than one value assigned to it
4114 on the command line,
4115 the last (right-most) value is
4121 if ARGUMENTS.get('debug', 0):
4122 env = Environment(CCFLAGS = '-g')
4127 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4130 A list of the targets which
4132 will actually try to build,
4133 regardless of whether they were specified on
4134 the command line or via the
4137 The elements of this list may be strings
4139 nodes, so you should run the list through the Python
4141 function to make sure any Node path names
4142 are converted to strings.
4144 Because this list may be taken from the
4145 list of targets specified using the
4148 the contents of the list may change
4149 on each successive call to
4154 for additional information.
4157 if 'foo' in BUILD_TARGETS:
4158 print "Don't forget to test the `foo' program!"
4159 if 'special/program' in BUILD_TARGETS:
4160 SConscript('special')
4165 list only contains targets expected listed
4166 on the command line or via calls to the
4171 contain all dependent targets that will be built as
4172 a result of making the sure the explicitly-specified
4173 targets are up to date.
4175 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4177 COMMAND_LINE_TARGETS
4178 A list of the targets explicitly specified on
4180 If there are no targets specified on the command line,
4182 This can be used, for example,
4183 to take specific actions only
4184 when a certain target or targets
4185 is explicitly being built:
4188 if 'foo' in COMMAND_LINE_TARGETS:
4189 print "Don't forget to test the `foo' program!"
4190 if 'special/program' in COMMAND_LINE_TARGETS:
4191 SConscript('special')
4194 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4197 A list of the target
4199 that have been specified using the
4202 The elements of the list are nodes,
4203 so you need to run them through the Python
4205 function to get at the path name for each Node.
4208 print str(DEFAULT_TARGETS[0])
4209 if 'foo' in map(str, DEFAULT_TARGETS):
4210 print "Don't forget to test the `foo' program!"
4215 list change on on each successive call to the
4220 print map(str, DEFAULT_TARGETS) # originally []
4222 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4224 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4226 print map(str, DEFAULT_TARGETS) # back to []
4229 Consequently, be sure to use
4231 only after you've made all of your
4234 or else simply be careful of the order
4235 of these statements in your SConscript files
4236 so that you don't look for a specific
4237 default target before it's actually been added to the list.
4239 .SS Construction Variables
4240 .\" XXX From Gary Ruben, 23 April 2002:
4241 .\" I think it would be good to have an example with each construction
4242 .\" variable description in the documentation.
4244 .\" CC The C compiler
4245 .\" Example: env["CC"] = "c68x"
4246 .\" Default: env["CC"] = "cc"
4248 .\" CCCOM The command line ...
4250 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4251 .\" env["CC"] = "c68x"
4252 .\" env["CFLAGS"] = "-ps -qq -mr"
4253 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4255 .\" (I dunno what this is ;-)
4256 A construction environment has an associated dictionary of
4257 .I construction variables
4258 that are used by built-in or user-supplied build rules.
4259 Construction variables must follow the same rules for
4261 the initial character must be an underscore or letter,
4262 followed by any number of underscores, letters, or digits.
4264 A number of useful construction variables are automatically defined by
4265 scons for each supported platform, and additional construction variables
4266 can be defined by the user. The following is a list of the automatically
4267 defined construction variables:
4270 The static library archiver.
4273 The command line used to generate a static library from object files.
4276 General options passed to the static library archiver.
4282 The command line used to generate an object file
4283 from an assembly-language source file.
4286 General options passed to the assembler.
4289 The command line used to assemble an assembly-language
4290 source file into an object file
4291 after first running the file through the C preprocessor.
4292 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4293 are included on this command line.
4296 The bibliography generator for the TeX formatter and typesetter and the
4297 LaTeX structured formatter and typesetter.
4300 The command line used to call the bibliography generator for the
4301 TeX formatter and typesetter and the LaTeX structured formatter and
4305 General options passed to the bibliography generator for the TeX formatter
4306 and typesetter and the LaTeX structured formatter and typesetter.
4309 The BitKeeper executable.
4312 The command line for
4313 fetching source files using BitKEeper.
4316 The command ($BITKEEPER) and subcommand
4317 for fetching source files using BitKeeper.
4319 .IP BITKEEPERGETFLAGS
4320 Options that are passed to the BitKeeper
4325 A dictionary mapping the names of the builders
4326 available through this environment
4327 to underlying Builder objects.
4329 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4330 are available by default.
4331 If you initialize this variable when an
4332 Environment is created:
4335 env = Environment(BUILDERS = {'NewBuilder' : foo})
4338 the default Builders will no longer be available.
4339 To use a new Builder object in addition to the default Builders,
4340 add your new Builder object like this:
4344 env.Append(BUILDERS = {'NewBuilder' : foo})
4351 env['BUILDERS]['NewBuilder'] = foo
4358 The command line used to compile a C source file to a (static) object file.
4359 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4360 are included on this command line.
4363 General options that are passed to the C compiler.
4366 The suffix for C source files.
4367 This is used by the internal CFile builder
4368 when generating C files from Lex (.l) or YACC (.y) input files.
4369 The default suffix, of course, is
4372 On case-insensitive systems (like Win32),
4379 The version number of the C compiler.
4380 This may or may not be set,
4381 depending on the specific C compiler being used.
4384 A function used to produce variables like $_CPPINCFLAGS. It takes
4386 arguments: a prefix to concatenate onto each element, a list of
4387 elements, a suffix to concatenate onto each element, an environment
4388 for variable interpolation, and an optional function that will be
4389 called to transform the list before concatenation.
4392 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4396 A platform independent specification of C preprocessor definitions.
4397 The definitions will be added to command lines
4398 through the automatically-generated
4399 $_CPPDEFFLAGS construction variable (see below),
4400 which is constructed according to
4401 the type of value of $CPPDEFINES:
4404 If $CPPDEFINES is a string,
4406 $CPPDEFPREFIX and $CPPDEFSUFFIX
4407 construction variables
4408 will be added to the beginning and end.
4411 # Will add -Dxyz to POSIX compiler command lines,
4412 # and /Dxyz to Microsoft Visual C++ command lines.
4413 env = Environment(CPPDEFINES='xyz')
4417 If $CPPDEFINES is a list,
4419 $CPPDEFPREFIX and $CPPDEFSUFFIX
4420 construction variables
4421 will be appended to the beginning and end
4422 of each element in the list.
4423 If any element is a list or tuple,
4424 then the first item is the name being
4425 defined and the second item is its value:
4428 # Will add -DB=2 -DA to POSIX compiler command lines,
4429 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4430 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4434 If $CPPDEFINES is a dictionary,
4436 $CPPDEFPREFIX and $CPPDEFSUFFIX
4437 construction variables
4438 will be appended to the beginning and end
4439 of each item from the dictionary.
4440 The key of each dictionary item
4441 is a name being defined
4442 to the dictionary item's corresponding value;
4445 then the name is defined without an explicit value.
4446 Note that the resulting flags are sorted by keyword
4447 to ensure that the order of the options on the
4448 command line is consistent each time
4453 # Will add -DA -DB=2 to POSIX compiler command lines,
4454 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4455 env = Environment(CPPDEFINES={'B':2, 'A':None})
4459 An automatically-generated construction variable
4460 containing the C preprocessor command-line options
4462 The value of $_CPPDEFFLAGS is created
4463 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4464 to the beginning and end
4465 of each directory in $CPPDEFINES.
4468 The prefix used to specify preprocessor definitions
4469 on the C compiler command line.
4470 This will be appended to the beginning of each definition
4471 in the $CPPDEFINES construction variable
4472 when the $_CPPDEFFLAGS variable is automatically generated.
4475 The suffix used to specify preprocessor definitions
4476 on the C compiler command line.
4477 This will be appended to the end of each definition
4478 in the $CPPDEFINES construction variable
4479 when the $_CPPDEFFLAGS variable is automatically generated.
4482 User-specified C preprocessor options.
4483 These will be included in any command that uses the C preprocessor,
4484 including not just compilation of C and C++ source files
4485 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4486 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4487 $F77PPCOM and $SHF77PPCOM command lines
4488 used to compile a Fortran source file,
4489 and the $ASPPCOM command line
4490 used to assemble an assembly language source file,
4491 after first running each file through the C preprocessor.
4492 Note that this variable does
4496 (or similar) include search path options
4497 that scons generates automatically from $CPPPATH.
4501 for the variable that expands to those options.
4504 An automatically-generated construction variable
4505 containing the C preprocessor command-line options
4506 for specifying directories to be searched for include files.
4507 The value of $_CPPINCFLAGS is created
4508 by appending $INCPREFIX and $INCSUFFIX
4509 to the beginning and end
4510 of each directory in $CPPPATH.
4513 The list of directories that the C preprocessor will search for include
4514 directories. The C/C++ implicit dependency scanner will search these
4515 directories for include files. Don't explicitly put include directory
4516 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4517 and the directories will not be searched by the dependency scanner. Note:
4518 directory names in CPPPATH will be looked-up relative to the SConscript
4519 directory when they are used in a command. To force
4521 to look-up a directory relative to the root of the source tree use #:
4524 env = Environment(CPPPATH='#/include')
4528 The directory look-up can also be forced using the
4533 include = Dir('include')
4534 env = Environment(CPPPATH=include)
4538 The directory list will be added to command lines
4539 through the automatically-generated
4541 construction variable,
4542 which is constructed by
4543 appending the values of the
4544 $INCPREFIX and $INCSUFFIX
4545 construction variables
4546 to the beginning and end
4547 of each directory in $CPPPATH.
4548 Any command lines you define that need
4549 the CPPPATH directory list should
4550 include $_CPPINCFLAGS:
4553 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4557 The list of suffixes of files that will be scanned
4558 for C preprocessor implicit dependencies
4560 The default list is:
4563 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4564 ".h", ".H", ".hxx", ".hpp", ".hh",
4565 ".F", ".fpp", ".FPP",
4566 ".S", ".spp", ".SPP"]
4573 Options that are passed to the CVS checkout subcommand.
4576 The command line used to
4577 fetch source files from a CVS repository.
4580 General options that are passed to CVS.
4581 By default, this is set to
4583 to specify from where the files must be fetched.
4586 The path to the CVS repository.
4587 This is referenced in the default
4594 The suffix for C++ source files.
4595 This is used by the internal CXXFile builder
4596 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4597 The default suffix is
4599 SCons also treats files with the suffixes
4606 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4613 The command line used to compile a C++ source file to an object file.
4614 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4615 are included on this command line.
4618 General options that are passed to the C++ compiler.
4621 The version number of the C++ compiler.
4622 This may or may not be set,
4623 depending on the specific C++ compiler being used.
4626 A function that converts a file name into a Dir instance relative to the
4630 The list of suffixes of files that will be scanned
4631 for imported D package files.
4632 The default list is:
4639 The TeX DVI file to PDF file converter.
4642 General options passed to the TeX DVI file to PDF file converter.
4645 The command line used to convert TeX DVI files into a PDF file.
4648 The TeX DVI file to PostScript converter.
4651 General options passed to the TeX DVI file to PostScript converter.
4654 A dictionary of environment variables
4655 to use when invoking commands. When ENV is used in a command all list
4656 values will be joined using the path separator and any other non-string
4657 values will simply be coerced to a string.
4658 Note that, by default,
4662 propagate the environment in force when you
4665 to the commands used to build target files.
4666 This is so that builds will be guaranteed
4667 repeatable regardless of the environment
4668 variables set at the time
4672 If you want to propagate your
4673 environment variables
4674 to the commands executed
4675 to build target files,
4676 you must do so explicitly:
4680 env = Environment(ENV = os.environ)
4684 Note that you can choose only to propagate
4685 certain environment variables.
4689 environment variable,
4692 uses the same utilities
4693 as the invoking shell (or other process):
4698 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4702 A function that will be called to escape shell special characters in
4703 command lines. The function should take one argument: the command line
4704 string to escape; and should return the escaped command line.
4707 The Fortran 77 compiler.
4708 You should normally set the $FORTRAN variable,
4709 which specifies the default Fortran compiler
4710 for all Fortran versions.
4711 You only need to set $F77 if you need to use a specific compiler
4712 or compiler version for Fortran 77 files.
4715 The command line used to compile a Fortran 77 source file to an object file.
4716 You only need to set $F77COM if you need to use a specific
4717 command line for Fortran 77 files.
4718 You should normally set the $FORTRANCOM variable,
4719 which specifies the default command line
4720 for all Fortran versions.
4723 General user-specified options that are passed to the Fortran 77 compiler.
4724 Note that this variable does
4728 (or similar) include search path options
4729 that scons generates automatically from $F77PATH.
4733 for the variable that expands to those options.
4734 You only need to set $F77FLAGS if you need to define specific
4735 user options for Fortran 77 files.
4736 You should normally set the $FORTRANFLAGS variable,
4737 which specifies the user-specified options
4738 passed to the default Fortran compiler
4739 for all Fortran versions.
4742 An automatically-generated construction variable
4743 containing the Fortran 77 compiler command-line options
4744 for specifying directories to be searched for include files.
4745 The value of $_F77INCFLAGS is created
4746 by appending $INCPREFIX and $INCSUFFIX
4747 to the beginning and end
4748 of each directory in $F77PATH.
4751 The list of directories that the Fortran 77 compiler will search for include
4752 directories. The implicit dependency scanner will search these
4753 directories for include files. Don't explicitly put include directory
4754 arguments in $F77FLAGS because the result will be non-portable
4755 and the directories will not be searched by the dependency scanner. Note:
4756 directory names in $F77PATH will be looked-up relative to the SConscript
4757 directory when they are used in a command. To force
4759 to look-up a directory relative to the root of the source tree use #:
4760 You only need to set $F77PATH if you need to define a specific
4761 include path for Fortran 77 files.
4762 You should normally set the $FORTRANPATH variable,
4763 which specifies the include path
4764 for the default Fortran compiler
4765 for all Fortran versions.
4768 env = Environment(F77PATH='#/include')
4772 The directory look-up can also be forced using the
4777 include = Dir('include')
4778 env = Environment(F77PATH=include)
4782 The directory list will be added to command lines
4783 through the automatically-generated
4785 construction variable,
4786 which is constructed by
4787 appending the values of the
4788 $INCPREFIX and $INCSUFFIX
4789 construction variables
4790 to the beginning and end
4791 of each directory in $F77PATH.
4792 Any command lines you define that need
4793 the F77PATH directory list should
4794 include $_F77INCFLAGS:
4797 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
4801 The command line used to compile a Fortran 77 source file to an object file
4802 after first running the file through the C preprocessor.
4803 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
4804 are included on this command line.
4805 You only need to set $F77PPCOM if you need to use a specific
4806 C-preprocessor command line for Fortran 77 files.
4807 You should normally set the $FORTRANPPCOM variable,
4808 which specifies the default C-preprocessor command line
4809 for all Fortran versions.
4812 The Fortran 90 compiler.
4813 You should normally set the $FORTRAN variable,
4814 which specifies the default Fortran compiler
4815 for all Fortran versions.
4816 You only need to set $F90 if you need to use a specific compiler
4817 or compiler version for Fortran 90 files.
4820 The command line used to compile a Fortran 90 source file to an object file.
4821 You only need to set $F90COM if you need to use a specific
4822 command line for Fortran 90 files.
4823 You should normally set the $FORTRANCOM variable,
4824 which specifies the default command line
4825 for all Fortran versions.
4828 General user-specified options that are passed to the Fortran 90 compiler.
4829 Note that this variable does
4833 (or similar) include search path options
4834 that scons generates automatically from $F90PATH.
4838 for the variable that expands to those options.
4839 You only need to set $F90FLAGS if you need to define specific
4840 user options for Fortran 90 files.
4841 You should normally set the $FORTRANFLAGS variable,
4842 which specifies the user-specified options
4843 passed to the default Fortran compiler
4844 for all Fortran versions.
4847 An automatically-generated construction variable
4848 containing the Fortran 90 compiler command-line options
4849 for specifying directories to be searched for include files.
4850 The value of $_F90INCFLAGS is created
4851 by appending $INCPREFIX and $INCSUFFIX
4852 to the beginning and end
4853 of each directory in $F90PATH.
4856 The list of directories that the Fortran 90 compiler will search for include
4857 directories. The implicit dependency scanner will search these
4858 directories for include files. Don't explicitly put include directory
4859 arguments in $F90FLAGS because the result will be non-portable
4860 and the directories will not be searched by the dependency scanner. Note:
4861 directory names in $F90PATH will be looked-up relative to the SConscript
4862 directory when they are used in a command. To force
4864 to look-up a directory relative to the root of the source tree use #:
4865 You only need to set $F90PATH if you need to define a specific
4866 include path for Fortran 90 files.
4867 You should normally set the $FORTRANPATH variable,
4868 which specifies the include path
4869 for the default Fortran compiler
4870 for all Fortran versions.
4873 env = Environment(F90PATH='#/include')
4877 The directory look-up can also be forced using the
4882 include = Dir('include')
4883 env = Environment(F90PATH=include)
4887 The directory list will be added to command lines
4888 through the automatically-generated
4890 construction variable,
4891 which is constructed by
4892 appending the values of the
4893 $INCPREFIX and $INCSUFFIX
4894 construction variables
4895 to the beginning and end
4896 of each directory in $F90PATH.
4897 Any command lines you define that need
4898 the F90PATH directory list should
4899 include $_F90INCFLAGS:
4902 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
4906 The command line used to compile a Fortran 90 source file to an object file
4907 after first running the file through the C preprocessor.
4908 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
4909 are included on this command line.
4910 You only need to set $F90PPCOM if you need to use a specific
4911 C-preprocessor command line for Fortran 90 files.
4912 You should normally set the $FORTRANPPCOM variable,
4913 which specifies the default C-preprocessor command line
4914 for all Fortran versions.
4917 The Fortran 95 compiler.
4918 You should normally set the $FORTRAN variable,
4919 which specifies the default Fortran compiler
4920 for all Fortran versions.
4921 You only need to set $F95 if you need to use a specific compiler
4922 or compiler version for Fortran 95 files.
4925 The command line used to compile a Fortran 95 source file to an object file.
4926 You only need to set $F95COM if you need to use a specific
4927 command line for Fortran 95 files.
4928 You should normally set the $FORTRANCOM variable,
4929 which specifies the default command line
4930 for all Fortran versions.
4933 General user-specified options that are passed to the Fortran 95 compiler.
4934 Note that this variable does
4938 (or similar) include search path options
4939 that scons generates automatically from $F95PATH.
4943 for the variable that expands to those options.
4944 You only need to set $F95FLAGS if you need to define specific
4945 user options for Fortran 95 files.
4946 You should normally set the $FORTRANFLAGS variable,
4947 which specifies the user-specified options
4948 passed to the default Fortran compiler
4949 for all Fortran versions.
4952 An automatically-generated construction variable
4953 containing the Fortran 95 compiler command-line options
4954 for specifying directories to be searched for include files.
4955 The value of $_F95INCFLAGS is created
4956 by appending $INCPREFIX and $INCSUFFIX
4957 to the beginning and end
4958 of each directory in $F95PATH.
4961 The list of directories that the Fortran 95 compiler will search for include
4962 directories. The implicit dependency scanner will search these
4963 directories for include files. Don't explicitly put include directory
4964 arguments in $F95FLAGS because the result will be non-portable
4965 and the directories will not be searched by the dependency scanner. Note:
4966 directory names in $F95PATH will be looked-up relative to the SConscript
4967 directory when they are used in a command. To force
4969 to look-up a directory relative to the root of the source tree use #:
4970 You only need to set $F95PATH if you need to define a specific
4971 include path for Fortran 95 files.
4972 You should normally set the $FORTRANPATH variable,
4973 which specifies the include path
4974 for the default Fortran compiler
4975 for all Fortran versions.
4978 env = Environment(F95PATH='#/include')
4982 The directory look-up can also be forced using the
4987 include = Dir('include')
4988 env = Environment(F95PATH=include)
4992 The directory list will be added to command lines
4993 through the automatically-generated
4995 construction variable,
4996 which is constructed by
4997 appending the values of the
4998 $INCPREFIX and $INCSUFFIX
4999 construction variables
5000 to the beginning and end
5001 of each directory in $F95PATH.
5002 Any command lines you define that need
5003 the F95PATH directory list should
5004 include $_F95INCFLAGS:
5007 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5011 The command line used to compile a Fortran 95 source file to an object file
5012 after first running the file through the C preprocessor.
5013 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5014 are included on this command line.
5015 You only need to set $F95PPCOM if you need to use a specific
5016 C-preprocessor command line for Fortran 95 files.
5017 You should normally set the $FORTRANPPCOM variable,
5018 which specifies the default C-preprocessor command line
5019 for all Fortran versions.
5022 The default Fortran compiler
5023 for all versions of Fortran.
5026 The command line used to compile a Fortran source file to an object file.
5027 By default, any options specified
5028 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5029 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5030 are included on this command line.
5033 General user-specified options that are passed to the Fortran compiler.
5034 Note that this variable does
5038 (or similar) include or module search path options
5039 that scons generates automatically from $FORTRANPATH.
5041 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5043 for the variables that expand those options.
5045 .IP _FORTRANINCFLAGS
5046 An automatically-generated construction variable
5047 containing the Fortran compiler command-line options
5048 for specifying directories to be searched for include
5049 files and module files.
5050 The value of $_FORTRANINCFLAGS is created
5051 by prepending/appending $INCPREFIX and $INCSUFFIX
5052 to the beginning and end
5053 of each directory in $FORTRANPATH.
5056 Directory location where the Fortran compiler should place
5057 any module files it generates. This variable is empty, by default. Some
5058 Fortran compilers will internally append this directory in the search path
5059 for module files, as well
5061 .IP FORTRANMODDIRPREFIX
5062 The prefix used to specify a module directory on the Fortran compiler command
5064 This will be appended to the beginning of the directory
5065 in the $FORTRANMODDIR construction variables
5066 when the $_FORTRANMODFLAG variables is automatically generated.
5068 .IP FORTRANMODDIRSUFFIX
5069 The suffix used to specify a module directory on the Fortran compiler command
5071 This will be appended to the beginning of the directory
5072 in the $FORTRANMODDIR construction variables
5073 when the $_FORTRANMODFLAG variables is automatically generated.
5076 An automatically-generated construction variable
5077 containing the Fortran compiler command-line option
5078 for specifying the directory location where the Fortran
5079 compiler should place any module files that happen to get
5080 generated during compilation.
5081 The value of $_FORTRANMODFLAG is created
5082 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5083 to the beginning and end of the directory in $FORTRANMODDIR.
5085 .IP FORTRANMODPREFIX
5086 The module file prefix used by the Fortran compiler. SCons assumes that
5087 the Fortran compiler follows the quasi-standard naming convention for
5089 .I <module_name>.mod.
5090 As a result, this variable is left empty, by default. For situations in
5091 which the compiler does not necessarily follow the normal convention,
5092 the user may use this variable. Its value will be appended to every
5093 module file name as scons attempts to resolve dependencies.
5095 .IP FORTRANMODSUFFIX
5096 The module file suffix used by the Fortran compiler. SCons assumes that
5097 the Fortran compiler follows the quasi-standard naming convention for
5099 .I <module_name>.mod.
5100 As a result, this variable is set to ".mod", by default. For situations
5101 in which the compiler does not necessarily follow the normal convention,
5102 the user may use this variable. Its value will be appended to every
5103 module file name as scons attempts to resolve dependencies.
5106 The list of directories that the Fortran compiler will search for
5107 include files and (for some compilers) module files. The Fortran implicit
5108 dependency scanner will search these directories for include files (but
5109 not module files since they are autogenerated and, as such, may not
5110 actually exist at the time the scan takes place). Don't explicitly put
5111 include directory arguments in FORTRANFLAGS because the result will be
5112 non-portable and the directories will not be searched by the dependency
5113 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5114 to the SConscript directory when they are used in a command. To force
5116 to look-up a directory relative to the root of the source tree use #:
5119 env = Environment(FORTRANPATH='#/include')
5123 The directory look-up can also be forced using the
5128 include = Dir('include')
5129 env = Environment(FORTRANPATH=include)
5133 The directory list will be added to command lines
5134 through the automatically-generated
5136 construction variable,
5137 which is constructed by
5138 appending the values of the
5139 $INCPREFIX and $INCSUFFIX
5140 construction variables
5141 to the beginning and end
5142 of each directory in $FORTRANPATH.
5143 Any command lines you define that need
5144 the FORTRANPATH directory list should
5145 include $_FORTRANINCFLAGS:
5148 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5152 The command line used to compile a Fortran source file to an object file
5153 after first running the file through the C preprocessor.
5154 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5155 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5156 construction variables are included on this command line.
5159 The list of suffixes of files that will be scanned
5160 for Fortran implicit dependencies
5161 (INCLUDE lines & USE statements).
5162 The default list is:
5165 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5166 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5170 A function that converts a file name into a File instance relative to the
5174 The Ghostscript program used to convert PostScript to PDF files.
5177 General options passed to the Ghostscript program
5178 when converting PostScript to PDF files.
5181 The Ghostscript command line used to convert PostScript to PDF files.
5184 The list of suffixes of files that will be scanned
5185 for IDL implicit dependencies
5186 (#include or import lines).
5187 The default list is:
5194 The prefix used to specify an include directory on the C compiler command
5196 This will be appended to the beginning of each directory
5197 in the $CPPPATH and $FORTRANPATH construction variables
5198 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5199 variables are automatically generated.
5202 The suffix used to specify an include directory on the C compiler command
5204 This will be appended to the end of each directory
5205 in the $CPPPATH and $FORTRANPATH construction variables
5206 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5207 variables are automatically generated.
5210 A function to be called to install a file into a
5211 destination file name.
5212 The default function copies the file into the destination
5213 (and sets the destination file's mode and permission bits
5214 to match the source file's).
5215 The function takes the following arguments:
5218 def install(dest, source, env):
5222 is the path name of the destination file.
5224 is the path name of the source file.
5226 is the construction environment
5227 (a dictionary of construction values)
5228 in force for this file installation.
5231 The Java archive tool.
5234 The directory to which the Java archive tool should change
5240 The command line used to call the Java archive tool.
5243 General options passed to the Java archive tool.
5244 By default this is set to
5246 to create the necessary
5251 The suffix for Java archives:
5259 The command line used to compile a directory tree containing
5260 Java source files to
5261 corresponding Java class files.
5262 Any options specified in the $JAVACFLAGS construction variable
5263 are included on this command line.
5266 General options that are passed to the Java compiler.
5269 The directory in which Java class files may be found.
5270 This is stripped from the beginning of any Java .class
5271 file names supplied to the
5276 The suffix for Java class files;
5281 The Java generator for C header and stub files.
5284 The command line used to generate C header and stub files
5286 Any options specified in the $JAVAHFLAGS construction variable
5287 are included on this command line.
5290 General options passed to the C header and stub file generator
5294 The suffix for Java files;
5299 The LaTeX structured formatter and typesetter.
5302 The command line used to call the LaTeX structured formatter and typesetter.
5305 General options passed to the LaTeX structured formatter and typesetter.
5308 The lexical analyzer generator.
5311 General options passed to the lexical analyzer generator.
5314 The command line used to call the lexical analyzer generator
5315 to generate a source file.
5318 An automatically-generated construction variable
5319 containing the linker command-line options
5320 for specifying directories to be searched for library.
5321 The value of $_LIBDIRFLAGS is created
5322 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5323 to the beginning and end
5324 of each directory in $LIBPATH.
5327 The prefix used to specify a library directory on the linker command line.
5328 This will be appended to the beginning of each directory
5329 in the $LIBPATH construction variable
5330 when the $_LIBDIRFLAGS variable is automatically generated.
5333 The suffix used to specify a library directory on the linker command line.
5334 This will be appended to the end of each directory
5335 in the $LIBPATH construction variable
5336 when the $_LIBDIRFLAGS variable is automatically generated.
5339 An automatically-generated construction variable
5340 containing the linker command-line options
5341 for specifying libraries to be linked with the resulting target.
5342 The value of $_LIBFLAGS is created
5343 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5344 to the beginning and end
5345 of each directory in $LIBS.
5348 The prefix used to specify a library to link on the linker command line.
5349 This will be appended to the beginning of each library
5350 in the $LIBS construction variable
5351 when the $_LIBFLAGS variable is automatically generated.
5354 The suffix used to specify a library to link on the linker command line.
5355 This will be appended to the end of each library
5356 in the $LIBS construction variable
5357 when the $_LIBFLAGS variable is automatically generated.
5360 The list of directories that will be searched for libraries.
5361 The implicit dependency scanner will search these
5362 directories for include files. Don't explicitly put include directory
5363 arguments in $LINKFLAGS or $SHLINKFLAGS
5364 because the result will be non-portable
5365 and the directories will not be searched by the dependency scanner. Note:
5366 directory names in LIBPATH will be looked-up relative to the SConscript
5367 directory when they are used in a command. To force
5369 to look-up a directory relative to the root of the source tree use #:
5372 env = Environment(LIBPATH='#/libs')
5376 The directory look-up can also be forced using the
5382 env = Environment(LIBPATH=libs)
5386 The directory list will be added to command lines
5387 through the automatically-generated
5389 construction variable,
5390 which is constructed by
5391 appending the values of the
5392 $LIBDIRPREFIX and $LIBDIRSUFFIX
5393 construction variables
5394 to the beginning and end
5395 of each directory in $LIBPATH.
5396 Any command lines you define that need
5397 the LIBPATH directory list should
5398 include $_LIBDIRFLAGS:
5401 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5405 The prefix used for (static) library file names.
5406 A default value is set for each platform
5407 (posix, win32, os2, etc.),
5408 but the value is overridden by individual tools
5409 (ar, mslib, sgiar, sunar, tlib, etc.)
5410 to reflect the names of the libraries they create.
5413 An array of legal prefixes for library file names.
5416 A list of one or more libraries
5417 that will be linked with
5418 any executable programs
5419 created by this environment.
5422 The library list will be added to command lines
5423 through the automatically-generated
5425 construction variable,
5426 which is constructed by
5427 appending the values of the
5428 $LIBLINKPREFIX and $LIBLINKSUFFIX
5429 construction variables
5430 to the beginning and end
5431 of each directory in $LIBS.
5432 Any command lines you define that need
5433 the LIBS library list should
5437 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5441 The suffix used for (static) library file names.
5442 A default value is set for each platform
5443 (posix, win32, os2, etc.),
5444 but the value is overridden by individual tools
5445 (ar, mslib, sgiar, sunar, tlib, etc.)
5446 to reflect the names of the libraries they create.
5449 An array of legal suffixes for library file names.
5455 General user options passed to the linker.
5456 Note that this variable should
5460 (or similar) options for linking with the libraries listed in $LIBS,
5463 (or similar) library search path options
5464 that scons generates automatically from $LIBPATH.
5468 for the variable that expands to library-link options,
5472 for the variable that expands to library search path options.
5475 The command line used to link object files into an executable.
5478 The M4 macro preprocessor.
5481 General options passed to the M4 macro preprocessor.
5484 The command line used to pass files through the macro preprocessor.
5487 The maximum number of characters allowed on an external command line.
5489 link lines longer than this many characters
5490 are linke via a temporary file name.
5493 When the Microsoft Visual Studio tools are initialized, they set up
5494 this dictionary with the following keys:
5497 the version of MSVS being used (can be set via
5501 the available versions of MSVS installed
5504 installed directory of Visual C++
5507 installed directory of Visual Studio
5510 installed directory of the .NET framework
5512 .B FRAMEWORKVERSIONS:
5513 list of installed versions of the .NET framework, sorted latest to oldest.
5515 .B FRAMEWORKVERSION:
5516 latest installed version of the .NET framework
5519 installed location of the .NET SDK.
5522 installed location of the Platform SDK.
5524 .B PLATFORMSDK_MODULES:
5525 dictionary of installed Platform SDK modules,
5526 where the dictionary keys are keywords for the various modules, and
5527 the values are 2-tuples where the first is the release date, and the
5528 second is the version number.
5530 If a value isn't set, it wasn't available in the registry.
5532 .IP MSVS_IGNORE_IDE_PATHS
5533 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5534 instead of the settings from the IDE.
5536 For Visual Studio, SCons will (by default) automatically determine
5537 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5538 set by the IDE. You can override this behavior by setting these
5539 variables after Environment initialization, or by setting
5540 .B MSVS_IGNORE_IDE_PATHS = 1
5541 in the Environment initialization.
5542 Specifying this will not leave these unset, but will set them to a
5543 minimal set of paths needed to run the tools successfully.
5546 For VS6, the mininimal set is:
5547 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5548 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5549 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5551 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5552 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5553 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5557 Where '<VSDir>' is the installed location of Visual Studio.
5559 .IP MSVS_USE_MFC_DIRS
5560 Tells the MS Visual Studio tool(s) to use
5561 the MFC directories in its default paths
5562 for compiling and linking.
5563 Under MSVS version 6,
5565 .B MSVS_USE_MFC_DIRS
5574 external environment variable,
5580 external environment variable.
5581 Under MSVS version 7,
5583 .B MSVS_USE_MFC_DIRS
5586 .B "atlmfc\\\\include"
5587 directory to the default
5589 external environment variable,
5592 directory to the default
5594 external environment variable.
5595 The current default value is
5597 which means these directories
5598 are added to the paths by default.
5599 This default value is likely to change
5600 in a future release,
5601 so users who want the ATL and MFC
5602 values included in their paths
5603 are encouraged to enable the
5604 .B MSVS_USE_MFC_DIRS
5606 to avoid future incompatibility.
5607 This variable has no effect if the
5611 environment variables are set explictly.
5614 Sets the preferred version of MSVS to use.
5616 SCons will (by default) select the latest version of MSVS
5617 installed on your machine. So, if you have version 6 and version 7
5618 (MSVS .NET) installed, it will prefer version 7. You can override this by
5621 variable in the Environment initialization, setting it to the
5622 appropriate version ('6.0' or '7.0', for example).
5623 If the given version isn't installed, tool initialization will fail.
5626 The action used to generate Microsoft Visual Studio
5627 project and solution files.
5629 .IP MSVSPROJECTSUFFIX
5630 The suffix used for Microsoft Visual Studio project (DSP) files.
5631 The default value is
5633 when using Visual Studio version 7.x (.NET),
5636 when using earlier versions of Visual Studio.
5638 .IP MSVSSOLUTIONSUFFIX
5639 The suffix used for Microsoft Visual Studio solution (DSW) files.
5640 The default value is
5642 when using Visual Studio version 7.x (.NET),
5645 when using earlier versions of Visual Studio.
5648 When set to non-zero,
5649 suppresses creation of a corresponding Win32 static import lib by the
5651 builder when used with
5652 MinGW or Microsoft Visual Studio.
5653 This also suppresses creation
5654 of an export (.exp) file
5655 when using Microsoft Visual Studio.
5658 The prefix used for (static) object file names.
5661 The suffix used for (static) object file names.
5664 The Perforce executable.
5667 The command line used to
5668 fetch source files from Perforce.
5671 General options that are passed to Perforce.
5674 The Microsoft Visual C++ precompiled header that will be used when compiling
5675 object files. This variable is ignored by tools other than Microsoft Visual C++.
5676 When this variable is
5677 defined SCons will add options to the compiler command line to
5678 cause it to use the precompiled header, and will also set up the
5679 dependencies for the PCH file. Example:
5682 env['PCH'] = 'StdAfx.pch'
5686 This variable specifies how much of a source file is precompiled. This
5687 variable is ignored by tools other than Microsoft Visual C++, or when
5688 the PCH variable is not being used. When this variable is define it
5689 must be a string that is the name of the header that
5690 is included at the end of the precompiled portion of the source files, or
5691 the empty string if the "#pragma hrdstop" construct is being used:
5694 env['PCHSTOP'] = 'StdAfx.h'
5698 The Microsoft Visual C++ PDB file that will store debugging information for
5699 object files, shared libraries, and programs. This variable is ignored by
5700 tools other than Microsoft Visual C++.
5701 When this variable is
5702 defined SCons will add options to the compiler and linker command line to
5703 cause them to generate external debugging information, and will also set up the
5704 dependencies for the PDB file. Example:
5707 env['PDB'] = 'hello.pdb'
5711 A deprecated synonym for $DVIPDFCOM.
5714 The prefix used for PDF file names.
5717 The suffix used for PDF file names.
5720 The name of the platform used to create the Environment. If no platform is
5721 specified when the Environment is created,
5723 autodetects the platform.
5726 env = Environment(tools = [])
5727 if env['PLATFORM'] == 'cygwin':
5733 .IP PRINT_CMD_LINE_FUNC
5734 A Python function used to print the command lines as they are executed
5735 (assuming command printing is not disabled by the
5739 options or their equivalents).
5740 The function should take four arguments:
5742 the command being executed (a string),
5744 the target being built (file node, list, or string name(s)),
5746 the source(s) used (file node, list, or string name(s)), and
5748 the environment being used.
5750 The function must do the printing itself. The default implementation,
5751 used if this variable is not set or is None, is:
5753 def print_cmd_line(s, target, source, env):
5754 sys.stdout.write(s + "\n")
5757 Here's an example of a more interesting function:
5759 def print_cmd_line(s, target, source, env):
5760 sys.stdout.write("Building %s -> %s...\n" %
5761 (' and '.join([str(x) for x in source]),
5762 ' and '.join([str(x) for x in target])))
5763 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
5764 env.Program('foo', 'foo.c')
5767 This just prints "Building <targetname> from <sourcename>..." instead
5768 of the actual commands.
5769 Such a function could also log the actual commands to a log file,
5773 The prefix used for executable file names.
5776 The suffix used for executable file names.
5779 The command line used to convert TeX DVI files into a PostScript file.
5782 The prefix used for PostScript file names.
5785 The prefix used for PostScript file names.
5788 The qt tool tries to take this from os.environ.
5789 It also initializes all QT_*
5790 construction variables listed below.
5791 (Note that all paths are constructed
5792 with python's os.path.join() method,
5793 but are listed here with the '/' separator
5794 for easier reading.)
5795 In addition, the construction environment
5796 variables CPPPATH, LIBPATH and LIBS may be modified
5798 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
5799 are modified. Because the build-performance is affected when using this tool,
5800 you have to explicitly specify it at Environment creation:
5803 Environment(tools=['default','qt'])
5806 The qt tool supports the following operations:
5808 .B Automatic moc file generation from header files.
5809 You do not have to specify moc files explicitly, the tool does it for you.
5810 However, there are a few preconditions to do so: Your header file must have
5811 the same filebase as your implementation file and must stay in the same
5812 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
5813 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
5814 See also the corresponding builder method
5817 .B Automatic moc file generation from cxx files.
5818 As stated in the qt documentation, include the moc file at the end of
5819 the cxx file. Note that you have to include the file, which is generated
5820 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
5821 <basename>.moc. A warning is generated after building the moc file, if you
5822 do not include the correct file. If you are using BuildDir, you may
5823 need to specify duplicate=1. You can turn off automatic moc file generation
5824 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
5827 .B Automatic handling of .ui files.
5828 The implementation files generated from .ui files are handled much the same
5829 as yacc or lex files. Each .ui file given as a source of Program, Library or
5830 SharedLibrary will generate three files, the declaration file, the
5831 implementation file and a moc file. Because there are also generated headers,
5832 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
5836 Turn off scanning for mocable files. Use the Moc Builder to explicitely
5837 specify files to run moc on.
5840 The path where the qt binaries are installed.
5841 The default value is '$QTDIR/bin'.
5844 The path where the qt header files are installed.
5845 The default value is '$QTDIR/include'.
5846 Note: If you set this variable to None, the tool won't change the CPPPATH
5847 construction variable.
5850 Prints lots of debugging information while scanning for moc files.
5853 The path where the qt libraries are installed.
5854 The default value is '$QTDIR/lib'.
5855 Note: If you set this variable to None, the tool won't change the LIBPATH
5856 construction variable.
5859 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
5860 this variable to None, the tool won't change the LIBS variable.
5863 Default value is '$QT_BINPATH/moc'.
5866 Default value is ''. Prefix for moc output files, when source is a cxx file.
5869 Default value is '.moc'. Suffix for moc output files, when source is a cxx
5872 .IP QT_MOCFROMCPPFLAGS
5873 Default value is '-i'. These flags are passed to moc, when moccing a
5876 .IP QT_MOCFROMCXXCOM
5877 Command to generate a moc file from a cpp file.
5880 Command to generate a moc file from a header.
5882 .IP QT_MOCFROMHFLAGS
5883 Default value is ''. These flags are passed to moc, when moccing a header
5887 Default value is 'moc_'. Prefix for moc output files, when source is a header.
5890 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
5894 Default value is '$QT_BINPATH/uic'.
5897 Command to generate header files from .ui files.
5900 Default value is ''. These flags are passed to uic, when creating a a h
5901 file from a .ui file.
5903 .IP QT_UICDECLPREFIX
5904 Default value is ''. Prefix for uic generated header files.
5906 .IP QT_UICDECLSUFFIX
5907 Default value is '.h'. Suffix for uic generated header files.
5910 Command to generate cxx files from .ui files.
5913 Default value is ''. These flags are passed to uic, when creating a cxx
5914 file from a .ui file.
5916 .IP QT_UICIMPLPREFIX
5917 Default value is 'uic_'. Prefix for uic generated implementation files.
5919 .IP QT_UICIMPLSUFFIX
5920 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
5924 Default value is '.ui'. Suffix of designer input files.
5927 The archive indexer.
5930 General options passed to the archive indexer.
5933 The resource compiler used by the RES builder.
5936 The command line used by the RES builder.
5939 The flags passed to the resource compiler by the RES builder.
5943 Note that this variable is not actually used
5944 for the command to fetch source files from RCS;
5947 construction variable, below.
5950 The RCS "checkout" executable,
5951 used to fetch source files from RCS.
5954 The command line used to
5955 fetch (checkout) source files from RCS.
5958 Options that are passed to the $RCS_CO command.
5961 A function that converts a file name into a list of Dir instances by
5962 searching the repositories.
5965 The Java RMI stub compiler.
5968 The command line used to compile stub
5969 and skeleton class files
5970 from Java classes that contain RMI implementations.
5971 Any options specified in the $RMICFLAGS construction variable
5972 are included on this command line.
5975 General options passed to the Java RMI stub compiler.
5978 The RPC protocol compiler.
5980 .IP RPCGENCLIENTFLAGS
5981 Options passed to the RPC protocol compiler
5982 when generating client side stubs.
5983 These are in addition to any flags specified in the
5985 construction variable.
5988 General options passed to the RPC protocol compiler.
5990 .IP RPCGENHEADERFLAGS
5991 Options passed to the RPC protocol compiler
5992 when generating a header file.
5993 These are in addition to any flags specified in the
5995 construction variable.
5997 .IP RPCGENSERVICEFLAGS
5998 Options passed to the RPC protocol compiler
5999 when generating server side stubs.
6000 These are in addition to any flags specified in the
6002 construction variable.
6005 Options passed to the RPC protocol compiler
6006 when generating XDR routines.
6007 These are in addition to any flags specified in the
6009 construction variable.
6012 A list of paths to search for shared libraries when running programs.
6013 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6014 Ignored on platforms and toolchains that don't support it.
6015 Note that the paths added to RPATH
6016 are not transformed by
6018 in any way: if you want an absolute
6019 path, you must make it absolute yourself.
6022 A list of the available implicit dependency scanners.
6023 New file scanners may be added by
6024 appending to this list,
6025 although the more flexible approach
6026 is to associate scanners
6027 with a specific Builder.
6028 See the sections "Builder Objects"
6029 and "Scanner Objects,"
6030 below, for more information.
6033 The SCCS executable.
6036 The command line used to
6037 fetch source files from SCCS.
6040 General options that are passed to SCCS.
6043 Options that are passed specifically to the SCCS "get" subcommand.
6044 This can be set, for example, to
6046 to check out editable files from SCCS.
6049 The C compiler used for generating shared-library objects.
6052 The command line used to compile a C source file
6053 to a shared-library object file.
6054 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6055 are included on this command line.
6058 Options that are passed to the C compiler
6059 to generate shared-library objects.
6062 The C++ compiler used for generating shared-library objects.
6065 The command line used to compile a C++ source file
6066 to a shared-library object file.
6067 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6068 are included on this command line.
6071 Options that are passed to the C++ compiler
6072 to generate shared-library objects.
6075 A string naming the shell program that will be passed to the
6080 construction variable for more information.
6083 The Fortran 77 compiler used for generating shared-library objects.
6084 You should normally set the $SHFORTRANC variable,
6085 which specifies the default Fortran compiler
6086 for all Fortran versions.
6087 You only need to set $SHF77 if you need to use a specific compiler
6088 or compiler version for Fortran 77 files.
6091 The command line used to compile a Fortran 77 source file
6092 to a shared-library object file.
6093 You only need to set $SHF77COM if you need to use a specific
6094 command line for Fortran 77 files.
6095 You should normally set the $SHFORTRANCOM variable,
6096 which specifies the default command line
6097 for all Fortran versions.
6100 Options that are passed to the Fortran 77 compiler
6101 to generated shared-library objects.
6102 You only need to set $SHF77FLAGS if you need to define specific
6103 user options for Fortran 77 files.
6104 You should normally set the $SHFORTRANFLAGS variable,
6105 which specifies the user-specified options
6106 passed to the default Fortran compiler
6107 for all Fortran versions.
6110 The command line used to compile a Fortran 77 source file to a
6111 shared-library object file
6112 after first running the file through the C preprocessor.
6113 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6114 are included on this command line.
6115 You only need to set $SHF77PPCOM if you need to use a specific
6116 C-preprocessor command line for Fortran 77 files.
6117 You should normally set the $SHFORTRANPPCOM variable,
6118 which specifies the default C-preprocessor command line
6119 for all Fortran versions.
6122 The Fortran 90 compiler used for generating shared-library objects.
6123 You should normally set the $SHFORTRANC variable,
6124 which specifies the default Fortran compiler
6125 for all Fortran versions.
6126 You only need to set $SHF90 if you need to use a specific compiler
6127 or compiler version for Fortran 90 files.
6130 The command line used to compile a Fortran 90 source file
6131 to a shared-library object file.
6132 You only need to set $SHF90COM if you need to use a specific
6133 command line for Fortran 90 files.
6134 You should normally set the $SHFORTRANCOM variable,
6135 which specifies the default command line
6136 for all Fortran versions.
6139 Options that are passed to the Fortran 90 compiler
6140 to generated shared-library objects.
6141 You only need to set $SHF90FLAGS if you need to define specific
6142 user options for Fortran 90 files.
6143 You should normally set the $SHFORTRANFLAGS variable,
6144 which specifies the user-specified options
6145 passed to the default Fortran compiler
6146 for all Fortran versions.
6149 The command line used to compile a Fortran 90 source file to a
6150 shared-library object file
6151 after first running the file through the C preprocessor.
6152 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6153 are included on this command line.
6154 You only need to set $SHF90PPCOM if you need to use a specific
6155 C-preprocessor command line for Fortran 90 files.
6156 You should normally set the $SHFORTRANPPCOM variable,
6157 which specifies the default C-preprocessor command line
6158 for all Fortran versions.
6161 The Fortran 95 compiler used for generating shared-library objects.
6162 You should normally set the $SHFORTRANC variable,
6163 which specifies the default Fortran compiler
6164 for all Fortran versions.
6165 You only need to set $SHF95 if you need to use a specific compiler
6166 or compiler version for Fortran 95 files.
6169 The command line used to compile a Fortran 95 source file
6170 to a shared-library object file.
6171 You only need to set $SHF95COM if you need to use a specific
6172 command line for Fortran 95 files.
6173 You should normally set the $SHFORTRANCOM variable,
6174 which specifies the default command line
6175 for all Fortran versions.
6178 Options that are passed to the Fortran 95 compiler
6179 to generated shared-library objects.
6180 You only need to set $SHF95FLAGS if you need to define specific
6181 user options for Fortran 95 files.
6182 You should normally set the $SHFORTRANFLAGS variable,
6183 which specifies the user-specified options
6184 passed to the default Fortran compiler
6185 for all Fortran versions.
6188 The command line used to compile a Fortran 95 source file to a
6189 shared-library object file
6190 after first running the file through the C preprocessor.
6191 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6192 are included on this command line.
6193 You only need to set $SHF95PPCOM if you need to use a specific
6194 C-preprocessor command line for Fortran 95 files.
6195 You should normally set the $SHFORTRANPPCOM variable,
6196 which specifies the default C-preprocessor command line
6197 for all Fortran versions.
6200 The default Fortran compiler used for generating shared-library objects.
6203 The command line used to compile a Fortran source file
6204 to a shared-library object file.
6207 Options that are passed to the Fortran compiler
6208 to generate shared-library objects.
6211 The command line used to compile a Fortran source file to a
6212 shared-library object file
6213 after first running the file through the C preprocessor.
6214 Any options specified
6215 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6216 are included on this command line.
6219 The prefix used for shared library file names.
6222 The suffix used for shared library file names.
6225 The linker for programs that use shared libraries.
6228 General user options passed to the linker for programs using shared libraries.
6229 Note that this variable should
6233 (or similar) options for linking with the libraries listed in $LIBS,
6236 (or similar) include search path options
6237 that scons generates automatically from $LIBPATH.
6241 for the variable that expands to library-link options,
6245 for the variable that expands to library search path options.
6248 The prefix used for shared object file names.
6251 The suffix used for shared object file names.
6254 A reserved variable name
6255 that may not be set or used in a construction environment.
6256 (See "Variable Substitution," below.)
6259 A reserved variable name
6260 that may not be set or used in a construction environment.
6261 (See "Variable Substitution," below.)
6264 A command interpreter function that will be called to execute command line
6265 strings. The function must expect the following arguments:
6268 def spawn(shell, escape, cmd, args, env):
6272 is a string naming the shell program to use.
6274 is a function that can be called to escape shell special characters in
6277 is the path to the command to be executed.
6279 is the arguments to the command.
6281 is a dictionary of the environment variables
6282 in which the command should be executed.
6285 '\"The Subversion executable (usually named
6289 '\"The command line used to
6290 '\"fetch source files from a Subversion repository.
6293 '\"General options that are passed to Subversion.
6296 The scripting language wrapper and interface generator.
6299 The suffix that will be used for intermediate C
6300 source files generated by
6301 the scripting language wrapper and interface generator.
6302 The default value is
6303 .BR _wrap$CFILESUFFIX .
6304 By default, this value is used whenever the
6308 specified as part of the
6310 construction variable.
6313 The command line used to call
6314 the scripting language wrapper and interface generator.
6316 .IP SWIGCXXFILESUFFIX
6317 The suffix that will be used for intermediate C++
6318 source files generated by
6319 the scripting language wrapper and interface generator.
6320 The default value is
6321 .BR _wrap$CFILESUFFIX .
6322 By default, this value is used whenever the
6324 option is specified as part of the
6326 construction variable.
6329 General options passed to
6330 the scripting language wrapper and interface generator.
6331 This is where you should set
6335 or whatever other options you want to specify to SWIG.
6338 option in this variable,
6341 generate a C++ intermediate source file
6342 with the extension that is specified as the
6350 The command line used to call the tar archiver.
6353 General options passed to the tar archiver.
6356 A reserved variable name
6357 that may not be set or used in a construction environment.
6358 (See "Variable Substitution," below.)
6361 A reserved variable name
6362 that may not be set or used in a construction environment.
6363 (See "Variable Substitution," below.)
6366 The suffix used for tar file names.
6369 The TeX formatter and typesetter.
6372 The command line used to call the TeX formatter and typesetter.
6375 General options passed to the TeX formatter and typesetter.
6378 A list of the names of the Tool specifications
6379 that are part of this construction environment.
6381 .IP WIN32_INSERT_DEF
6382 When this is set to true,
6383 a library build of a WIN32 shared library (.dll file)
6384 will also build a corresponding .def file at the same time,
6385 if a .def file is not already listed as a build target.
6386 The default is 0 (do not build a .def file).
6389 The prefix used for WIN32 .def file names.
6392 The suffix used for WIN32 .def file names.
6395 The parser generator.
6398 The command line used to call the parser generator
6399 to generate a source file.
6402 General options passed to the parser generator.
6403 If $YACCFLAGS contains a \-d option,
6404 SCons assumes that the call will also create a .h file
6405 (if the yacc source file ends in a .y suffix)
6407 (if the yacc source file ends in a .yy suffix)
6410 The zip compression and file packaging utility.
6413 The command line used to call the zip utility,
6414 or the internal Python function used to create a
6423 module used by the internal Python function
6424 to control whether the zip archive
6425 is compressed or not.
6426 The default value is
6427 .BR zipfile.ZIP_DEFLATED ,
6428 which creates a compressed zip archive.
6429 This value has no effect when using Python 1.5.2
6432 module is otherwise unavailable.
6435 General options passed to the zip utility.
6438 Construction variables can be retrieved and set using the
6440 method of the construction environment:
6443 dict = env.Dictionary()
6447 or using the [] operator:
6453 Construction variables can also be passed to the construction environment
6457 env = Environment(CC="cc")
6460 or when copying a construction environment using the
6465 env2 = env.Copy(CC="cl.exe")
6468 .SS Configure Contexts
6472 .I configure contexts,
6473 an integrated mechanism similar to the
6474 various AC_CHECK macros in GNU autoconf
6475 for testing for the existence of C header
6476 files, libraries, etc.
6477 In contrast to autoconf,
6479 does not maintain an explicit cache of the tested values,
6480 but uses its normal dependency tracking to keep the checked values
6481 up to date. However, users may override this behaviour with the
6483 command line option.
6485 The following methods can be used to perform checks:
6488 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
6490 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
6491 This creates a configure context, which can be used to perform checks.
6493 specifies the environment for building the tests.
6494 This environment may be modified when performing checks.
6496 is a dictionary containing custom tests.
6497 See also the section about custom tests below.
6498 By default, no custom tests are added to the configure context.
6500 specifies a directory where the test cases are built.
6501 Note that this directory is not used for building
6503 The default value is the directory
6506 specifies a file which collects the output from commands
6507 that are executed to check for the existence of header files, libraries, etc.
6508 The default is the file #/config.log.
6509 If you are using the
6512 you may want to specify a subdirectory under your build directory.
6514 specifies a C header file where the results of tests
6515 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
6516 The default is to not write a
6519 You can specify the same
6521 file in multiple calls to Configure,
6524 will concatenate all results in the specified file.
6526 uses its normal dependency checking
6527 to decide if it's necessary to rebuild
6531 This means that the file is not necessarily re-built each
6533 but is only rebuilt if its contents will have changed
6534 and some target that depends on the
6536 file is being built.
6541 instance has the following associated methods:
6544 .RI Configure.Finish( self )
6545 This method should be called after configuration is done.
6546 It returns the environment as modified
6547 by the configuration checks performed.
6548 After this method is called, no further checks can be performed
6549 with this configuration context.
6550 However, you can create a new
6552 context to perform additional checks.
6553 Only one context should be active at a time.
6555 The following Checks are predefined.
6556 (This list will likely grow larger as time
6557 goes by and developers contribute new useful tests.)
6560 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
6563 is usable in the specified language.
6566 in which case the last item in the list
6567 is the header file to be checked,
6568 and the previous list items are
6571 lines should precede the
6572 header line being checked for.
6573 The optional argument
6576 a two character string, where the first character denotes the opening
6577 quote and the second character denotes the closing quote.
6578 By default, both characters are " (double quote).
6579 The optional argument
6585 and selects the compiler to be used for the check.
6586 Returns 1 on success and 0 on failure.
6589 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
6590 This is a wrapper around
6591 .B Configure.CheckHeader
6594 is usable in the C language.
6597 in which case the last item in the list
6598 is the header file to be checked,
6599 and the previous list items are
6602 lines should precede the
6603 header line being checked for.
6604 The optional argument
6607 a two character string, where the first character denotes the opening
6608 quote and the second character denotes the closing quote (both default
6610 Returns 1 on success and 0 on failure.
6613 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
6614 This is a wrapper around
6615 .B Configure.CheckHeader
6618 is usable in the C++ language.
6621 in which case the last item in the list
6622 is the header file to be checked,
6623 and the previous list items are
6626 lines should precede the
6627 header line being checked for.
6628 The optional argument
6631 a two character string, where the first character denotes the opening
6632 quote and the second character denotes the closing quote (both default
6634 Returns 1 on success and 0 on failure.
6637 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
6638 Checks if the specified
6639 C or C++ function is available.
6641 is the name of the function to check for.
6644 argument is a string
6648 that will be compiled
6649 to check if the function exists;
6655 char function_name();
6663 and selects the compiler to be used for the check;
6667 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
6674 is 1 and the library provides the specified
6676 appends the library to the LIBS construction environment variable.
6678 may also be None (the default),
6681 is checked with the current LIBS variable,
6682 or a list of library names,
6683 in which case each library in the list
6690 you can link against the specified
6698 and selects the compiler to be used for the check;
6700 The default value for
6703 It is assumed, that the C-language is used.
6704 This method returns 1 on success and 0 on error.
6707 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
6710 .RI Configure.CheckLib
6711 call, this call provides a more sophisticated way to check against libraries.
6714 specifies the library or a list of libraries to check.
6716 specifies a header to check for.
6719 in which case the last item in the list
6720 is the header file to be checked,
6721 and the previous list items are
6724 lines should precede the
6725 header line being checked for.
6727 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
6729 can be any valid expression (with a trailing ';'). The default is 'main();'.
6731 specifies whether to add the library to the environment (only if the check
6732 succeeds). This method returns 1 on success and 0 on error.
6735 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
6736 Checks for the existence of a type defined by
6739 specifies the typedef name to check for.
6741 is a string containing one or more
6743 lines that will be inserted into the program
6744 that will be run to test for the existence of the type.
6751 and selects the compiler to be used for the check;
6755 Example of a typical Configure usage:
6759 conf = Configure( env )
6760 if not conf.CheckCHeader( 'math.h' ):
6761 print 'We really need math.h!'
6763 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
6764 # do stuff for qt - usage, e.g.
6765 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
6770 You can define your own custom checks.
6771 in addition to the predefined checks.
6772 These are passed in a dictionary to the Configure function.
6773 This dictionary maps the names of the checks
6774 to user defined Python callables
6775 (either Python functions or class instances implementing the
6778 The first argument of the call is always a
6780 instance followed by the arguments,
6781 which must be supplied by the user of the check.
6782 These CheckContext instances define the following methods:
6785 .RI CheckContext.Message( self ", " text )
6787 Usually called before the check is started.
6789 will be displayed to the user, e.g. 'Checking for library X...'
6792 .RI CheckContext.Result( self, ", " res )
6794 Usually called after the check is done.
6796 can be either an integer or a string. In the former case, 'ok' (res != 0)
6797 or 'failed' (res == 0) is displayed to the user, in the latter case the
6798 given string is displayed.
6801 .RI CheckContext.TryCompile( self ", " text ", " extension )
6802 Checks if a file with the specified
6804 (e.g. '.c') containing
6806 can be compiled using the environment's
6808 builder. Returns 1 on success and 0 on failure.
6811 .RI CheckContext.TryLink( self ", " text ", " extension )
6812 Checks, if a file with the specified
6814 (e.g. '.c') containing
6816 can be compiled using the environment's
6818 builder. Returns 1 on success and 0 on failure.
6821 .RI CheckContext.TryRun( self ", " text ", " extension )
6822 Checks, if a file with the specified
6824 (e.g. '.c') containing
6826 can be compiled using the environment's
6828 builder. On success, the program is run. If the program
6829 executes successfully
6830 (that is, its return status is 0),
6835 is the standard output of the
6837 If the program fails execution
6838 (its return status is non-zero),
6839 then (0, '') is returned.
6842 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
6843 Checks if the specified
6845 with an optional source file (contents
6852 may be anything which can be converted to a
6859 is the content of the target file.
6865 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
6866 Low level implementation for testing specific builds;
6867 the methods above are based on this method.
6868 Given the Builder instance
6872 of a source file with optional
6874 this method returns 1 on success and 0 on failure. In addition,
6876 is set to the build target node, if the build was successful.
6879 Example for implementing and using custom tests:
6882 def CheckQt(context, qtdir):
6883 context.Message( 'Checking for qt ...' )
6884 lastLIBS = context.env['LIBS']
6885 lastLIBPATH = context.env['LIBPATH']
6886 lastCPPPATH= context.env['CPPPATH']
6887 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
6888 ret = context.TryLink("""
6890 int main(int argc, char **argv) {
6891 QApplication qapp(argc, argv);
6896 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
6897 context.Result( ret )
6901 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
6902 if not conf.CheckQt('/usr/lib/qt'):
6903 print 'We really need qt!'
6908 .SS Construction Variable Options
6910 Often when building software, various options need to be specified at build
6911 time that are not known when the SConstruct/SConscript files are
6912 written. For example, libraries needed for the build may be in non-standard
6913 locations, or site-specific compiler options may need to be passed to the
6916 provides a mechanism for overridding construction variables from the
6917 command line or a text-based SConscript file through an Options
6918 object. To create an Options object, call the Options() function:
6921 .RI Options([ files "], [" args ])
6922 This creates an Options object that will read construction variables from
6923 the file or list of filenames specified in
6925 If no files are specified,
6930 then no files will be read.
6931 The optional argument
6934 values that will override anything read from the specified files;
6935 it is primarily intended to be passed the
6937 dictionary that holds variables
6938 specified on the command line.
6942 opts = Options('custom.py')
6943 opts = Options('overrides.py', ARGUMENTS)
6944 opts = Options(None, {FOO:'expansion', BAR:7})
6947 Options objects have the following methods:
6950 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
6951 This adds a customizable construction variable to the Options object.
6953 is the name of the variable.
6955 is the help text for the variable.
6957 is the default value of the variable.
6959 is called to validate the value of the variable, and should take three
6960 arguments: key, value, and environment
6962 is called to convert the value before putting it in the environment, and
6963 should take a single argument: value. Example:
6966 opts.Add('CC', 'The C compiler')
6970 .RI AddOptions( list )
6971 A wrapper script that adds
6972 multiple customizable construction variables
6973 to an Options object.
6975 is a list of tuple or list objects
6976 that contain the arguments
6977 for an individual call to the
6984 ('CC', 'The C compiler'),
6985 ('VALIDATE', 'An option for testing validation',
6986 'notset', validator, None),
6991 .RI Update( env ", [" args ])
6992 This updates a construction environment
6994 with the customized construction variables. Normally this method is not
6995 called directly, but is called indirectly by passing the Options object to
6996 the Environment() function:
6999 env = Environment(options=opts)
7003 .RI Save( filename ", " env )
7004 This saves the currently set options into a script file named
7006 that can be used on the next invocation to automatically load the current
7007 settings. This method combined with the Options method can be used to
7008 support caching of options between runs.
7012 opts = Options(['options.cache', 'custom.py'])
7015 opts.Save('options.cache', env)
7019 .RI GenerateHelpText( env ", [" sort ])
7020 This generates help text documenting the customizable construction
7021 variables suitable to passing in to the Help() function.
7023 is the construction environment that will be used to get the actual values
7024 of customizable variables. Calling with
7028 will cause the output to be sorted
7029 by the specified argument.
7033 should take two arguments
7036 (like the standard Python
7041 Help(opts.GenerateHelpText(env))
7042 Help(opts.GenerateHelpText(env, sort=cmp))
7045 The text based SConscript file is executed as a Python script, and the
7046 global variables are queried for customizable construction
7053 To make it more convenient to work with customizable Options,
7055 provides a number of functions
7056 that make it easy to set up
7057 various types of Options:
7060 .RI BoolOption( key ", " help ", " default )
7061 Return a tuple of arguments
7062 to set up a Boolean option.
7066 have a default value of
7068 and display the specified
7071 The option will interpret the values
7093 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7094 Return a tuple of arguments
7096 whose value may be one
7097 of a specified list of legal enumerated values.
7101 have a default value of
7103 and display the specified
7106 The option will only support those
7112 argument is a dictionary
7113 that can be used to convert
7114 input values into specific legal values
7123 then the values are case-sensitive.
7128 then values will be matched
7134 then values will be matched
7136 and all input values will be
7137 converted to lower case.
7140 .RI ListOption( key ", " help ", " default ", " names )
7141 Return a tuple of arguments
7143 whose value may be one or more
7144 of a specified list of legal enumerated values.
7148 have a default value of
7150 and display the specified
7153 The option will only support the values
7156 or the values in the
7159 More than one value may be specified,
7160 with all values separated by commas.
7161 The default may be a string of
7162 comma-separated default values,
7163 or a list of the default values.
7166 .RI PackageOption( key ", " help ", " default )
7167 Return a tuple of arguments
7169 whose value is a path name
7170 of a package that may be
7171 enabled, disabled or
7172 given an explicit path name.
7176 have a default value of
7178 and display the specified
7181 The option will support the values
7188 in which case the specified
7191 or the option may be set to an
7193 (typically the path name to a package
7194 that is being enabled).
7195 The option will also support the values
7201 to disable use of the specified option.
7204 .RI PathOption( key ", " help ", " default ", [" validator ])
7205 Return a tuple of arguments
7207 whose value is expected to be a path name.
7211 have a default value of
7213 and display the specified
7219 that will be called to
7220 verify that the specified path
7223 following ready-made validators:
7224 .BR PathOption.PathExists
7226 which verifies that the specified path exists;
7227 .BR PathOption.PathIsFile ,
7228 which verifies that the specified path is an existing file;
7229 .BR PathOption.PathIsDir ,
7230 which verifies that the specified path is an existing directory;
7232 .BR PathOption.PathIsDirCreate ,
7233 which verifies that the specified path is a directory,
7234 and will create the specified directory if the path exist.
7235 You may supply your own
7238 which must take three arguments
7240 the name of the options variable to be set;
7242 the specified value being checked;
7245 the construction environment)
7246 and should raise an exception
7247 if the specified value is not acceptable.
7250 These functions make it
7251 convenient to create a number
7252 of options with consistent behavior
7253 in a single call to the
7259 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7260 EnumOption('debug', 'debug output and symbols', 'no'
7261 allowed_values=('yes', 'no', 'full'),
7262 map={}, ignorecase=0), # case sensitive
7263 ListOption('shared',
7264 'libraries to build as shared libraries',
7266 names = list_of_libs),
7267 PackageOption('x11',
7268 'use X11 installed here (yes = search some places)',
7270 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7271 PathOption('foopath', 'where the foo library is installed', foopath,
7272 PathOption.PathIsDir),
7277 .SS File and Directory Nodes
7287 Nodes, respectively.
7288 python objects, respectively.
7289 Those objects have several user-visible attributes
7290 and methods that are often useful:
7296 This path is relative to the top-level directory
7300 The build path is the same as the source path if
7305 The absolute build path of the given file or directory.
7315 object representing the
7324 # Get the current build dir's path, relative to top.
7326 # Current dir's absolute path
7328 # Next line is always '.', because it is the top dir's path relative to itself.
7330 File('foo.c').srcnode().path # source path of the given source file.
7332 # Builders also return File objects:
7333 foo = env.Program('foo.c')
7334 print "foo will be built in %s"%foo.path
7340 can be extended to build different types of targets
7341 by adding new Builder objects
7342 to a construction environment.
7344 you should only need to add a new Builder object
7345 when you want to build a new type of file or other external target.
7346 If you just want to invoke a different compiler or other tool
7347 to build a Program, Object, Library, or any other
7348 type of output file for which
7350 already has an existing Builder,
7351 it is generally much easier to
7352 use those existing Builders
7353 in a construction environment
7354 that sets the appropriate construction variables
7357 Builder objects are created
7363 function accepts the following arguments:
7366 The command line string used to build the target from the source.
7369 a list of strings representing the command
7370 to be executed and its arguments
7371 (suitable for enclosing white space in an argument),
7373 mapping source file name suffixes to
7374 any combination of command line strings
7375 (if the builder should accept multiple source file extensions),
7378 (see the next section);
7379 or a list of any of the above.
7382 takes three arguments:
7384 - a list of source nodes,
7386 - a list of target nodes,
7388 - the construction environment.
7391 The prefix that will be prepended to the target file name.
7392 This may be specified as a:
7402 - a function or other callable that takes
7403 two arguments (a construction environment and a list of sources)
7404 and returns a prefix,
7409 - specifies a mapping from a specific source suffix (of the first
7410 source specified) to a corresponding target prefix. Both the source
7411 suffix and target prefix specifications may use environment variable
7412 substitution, and the target prefix (the 'value' entries in the
7413 dictionary) may also be a callable object. The default target prefix
7414 may be indicated by a dictionary entry with a key value of None.
7419 b = Builder("build_it < $SOURCE > $TARGET"
7422 def gen_prefix(env, sources):
7423 return "file-" + env['PLATFORM'] + '-'
7424 b = Builder("build_it < $SOURCE > $TARGET",
7425 prefix = gen_prefix)
7427 b = Builder("build_it < $SOURCE > $TARGET",
7428 suffix = { None: "file-",
7429 "$SRC_SFX_A": gen_prefix })
7433 The suffix that will be appended to the target file name.
7434 This may be specified in the same manner as the prefix above.
7435 If the suffix is a string, then
7437 will append a '.' to the beginning of the suffix if it's not already
7438 there. The string returned by callable object (or obtained from the
7439 dictionary) is untouched and must append its own '.' to the beginning
7443 b = Builder("build_it < $SOURCE > $TARGET"
7446 def gen_suffix(env, sources):
7447 return "." + env['PLATFORM'] + "-file"
7448 b = Builder("build_it < $SOURCE > $TARGET",
7449 suffix = gen_suffix)
7451 b = Builder("build_it < $SOURCE > $TARGET",
7452 suffix = { None: ".sfx1",
7453 "$SRC_SFX_A": gen_suffix })
7457 The expected source file name suffix. This may be a string or a list
7461 A Scanner object that
7462 will be invoked to find
7463 implicit dependencies for this target file.
7464 This keyword argument should be used
7465 for Scanner objects that find
7466 implicit dependencies
7467 based only on the target file
7468 and the construction environment,
7471 (See the section "Scanner Objects," below,
7472 for information about creating Scanner objects.)
7475 A Scanner object that
7477 find implicit dependences in
7479 used to build this target file.
7480 This is where you would
7481 specify a scanner to
7484 lines in source files.
7485 (See the section "Scanner Objects," below,
7486 for information about creating Scanner objects.)
7489 A factory function that the Builder will use
7490 to turn any targets specified as strings into SCons Nodes.
7492 SCons assumes that all targets are files.
7493 Other useful target_factory
7496 for when a Builder creates a directory target,
7499 for when a Builder can create either a file
7500 or directory target.
7505 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
7507 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
7508 env.MakeDirectory('new_directory')
7512 A factory function that the Builder will use
7513 to turn any sources specified as strings into SCons Nodes.
7515 SCons assumes that all source are files.
7516 Other useful source_factory
7519 for when a Builder uses a directory as a source,
7522 for when a Builder can use files
7523 or directories (or both) as sources.
7528 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
7530 env.Append(BUILDERS = {'Collect':CollectBuilder})
7531 env.Collect('archive', ['directory_name', 'file_name'])
7535 A function or list of functions to manipulate the target and source
7536 lists before dependencies are established
7537 and the target(s) are actually built.
7539 can also be a string containing a construction variable to expand
7540 to an emitter function or list of functions,
7541 or a dictionary mapping source file suffixes
7542 to emitter functions.
7543 (Only the suffix of the first source file
7544 is used to select the actual emitter function
7545 from an emitter dictionary.)
7548 takes three arguments:
7550 - a list of source nodes,
7552 - a list of target nodes,
7554 - the construction environment.
7555 An emitter must return a tuple containing two lists,
7556 the list of targets to be built by this builder,
7557 and the list of sources for this builder.
7562 def e(target, source, env):
7563 return (target + ['foo.foo'], source + ['foo.src'])
7565 # Simple association of an emitter function with a Builder.
7566 b = Builder("my_build < $TARGET > $SOURCE",
7569 def e2(target, source, env):
7570 return (target + ['bar.foo'], source + ['bar.src'])
7572 # Simple association of a list of emitter functions with a Builder.
7573 b = Builder("my_build < $TARGET > $SOURCE",
7576 # Calling an emitter function through a construction variable.
7577 env = Environment(MY_EMITTER = e)
7578 b = Builder("my_build < $TARGET > $SOURCE",
7579 emitter = '$MY_EMITTER')
7581 # Calling a list of emitter functions through a construction variable.
7582 env = Environment(EMITTER_LIST = [e, e2])
7583 b = Builder("my_build < $TARGET > $SOURCE",
7584 emitter = '$EMITTER_LIST')
7586 # Associating multiple emitters with different file
7587 # suffixes using a dictionary.
7588 def e_suf1(target, source, env):
7589 return (target + ['another_target_file'], source)
7590 def e_suf2(target, source, env):
7591 return (target, source + ['another_source_file'])
7592 b = Builder("my_build < $TARGET > $SOURCE",
7593 emitter = {'.suf1' : e_suf1,
7601 arguments must not both be used for the same Builder.
7604 Specifies whether this builder is allowed to be called multiple times for
7605 the same target file(s). The default is 0, which means the builder
7606 can not be called multiple times for the same target file(s). Calling a
7607 builder multiple times for the same target simply adds additional source
7608 files to the target; it is not allowed to change the environment associated
7609 with the target, specify addition environment overrides, or associate a different
7610 builder with the target.
7613 A construction environment that can be used
7614 to fetch source code using this Builder.
7615 (Note that this environment is
7617 used for normal builds of normal target files,
7618 which use the environment that was
7619 used to call the Builder for the target file.)
7622 A function that returns a list of actions that will be executed to build
7623 the target(s) from the source(s).
7624 The returned action(s) may be
7625 an Action object, or anything that
7626 can be converted into an Action object
7627 (see the next section).
7629 The generator function
7630 takes four arguments:
7632 - a list of source nodes,
7634 - a list of target nodes,
7636 - the construction environment,
7638 - a Boolean value that specifies
7639 whether the generator is being called
7640 for generating a build signature
7641 (as opposed to actually executing the command).
7645 def g(source, target, env, for_signature):
7646 return [["gcc", "-c", "-o"] + target + source]
7648 b = Builder(generator=g)
7652 Specifies a builder to use when a source file name suffix does not match
7653 any of the suffixes of the builder. Using this argument produces a
7654 multi-stage builder.
7657 Specifies that this builder expects exactly one source file per call. Giving
7658 more than one source files without target files results in implicitely calling
7659 the builder multiple times (once for each source given). Giving multiple
7660 source files together with target files results in a UserError exception.
7668 arguments must not both be used for the same Builder.
7671 A construction environment that can be used
7672 to fetch source code using this Builder.
7673 (Note that this environment is
7675 used for normal builds of normal target files,
7676 which use the environment that was
7677 used to call the Builder for the target file.)
7680 b = Builder(action="build < $SOURCE > $TARGET")
7681 env = Environment(BUILDERS = {'MyBuild' : b})
7682 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
7686 Any additional keyword arguments supplied
7687 when a Builder object is created
7688 (that is, when the Builder() function is called)
7689 will be set in the executing construction
7690 environment when the Builder object is called.
7691 The canonical example here would be
7692 to set a construction variable to
7693 the repository of a source code system.
7695 Any additional keyword arguments supplied
7699 will only be associated with the target
7700 created by that particular Builder call
7701 (and any other files built as a
7702 result of the call).
7704 These extra keyword arguments are passed to the
7705 following functions:
7706 command generator functions,
7708 and emitter functions.
7714 function will turn its
7716 keyword argument into an appropriate
7717 internal Action object.
7718 You can also explicity create Action objects
7722 which can then be passed to the
7725 This can be used to configure
7726 an Action object more flexibly,
7727 or it may simply be more efficient
7728 than letting each separate Builder object
7729 create a separate Action
7731 Builder objects need to do the same thing.
7736 returns an appropriate object for the action
7737 represented by the type of the first argument:
7740 If the first argument is already an Action object,
7741 the object is simply returned.
7744 If the first argument is a string,
7745 a command-line Action is returned.
7748 Action('$CC -c -o $TARGET $SOURCES')
7751 .\" XXX From Gary Ruben, 23 April 2002:
7752 .\" What would be useful is a discussion of how you execute command
7753 .\" shell commands ie. what is the process used to spawn the shell, pass
7754 .\" environment variables to it etc., whether there is one shell per
7755 .\" environment or one per command etc. It might help to look at the Gnu
7756 .\" make documentation to see what they think is important to discuss about
7757 .\" a build system. I'm sure you can do a better job of organising the
7758 .\" documentation than they have :-)
7762 If the first argument is a list,
7763 then a list of Action objects is returned.
7764 An Action object is created as necessary
7765 for each element in the list.
7768 the list is itself a list,
7769 the internal list is the
7770 command and arguments to be executed via
7772 This allows white space to be enclosed
7773 in an argument by defining
7774 a command in a list within a list:
7777 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
7781 If the first argument is a Python function,
7782 a function Action is returned.
7783 The Python function takes three keyword arguments,
7785 (a Node object representing the target file),
7787 (a Node object representing the source file)
7790 (the construction environment
7791 used for building the target file).
7796 arguments may be lists of Node objects if there is
7797 more than one target file or source file.
7798 The actual target and source file name(s) may
7799 be retrieved from their Node objects
7800 via the built-in Python str() function:
7803 target_file_name = str(target)
7804 source_file_names = map(lambda x: str(x), source)
7807 The function should return
7811 to indicate a successful build of the target file(s).
7812 The function may raise an exception
7813 or return a non-zero exit status
7814 to indicate an unsuccessful build.
7817 def build_it(target = None, source = None, env = None):
7818 # build the target from the source
7821 a = Action(build_it)
7824 The second, optional argument
7825 is a Python function that returns
7826 a string to be printed to describe the action being executed.
7827 Like a function to build a file,
7828 this function takes three arguments:
7830 (a Node object representing the target file),
7832 (a Node object representing the source file)
7835 (a construction environment).
7840 arguments may be lists of Node objects if there is
7841 more than one target file or source file.
7845 def build_it(target, source, env):
7846 # build the target from the source
7849 def string_it(target, source, env):
7850 return "building '%s' from '%s'" % (target[0], source[0])
7852 # Use a positional argument.
7853 a = Action(build_it, string_it)
7855 # Alternatively, use a keyword argument.
7856 a = Action(build_it, strfunction=string_it)
7859 The third, also optional argument
7860 is a list of construction variables
7861 whose values will be included
7862 in the signature of the Action
7863 when deciding whether a target should
7864 be rebuilt because the action changed.
7865 This is necessary whenever you want a target to
7866 be rebuilt when a specific
7867 construction variable changes,
7868 because the underlying Python code for a function
7869 will not change when the value of the construction variable does.
7872 def build_it(target, source, env):
7873 # build the target from the 'XXX' construction variable
7874 open(target[0], 'w').write(env['XXX'])
7877 def string_it(target, source):
7878 return "building '%s' from '%s'" % (target[0], source[0])
7880 # Use positional arguments.
7881 a = Action(build_it, string_it, ['XXX'])
7883 # Alternatively, use a keyword argument.
7884 a = Action(build_it, varlist=['XXX'])
7887 If the action argument is not one of the above,
7890 .SS Miscellaneous Action Functions
7893 supplies a number of functions
7894 that arrange for various common
7895 file and directory manipulations
7897 These are similar in concept to "tasks" in the
7899 although the implementation is slightly different.
7900 These functions do not actually
7901 perform the specified action
7902 at the time the function is called,
7903 but instead return an Action object
7904 that can be executed at the
7906 (In Object-Oriented terminology,
7911 that return Action objects.)
7914 there are two natural ways
7917 are intended to be used.
7921 to perform the action
7922 at the time the SConscript
7926 global function to do so:
7928 Execute(Touch('file'))
7932 you can use these functions
7933 to supply Actions in a list
7937 This can allow you to
7938 perform more complicated
7939 sequences of file manipulation
7941 on platform-specific
7945 env = Environment(TMPBUILD = '/tmp/builddir')
7946 env.Command('foo.out', 'foo.in',
7947 [Mkdir('$TMPBUILD'),
7948 Copy('${SOURCE.dir}', '$TMPBUILD')
7949 "cd $TMPBUILD && make",
7950 Delete('$TMPBUILD')])
7954 .RI Chmod( dest ", " mode )
7955 Returns an Action object that
7956 changes the permissions on the specified
7958 file or directory to the specified
7963 Execute(Chmod('file', 0755))
7965 env.Command('foo.out', 'foo.in',
7966 [Copy('$TARGET', '$SOURCE'),
7967 Chmod('$TARGET', 0755)])
7971 .RI Copy( dest ", " src )
7972 Returns an Action object
7975 source file or directory to the
7977 destination file or directory.
7981 Execute(Copy('foo.output', 'foo.input'))
7983 env.Command('bar.out', 'bar.in',
7984 Copy('$TARGET', '$SOURCE'))
7988 .RI Delete( entry ", [" must_exist ])
7989 Returns an Action that
7990 deletes the specified
7992 which may be a file or a directory tree.
7993 If a directory is specified,
7994 the entire directory tree
7999 then a Python error will be thrown
8000 if the specified entry does not exist;
8003 that is, the Action will silently do nothing
8004 if the entry does not exist.
8008 Execute(Delete('/tmp/buildroot'))
8010 env.Command('foo.out', 'foo.in',
8011 [Delete('${TARGET.dir}'),
8014 Execute(Delete('file_that_must_exist', must_exist=1))
8020 that creates the specified
8026 Execute(Mkdir('/tmp/outputdir'))
8028 env.Command('foo.out', 'foo.in',
8029 [Mkdir('/tmp/builddir',
8030 Copy('$SOURCE', '/tmp/builddir')
8031 "cd /tmp/builddir && ])
8036 .RI Move( dest ", " src )
8038 that moves the specified
8040 file or directory to
8047 Execute(Move('file.destination', 'file.source'))
8049 env.Command('output_file', 'input_file',
8051 Move('$TARGET', 'file_created_by_MyBuildAction')])
8057 that updates the modification time
8063 Execute(Touch('file_to_be_touched'))
8065 env.Command('marker', 'input_file',
8070 .SS Variable Substitution
8072 Before executing a command,
8074 performs construction variable interpolation on the strings that make up
8075 the command line of builders.
8076 Variables are introduced by a
8079 Besides construction variables, scons provides the following
8080 variables for each command execution:
8083 The file name of the target being built, or the file name of the first
8084 target if multiple targets are being built.
8087 The file names of all targets being built.
8090 The file name of the source of the build command, or the file name of the
8091 first source if multiple sources are being built.
8094 The file names of the sources of the build command.
8096 (Note that the above variables are reserved
8097 and may not be set in a construction environment.)
8100 For example, given the construction variable CC='cc', targets=['foo'], and
8101 sources=['foo.c', 'bar.c']:
8104 action='$CC -c -o $TARGET $SOURCES'
8107 would produce the command line:
8110 cc -c -o foo foo.c bar.c
8113 Variable names may be surrounded by curly braces ({})
8114 to separate the name from the trailing characters.
8115 Within the curly braces, a variable name may have
8116 a Python slice subscript appended to select one
8117 or more items from a list.
8118 In the previous example, the string:
8130 Additionally, a variable name may
8131 have the following special
8132 modifiers appended within the enclosing curly braces
8133 to modify the interpolated string:
8136 The base path of the file name,
8137 including the directory path
8138 but excluding any suffix.
8141 The name of the directory in which the file exists.
8145 minus any directory portion.
8148 Just the basename of the file,
8150 and minus the directory.
8153 Just the file suffix.
8156 The absolute path name of the file.
8159 The POSIX form of the path,
8160 with directories separated by
8164 This is sometimes necessary on Win32 systems
8165 when a path references a file on other (POSIX) systems.
8168 The directory and file name to the source file linked to this file
8169 through BuildDir. If this file isn't linked, it just returns the
8170 directory and filename unchanged.
8173 The directory containing the source file linked to this file
8174 through BuildDir. If this file isn't linked, it just returns the
8175 directory part of the filename.
8178 The directory and file name to the source file linked to this file
8179 through BuildDir. If the file does not exist locally but exists in
8180 a Repository, the path in the Repository is returned.
8181 If this file isn't linked, it just returns the
8182 directory and filename unchanged.
8185 The Repository directory containing the source file linked to this file
8186 through BuildDir. If this file isn't linked, it just returns the
8187 directory part of the filename.
8190 For example, the specified target will
8191 expand as follows for the corresponding modifiers:
8194 $TARGET => sub/dir/file.x
8195 ${TARGET.base} => sub/dir/file
8196 ${TARGET.dir} => sub/dir
8197 ${TARGET.file} => file.x
8198 ${TARGET.filebase} => file
8199 ${TARGET.suffix} => .x
8200 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8202 BuildDir('sub/dir','src')
8203 $SOURCE => sub/dir/file.x
8204 ${SOURCE.srcpath} => src/file.x
8205 ${SOURCE.srcdir} => src
8207 Repository('/usr/repository')
8208 $SOURCE => sub/dir/file.x
8209 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8210 ${SOURCE.rsrcdir} => /usr/repository/src
8213 Lastly, a variable name
8214 may be a callable Python function
8216 construction variable in the environment.
8218 take four arguments:
8220 - a list of target nodes,
8222 - a list of source nodes,
8224 - the construction environment,
8226 - a Boolean value that specifies
8227 whether the function is being called
8228 for generating a build signature.
8229 SCons will insert whatever
8230 the called function returns
8231 into the expanded string:
8234 def foo(target, source, env, for_signature):
8237 # Will expand $BAR to "bar baz"
8238 env=Environment(FOO=foo, BAR="$FOO baz")
8241 You can use this feature to pass arguments to a
8242 Python function by creating a callable class
8243 that stores one or more arguments in an object,
8244 and then uses them when the
8247 Note that in this case,
8248 the entire variable expansion must
8249 be enclosed by curly braces
8250 so that the arguments will
8251 be associated with the
8252 instantiation of the class:
8256 def __init__(self, arg):
8259 def __call__(self, target, source, env, for_signature):
8262 # Will expand $BAR to "my argument bar baz"
8263 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8267 The special pseudo-variables
8271 may be used to surround parts of a command line
8274 causing a rebuild--that is,
8275 which are not included in the signature
8276 of target files built with this command.
8281 will be removed from the command line
8282 before it is added to file signatures,
8287 will be removed before the command is executed.
8288 For example, the command line:
8291 echo Last build occurred $( $TODAY $). > $TARGET
8295 would execute the command:
8298 echo Last build occurred $TODAY. > $TARGET
8302 but the command signature added to any target files would be:
8305 echo Last build occurred . > $TARGET
8308 SCons uses the following rules when converting construction variables into
8312 When the value is a string it is interpreted as a space delimited list of
8313 command line arguments.
8316 When the value is a list it is interpreted as a list of command line
8317 arguments. Each element of the list is converted to a string.
8320 Anything that is not a list or string is converted to a string and
8321 interpreted as a single command line argument.
8324 Newline characters (\\n) delimit lines. The newline parsing is done after
8325 all other parsing, so it is not possible for arguments (e.g. file names) to
8326 contain embedded newline characters. This limitation will likely go away in
8327 a future version of SCons.
8335 new file types for implicit dependencies.
8336 Scanner accepts the following arguments:
8339 A Python function that will process
8341 and return a list of strings (file names)
8342 representing the implicit
8343 dependencies found in the contents.
8344 The function takes three or four arguments:
8346 def scanner_function(node, env, path):
8348 def scanner_function(node, env, path, arg):
8352 argument is the internal
8353 SCons node representing the file.
8356 to fetch the name of the file, and
8357 .B node.get_contents()
8358 to fetch contents of the file.
8362 argument is the construction environment for the scan.
8363 Fetch values from it using the
8369 argument is a tuple (or list)
8370 of directories that can be searched
8372 This will usually be the tuple returned by the
8374 argument (see below).
8378 argument is the argument supplied
8379 when the scanner was created, if any.
8382 The name of the Scanner.
8384 to identify the Scanner internally.
8387 An optional argument that, if specified,
8388 will be passed to the scanner function
8390 and the path function
8394 An optional list that can be used to
8395 determine which scanner should be used for
8397 In the usual case of scanning for file names,
8398 this argument will be a list of suffixes
8399 for the different file types that this
8400 Scanner knows how to scan.
8401 If the argument is a string,
8402 then it will be expanded
8403 into a list by the current environment.
8406 A Python function that takes
8407 two or three arguments:
8408 a construction environment, directory Node,
8409 and optional argument supplied
8410 when the scanner was created.
8413 returns a tuple of directories
8414 that can be searched for files to be returned
8415 by this Scanner object.
8418 The class of Node that should be returned
8419 by this Scanner object.
8420 Any strings or other objects returned
8421 by the scanner function
8422 that are not of this class
8423 will be run through the
8428 A Python function that will take a string
8430 and turn it into the appropriate class of Node
8431 to be returned by this Scanner object.
8434 An optional Python function that takes two arguments,
8435 a Node (file) and a construction environment,
8436 and returns whether the
8437 Node should, in fact,
8438 be scanned for dependencies.
8439 This check can be used to eliminate unnecessary
8440 calls to the scanner function when,
8441 for example, the underlying file
8442 represented by a Node does not yet exist.
8445 An optional flag that
8446 specifies whether this scanner should be re-invoked
8447 on the dependency files returned by the scanner.
8448 When this flag is not set,
8449 the Node subsystem will
8450 only invoke the scanner on the file being scanned,
8451 and not (for example) also on the files
8452 specified by the #include lines
8453 in the file being scanned.
8455 .SH SYSTEM-SPECIFIC BEHAVIOR
8456 SCons and its configuration files are very portable,
8457 due largely to its implementation in Python.
8458 There are, however, a few portability
8459 issues waiting to trap the unwary.
8461 SCons handles the upper-case
8463 file suffix differently,
8464 depending on the capabilities of
8465 the underlying system.
8466 On a case-sensitive system
8467 such as Linux or UNIX,
8468 SCons treats a file with a
8470 suffix as a C++ source file.
8471 On a case-insensitive system
8473 SCons treats a file with a
8475 suffix as a C source file.
8477 SCons handles the upper-case
8479 file suffix differently,
8480 depending on the capabilities of
8481 the underlying system.
8482 On a case-sensitive system
8483 such as Linux or UNIX,
8484 SCons treats a file with a
8486 suffix as a Fortran source file
8487 that is to be first run through
8488 the standard C preprocessor.
8489 On a case-insensitive system
8491 SCons treats a file with a
8493 suffix as a Fortran source file that should
8495 be run through the C preprocessor.
8496 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
8497 Cygwin supplies a set of tools and utilities
8498 that let users work on a
8499 Windows system using a more POSIX-like environment.
8500 The Cygwin tools, including Cygwin Python,
8502 by sharing an ability to interpret UNIX-like path names.
8503 For example, the Cygwin tools
8504 will internally translate a Cygwin path name
8505 like /cygdrive/c/mydir
8506 to an equivalent Windows pathname
8507 of C:/mydir (equivalent to C:\\mydir).
8510 that are built for native Windows execution,
8511 such as the python.org and ActiveState versions,
8512 do not have the Cygwin path name semantics.
8513 This means that using a native Windows version of Python
8514 to build compiled programs using Cygwin tools
8515 (such as gcc, bison, and flex)
8516 may yield unpredictable results.
8517 "Mixing and matching" in this way
8518 can be made to work,
8519 but it requires careful attention to the use of path names
8520 in your SConscript files.
8522 In practice, users can sidestep
8523 the issue by adopting the following rules:
8525 use the Cygwin-supplied Python interpreter
8527 when using Microsoft Visual C/C++
8528 (or some other Windows compiler)
8529 use the python.org or ActiveState version of Python
8531 .SS WIN32: scons.bat file
8533 SCons is executed via a wrapper
8536 This has (at least) two ramifications:
8538 First, Windows command-line users
8539 that want to use variable assignment
8541 may have to put double quotes
8542 around the assignments:
8545 scons "FOO=BAR" "BAZ=BLEH"
8548 Second, the Cygwin shell does not
8549 recognize this file as being the same
8552 command issued at the command-line prompt.
8553 You can work around this either by
8556 from the Cygwin command line,
8557 or by creating a wrapper shell
8563 The MinGW bin directory must be in your PATH environment variable or the
8564 PATH variable under the ENV construction variable for SCons
8565 to detect and use the MinGW tools. When running under the native Windows
8566 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
8567 tools, if they are both installed, regardless of the order of the bin
8568 directories in the PATH variable. If you have both MSVC and MinGW
8569 installed and you want to use MinGW instead of MSVC,
8570 then you must explictly tell SCons to use MinGW by passing
8576 to the Environment() function, because SCons will prefer the MSVC tools
8577 over the MinGW tools.
8581 To help you get started using SCons,
8582 this section contains a brief overview of some common tasks.
8584 .SS Basic Compilation From a Single Source File
8588 env.Program(target = 'foo', source = 'foo.c')
8591 Note: Build the file by specifying
8592 the target as an argument
8593 ("scons foo" or "scons foo.exe").
8594 or by specifying a dot ("scons .").
8596 .SS Basic Compilation From Multiple Source Files
8600 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
8603 .SS Setting a Compilation Flag
8606 env = Environment(CCFLAGS = '-g')
8607 env.Program(target = 'foo', source = 'foo.c')
8610 .SS Search The Local Directory For .h Files
8614 need to set CCFLAGS to specify -I options by hand.
8615 SCons will construct the right -I options from CPPPATH.
8618 env = Environment(CPPPATH = ['.'])
8619 env.Program(target = 'foo', source = 'foo.c')
8622 .SS Search Multiple Directories For .h Files
8625 env = Environment(CPPPATH = ['include1', 'include2'])
8626 env.Program(target = 'foo', source = 'foo.c')
8629 .SS Building a Static Library
8633 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
8634 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
8637 .SS Building a Shared Library
8641 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
8642 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
8645 .SS Linking a Local Library Into a Program
8648 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
8649 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
8650 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
8653 .SS Defining Your Own Builder Object
8655 Notice that when you invoke the Builder,
8656 you can leave off the target file suffix,
8657 and SCons will add it automatically.
8660 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8662 src_suffix = '.tex')
8663 env = Environment(BUILDERS = {'PDFBuilder' : bld})
8664 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8666 # The following creates "bar.pdf" from "bar.tex"
8667 env.PDFBuilder(target = 'bar', source = 'bar')
8670 Note also that the above initialization
8671 overwrites the default Builder objects,
8672 so the Environment created above
8673 can not be used call Builders like env.Program(),
8674 env.Object(), env.StaticLibrary(), etc.
8676 .SS Adding Your Own Builder Object to an Environment
8679 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
8681 src_suffix = '.tex')
8683 env.Append(BUILDERS = {'PDFBuilder' : bld})
8684 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
8685 env.Program(target = 'bar', source = 'bar.c')
8688 You also can use other Pythonic techniques to add
8689 to the BUILDERS construction variable, such as:
8693 env['BUILDERS]['PDFBuilder'] = bld
8696 .SS Defining Your Own Scanner Object
8701 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
8703 def kfile_scan(node, env, path, arg):
8704 contents = node.get_contents()
8705 includes = include_re.findall(contents)
8708 kscan = Scanner(name = 'kfile',
8709 function = kfile_scan,
8712 scanners = Environment().Dictionary('SCANNERS')
8713 env = Environment(SCANNERS = scanners + [kscan])
8715 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
8717 bar_in = File('bar.in')
8718 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
8719 bar_in.target_scanner = kscan
8722 .SS Creating a Hierarchical Build
8724 Notice that the file names specified in a subdirectory's
8726 file are relative to that subdirectory.
8732 env.Program(target = 'foo', source = 'foo.c')
8734 SConscript('sub/SConscript')
8739 # Builds sub/foo from sub/foo.c
8740 env.Program(target = 'foo', source = 'foo.c')
8742 SConscript('dir/SConscript')
8747 # Builds sub/dir/foo from sub/dir/foo.c
8748 env.Program(target = 'foo', source = 'foo.c')
8751 .SS Sharing Variables Between SConscript Files
8753 You must explicitly Export() and Import() variables that
8754 you want to share between SConscript files.
8760 env.Program(target = 'foo', source = 'foo.c')
8763 SConscript('subdirectory/SConscript')
8765 subdirectory/SConscript:
8768 env.Program(target = 'foo', source = 'foo.c')
8771 .SS Building Multiple Variants From the Same Source
8773 Use the BuildDir() method to establish
8774 one or more separate build directories for
8775 a given source directory,
8776 then use the SConscript() method
8777 to specify the SConscript files
8778 in the build directories:
8785 BuildDir('foo', 'src')
8786 SConscript('foo/SConscript')
8790 BuildDir('bar', 'src')
8791 SConscript('bar/SConscript')
8796 env = Environment(CCFLAGS = ccflags)
8797 env.Program(target = 'src', source = 'src.c')
8800 Note the use of the Export() method
8801 to set the "ccflags" variable to a different
8802 value for each variant build.
8804 .SS Hierarchical Build of Two Libraries Linked With a Program
8809 env = Environment(LIBPATH = ['#libA', '#libB'])
8811 SConscript('libA/SConscript')
8812 SConscript('libB/SConscript')
8813 SConscript('Main/SConscript')
8818 env.Library('a', Split('a1.c a2.c a3.c'))
8823 env.Library('b', Split('b1.c b2.c b3.c'))
8828 e = env.Copy(LIBS = ['a', 'b'])
8829 e.Program('foo', Split('m1.c m2.c m3.c'))
8832 The '#' in the LIBPATH directories specify that they're relative to the
8833 top-level directory, so they don't turn into "Main/libA" when they're
8834 used in Main/SConscript.
8836 Specifying only 'a' and 'b' for the library names
8837 allows SCons to append the appropriate library
8838 prefix and suffix for the current platform
8839 (for example, 'liba.a' on POSIX systems,
8840 'a.lib' on Windows).
8842 .SS Customizing contruction variables from the command line.
8844 The following would allow the C compiler to be specified on the command
8845 line or in the file custom.py.
8848 opts = Options('custom.py')
8849 opts.Add('CC', 'The C compiler.')
8850 env = Environment(options=opts)
8851 Help(opts.GenerateHelpText(env))
8854 The user could specify the C compiler on the command line:
8860 or in the custom.py file:
8866 or get documentation on the options:
8877 .SS Using Microsoft Visual C++ precompiled headers
8879 Since windows.h includes everything and the kitchen sink, it can take quite
8880 some time to compile it over and over again for a bunch of object files, so
8881 Microsoft provides a mechanism to compile a set of headers once and then
8882 include the previously compiled headers in any object file. This
8883 technology is called precompiled headers. The general recipe is to create a
8884 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
8885 then include every header you want to precompile in "StdAfx.h", and finally
8886 include "StdAfx.h" as the first header in all the source files you are
8887 compiling to object files. For example:
8891 #include <windows.h>
8892 #include <my_big_header.h>
8911 /* do some other stuff */
8917 env['PCHSTOP'] = 'StdAfx.h'
8918 env['PCH'] = env.PCH('StdAfx.cpp')[0]
8919 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8922 For more information see the document for the PCH builder, and the PCH and
8923 PCHSTOP construction variables. To learn about the details of precompiled
8924 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
8926 .SS Using Microsoft Visual C++ external debugging information
8928 Since including debugging information in programs and shared libraries can
8929 cause their size to increase significantly, Microsoft provides a mechanism
8930 for including the debugging information in an external file called a PDB
8931 file. SCons supports PDB files through the PDB construction
8937 env['PDB'] = 'MyApp.pdb'
8938 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
8941 For more information see the document for the PDB construction variable.
8946 Specifies the directory that contains the SCons Python module directory
8947 (e.g. /home/aroach/scons-src-0.01/src/engine).
8950 A string of options that will be used by scons in addition to those passed
8951 on the command line.
8962 Steven Knight <knight@baldmt.com>
8964 Anthony Roach <aroach@electriceyeball.com>