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 "October 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 Instruct the scanner that searches for libraries
525 to print a message about each potential library
526 name it is searching for,
527 and about the actual libraries it finds.
531 Print the include tree after each top-level target is built.
532 This is generally used to find out what files are included by the sources
533 of a given derived file:
536 $ scons --debug=includes foo.o
541 Prints how much memory SCons uses
542 before and after reading the SConscript files
543 and before and after building.
547 Prints a list of the various objects
548 of the various classes used internally by SCons.
549 This only works when run under Python 2.1 or later.
553 Re-run SCons under the control of the
560 Print the raw command line used to build each target
561 before the construction environment variables are substituted.
562 Also shows which targets are being built by this command.
563 Output looks something like this:
565 $ scons --debug=presub
566 Building myprog.o with action(s):
567 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
573 Prints an internal Python stack trace
574 when encountering an otherwise unexplained error.
578 Print the dependency tree along with status information. This is the
579 same as the debug=tree option, but additional status information is
580 provided for each node in the tree.
584 Prints various time profiling information: the time spent
585 executing each build command, the total build time, the total time spent
586 executing build commands, the total time spent executing SConstruct and
587 SConscript files, and the total time spent executing SCons itself.
591 Print the dependency tree
592 after each top-level target is built. This prints out the complete
593 dependency tree including implicit dependencies and ignored
597 .\" -e, --environment-overrides
598 .\" Variables from the execution environment override construction
599 .\" variables from the SConscript files.
602 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
605 as the initial SConscript file.
609 Print a local help message for this build, if one is defined in
610 the SConscript file(s), plus a line that describes the
612 option for command-line option help. If no local help message
613 is defined, prints the standard help message about command-line
614 options. Exits after displaying the appropriate message.
618 Print the standard help message about command-line options and
623 Ignore all errors from commands executed to rebuild files.
626 .RI -I " directory" ", --include-dir=" directory
630 imported Python modules. If several
633 are used, the directories are searched in the order specified.
637 Cache implicit dependencies. This can cause
639 to miss changes in the implicit dependencies in cases where a new implicit
640 dependency is added earlier in the implicit dependency search path
641 (e.g. CPPPATH) than a current implicit dependency with the same name.
644 --implicit-deps-changed
645 Force SCons to ignore the cached implicit dependencies. This causes the
646 implicit dependencies to be rescanned and recached. This implies
647 .BR --implicit-cache .
650 --implicit-deps-unchanged
651 Force SCons to ignore changes in the implicit dependencies.
652 This causes cached implicit dependencies to always be used.
654 .BR --implicit-cache .
657 .RI -j " N" ", --jobs=" N
658 Specifies the number of jobs (commands) to run simultaneously.
659 If there is more than one
661 option, the last one is effective.
665 .\" is specified without an argument,
667 .\" will not limit the number of
668 .\" simultaneous jobs.
672 Continue as much as possible after an error. The target that
673 failed and those that depend on it will not be remade, but other
674 targets specified on the command line will still be processed.
677 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
678 .\" No new jobs (commands) will be started if
679 .\" there are other jobs running and the system load
680 .\" average is at least
682 .\" (a floating-point number).
685 .RI --duplicate= ORDER
686 There are three ways to duplicate files in a build tree: hard links,
687 soft (symbolic) links and copies. The default behaviour of SCons is to
688 prefer hard links to soft links to copies. You can specify different
689 behaviours with this option.
699 SCons will attempt to duplicate files using
700 the mechanisms in the specified order.
705 .\" List derived files (targets, dependencies) that would be built,
706 .\" but do not build them.
707 .\" [XXX This can probably go away with the right
708 .\" combination of other options. Revisit this issue.]
712 .\" List derived files that would be built, with the actions
713 .\" (commands) that build them. Does not build the files.
714 .\" [XXX This can probably go away with the right
715 .\" combination of other options. Revisit this issue.]
719 .\" List derived files that would be built, plus where the file is
720 .\" defined (file name and line number). Does not build the files.
721 .\" [XXX This can probably go away with the right
722 .\" combination of other options. Revisit this issue.]
726 Ignored for compatibility with non-GNU versions of
730 .RI --max-drift= SECONDS
731 Set the maximum expected drift in the modification time of files to
733 This value determines how old a file must be before its content signature
734 is cached. The default value is 2 days, which means a file must have a
735 modification time of at least two days ago in order to have its content
736 signature cached. A negative value means to never cache the content
737 signature and to ignore the cached value if there already is one. A value
738 of 0 means to always cache the signature, no matter how old the file is.
741 -n, --just-print, --dry-run, --recon
742 No execute. Print the commands that would be executed to build
743 any out-of-date target files, but do not execute the commands.
746 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
750 .\" not rebuild anything due to changes in the contents of
753 .\" .RI --override " file"
754 .\" Read values to override specific build environment variables
755 .\" from the specified
759 .\" Print the data base (construction environments,
760 .\" Builder and Scanner objects) that are defined
761 .\" after reading the SConscript files.
762 .\" After printing, a normal build is performed
763 .\" as usual, as specified by other command-line options.
764 .\" This also prints version information
769 .\" To print the database without performing a build do:
777 Run SCons under the Python profiler
778 and save the results in the specified
780 The results may be analyzed using the Python
784 Do not run any commands, or print anything. Just return an exit
785 status that is zero if the specified targets are already up to
786 date, non-zero otherwise.
789 Quiets SCons status messages about
790 reading SConscript files,
792 and entering directories.
793 Commands that are executed
794 to rebuild target files are still printed.
797 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
798 .\" Clear the default construction variables. Construction
799 .\" environments that are created will be completely empty.
803 Build dependencies in a random order. This is useful when
804 building multiple trees simultaneously with caching enabled,
805 to prevent multiple builds from simultaneously trying to build
806 or retrieve the same target files.
809 -s, --silent, --quiet
810 Silent. Do not print commands that are executed to rebuild
812 Also suppresses SCons status messages.
815 -S, --no-keep-going, --stop
816 Ignored for compatibility with GNU
821 Ignored for compatibility with GNU
823 (Touching a file to make it
824 appear up-to-date is unnecessary when using
828 -u, --up, --search-up
829 Walks up the directory structure until an
834 file is found, and uses that
835 as the top of the directory tree.
836 If no targets are specified on the command line,
837 only targets at or below the
838 current directory will be built.
842 Works exactly the same way as the
844 option except for the way default targets are handled.
845 When this option is used and no targets are specified on the command line,
846 all default targets that are defined in the SConscript(s) in the current
847 directory are built, regardless of what directory the resultant targets end
854 version, copyright information,
855 list of authors, and any other relevant information.
859 -w, --print-directory
860 Print a message containing the working directory before and
861 after other processing.
864 .RI --warn= type ", --warn=no-" type
865 Enable or disable warnings.
867 specifies the type of warnings to be enabled or disabled:
870 --warn=all, --warn=no-all
871 Enables or disables all warnings.
874 --warn=dependency, --warn=no-dependency
875 Enables or disables warnings about dependencies.
876 These warnings are disabled by default.
879 --warn=deprecated, --warn=no-deprecated
880 Enables or disables warnings about use of deprecated features.
881 These warnings are enabled by default.
884 --warn=missing-sconscript, --warn=no-missing-sconscript
885 Enables or disables warnings about missing SConscript files.
886 These warnings are enabled by default.
890 Turn off -w, even if it was turned on implicitly.
893 .\" .RI --write-filenames= file
894 .\" Write all filenames considered into
898 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
899 .\" Pretend that the target
902 .\" modified. When used with the
905 .\" show you what would be rebuilt if you were to modify that file.
911 .\" --warn-undefined-variables
912 .\" Warn when an undefined variable is referenced.
915 .RI -Y " repository" ", --repository=" repository
916 Search the specified repository for any input and target
917 files not found in the local directory hierarchy. Multiple
919 options may specified, in which case the
920 repositories are searched in the order specified.
922 .SH CONFIGURATION FILE REFERENCE
923 .\" .SS Python Basics
924 .\" XXX Adding this in the future would be a help.
925 .SS Construction Environments
926 A construction environment is the basic means by which the SConscript
927 files communicate build information to
929 A new construction environment is created using the
937 By default, a new construction environment is
938 initialized with a set of builder methods
939 and construction variables that are appropriate
940 for the current platform.
941 An optional platform keyword argument may be
942 used to specify that an environment should
943 be initialized for a different platform:
946 env = Environment(platform = 'cygwin')
947 env = Environment(platform = 'os2')
948 env = Environment(platform = 'posix')
949 env = Environment(platform = 'win32')
952 Specifying a platform initializes the appropriate
953 construction variables in the environment
954 to use and generate file names with prefixes
955 and suffixes appropriate for the platform.
961 variable from the user's external environment
962 to the construction environment's
965 This is so that any executed commands
966 that use sockets to connect with other systems
967 (such as fetching source files from
968 external CVS repository specifications like
969 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
970 will work on Win32 systems.
972 The platform argument may be function or callable object,
973 in which case the Environment() method
974 will call the specified argument to update
975 the new construction environment:
978 def my_platform(env):
981 env = Environment(platform = my_platform)
984 Additionally, a specific set of tools
985 with which to initialize the environment
986 may specified as an optional keyword argument:
989 env = Environment(tools = ['msvc', 'lex'])
992 Non-built-in tools may be specified using the toolpath argument:
995 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
998 This looks for a tool specification in tools/foo.py (as well as
999 using the ordinary default tools for the platform). foo.py should
1000 have two functions: generate(env, **kw) and exists(env).
1004 modifies the passed in environment
1005 to set up variables so that the tool
1007 it may use any keyword arguments
1008 that the user supplies (see below)
1009 to vary its initialization.
1012 function should return a true
1013 value if the tool is available.
1014 Tools in the toolpath are used before
1015 any of the built-in ones. For example, adding gcc.py to the toolpath
1016 would override the built-in gcc tool.
1018 The elements of the tools list may also
1019 be functions or callable objects,
1020 in which case the Environment() method
1021 will call the specified elements
1022 to update the new construction environment:
1026 env['XYZZY'] = 'xyzzy'
1028 env = Environment(tools = [my_tool])
1031 The individual elements of the tools list
1032 may also themselves be two-element lists of the form
1033 .RI ( toolname ", " kw_dict ).
1034 SCons searches for the
1036 specification file as described above, and
1039 which must be a dictionary, as keyword arguments to the tool's
1044 function can use the arguments to modify the tool's behavior
1045 by setting up the environment in different ways
1046 or otherwise changing its initialization.
1049 # in tools/my_tool.py:
1050 def generate(env, **kw):
1051 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1052 env['MY_TOOL'] = kw.get('arg1', '1')
1057 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1061 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1062 the environment it receives to customize the tool for different platforms.
1064 If no tool list is specified, then SCons will auto-detect the installed
1065 tools using the PATH variable in the ENV construction variable and the
1066 platform name when the Environment is constructed. Changing the PATH
1067 variable after the Environment is constructed will not cause the tools to
1070 SCons supports the following tool specifications out of the box:
1146 Additionally, there is a "tool" named
1148 which configures the
1149 environment with a default set of tools for the current platform.
1151 On posix and cygwin platforms
1152 the GNU tools (e.g. gcc) are preferred by SCons,
1153 on win32 the Microsoft tools (e.g. msvc)
1154 followed by MinGW are preferred by SCons,
1155 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1159 Build rules are specified by calling a construction
1160 environment's builder methods.
1161 The arguments to the builder methods are
1163 (a list of target files)
1166 (a list of source files).
1168 Because long lists of file names
1169 can lead to a lot of quoting,
1174 and a same-named environment method
1175 that split a single string
1176 into a list, separated on
1177 strings of white-space characters.
1178 (These are similar to the
1179 string.split() method
1180 from the standard Python library,
1181 but work even if the input isn't a string.)
1183 Like all Python arguments,
1184 the target and source arguments to a builder method
1185 can be specified either with or without
1186 the "target" and "source" keywords.
1187 When the keywords are omitted,
1188 the target is first,
1189 followed by the source.
1190 The following are equivalent examples of calling the Program builder method:
1193 env.Program('bar', ['bar.c', 'foo.c'])
1194 env.Program('bar', Split('bar.c foo.c'))
1195 env.Program('bar', env.Split('bar.c foo.c'))
1196 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1197 env.Program(target = 'bar', Split('bar.c foo.c'))
1198 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1199 env.Program('bar', source = string.split('bar.c foo.c'))
1202 When the target shares the same base name
1203 as the source and only the suffix varies,
1204 and if the builder method has a suffix defined for the target file type,
1205 then the target argument may be omitted completely,
1208 will deduce the target file name from
1209 the source file name.
1210 The following examples all build the
1216 (on Windows systems)
1217 from the bar.c source file:
1220 env.Program(target = 'bar', source = 'bar.c')
1221 env.Program('bar', source = 'bar.c')
1222 env.Program(source = 'bar.c')
1223 env.Program('bar.c')
1226 It is possible to override or add construction variables when calling a
1227 builder method by passing additional keyword arguments.
1228 These overridden or added
1229 variables will only be in effect when building the target, so they will not
1230 affect other parts of the build. For example, if you want to add additional
1231 libraries for just one program:
1234 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1237 or generate a shared library with a nonstandard suffix:
1240 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1243 Although the builder methods defined by
1246 methods of a construction environment object,
1247 they may also be called without an explicit environment:
1250 Program('hello', 'hello.c')
1251 SharedLibrary('word', 'word.cpp')
1255 the methods are called internally using a default construction
1256 environment that consists of the tools and values that
1258 has determined are appropriate for the local system.
1260 All builder methods return a list of Nodes
1261 that represent the target or targets that will be built.
1264 is an internal SCons object
1266 build targets or sources.
1268 The returned Node(s)
1269 can be passed to other builder methods as source(s)
1270 or passed to any SCons function or method
1271 where a filename would normally be accepted.
1272 For example, if it were necessary
1275 flag when compiling one specific object file:
1278 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1279 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1282 Using a Node in this way
1283 makes for a more portable build
1284 by avoiding having to specify
1285 a platform-specific object suffix
1286 when calling the Program() builder method.
1288 Note that Builder calls will automatically "flatten"
1289 the source and target file lists,
1290 so it's all right to have the bar_obj list
1291 return by the StaticObject() call
1292 in the middle of the source file list.
1293 If you need to manipulate a list of lists returned by Builders
1294 directly using Python,
1295 you can either build the list by hand:
1298 foo = Object('foo.c')
1299 bar = Object('bar.c')
1300 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1301 for object in objects:
1308 to create a list containing just the Nodes,
1309 which may be more convenient:
1312 foo = Object('foo.c')
1313 bar = Object('bar.c')
1314 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1315 for object in objects:
1319 The path name for a Node's file may be used
1320 by passing the Node to the Python-builtin
1325 bar_obj_list = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1326 print "The path to bar_obj is:", str(bar_obj_list[0])
1329 Note again that because the Builder call returns a list,
1330 we have to access the first element in the list
1331 .B (bar_obj_list[0])
1332 to get at the Node that actually represents
1335 Builder calls support a
1337 keyword argument that
1338 specifies that the Builder's action(s)
1340 after changing directory.
1344 a string or a directory Node,
1345 scons will change to the specified directory.
1348 is not a string or Node
1350 then scons will change to the
1351 target file's directory.
1354 # scons will change to the "sub" subdirectory
1355 # before executing the "cp" command.
1356 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1357 "cp dir/foo.in dir/foo.out",
1360 # Because chdir is not a string, scons will change to the
1361 # target's directory ("sub/dir") before executing the
1363 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1364 "cp foo.in foo.out",
1368 Note that scons will
1370 automatically modify
1372 construction variables like
1376 when using the chdir
1377 keyword argument--that is,
1378 the expanded file names
1379 will still be relative to
1380 the top-level SConstruct directory,
1381 and consequently incorrect
1382 relative to the chdir directory.
1383 If you use the chdir keyword argument,
1384 you will typically need to supply a different
1390 to use just the filename portion of the
1394 provides the following builder methods:
1396 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1399 Builds a C source file given a lex (.l) or yacc (.y) input file.
1400 The suffix specified by the $CFILESUFFIX construction variable
1402 is automatically added to the target
1403 if it is not already present. Example:
1407 env.CFile(target = 'foo.c', source = 'foo.l')
1409 env.CFile(target = 'bar', source = 'bar.y')
1412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1415 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1417 The suffix specified by the $CXXFILESUFFIX construction variable
1419 is automatically added to the target
1420 if it is not already present. Example:
1424 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1426 env.CXXFile(target = 'bar', source = 'bar.yy')
1429 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1432 Builds a .dvi file from a .tex, .ltx or .latex input file.
1433 If the source file suffix is .tex,
1435 will examine the contents of the file;
1440 is found, the file is assumed to be a LaTeX file and
1441 the target is built by invoking the $LATEXCOM command line;
1442 otherwise, the $TEXCOM command line is used.
1443 If the file is a LaTeX file,
1446 builder method will also examine the contents
1449 and invoke the $BIBTEX command line
1453 and will examine the contents
1455 file and re-run the $LATEXCOM command
1456 if the log file says it is necessary.
1459 (hard-coded within TeX itself)
1460 is automatically added to the target
1461 if it is not already present. Examples:
1464 # builds from aaa.tex
1465 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1467 env.DVI(target = 'bbb', source = 'bbb.ltx')
1468 # builds from ccc.latex
1469 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1472 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1475 Builds a Java archive (.jar) file
1476 from a source tree of .class files.
1477 If the $JARCHDIR value is set, the
1479 command will change to the specified directory using the
1482 If the contents any of the source files begin with the string
1483 .BR Manifest-Version ,
1484 the file is assumed to be a manifest
1485 and is passed to the
1492 env.Jar(target = 'foo.jar', source = 'classes')
1495 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1498 Builds one or more Java class files
1499 from one or more source trees of .java files.
1500 The class files will be placed underneath
1501 the specified target directory.
1502 SCons will parse each source .java file
1504 (including inner classes)
1505 defined within that file,
1506 and from that figure out the
1507 target .class files that will be created.
1508 SCons will also search each Java file
1509 for the Java package name,
1510 which it assumes can be found on a line
1511 beginning with the string
1513 in the first column;
1514 the resulting .class files
1515 will be placed in a directory reflecting
1516 the specified package name.
1520 defining a single public
1523 containing a package name of
1525 will generate a corresponding
1526 .IR sub/dir/Foo.class
1532 env.Java(target = 'classes', source = 'src')
1533 env.Java(target = 'classes', source = ['src1', 'src2'])
1536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1539 Builds C header and source files for
1540 implementing Java native methods.
1541 The target can be either a directory
1542 in which the header files will be written,
1543 or a header file name which
1544 will contain all of the definitions.
1545 The source can be either the names of .class files,
1546 or the objects returned from the
1550 If the construction variable
1552 is set, either in the environment
1553 or in the call to the
1555 builder method itself,
1556 then the value of the variable
1557 will be stripped from the
1558 beginning of any .class file names.
1563 # builds java_native.h
1564 classes = env.Java(target = 'classdir', source = 'src')
1565 env.JavaH(target = 'java_native.h', source = classes)
1567 # builds include/package_foo.h and include/package_bar.h
1568 env.JavaH(target = 'include',
1569 source = ['package/foo.class', 'package/bar.class'])
1571 # builds export/foo.h and export/bar.h
1572 env.JavaH(target = 'export',
1573 source = ['classes/foo.class', 'classes/bar.class'],
1574 JAVACLASSDIR = 'classes')
1577 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1584 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1587 Builds an output file from an M4 input file.
1588 This uses a default $M4FLAGS value of
1590 which considers all warnings to be fatal
1591 and stops on the first warning
1592 when using the GNU version of m4.
1596 env.M4(target = 'foo.c', source = 'foo.c.m4')
1599 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1602 Builds an output file from a moc input file. Moc input files are either
1603 header files or cxx files. This builder is only available after using the
1604 tool 'qt'. See the QTDIR variable for more information.
1608 env.Moc('foo.h') # generates moc_foo.cc
1609 env.Moc('foo.cpp') # generates foo.moc
1612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1614 .IP env.MSVSProject()
1615 Builds Microsoft Visual Studio project files.
1616 This builds a Visual Studio project file, based on the version of
1617 Visual Studio that is configured (either the latest installed version,
1618 or the version set by
1620 in the Environment constructor).
1621 For VS 6, it will generate
1625 files, for VS 7, it will
1632 It takes several lists of filenames to be placed into the project
1633 file, currently these are limited to
1634 .B srcs, incs, localincs, resources,
1637 These are pretty self explanatory, but it
1638 should be noted that the 'srcs' list is NOT added to the $SOURCES
1639 environment variable. This is because it represents a list of files
1640 to be added to the project file, not the source used to build the
1641 project file (in this case, the 'source' is the SConscript file used
1642 to call MSVSProject).
1644 In addition to these values (which are all optional, although not
1645 specifying any of them results in an empty project file), the
1646 following values must be specified:
1648 target: The name of the target .dsp or .vcproj file. The correct
1649 suffix for the version of Visual Studio must be used, but the value
1651 env['MSVSPROJECTSUFFIX']
1653 will be defined to the correct value (see example below).
1655 variant: The name of this particular variant. These are typically
1656 things like "Debug" or "Release", but really can be anything you want.
1657 Multiple calls to MSVSProject with different variants are allowed: all
1658 variants will be added to the project file with their appropriate
1659 build targets and sources.
1661 buildtarget: A list of SCons.Node.FS objects which is returned from
1662 the command which builds the target. This is used to tell SCons what
1663 to build when the 'build' button is pressed inside of the IDE.
1668 barsrcs = ['bar.cpp'],
1669 barincs = ['bar.h'],
1670 barlocalincs = ['StdAfx.h']
1671 barresources = ['bar.rc','resource.h']
1672 barmisc = ['bar_readme.txt']
1674 dll = local.SharedLibrary(target = 'bar.dll',
1677 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1680 localincs = barlocalincs,
1681 resources = barresources,
1684 variant = 'Release')
1687 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1694 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1697 Builds a Microsoft Visual C++ precompiled header.
1698 Calling this builder method
1699 returns a list of two targets: the PCH as the first element, and the object
1700 file as the second element. Normally the object file is ignored.
1701 This builder method is only
1702 provided when Microsoft Visual C++ is being used as the compiler.
1703 The PCH builder method is generally used in
1704 conjuction with the PCH construction variable to force object files to use
1705 the precompiled header:
1708 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1711 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1714 Builds a .pdf file from a .dvi input file
1715 (or, by extension, a .tex, .ltx, or .latex input file).
1716 The suffix specified by the $PDFSUFFIX construction variable
1718 is added automatically to the target
1719 if it is not already present. Example:
1722 # builds from aaa.tex
1723 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1724 # builds bbb.pdf from bbb.dvi
1725 env.PDF(target = 'bbb', source = 'bbb.dvi')
1728 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1730 .IP env.PostScript()
1731 Builds a .ps file from a .dvi input file
1732 (or, by extension, a .tex, .ltx, or .latex input file).
1733 The suffix specified by the $PSSUFFIX construction variable
1735 is added automatically to the target
1736 if it is not already present. Example:
1739 # builds from aaa.tex
1740 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1741 # builds bbb.ps from bbb.dvi
1742 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1745 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1748 Builds an executable given one or more object files
1749 or C, C++, D, or Fortran source files.
1750 If any C, C++, D or Fortran source files are specified,
1751 then they will be automatically
1752 compiled to object files using the
1755 see that builder method's description for
1756 a list of legal source file suffixes
1757 and how they are interpreted.
1758 The target executable file prefix
1759 (specified by the $PROGPREFIX construction variable; nothing by default)
1761 (specified by the $PROGSUFFIX construction variable;
1762 by default, .exe on Windows systems, nothing on POSIX systems)
1763 are automatically added to the target if not already present.
1767 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1770 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1773 Builds a Microsoft Visual C++ resource file.
1774 This builder method is only provided
1775 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1779 for MinGW) suffix is added to the target name if no other suffix is given. The source
1780 file is scanned for implicit dependencies as though it were a C file. Example:
1783 env.RES('resource.rc')
1786 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1789 Builds stub and skeleton class files
1791 from Java .class files.
1792 The target is a directory
1793 relative to which the stub
1794 and skeleton class files will be written.
1795 The source can be the names of .class files,
1796 or the objects return from the
1800 If the construction variable
1802 is set, either in the environment
1803 or in the call to the
1805 builder method itself,
1806 then the value of the variable
1807 will be stripped from the
1808 beginning of any .class file names.
1811 classes = env.Java(target = 'classdir', source = 'src')
1812 env.RMIC(target = 'outdir1', source = classes)
1814 env.RMIC(target = 'outdir2',
1815 source = ['package/foo.class', 'package/bar.class'])
1817 env.RMIC(target = 'outdir3',
1818 source = ['classes/foo.class', 'classes/bar.class'],
1819 JAVACLASSDIR = 'classes')
1822 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1824 .IP env.RPCGenClient()
1825 Generates an RPC client stub (_clnt.c) file
1826 from a specified RPC (.x) source file.
1827 Because rpcgen only builds output files
1828 in the local directory,
1829 the command will be executed
1830 in the source file's directory by default.
1833 # Builds src/rpcif_clnt.c
1834 env.RPCGenClient('src/rpcif.x')
1837 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1839 .IP env.RPCGenHeader()
1840 Generates an RPC header (.h) file
1841 from a specified RPC (.x) source file.
1842 Because rpcgen only builds output files
1843 in the local directory,
1844 the command will be executed
1845 in the source file's directory by default.
1848 # Builds src/rpcif.h
1849 env.RPCGenHeader('src/rpcif.x')
1852 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1854 .IP env.RPCGenService()
1855 Generates an RPC server-skeleton (_svc.c) file
1856 from a specified RPC (.x) source file.
1857 Because rpcgen only builds output files
1858 in the local directory,
1859 the command will be executed
1860 in the source file's directory by default.
1863 # Builds src/rpcif_svc.c
1864 env.RPCGenClient('src/rpcif.x')
1867 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1870 Generates an RPC XDR routine (_xdr.c) file
1871 from a specified RPC (.x) source file.
1872 Because rpcgen only builds output files
1873 in the local directory,
1874 the command will be executed
1875 in the source file's directory by default.
1878 # Builds src/rpcif_xdr.c
1879 env.RPCGenClient('src/rpcif.x')
1882 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1884 .IP env.SharedLibrary()
1885 Builds a shared library
1886 (.so on a POSIX system, .dll on WIN32)
1887 given one or more object files
1888 or C, C++, D or Fortran source files.
1889 If any source files are given,
1890 then they will be automatically
1891 compiled to object files.
1892 The static library prefix and suffix (if any)
1893 are automatically added to the target.
1894 The target library file prefix
1895 (specified by the $SHLIBPREFIX construction variable;
1896 by default, lib on POSIX systems, nothing on Windows systems)
1898 (specified by the $SHLIBSUFFIX construction variable;
1899 by default, .dll on Windows systems, .so on POSIX systems)
1900 are automatically added to the target if not already present.
1904 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1907 On WIN32 systems, the
1909 builder method will always build an import (.lib) library
1910 in addition to the shared (.dll) library,
1911 adding a .lib library with the same basename
1912 if there is not already a .lib file explicitly
1913 listed in the targets.
1915 Any object files listed in the
1917 must have been built for a shared library
1922 will raise an error if there is any mismatch.
1924 On WIN32 systems, specifying "register=1" will cause the dll to be
1925 registered after it is built using REGSVR32. The command that is run
1926 ("regsvr32" by default) is determined by $REGSVR construction
1927 variable, and the flags passed are determined by $REGSVRFLAGS. By
1928 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1929 up and requiring user attention when it is run. If you change
1930 $REGSVRFLAGS, be sure to include "/s". For example,
1933 env.SharedLibrary(target = 'bar',
1934 source = ['bar.cxx', 'foo.obj'],
1939 will register "bar.dll" as a COM object when it is done linking it.
1941 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1943 .IP env.SharedObject()
1944 Builds an object file for
1945 inclusion in a shared library.
1946 Source files must have one of the same set of extensions
1947 specified above for the
1950 On some platforms building a shared object requires additional
1951 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1952 normal (static) object, but on some platforms there is no difference between a
1953 shared object and a normal (static) one. When there is a difference, SCons
1954 will only allow shared objects to be linked into a shared library, and will
1955 use a different suffix for shared objects. On platforms where there is no
1956 difference, SCons will allow both normal (static)
1957 and shared objects to be linked into a
1958 shared library, and will use the same suffix for shared and normal
1960 The target object file prefix
1961 (specified by the $SHOBJPREFIX construction variable;
1962 by default, the same as $OBJPREFIX)
1964 (specified by the $SHOBJSUFFIX construction variable)
1965 are automatically added to the target if not already present.
1969 env.SharedObject(target = 'ddd', source = 'ddd.c')
1970 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1971 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1974 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1976 .IP env.StaticLibrary()
1977 Builds a static library given one or more object files
1978 or C, C++, D or Fortran source files.
1979 If any source files are given,
1980 then they will be automatically
1981 compiled to object files.
1982 The static library prefix and suffix (if any)
1983 are automatically added to the target.
1984 The target library file prefix
1985 (specified by the $LIBPREFIX construction variable;
1986 by default, lib on POSIX systems, nothing on Windows systems)
1988 (specified by the $LIBSUFFIX construction variable;
1989 by default, .lib on Windows systems, .a on POSIX systems)
1990 are automatically added to the target if not already present.
1994 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1998 Any object files listed in the
2000 must have been built for a static library
2005 will raise an error if there is any mismatch.
2007 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2009 .IP env.StaticObject()
2010 Builds a static object file
2011 from one or more C, C++, D, or Fortran source files.
2012 Source files must have one of the following extensions:
2015 .asm assembly language file
2016 .ASM assembly language file
2028 .F WIN32: Fortran file
2029 POSIX: Fortran file + C pre-processor
2032 .fpp Fortran file + C pre-processor
2033 .FPP Fortran file + C pre-processor
2034 .s assembly language file
2035 .S WIN32: assembly language file
2036 POSIX: assembly language file + C pre-processor
2037 .spp assembly language file + C pre-processor
2038 .SPP assembly language file + C pre-processor
2041 The target object file prefix
2042 (specified by the $OBJPREFIX construction variable; nothing by default)
2044 (specified by the $OBJSUFFIX construction variable;
2045 \.obj on Windows systems, .o on POSIX systems)
2046 are automatically added to the target if not already present.
2050 env.StaticObject(target = 'aaa', source = 'aaa.c')
2051 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2052 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2055 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2058 Builds a tar archive of the specified files
2060 Unlike most builder methods,
2063 builder method may be called multiple times
2065 each additional call
2066 adds to the list of entries
2067 that will be built into the archive.
2070 env.Tar('src.tar', 'src')
2072 # Create the stuff.tar file.
2073 env.Tar('stuff', ['subdir1', 'subdir2'])
2074 # Also add "another" to the stuff.tar file.
2075 env.Tar('stuff', 'another')
2077 # Set TARFLAGS to create a gzip-filtered archive.
2078 env = Environment(TARFLAGS = '-c -z')
2079 env.Tar('foo.tar.gz', 'foo')
2081 # Also set the suffix to .tgz.
2082 env = Environment(TARFLAGS = '-c -z',
2087 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2089 .IP env.TypeLibrary()
2090 Builds a Windows type library (.tlb) file from and input IDL file
2091 (.idl). In addition, it will build the associated inteface stub and
2092 proxy source files. It names them according to the base name of the .idl file.
2097 env.TypeLibrary(source="foo.idl")
2100 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2102 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2105 Builds a header file, an implementation file and a moc file from an ui file.
2106 and returns the corresponding nodes in the above order.
2107 This builder is only available after using the tool 'qt'. Note: you can
2108 specify .ui files directly as inputs for Program, Library and SharedLibrary
2109 without using this builder. Using the builder lets you override the standard
2110 naming conventions (be careful: prefixes are always prepended to names of
2111 built files; if you don't want prefixes, you may set them to ``).
2112 See the QTDIR variable for more information.
2116 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2117 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2118 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2121 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2124 Builds a zip archive of the specified files
2126 Unlike most builder methods,
2129 builder method may be called multiple times
2131 each additional call
2132 adds to the list of entries
2133 that will be built into the archive.
2136 env.Zip('src.zip', 'src')
2138 # Create the stuff.zip file.
2139 env.Zip('stuff', ['subdir1', 'subdir2'])
2140 # Also add "another" to the stuff.tar file.
2141 env.Zip('stuff', 'another')
2146 C source files, C++ source files,
2147 Fortran source files with
2149 (POSIX systems only),
2154 and assembly language files with
2156 (POSIX systems only),
2161 for C preprocessor dependencies,
2162 so the dependencies do not need to be specified explicitly.
2164 targets of builder methods automatically depend on their sources.
2165 An explicit dependency can
2166 be specified using the
2168 method of a construction environment (see below).
2170 .SS Methods and Functions to Do Things
2171 In addition to Builder methods,
2173 provides a number of other construction environment methods
2174 and global functions to
2175 manipulate the build configuration.
2177 Usually, a construction environment method
2178 and global function with the same name both exist
2179 so that you don't have to remember whether
2180 to a specific bit of functionality
2181 must be called with or without a construction environment.
2182 In the following list,
2183 if you call something as a global function
2186 .RI Function( arguments )
2188 and if you call something through a construction
2189 environment it looks like:
2191 .RI env.Function( arguments )
2193 If you can call the functionality in both ways,
2194 then both forms are listed.
2196 Except where otherwise noted,
2198 construction environment method
2200 provide the exact same functionality.
2201 The only difference is that,
2203 calling the functionality through a construction environment will
2204 substitute construction variables into
2205 any supplied strings.
2208 env = Environment(FOO = 'foo')
2212 the first call to the global
2214 function will actually add a target named
2216 to the list of default targets,
2217 while the second call to the
2219 construction environment method
2220 will expand the value
2221 and add a target named
2223 to the list of default targets.
2224 For more on construction variable expansion,
2225 see the next section on
2226 construction variables.
2228 Construction environment methods
2229 and global functions supported by
2233 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2235 .RI Action( action ", [" strfunction ", " varlist ])
2237 .RI env.Action( action ", [" strfunction ", " varlist ])
2238 Creates an Action object for
2241 See the section "Action Objects,"
2242 below, for a complete explanation of the arguments and behavior.
2244 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2246 .RI AddPostAction( target ", " action )
2248 .RI env.AddPostAction( target ", " action )
2249 Arranges for the specified
2255 The specified action(s) may be
2256 an Action object, or anything that
2257 can be converted into an Action object
2260 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2262 .RI AddPreAction( target ", " action )
2264 .RI env.AddPreAction( target ", " action )
2265 Arranges for the specified
2268 before the specified
2271 The specified action(s) may be
2272 an Action object, or anything that
2273 can be converted into an Action object
2276 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2278 .RI Alias( alias ", [" targets ", [" action ]])
2280 .RI env.Alias( alias ", [" targets ", [" action ]])
2281 Creates one or more phony targets that
2282 expand to one or more other targets.
2287 can be specified that will be executed
2288 whenever the any of the alias targets are out-of-date.
2289 Returns the Node object representing the alias,
2290 which exists outside of any file system.
2291 This Node object, or the alias name,
2292 may be used as a dependency of any other target,
2293 including another alias.
2295 can be called multiple times for the same
2296 alias to add additional targets to the alias,
2297 or additional actions to the list for this alias.
2301 Alias('install', '/usr/bin')
2302 Alias(['install', 'install-lib'], '/usr/local/lib')
2304 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2305 env.Alias('install', ['/usr/local/man'])
2307 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2310 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2312 .RI AlwaysBuild( target ", ...)"
2314 .RI env.AlwaysBuild( target ", ...)"
2317 so that it is always assumed to be out of date,
2318 and will always be rebuilt if needed.
2321 does not add its target(s) to the default target list,
2322 so the targets will only be built
2323 if they are specified on the command line,
2324 or are a dependent of a target specified on the command line--but
2327 be built if so specified.
2328 Multiple targets can be passed in to a single call to
2331 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2333 .RI env.Append( key = val ", [...])"
2334 Appends the specified keyword arguments
2335 to the end of construction variables in the environment.
2336 If the Environment does not have
2337 the specified construction variable,
2338 it is simply added to the environment.
2339 If the values of the construction variable
2340 and the keyword argument are the same type,
2341 then the two values will be simply added together.
2342 Otherwise, the construction variable
2343 and the value of the keyword argument
2344 are both coerced to lists,
2345 and the lists are added together.
2346 (See also the Prepend method, below.)
2349 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2352 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2354 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2355 This appends new path elements to the given path in the
2356 specified external environment
2360 any particular path once (leaving the last one it encounters and
2361 ignoring the rest, to preserve path order),
2362 and to help assure this,
2363 will normalize all paths (using
2366 .BR os.path.normcase ).
2367 This can also handle the
2368 case where the given old path variable is a list instead of a
2369 string, in which case a list will be returned instead of a string.
2373 print 'before:',env['ENV']['INCLUDE']
2374 include_path = '/foo/bar:/foo'
2375 env.PrependENVPath('INCLUDE', include_path)
2376 print 'after:',env['ENV']['INCLUDE']
2380 after: /biz:/foo/bar:/foo
2383 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2385 .RI env.AppendUnique( key = val ", [...])"
2386 Appends the specified keyword arguments
2387 to the end of construction variables in the environment.
2388 If the Environment does not have
2389 the specified construction variable,
2390 it is simply added to the environment.
2391 If the construction variable being appended to is a list,
2392 then any value(s) that already exist in the
2393 construction variable will
2395 be added again to the list.
2398 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2401 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2404 A factory function that
2405 returns a Builder object
2406 to be used to fetch source files
2408 The returned Builder
2409 is intended to be passed to the
2414 env.SourceCode('.', env.BitKeeper())
2417 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2419 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2421 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2422 This specifies a build directory
2424 in which to build all derived files
2425 that would normally be built under
2427 Multiple build directories can be set up for multiple build variants, for
2430 must be underneath the SConstruct file's directory,
2433 may not be underneath the
2436 The default behavior is for
2438 to duplicate all of the files in the tree underneath
2442 and then build the derived files within the copied tree.
2443 (The duplication is performed by
2445 depending on the platform; see also the
2448 This guarantees correct builds
2449 regardless of whether intermediate source files
2450 are generated during the build,
2451 where preprocessors or other scanners search
2453 or whether individual compilers or other invoked tools
2454 are hard-coded to put derived files in the same directory as source files.
2456 This behavior of making a complete copy of the source tree
2457 may be disabled by setting
2462 to invoke Builders using the
2463 path names of source files in
2465 and the path names of derived files within
2467 This is always more efficient than
2469 and is usually safe for most builds.
2473 may cause build problems
2474 if source files are generated during the build,
2475 if any invoked tools are hard-coded to
2476 put derived files in the same directory as the source files.
2478 Note that specifying a
2480 works most naturally
2481 with a subsidiary SConscript file
2482 in the source directory.
2484 you would then call the subsidiary SConscript file
2485 not in the source directory,
2490 had made a virtual copy of the source tree
2491 regardless of the value of
2493 This is how you tell
2495 which variant of a source tree to build.
2499 BuildDir('build-variant1', 'src')
2500 SConscript('build-variant1/SConscript')
2501 BuildDir('build-variant2', 'src')
2502 SConscript('build-variant2/SConscript')
2508 function, described below,
2510 specify a build directory
2511 in conjunction with calling a subsidiary
2514 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2516 .RI Builder( action ", [" arguments ])
2518 .RI env.Builder( action ", [" arguments ])
2519 Creates a Builder object for
2522 See the section "Builder Objects,"
2523 below, for a complete explanation of the arguments and behavior.
2525 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2527 .RI CacheDir( cache_dir )
2529 .RI env.CacheDir( cache_dir )
2532 will maintain a cache of derived files in
2534 The derived files in the cache will be shared
2535 among all the builds using the same
2543 finds a derived file that needs to be rebuilt,
2544 it will first look in the cache to see if a
2545 derived file has already been built
2546 from identical input files and an identical build action
2547 (as incorporated into the MD5 build signature).
2550 will retrieve the file from the cache.
2551 If the derived file is not present in the cache,
2554 then place a copy of the built file in the cache
2555 (identified by its MD5 build signature),
2556 so that it may be retrieved by other
2557 builds that need to build the same derived file
2558 from identical inputs.
2562 may be disabled for any invocation
2571 will place a copy of
2573 derived files in the cache,
2574 even if they already existed
2575 and were not built by this invocation.
2576 This is useful to populate a cache
2579 is added to a build,
2588 "Retrieved `file' from cache,"
2591 option is being used.
2596 will print the action that
2598 have been used to build the file,
2599 without any indication that
2600 the file was actually retrieved from the cache.
2601 This is useful to generate build logs
2602 that are equivalent regardless of whether
2603 a given derived file has been built in-place
2604 or retrieved from the cache.
2606 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2608 .RI Clean( targets ", " files_or_dirs )
2610 .RI env.Clean( targets ", " files_or_dirs )
2611 This specifies a list of files or directories which should be removed
2612 whenever the targets are specified with the
2614 command line option.
2615 The specified targets may be a list
2616 or an individual target.
2620 and create new targets or add files and directories to the
2621 clean list for the specified targets.
2623 Multiple files or directories should be specified
2624 either as separate arguments to the
2626 method, or as a list.
2628 will also accept the return value of any of the construction environment
2633 Clean('foo', ['bar', 'baz'])
2634 Clean('dist', env.Program('hello', 'hello.c'))
2635 Clean(['foo', 'bar'], 'something_else_to_clean')
2638 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2640 .RI Command( target ", " source ", " commands ", [" key = val ", ...])"
2642 .RI env.Command( target ", " source ", " commands ", [" key = val ", ...])"
2643 Executes a specific action
2644 (or list of actions)
2645 to build a target file or files.
2646 This is more convenient
2647 than defining a separate Builder object
2648 for a single special-case build.
2649 Any keyword arguments specified override any
2650 same-named existing construction variables.
2652 Note that an action can be an external command,
2653 specified as a string,
2654 or a callable Python object;
2655 see "Action Objects," below.
2659 env.Command('foo.out', 'foo.in',
2660 "$FOO_BUILD < $SOURCES > $TARGET")
2662 env.Command('bar.out', 'bar.in',
2664 "$BAR_BUILD < $SOURCES > $TARGET"],
2665 ENV = {'PATH' : '/usr/local/bin/'})
2667 def rename(env, target, source):
2669 os.rename('.tmp', str(target[0]))
2671 env.Command('baz.out', 'baz.in',
2672 ["$BAZ_BUILD < $SOURCES > .tmp",
2676 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2678 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2680 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2681 Creates a Configure object for integrated
2682 functionality similar to GNU autoconf.
2683 See the section "Configure Contexts,"
2684 below, for a complete explanation of the arguments and behavior.
2686 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2688 .RI env.Copy([ key = val ", ...])"
2689 Return a separate copy of a construction environment.
2690 If there are any keyword arguments specified,
2691 they are added to the returned copy,
2692 overwriting any existing values
2697 env3 = env.Copy(CCFLAGS = '-g')
2700 Additionally, a list of tools and a toolpath may be specified, as in
2701 the Environment constructor:
2704 def MyTool(env): env['FOO'] = 'bar'
2705 env4 = env.Copy(tools = ['msvc', MyTool])
2708 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2710 .RI env.CVS( repository ", " module )
2711 A factory function that
2712 returns a Builder object
2713 to be used to fetch source files
2717 The returned Builder
2718 is intended to be passed to the
2722 The optional specified
2724 will be added to the beginning
2725 of all repository path names;
2726 this can be used, in essence,
2727 to strip initial directory names
2728 from the repository path names,
2729 so that you only have to
2730 replicate part of the repository
2731 directory hierarchy in your
2732 local build directory:
2735 # Will fetch foo/bar/src.c
2736 # from /usr/local/CVSROOT/foo/bar/src.c.
2737 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2739 # Will fetch bar/src.c
2740 # from /usr/local/CVSROOT/foo/bar/src.c.
2741 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2744 # from /usr/local/CVSROOT/foo/bar/src.c.
2745 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2748 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2750 .RI Default( targets )
2752 .RI env.Default( targets )
2753 This specifies a list of default targets,
2754 which will be built by
2756 if no explicit targets are given on the command line.
2760 and add to the list of default targets.
2762 Multiple targets should be specified as
2763 separate arguments to the
2765 method, or as a list.
2767 will also accept the Node returned by any
2768 of a construction environment's
2773 Default('foo', 'bar', 'baz')
2774 env.Default(['a', 'b', 'c'])
2775 hello = env.Program('hello', 'hello.c')
2783 will clear all default targets.
2786 will add to the (now empty) default-target list
2789 The current list of targets added using the
2791 function or method is available in the
2796 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2798 .RI DefaultEnvironment([ args ])
2799 Creates and returns a default construction environment object.
2800 This construction environment is used internally by SCons
2801 in order to execute many of the global functions in this list,
2802 and to fetch source files transparently
2803 from source code management systems.
2805 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2807 .RI Depends( target ", " dependency )
2809 .RI env.Depends( target ", " dependency )
2810 Specifies an explicit dependency;
2811 the target file(s) will be rebuilt
2812 whenever the dependency file(s) has changed.
2813 This should only be necessary
2814 for cases where the dependency
2815 is not caught by a Scanner
2819 env.Depends('foo', 'other-input-file-for-foo')
2822 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2824 .RI env.Dictionary([ vars ])
2825 Returns a dictionary object
2826 containing copies of all of the
2827 construction variables in the environment.
2828 If there are any variable names specified,
2829 only the specified construction
2830 variables are returned in the dictionary.
2833 dict = env.Dictionary()
2834 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
2837 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2839 .RI Dir( name ", [" directory ])
2841 .RI env.Dir( name ", [" directory ])
2842 This returns a Directory Node,
2843 an object that represents the specified directory
2846 can be a relative or absolute path.
2848 is an optional directory that will be used as the parent directory.
2851 is specified, the current script's directory is used as the parent.
2853 Directory Nodes can be used anywhere you
2854 would supply a string as a directory name
2855 to a Builder method or function.
2856 Directory Nodes have attributes and methods
2857 that are useful in many situations;
2858 see "File and Directory Nodes," below.
2860 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2862 .RI env.Dump([ key ])
2863 Returns a pretty printable representation of the environment.
2867 should be a string containing the name of the variable of interest.
2872 print env.Dump('CCCOM')
2876 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
2886 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
2889 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
2894 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2896 .RI EnsurePythonVersion( major ", " minor )
2898 .RI env.EnsurePythonVersion( major ", " minor )
2899 Ensure that the Python version is at least
2902 print out an error message and exit SCons with a non-zero exit code if the
2903 actual Python version is not late enough.
2906 EnsurePythonVersion(2,2)
2909 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2911 .RI EnsureSConsVersion( major ", " minor )
2913 .RI env.EnsureSConsVersion( major ", " minor )
2914 Ensure that the SCons version is at least
2917 print out an error message and exit SCons with a non-zero exit code if the
2918 actual SCons version is not late enough.
2921 EnsureSConsVersion(0,9)
2924 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2926 .RI Environment([ key = value ", ...])"
2928 .RI env.Environment([ key = value ", ...])"
2929 Return a new construction environment
2930 initialized with the specified
2934 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2936 .RI Execute( action ", [" strfunction ", " varlist ])
2938 .RI env.Execute( action ", [" strfunction ", " varlist ])
2939 Executes an Action object.
2942 may be an Action object
2943 (see the section "Action Objects,"
2944 below, for a complete explanation of the arguments and behavior),
2945 or it may be a command-line string,
2947 or executable Python function,
2948 each of which will be converted
2949 into an Action object
2951 The exit value of the command
2952 or return value of the Python function
2955 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2959 .RI env.Exit([ value ])
2965 A default exit value of
2968 is used if no value is specified.
2970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2974 .RI env.Export( vars )
2977 to export a list of variables from the current
2978 SConscript file to all other SConscript files.
2979 The exported variables are kept in a global collection,
2980 so subsequent calls to
2982 will over-write previous exports that have the same name.
2983 Multiple variable names can be passed to
2985 as separate arguments or as a list. A dictionary can be used to map
2986 variables to a different name when exported. Both local variables and
2987 global variables can be exported.
2992 # Make env available for all SConscript files to Import().
2996 # Make env and package available for all SConscript files:.
2997 Export("env", "package")
2999 # Make env and package available for all SConscript files:
3000 Export(["env", "package"])
3002 # Make env available using the name debug:.
3003 Export({"debug":env})
3009 function supports an
3011 argument that makes it easier to to export a variable or
3012 set of variables to a single SConscript file.
3013 See the description of the
3017 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3019 .RI File( name ", [" directory ])
3021 .RI env.File( name ", [" directory ])
3024 an object that represents the specified file
3027 can be a relative or absolute path.
3029 is an optional directory that will be used as the parent directory.
3031 File Nodes can be used anywhere you
3032 would supply a string as a file name
3033 to a Builder method or function.
3034 File Nodes have attributes and methods
3035 that are useful in many situations;
3036 see "File and Directory Nodes," below.
3038 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3040 .RI FindFile( file ", " dirs )
3042 .RI env.FindFile( file ", " dirs )
3045 in the path specified by
3048 may be a list of file names or a single file name. In addition to searching
3049 for files that exist in the filesytem, this function also searches for
3050 derived files that have not yet been built.
3053 foo = env.FindFile('foo', ['dir1', 'dir2'])
3056 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3058 .RI Flatten( sequence )
3060 .RI env.Flatten( sequence )
3061 Takes a sequence (that is, a Python list or tuple)
3062 that may contain nested sequences
3063 and returns a flattened list containing
3064 all of the individual elements in any sequence.
3065 This can be helpful for collecting
3066 the lists returned by calls to Builders;
3067 other Builders will automatically
3068 flatten lists specified as input,
3069 but direct Python manipulation of
3070 these lists does not:
3073 foo = Object('foo.c')
3074 bar = Object('bar.c')
3076 # Because `foo' and `bar' are lists returned by the Object() Builder,
3077 # `objects' will be a list containing nested lists:
3078 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3080 # Passing such a list to another Builder is all right because
3081 # the Builder will flatten the list automatically:
3082 Program(source = objects)
3084 # If you need to manipulate the list directly using Python, you need to
3085 # call Flatten() yourself, or otherwise handle nested lists:
3086 for object in Flatten(objects):
3090 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3092 .RI GetBuildPath( file ", [" ... ])
3094 .RI env.GetBuildPath( file ", [" ... ])
3097 path name (or names) for the specified
3105 Nodes or strings representing path names.
3107 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3111 .RI env.GetLaunchDir()
3112 Returns the absolute path name of the directory from which
3115 was initially invoked.
3116 This can be useful when using the
3121 options, which internally
3122 change to the directory in which the
3126 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3128 .RI GetOption( name )
3130 .RI env.GetOption( name )
3131 This function provides a way to query a select subset of the scons command line
3132 options from a SConscript file. See
3134 for a description of the options available.
3136 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3138 '\".RI GlobalBuilders( flag )
3142 '\"adds the names of the default builders
3143 '\"(Program, Library, etc.)
3144 '\"to the global name space
3145 '\"so they can be called without an explicit construction environment.
3146 '\"(This is the default.)
3150 '\"the names of the default builders are removed
3151 '\"from the global name space
3152 '\"so that an explicit construction environment is required
3153 '\"to call all builders.
3155 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3159 .RI env.Help( text )
3160 This specifies help text to be printed if the
3162 argument is given to
3166 is called multiple times, the text is appended together in the order
3171 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3173 .RI Ignore( target ", " dependency )
3175 .RI env.Ignore( target ", " dependency )
3176 The specified dependency file(s)
3177 will be ignored when deciding if
3178 the target file(s) need to be rebuilt.
3181 env.Ignore('foo', 'foo.c')
3182 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3185 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3189 .RI env.Import( vars )
3192 to import a list of variables into the current SConscript file. This
3193 will import variables that were exported with
3199 Variables exported by
3202 Multiple variable names can be passed to
3204 as separate arguments or as a list. The variable "*" can be used
3205 to import all variables.
3210 Import("env", "variable")
3211 Import(["env", "variable"])
3215 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3217 .RI Install( dir ", " source )
3219 .RI env.Install( dir ", " source )
3220 Installs one or more files in a destination directory.
3221 The file names remain the same.
3224 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3227 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3229 .RI InstallAs( target ", " source )
3231 .RI env.InstallAs( target ", " source )
3232 Installs one or more files as specific file names,
3233 allowing changing a file name as part of the
3235 It is an error if the target and source
3236 list different numbers of files.
3239 env.InstallAs(target = '/usr/local/bin/foo',
3240 source = 'foo_debug')
3241 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3242 source = ['libFOO.a', 'libBAR.a'])
3245 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3247 .RI Literal( string )
3249 .RI env.Literal( string )
3252 will be preserved as-is
3253 and not have construction variables expanded.
3255 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3257 .RI Local( targets )
3259 .RI env.Local( targets )
3262 will have copies made in the local tree,
3263 even if an already up-to-date copy
3264 exists in a repository.
3265 Returns a list of the target Node or Nodes.
3267 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3269 .RI env.ParseConfig( command ", [" function ", " unique ])
3272 to modify the environment as specified by the output of
3276 expects the output of a typical
3280 and adds the options
3281 to the appropriate construction variables.
3283 duplicate values are not
3284 added to any construction variables;
3307 construction variables,
3311 option gets added to both the
3318 option gets added to the
3321 Any other strings not associated with options
3322 are assumed to be the names of libraries
3325 construction variable.
3327 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3329 .RI ParseDepends( filename ", [" must_exist ])
3331 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3332 Parses the contents of the specified
3334 as a list of dependencies in the style of
3338 and explicitly establishes all of the listed dependencies.
3347 argument may be set to a non-zero
3350 throw an exception and
3351 generate an error if the file does not exist,
3352 or is otherwise inaccessible.
3356 argument may be set to a non-zero
3359 thrown an exception and
3361 if the file contains dependency
3362 information for more than one target.
3363 This can provide a small sanity check
3364 for files intended to be generated
3365 by, for example, the
3368 which should typically only
3369 write dependency information for
3370 one output file into a corresponding
3376 and all of the files listed therein
3377 will be interpreted relative to
3378 the directory of the
3380 file which calls the
3384 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3387 A factory function that
3388 returns a Builder object
3389 to be used to fetch source files
3390 from the Perforce source code management system.
3391 The returned Builder
3392 is intended to be passed to the
3397 env.SourceCode('.', env.Perforce())
3400 Perforce uses a number of external
3401 environment variables for its operation.
3402 Consequently, this function adds the
3403 following variables from the user's external environment
3404 to the construction environment's
3417 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3419 .RI Platform( string )
3420 Returns a callable object
3421 that can be used to initialize
3422 a construction environment using the
3423 platform keyword of the Environment() method:
3426 env = Environment(platform = Platform('win32'))
3429 .RI env.Platform( string )
3430 Applies the callable object for the specified platform
3432 to the environment through which the method was called.
3435 env.Platform('posix')
3442 variable from the user's external environment
3443 to the construction environment's
3446 This is so that any executed commands
3447 that use sockets to connect with other systems
3448 (such as fetching source files from
3449 external CVS repository specifications like
3450 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3451 will work on Win32 systems.
3453 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3455 .RI Precious( target ", ...)"
3457 .RI env.Precious( target ", ...)"
3460 as precious so it is not deleted before it is rebuilt. Normally
3462 deletes a target before building it.
3463 Multiple targets can be passed in to a single call to
3466 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3468 .RI env.Prepend( key = val ", [...])"
3469 Appends the specified keyword arguments
3470 to the beginning of construction variables in the environment.
3471 If the Environment does not have
3472 the specified construction variable,
3473 it is simply added to the environment.
3474 If the values of the construction variable
3475 and the keyword argument are the same type,
3476 then the two values will be simply added together.
3477 Otherwise, the construction variable
3478 and the value of the keyword argument
3479 are both coerced to lists,
3480 and the lists are added together.
3481 (See also the Append method, above.)
3484 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3487 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3489 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3490 This appends new path elements to the given path in the
3491 specified external environment
3495 any particular path once (leaving the first one it encounters and
3496 ignoring the rest, to preserve path order),
3497 and to help assure this,
3498 will normalize all paths (using
3501 .BR os.path.normcase ).
3502 This can also handle the
3503 case where the given old path variable is a list instead of a
3504 string, in which case a list will be returned instead of a string.
3508 print 'before:',env['ENV']['INCLUDE']
3509 include_path = '/foo/bar:/foo'
3510 env.PrependENVPath('INCLUDE', include_path)
3511 print 'after:',env['ENV']['INCLUDE']
3515 after: /foo/bar:/foo:/biz
3518 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3520 .RI env.AppendUnique( key = val ", [...])"
3521 Appends the specified keyword arguments
3522 to the beginning of construction variables in the environment.
3523 If the Environment does not have
3524 the specified construction variable,
3525 it is simply added to the environment.
3526 If the construction variable being appended to is a list,
3527 then any value(s) that already exist in the
3528 construction variable will
3530 be added again to the list.
3533 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3539 A factory function that
3540 returns a Builder object
3541 to be used to fetch source files
3543 The returned Builder
3544 is intended to be passed to the
3549 env.SourceCode('.', env.RCS())
3554 will fetch source files
3555 from RCS subdirectories automatically,
3557 as demonstrated in the above example
3558 should only be necessary if
3559 you are fetching from
3562 directory as the source files,
3563 or if you need to explicitly specify RCS
3564 for a specific subdirectory.
3566 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3568 .RI env.Replace( key = val ", [...])"
3569 Replaces construction variables in the Environment
3570 with the specified keyword arguments.
3573 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3576 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3578 .RI Repository( directory )
3580 .RI env.Repository( directory )
3583 is a repository to be searched for files.
3587 and each one adds to the list of
3588 repositories that will be searched.
3592 a repository is a copy of the source tree,
3593 from the top-level directory on down,
3595 both source files and derived files
3596 that can be used to build targets in
3597 the local source tree.
3598 The canonical example would be an
3599 official source tree maintained by an integrator.
3600 If the repository contains derived files,
3601 then the derived files should have been built using
3603 so that the repository contains the necessary
3604 signature information to allow
3606 to figure out when it is appropriate to
3607 use the repository copy of a derived file,
3608 instead of building one locally.
3610 Note that if an up-to-date derived file
3611 already exists in a repository,
3615 make a copy in the local directory tree.
3616 In order to guarantee that a local copy
3622 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3627 what variable(s) to use as the return value(s) of the current SConscript
3628 file. These variables will be returned to the "calling" SConscript file
3629 as the return value(s) of
3631 Multiple variable names should be passed to
3637 Return(["foo", "bar"])
3640 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3642 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3644 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3645 Creates a Scanner object for
3648 See the section "Scanner Objects,"
3649 below, for a complete explanation of the arguments and behavior.
3651 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3654 A factory function that
3655 returns a Builder object
3656 to be used to fetch source files
3658 The returned Builder
3659 is intended to be passed to the
3664 env.SourceCode('.', env.SCCS())
3669 will fetch source files
3670 from SCCS subdirectories automatically,
3672 as demonstrated in the above example
3673 should only be necessary if
3674 you are fetching from
3677 directory as the source files,
3678 or if you need to explicitly specify SCCS
3679 for a specific subdirectory.
3681 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3683 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3685 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3687 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3689 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3693 one or more subsidiary SConscript (configuration) files.
3694 There are two ways to call the
3698 The first way you can call
3700 is to explicitly specify one or more
3702 as the first argument.
3703 A single script may be specified as a string;
3704 multiple scripts must be specified as a list
3705 (either explicitly or as created by
3709 The second way you can call
3711 is to specify a list of (sub)directory names
3718 execute a subsidiary configuration file named
3720 in each of the specified directories.
3721 You may specify a name other than
3723 by supplying an optional
3729 argument provides a list of variable names or a dictionary of
3730 named values to export to the
3732 These variables are locally exported only to the specified
3734 and do not affect the
3735 global pool of variables used by
3739 '\"If multiple dirs are provided,
3740 '\"each script gets a fresh export.
3745 function to import the variables.
3749 argument specifies that all of the target files
3750 (for example, object files and executables)
3751 that would normally be built in the subdirectory in which
3753 resides should actually
3757 is interpreted relative to the directory
3758 of the calling SConscript file.
3762 argument specifies that the
3763 source files from which
3764 the target files should be built
3768 is interpreted relative to the directory
3769 of the calling SConscript file.
3773 will link or copy (depending on the platform)
3774 all the source files into the build directory.
3775 This behavior may be disabled by
3776 setting the optional
3779 (it is set to 1 by default),
3782 will refer directly to
3783 the source files in their source directory
3784 when building target files.
3787 is usually safe, and always more efficient
3790 but it may cause build problems in certain end-cases,
3791 such as compiling from source files that
3792 are generated by the build.)
3794 Any variables returned by
3798 will be returned by the call to
3804 SConscript('subdir/SConscript')
3805 foo = SConscript('sub/SConscript', exports='env')
3806 SConscript('dir/SConscript', exports=['env', 'variable'])
3807 SConscript('src/SConscript', build_dir='build', duplicate=0)
3808 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3809 SConscript(dirs=['sub1', 'sub2'])
3810 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
3813 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3815 .RI SConscriptChdir( value )
3817 .RI env.SConscriptChdir( value )
3820 changes its working directory
3821 to the directory in which each
3822 subsidiary SConscript file lives.
3823 This behavior may be disabled
3824 by specifying either:
3828 env.SConscriptChdir(0)
3833 will stay in the top-level directory
3834 while reading all SConscript files.
3835 (This may be necessary when building from repositories,
3836 when all the directories in which SConscript files may be found
3837 don't necessarily exist locally.)
3839 You may enable and disable
3840 this ability by calling
3847 SConscript('foo/SConscript') # will not chdir to foo
3848 env.SConscriptChdir(1)
3849 SConscript('bar/SConscript') # will chdir to bar
3852 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3854 .RI SConsignFile([ file , dbm_module ])
3856 .RI env.SConsignFile([ file , dbm_module ])
3859 to store all file signatures
3869 is not an absolute path name,
3870 the file is placed in the same directory as the top-level
3876 argument can be used to specify
3877 which Python database module
3878 The default is to use a custom
3880 module that uses pickled
3881 Python data structures,
3882 and which works on all Python versions from 1.5.2 on.
3887 # Stores signatures in ".sconsign.dbm"
3888 # in the top-level SConstruct directory.
3891 # Stores signatures in the file "etc/scons-signatures"
3892 # relative to the top-level SConstruct directory.
3893 SConsignFile("etc/scons-signatures")
3895 # Stores signatures in the specified absolute file name.
3896 SConsignFile("/home/me/SCons/signatures")
3899 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3901 .RI env.SetDefault(key = val ", [...])"
3902 Sets construction variables to default values specified with the keyword
3903 arguments if (and only if) the variables are not already set.
3904 The following statements are equivalent:
3907 env.SetDefault(FOO = 'foo')
3909 if not env.has_key('FOO'): env['FOO'] = 'foo'
3912 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3914 .RI SetOption( name ", " value )
3916 .RI env.SetOption( name ", " value )
3917 This function provides a way to set a select subset of the scons command
3918 line options from a SConscript file. The options supported are:
3920 which corresponds to -c, --clean, and --remove;
3923 corresponds to --duplicate;
3925 which corresponds to --implicit-cache;
3927 which corresponds to --max-drift;
3929 which corresponds to -j and --jobs.
3930 See the documentation for the
3931 corresponding command line object for information about each specific
3935 SetOption('max_drift', 1)
3938 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3940 .RI SideEffect( side_effect ", " target )
3942 .RI env.SideEffect( side_effect ", " target )
3945 as a side effect of building
3951 can be a list, a file name, or a node.
3952 A side effect is a target that is created
3953 as a side effect of building other targets.
3954 For example, a Windows PDB
3955 file is created as a side effect of building the .obj
3956 files for a static library.
3957 If a target is a side effect of multiple build commands,
3959 will ensure that only one set of commands
3960 is executed at a time.
3961 Consequently, you only need to use this method
3962 for side-effect targets that are built as a result of
3963 multiple build commands.
3965 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3967 .RI SourceCode( entries ", " builder )
3969 .RI env.SourceCode( entries ", " builder )
3970 Arrange for non-existent source files to
3971 be fetched from a source code management system
3976 may be a Node, string or list of both,
3977 and may represent either individual
3978 source files or directories in which
3979 source files can be found.
3981 For any non-existent source files,
3983 will search up the directory tree
3993 will not use a builder to fetch
3994 source files for the specified
3998 builder has been specified
3999 for a directory higher up the tree.
4003 fetch files from SCCS or RCS subdirectories
4004 without explicit configuration.
4005 This takes some extra processing time
4006 to search for the necessary
4007 source code management files on disk.
4008 You can avoid these extra searches
4009 and speed up your build a little
4010 by disabling these searches as follows:
4013 env.SourceCode('.', None)
4017 Note that if the specified
4019 is one you create by hand,
4020 it must have an associated
4021 construction environment to use
4022 when fetching a source file.
4025 provides a set of canned factory
4026 functions that return appropriate
4027 Builders for various popular
4028 source code management systems.
4029 Canonical examples of invocation include:
4032 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4033 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4034 env.SourceCode('/', env.RCS())
4035 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4036 env.SourceCode('no_source.c', None)
4038 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4040 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4042 '\".RI Subversion( repository ", " module )
4043 '\"A factory function that
4044 '\"returns a Builder object
4045 '\"to be used to fetch source files
4046 '\"from the specified Subversion
4048 '\"The returned Builder
4049 '\"is intended to be passed to the
4053 '\"The optional specified
4055 '\"will be added to the beginning
4056 '\"of all repository path names;
4057 '\"this can be used, in essence,
4058 '\"to strip initial directory names
4059 '\"from the repository path names,
4060 '\"so that you only have to
4061 '\"replicate part of the repository
4062 '\"directory hierarchy in your
4063 '\"local build directory:
4066 '\"# Will fetch foo/bar/src.c
4067 '\"# from /usr/local/Subversion/foo/bar/src.c.
4068 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4070 '\"# Will fetch bar/src.c
4071 '\"# from /usr/local/Subversion/foo/bar/src.c.
4072 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4074 '\"# Will fetch src.c
4075 '\"# from /usr/local/Subversion/foo/bar/src.c.
4076 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4079 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4081 .RI SourceSignatures( type )
4083 .RI env.SourceSignatures( type )
4084 This function tells SCons what type of signature to use for source files:
4088 If the environment method is used,
4089 the specified type of source signature
4090 is only used when deciding whether targets
4091 built with that environment are up-to-date or must be rebuilt.
4092 If the global function is used,
4093 the specified type of source signature becomes the default
4094 used for all decisions
4095 about whether targets are up-to-date.
4097 "MD5" means the signature of a source file
4098 is the MD5 checksum of its contents.
4099 "timestamp" means the signature of a source file
4100 is its timestamp (modification time).
4101 There is no different between the two behaviors
4105 "MD5" signatures take longer to compute,
4106 but are more accurate than "timestamp" signatures.
4107 The default is "MD5".
4109 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4113 .RI env.Split( arg )
4114 Returns a list of file names or other objects.
4116 it will be split on strings of white-space characters
4118 making it easier to write long lists of file names.
4119 If arg is already a list,
4120 the list will be returned untouched.
4121 If arg is any other type of object,
4122 it will be returned as a list
4123 containing just the object.
4126 files = Split("f1.c f2.c f3.c")
4127 files = env.Split("f4.c f5.c f6.c")
4135 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4137 .RI TargetSignatures( type )
4139 .RI env.TargetSignatures( type )
4140 This function tells SCons what type of signatures to use
4145 If the environment method is used,
4146 the specified type of signature is only used
4147 for targets built with that environment.
4148 If the global function is used,
4149 the specified type of signature becomes the default
4150 used for all target files that
4151 don't have an explicit target signature type
4152 specified for their environments.
4154 "build" means the signature of a target file
4155 is made by concatenating all of the
4156 signatures of all its source files.
4157 "content" means the signature of a target
4158 file is an MD5 checksum of its contents.
4159 "build" signatures are usually faster to compute,
4160 but "content" signatures can prevent unnecessary rebuilds
4161 when a target file is rebuilt to the exact same contents
4162 as the previous build.
4163 The default is "build".
4165 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4167 .RI Tool( string [, toolpath ", " **kw ])
4168 Returns a callable object
4169 that can be used to initialize
4170 a construction environment using the
4171 tools keyword of the Environment() method.
4172 The object may be called with a construction
4173 environment as an argument,
4174 in which case the object will
4175 add the necessary variables
4176 to the construction environment
4177 and the name of the tool will be added to the
4179 construction variable.
4181 Additional keyword arguments are passed to the tool's
4186 env = Environment(tools = [ Tool('msvc') ])
4190 t(env) # adds 'msvc' to the TOOLS variable
4191 u = Tool('opengl', toolpath = ['tools'])
4192 u(env) # adds 'opengl' to the TOOLS variable
4195 .RI env.Tool( string [, toolpath ", " **kw ])
4196 Applies the callable object for the specified tool
4198 to the environment through which the method was called.
4200 Additional keyword arguments are passed to the tool's
4206 env.Tool('opengl', toolpath = ['build/tools'])
4209 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4213 .RI env.Value( value )
4214 Returns a Node object representing the specified Python value. Value
4215 nodes can be used as dependencies of targets. If the result of
4218 changes between SCons runs, any targets depending on
4220 will be rebuilt. When using timestamp source signatures, Value nodes'
4221 timestamps are equal to the system time when the node is created.
4224 def create(target, source, env):
4225 f = open(str(target[0]), 'wb')
4226 f.write('prefix=' + source[0].get_contents())
4228 prefix = ARGUMENTS.get('prefix', '/usr/local')
4230 env['BUILDERS']['Config'] = Builder(action = create)
4231 env.Config(target = 'package-config', source = Value(prefix))
4234 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4236 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4238 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4240 Searches for the specified executable
4242 returning the full path name to the program
4244 and returning None if not.
4245 Searches the specified
4247 the value of the calling environment's PATH
4248 (env['ENV']['PATH']),
4249 or the user's current external PATH
4250 (os.environ['PATH'])
4252 On Win32 systems, searches for executable
4253 programs with any of the file extensions
4254 listed in the specified
4256 the calling environment's PATHEXT
4257 (env['ENV']['PATHEXT'])
4258 or the user's current PATHEXT
4259 (os.environ['PATHEXT'])
4267 .SS SConscript Variables
4268 In addition to the global functions and methods,
4270 supports a number of Python variables
4271 that can be used in SConscript files
4272 to affect how you want the build to be performed.
4274 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4279 arguments specified on the command line.
4280 Each element in the list is a tuple
4282 .RI ( keyword , value )
4288 elements of the tuple
4290 subscripting for element
4294 of the tuple, respectively.
4297 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4298 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4299 third_tuple = ARGLIST[2]
4300 print "third keyword, value =", third_tuple[0], third_tuple[1]
4301 for key, value in ARGLIST:
4302 # process key and value
4305 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4308 A dictionary of all the
4310 arguments specified on the command line.
4311 The dictionary is not in order,
4312 and if a given keyword has
4313 more than one value assigned to it
4314 on the command line,
4315 the last (right-most) value is
4321 if ARGUMENTS.get('debug', 0):
4322 env = Environment(CCFLAGS = '-g')
4327 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4330 A list of the targets which
4332 will actually try to build,
4333 regardless of whether they were specified on
4334 the command line or via the
4337 The elements of this list may be strings
4339 nodes, so you should run the list through the Python
4341 function to make sure any Node path names
4342 are converted to strings.
4344 Because this list may be taken from the
4345 list of targets specified using the
4348 the contents of the list may change
4349 on each successive call to
4354 for additional information.
4357 if 'foo' in BUILD_TARGETS:
4358 print "Don't forget to test the `foo' program!"
4359 if 'special/program' in BUILD_TARGETS:
4360 SConscript('special')
4365 list only contains targets expected listed
4366 on the command line or via calls to the
4371 contain all dependent targets that will be built as
4372 a result of making the sure the explicitly-specified
4373 targets are up to date.
4375 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4377 COMMAND_LINE_TARGETS
4378 A list of the targets explicitly specified on
4380 If there are no targets specified on the command line,
4382 This can be used, for example,
4383 to take specific actions only
4384 when a certain target or targets
4385 is explicitly being built:
4388 if 'foo' in COMMAND_LINE_TARGETS:
4389 print "Don't forget to test the `foo' program!"
4390 if 'special/program' in COMMAND_LINE_TARGETS:
4391 SConscript('special')
4394 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4397 A list of the target
4399 that have been specified using the
4402 The elements of the list are nodes,
4403 so you need to run them through the Python
4405 function to get at the path name for each Node.
4408 print str(DEFAULT_TARGETS[0])
4409 if 'foo' in map(str, DEFAULT_TARGETS):
4410 print "Don't forget to test the `foo' program!"
4415 list change on on each successive call to the
4420 print map(str, DEFAULT_TARGETS) # originally []
4422 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4424 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4426 print map(str, DEFAULT_TARGETS) # back to []
4429 Consequently, be sure to use
4431 only after you've made all of your
4434 or else simply be careful of the order
4435 of these statements in your SConscript files
4436 so that you don't look for a specific
4437 default target before it's actually been added to the list.
4439 .SS Construction Variables
4440 .\" XXX From Gary Ruben, 23 April 2002:
4441 .\" I think it would be good to have an example with each construction
4442 .\" variable description in the documentation.
4444 .\" CC The C compiler
4445 .\" Example: env["CC"] = "c68x"
4446 .\" Default: env["CC"] = "cc"
4448 .\" CCCOM The command line ...
4450 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4451 .\" env["CC"] = "c68x"
4452 .\" env["CFLAGS"] = "-ps -qq -mr"
4453 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4455 .\" (I dunno what this is ;-)
4456 A construction environment has an associated dictionary of
4457 .I construction variables
4458 that are used by built-in or user-supplied build rules.
4459 Construction variables must follow the same rules for
4461 the initial character must be an underscore or letter,
4462 followed by any number of underscores, letters, or digits.
4464 A number of useful construction variables are automatically defined by
4465 scons for each supported platform, and additional construction variables
4466 can be defined by the user. The following is a list of the automatically
4467 defined construction variables:
4470 The static library archiver.
4473 The command line used to generate a static library from object files.
4476 The string displayed when an object file
4477 is generated from an assembly-language source file.
4478 If this is not set, then $ARCOM (the command line) is displayed.
4481 env = Environment(ARCOMSTR = "Archiving $TARGET")
4485 General options passed to the static library archiver.
4491 The command line used to generate an object file
4492 from an assembly-language source file.
4495 The string displayed when an object file
4496 is generated from an assembly-language source file.
4497 If this is not set, then $ASCOM (the command line) is displayed.
4500 env = Environment(ASCOMSTR = "Assembling $TARGET")
4504 General options passed to the assembler.
4507 The command line used to assemble an assembly-language
4508 source file into an object file
4509 after first running the file through the C preprocessor.
4510 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4511 are included on this command line.
4514 The string displayed when an object file
4515 is generated from an assembly-language source file
4516 after first running the file through the C preprocessor.
4517 If this is not set, then $ASPPCOM (the command line) is displayed.
4520 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4524 General options when an assembling an assembly-language
4525 source file into an object file
4526 after first running the file through the C preprocessor.
4527 The default is to use the value of $ASFLAGS.
4530 The bibliography generator for the TeX formatter and typesetter and the
4531 LaTeX structured formatter and typesetter.
4534 The command line used to call the bibliography generator for the
4535 TeX formatter and typesetter and the LaTeX structured formatter and
4539 The string displayed when generating a bibliography
4541 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4544 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4549 General options passed to the bibliography generator for the TeX formatter
4550 and typesetter and the LaTeX structured formatter and typesetter.
4553 The BitKeeper executable.
4556 The command line for
4557 fetching source files using BitKeeper.
4560 The string displayed when fetching
4561 a source file using BitKeeper.
4562 If this is not set, then $BITKEEPERCOM
4563 (the command line) is displayed.
4566 The command ($BITKEEPER) and subcommand
4567 for fetching source files using BitKeeper.
4569 .IP BITKEEPERGETFLAGS
4570 Options that are passed to the BitKeeper
4575 A dictionary mapping the names of the builders
4576 available through this environment
4577 to underlying Builder objects.
4579 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4580 are available by default.
4581 If you initialize this variable when an
4582 Environment is created:
4585 env = Environment(BUILDERS = {'NewBuilder' : foo})
4588 the default Builders will no longer be available.
4589 To use a new Builder object in addition to the default Builders,
4590 add your new Builder object like this:
4594 env.Append(BUILDERS = {'NewBuilder' : foo})
4601 env['BUILDERS]['NewBuilder'] = foo
4608 The command line used to compile a C source file to a (static) object file.
4609 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4610 are included on this command line.
4613 The string displayed when a C source file
4614 is compiled to a (static) object file.
4615 If this is not set, then $CCCOM (the command line) is displayed.
4618 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4622 General options that are passed to the C compiler.
4625 The suffix for C source files.
4626 This is used by the internal CFile builder
4627 when generating C files from Lex (.l) or YACC (.y) input files.
4628 The default suffix, of course, is
4631 On case-insensitive systems (like Win32),
4638 The version number of the C compiler.
4639 This may or may not be set,
4640 depending on the specific C compiler being used.
4643 A function used to produce variables like $_CPPINCFLAGS. It takes
4645 arguments: a prefix to concatenate onto each element, a list of
4646 elements, a suffix to concatenate onto each element, an environment
4647 for variable interpolation, and an optional function that will be
4648 called to transform the list before concatenation.
4651 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4655 A platform independent specification of C preprocessor definitions.
4656 The definitions will be added to command lines
4657 through the automatically-generated
4658 $_CPPDEFFLAGS construction variable (see below),
4659 which is constructed according to
4660 the type of value of $CPPDEFINES:
4663 If $CPPDEFINES is a string,
4665 $CPPDEFPREFIX and $CPPDEFSUFFIX
4666 construction variables
4667 will be added to the beginning and end.
4670 # Will add -Dxyz to POSIX compiler command lines,
4671 # and /Dxyz to Microsoft Visual C++ command lines.
4672 env = Environment(CPPDEFINES='xyz')
4676 If $CPPDEFINES is a list,
4678 $CPPDEFPREFIX and $CPPDEFSUFFIX
4679 construction variables
4680 will be appended to the beginning and end
4681 of each element in the list.
4682 If any element is a list or tuple,
4683 then the first item is the name being
4684 defined and the second item is its value:
4687 # Will add -DB=2 -DA to POSIX compiler command lines,
4688 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4689 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4693 If $CPPDEFINES is a dictionary,
4695 $CPPDEFPREFIX and $CPPDEFSUFFIX
4696 construction variables
4697 will be appended to the beginning and end
4698 of each item from the dictionary.
4699 The key of each dictionary item
4700 is a name being defined
4701 to the dictionary item's corresponding value;
4704 then the name is defined without an explicit value.
4705 Note that the resulting flags are sorted by keyword
4706 to ensure that the order of the options on the
4707 command line is consistent each time
4712 # Will add -DA -DB=2 to POSIX compiler command lines,
4713 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4714 env = Environment(CPPDEFINES={'B':2, 'A':None})
4718 An automatically-generated construction variable
4719 containing the C preprocessor command-line options
4721 The value of $_CPPDEFFLAGS is created
4722 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4723 to the beginning and end
4724 of each directory in $CPPDEFINES.
4727 The prefix used to specify preprocessor definitions
4728 on the C compiler command line.
4729 This will be appended to the beginning of each definition
4730 in the $CPPDEFINES construction variable
4731 when the $_CPPDEFFLAGS variable is automatically generated.
4734 The suffix used to specify preprocessor definitions
4735 on the C compiler command line.
4736 This will be appended to the end of each definition
4737 in the $CPPDEFINES construction variable
4738 when the $_CPPDEFFLAGS variable is automatically generated.
4741 User-specified C preprocessor options.
4742 These will be included in any command that uses the C preprocessor,
4743 including not just compilation of C and C++ source files
4744 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4745 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4746 $F77PPCOM and $SHF77PPCOM command lines
4747 used to compile a Fortran source file,
4748 and the $ASPPCOM command line
4749 used to assemble an assembly language source file,
4750 after first running each file through the C preprocessor.
4751 Note that this variable does
4755 (or similar) include search path options
4756 that scons generates automatically from $CPPPATH.
4760 for the variable that expands to those options.
4763 An automatically-generated construction variable
4764 containing the C preprocessor command-line options
4765 for specifying directories to be searched for include files.
4766 The value of $_CPPINCFLAGS is created
4767 by appending $INCPREFIX and $INCSUFFIX
4768 to the beginning and end
4769 of each directory in $CPPPATH.
4772 The list of directories that the C preprocessor will search for include
4773 directories. The C/C++ implicit dependency scanner will search these
4774 directories for include files. Don't explicitly put include directory
4775 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
4776 and the directories will not be searched by the dependency scanner. Note:
4777 directory names in CPPPATH will be looked-up relative to the SConscript
4778 directory when they are used in a command. To force
4780 to look-up a directory relative to the root of the source tree use #:
4783 env = Environment(CPPPATH='#/include')
4787 The directory look-up can also be forced using the
4792 include = Dir('include')
4793 env = Environment(CPPPATH=include)
4797 The directory list will be added to command lines
4798 through the automatically-generated
4800 construction variable,
4801 which is constructed by
4802 appending the values of the
4803 $INCPREFIX and $INCSUFFIX
4804 construction variables
4805 to the beginning and end
4806 of each directory in $CPPPATH.
4807 Any command lines you define that need
4808 the CPPPATH directory list should
4809 include $_CPPINCFLAGS:
4812 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
4816 The list of suffixes of files that will be scanned
4817 for C preprocessor implicit dependencies
4819 The default list is:
4822 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
4823 ".h", ".H", ".hxx", ".hpp", ".hh",
4824 ".F", ".fpp", ".FPP",
4825 ".S", ".spp", ".SPP"]
4832 Options that are passed to the CVS checkout subcommand.
4835 The command line used to
4836 fetch source files from a CVS repository.
4839 The string displayed when fetching
4840 a source file from a CVS repository.
4841 If this is not set, then $CVSCOM
4842 (the command line) is displayed.
4845 General options that are passed to CVS.
4846 By default, this is set to
4848 to specify from where the files must be fetched.
4851 The path to the CVS repository.
4852 This is referenced in the default
4859 The suffix for C++ source files.
4860 This is used by the internal CXXFile builder
4861 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
4862 The default suffix is
4864 SCons also treats files with the suffixes
4871 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
4878 The command line used to compile a C++ source file to an object file.
4879 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
4880 are included on this command line.
4883 The string displayed when a C++ source file
4884 is compiled to a (static) object file.
4885 If this is not set, then $CXXCOM (the command line) is displayed.
4888 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
4892 General options that are passed to the C++ compiler.
4895 The version number of the C++ compiler.
4896 This may or may not be set,
4897 depending on the specific C++ compiler being used.
4900 A function that converts a file name into a Dir instance relative to the
4904 The list of suffixes of files that will be scanned
4905 for imported D package files.
4906 The default list is:
4913 The TeX DVI file to PDF file converter.
4916 General options passed to the TeX DVI file to PDF file converter.
4919 The command line used to convert TeX DVI files into a PDF file.
4922 The string displayed when a TeX DVI file
4923 is converted into a PDF file.
4924 If this is not set, then $DVIPDFCOM (the command line) is displayed.
4927 The TeX DVI file to PostScript converter.
4930 General options passed to the TeX DVI file to PostScript converter.
4933 A dictionary of environment variables
4934 to use when invoking commands. When ENV is used in a command all list
4935 values will be joined using the path separator and any other non-string
4936 values will simply be coerced to a string.
4937 Note that, by default,
4941 propagate the environment in force when you
4944 to the commands used to build target files.
4945 This is so that builds will be guaranteed
4946 repeatable regardless of the environment
4947 variables set at the time
4951 If you want to propagate your
4952 environment variables
4953 to the commands executed
4954 to build target files,
4955 you must do so explicitly:
4959 env = Environment(ENV = os.environ)
4963 Note that you can choose only to propagate
4964 certain environment variables.
4968 environment variable,
4971 uses the same utilities
4972 as the invoking shell (or other process):
4977 env = Environment(ENV = {'PATH' : os.environ['PATH']})
4981 A function that will be called to escape shell special characters in
4982 command lines. The function should take one argument: the command line
4983 string to escape; and should return the escaped command line.
4986 The Fortran 77 compiler.
4987 You should normally set the $FORTRAN variable,
4988 which specifies the default Fortran compiler
4989 for all Fortran versions.
4990 You only need to set $F77 if you need to use a specific compiler
4991 or compiler version for Fortran 77 files.
4994 The command line used to compile a Fortran 77 source file to an object file.
4995 You only need to set $F77COM if you need to use a specific
4996 command line for Fortran 77 files.
4997 You should normally set the $FORTRANCOM variable,
4998 which specifies the default command line
4999 for all Fortran versions.
5002 The string displayed when a Fortran 77 source file
5003 is compiled to an object file.
5004 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5007 General user-specified options that are passed to the Fortran 77 compiler.
5008 Note that this variable does
5012 (or similar) include search path options
5013 that scons generates automatically from $F77PATH.
5017 for the variable that expands to those options.
5018 You only need to set $F77FLAGS if you need to define specific
5019 user options for Fortran 77 files.
5020 You should normally set the $FORTRANFLAGS variable,
5021 which specifies the user-specified options
5022 passed to the default Fortran compiler
5023 for all Fortran versions.
5026 An automatically-generated construction variable
5027 containing the Fortran 77 compiler command-line options
5028 for specifying directories to be searched for include files.
5029 The value of $_F77INCFLAGS is created
5030 by appending $INCPREFIX and $INCSUFFIX
5031 to the beginning and end
5032 of each directory in $F77PATH.
5035 The list of directories that the Fortran 77 compiler will search for include
5036 directories. The implicit dependency scanner will search these
5037 directories for include files. Don't explicitly put include directory
5038 arguments in $F77FLAGS because the result will be non-portable
5039 and the directories will not be searched by the dependency scanner. Note:
5040 directory names in $F77PATH will be looked-up relative to the SConscript
5041 directory when they are used in a command. To force
5043 to look-up a directory relative to the root of the source tree use #:
5044 You only need to set $F77PATH if you need to define a specific
5045 include path for Fortran 77 files.
5046 You should normally set the $FORTRANPATH variable,
5047 which specifies the include path
5048 for the default Fortran compiler
5049 for all Fortran versions.
5052 env = Environment(F77PATH='#/include')
5056 The directory look-up can also be forced using the
5061 include = Dir('include')
5062 env = Environment(F77PATH=include)
5066 The directory list will be added to command lines
5067 through the automatically-generated
5069 construction variable,
5070 which is constructed by
5071 appending the values of the
5072 $INCPREFIX and $INCSUFFIX
5073 construction variables
5074 to the beginning and end
5075 of each directory in $F77PATH.
5076 Any command lines you define that need
5077 the F77PATH directory list should
5078 include $_F77INCFLAGS:
5081 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5085 The command line used to compile a Fortran 77 source file to an object file
5086 after first running the file through the C preprocessor.
5087 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5088 are included on this command line.
5089 You only need to set $F77PPCOM if you need to use a specific
5090 C-preprocessor command line for Fortran 77 files.
5091 You should normally set the $FORTRANPPCOM variable,
5092 which specifies the default C-preprocessor command line
5093 for all Fortran versions.
5096 The Fortran 90 compiler.
5097 You should normally set the $FORTRAN variable,
5098 which specifies the default Fortran compiler
5099 for all Fortran versions.
5100 You only need to set $F90 if you need to use a specific compiler
5101 or compiler version for Fortran 90 files.
5104 The command line used to compile a Fortran 90 source file to an object file.
5105 You only need to set $F90COM if you need to use a specific
5106 command line for Fortran 90 files.
5107 You should normally set the $FORTRANCOM variable,
5108 which specifies the default command line
5109 for all Fortran versions.
5112 The string displayed when a Fortran 90 source file
5113 is compiled to an object file.
5114 If this is not set, then $F90COM or $FORTRANCOM
5115 (the command line) is displayed.
5118 General user-specified options that are passed to the Fortran 90 compiler.
5119 Note that this variable does
5123 (or similar) include search path options
5124 that scons generates automatically from $F90PATH.
5128 for the variable that expands to those options.
5129 You only need to set $F90FLAGS if you need to define specific
5130 user options for Fortran 90 files.
5131 You should normally set the $FORTRANFLAGS variable,
5132 which specifies the user-specified options
5133 passed to the default Fortran compiler
5134 for all Fortran versions.
5137 An automatically-generated construction variable
5138 containing the Fortran 90 compiler command-line options
5139 for specifying directories to be searched for include files.
5140 The value of $_F90INCFLAGS is created
5141 by appending $INCPREFIX and $INCSUFFIX
5142 to the beginning and end
5143 of each directory in $F90PATH.
5146 The list of directories that the Fortran 90 compiler will search for include
5147 directories. The implicit dependency scanner will search these
5148 directories for include files. Don't explicitly put include directory
5149 arguments in $F90FLAGS because the result will be non-portable
5150 and the directories will not be searched by the dependency scanner. Note:
5151 directory names in $F90PATH will be looked-up relative to the SConscript
5152 directory when they are used in a command. To force
5154 to look-up a directory relative to the root of the source tree use #:
5155 You only need to set $F90PATH if you need to define a specific
5156 include path for Fortran 90 files.
5157 You should normally set the $FORTRANPATH variable,
5158 which specifies the include path
5159 for the default Fortran compiler
5160 for all Fortran versions.
5163 env = Environment(F90PATH='#/include')
5167 The directory look-up can also be forced using the
5172 include = Dir('include')
5173 env = Environment(F90PATH=include)
5177 The directory list will be added to command lines
5178 through the automatically-generated
5180 construction variable,
5181 which is constructed by
5182 appending the values of the
5183 $INCPREFIX and $INCSUFFIX
5184 construction variables
5185 to the beginning and end
5186 of each directory in $F90PATH.
5187 Any command lines you define that need
5188 the F90PATH directory list should
5189 include $_F90INCFLAGS:
5192 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5196 The command line used to compile a Fortran 90 source file to an object file
5197 after first running the file through the C preprocessor.
5198 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5199 are included on this command line.
5200 You only need to set $F90PPCOM if you need to use a specific
5201 C-preprocessor command line for Fortran 90 files.
5202 You should normally set the $FORTRANPPCOM variable,
5203 which specifies the default C-preprocessor command line
5204 for all Fortran versions.
5207 The Fortran 95 compiler.
5208 You should normally set the $FORTRAN variable,
5209 which specifies the default Fortran compiler
5210 for all Fortran versions.
5211 You only need to set $F95 if you need to use a specific compiler
5212 or compiler version for Fortran 95 files.
5215 The command line used to compile a Fortran 95 source file to an object file.
5216 You only need to set $F95COM if you need to use a specific
5217 command line for Fortran 95 files.
5218 You should normally set the $FORTRANCOM variable,
5219 which specifies the default command line
5220 for all Fortran versions.
5223 The string displayed when a Fortran 95 source file
5224 is compiled to an object file.
5225 If this is not set, then $F95COM or $FORTRANCOM
5226 (the command line) is displayed.
5229 General user-specified options that are passed to the Fortran 95 compiler.
5230 Note that this variable does
5234 (or similar) include search path options
5235 that scons generates automatically from $F95PATH.
5239 for the variable that expands to those options.
5240 You only need to set $F95FLAGS if you need to define specific
5241 user options for Fortran 95 files.
5242 You should normally set the $FORTRANFLAGS variable,
5243 which specifies the user-specified options
5244 passed to the default Fortran compiler
5245 for all Fortran versions.
5248 An automatically-generated construction variable
5249 containing the Fortran 95 compiler command-line options
5250 for specifying directories to be searched for include files.
5251 The value of $_F95INCFLAGS is created
5252 by appending $INCPREFIX and $INCSUFFIX
5253 to the beginning and end
5254 of each directory in $F95PATH.
5257 The list of directories that the Fortran 95 compiler will search for include
5258 directories. The implicit dependency scanner will search these
5259 directories for include files. Don't explicitly put include directory
5260 arguments in $F95FLAGS because the result will be non-portable
5261 and the directories will not be searched by the dependency scanner. Note:
5262 directory names in $F95PATH will be looked-up relative to the SConscript
5263 directory when they are used in a command. To force
5265 to look-up a directory relative to the root of the source tree use #:
5266 You only need to set $F95PATH if you need to define a specific
5267 include path for Fortran 95 files.
5268 You should normally set the $FORTRANPATH variable,
5269 which specifies the include path
5270 for the default Fortran compiler
5271 for all Fortran versions.
5274 env = Environment(F95PATH='#/include')
5278 The directory look-up can also be forced using the
5283 include = Dir('include')
5284 env = Environment(F95PATH=include)
5288 The directory list will be added to command lines
5289 through the automatically-generated
5291 construction variable,
5292 which is constructed by
5293 appending the values of the
5294 $INCPREFIX and $INCSUFFIX
5295 construction variables
5296 to the beginning and end
5297 of each directory in $F95PATH.
5298 Any command lines you define that need
5299 the F95PATH directory list should
5300 include $_F95INCFLAGS:
5303 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5307 The command line used to compile a Fortran 95 source file to an object file
5308 after first running the file through the C preprocessor.
5309 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5310 are included on this command line.
5311 You only need to set $F95PPCOM if you need to use a specific
5312 C-preprocessor command line for Fortran 95 files.
5313 You should normally set the $FORTRANPPCOM variable,
5314 which specifies the default C-preprocessor command line
5315 for all Fortran versions.
5318 The default Fortran compiler
5319 for all versions of Fortran.
5322 The command line used to compile a Fortran source file to an object file.
5323 By default, any options specified
5324 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5325 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5326 are included on this command line.
5329 The string displayed when a Fortran source file
5330 is compiled to an object file.
5331 If this is not set, then $FORTRANCOM
5332 (the command line) is displayed.
5335 General user-specified options that are passed to the Fortran compiler.
5336 Note that this variable does
5340 (or similar) include or module search path options
5341 that scons generates automatically from $FORTRANPATH.
5343 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5345 for the variables that expand those options.
5347 .IP _FORTRANINCFLAGS
5348 An automatically-generated construction variable
5349 containing the Fortran compiler command-line options
5350 for specifying directories to be searched for include
5351 files and module files.
5352 The value of $_FORTRANINCFLAGS is created
5353 by prepending/appending $INCPREFIX and $INCSUFFIX
5354 to the beginning and end
5355 of each directory in $FORTRANPATH.
5358 Directory location where the Fortran compiler should place
5359 any module files it generates. This variable is empty, by default. Some
5360 Fortran compilers will internally append this directory in the search path
5361 for module files, as well
5363 .IP FORTRANMODDIRPREFIX
5364 The prefix used to specify a module directory on the Fortran compiler command
5366 This will be appended to the beginning of the directory
5367 in the $FORTRANMODDIR construction variables
5368 when the $_FORTRANMODFLAG variables is automatically generated.
5370 .IP FORTRANMODDIRSUFFIX
5371 The suffix used to specify a module directory on the Fortran compiler command
5373 This will be appended to the beginning of the directory
5374 in the $FORTRANMODDIR construction variables
5375 when the $_FORTRANMODFLAG variables is automatically generated.
5378 An automatically-generated construction variable
5379 containing the Fortran compiler command-line option
5380 for specifying the directory location where the Fortran
5381 compiler should place any module files that happen to get
5382 generated during compilation.
5383 The value of $_FORTRANMODFLAG is created
5384 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5385 to the beginning and end of the directory in $FORTRANMODDIR.
5387 .IP FORTRANMODPREFIX
5388 The module file prefix used by the Fortran compiler. SCons assumes that
5389 the Fortran compiler follows the quasi-standard naming convention for
5391 .I <module_name>.mod.
5392 As a result, this variable is left empty, by default. For situations in
5393 which the compiler does not necessarily follow the normal convention,
5394 the user may use this variable. Its value will be appended to every
5395 module file name as scons attempts to resolve dependencies.
5397 .IP FORTRANMODSUFFIX
5398 The module file suffix used by the Fortran compiler. SCons assumes that
5399 the Fortran compiler follows the quasi-standard naming convention for
5401 .I <module_name>.mod.
5402 As a result, this variable is set to ".mod", by default. For situations
5403 in which the compiler does not necessarily follow the normal convention,
5404 the user may use this variable. Its value will be appended to every
5405 module file name as scons attempts to resolve dependencies.
5408 The list of directories that the Fortran compiler will search for
5409 include files and (for some compilers) module files. The Fortran implicit
5410 dependency scanner will search these directories for include files (but
5411 not module files since they are autogenerated and, as such, may not
5412 actually exist at the time the scan takes place). Don't explicitly put
5413 include directory arguments in FORTRANFLAGS because the result will be
5414 non-portable and the directories will not be searched by the dependency
5415 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5416 to the SConscript directory when they are used in a command. To force
5418 to look-up a directory relative to the root of the source tree use #:
5421 env = Environment(FORTRANPATH='#/include')
5425 The directory look-up can also be forced using the
5430 include = Dir('include')
5431 env = Environment(FORTRANPATH=include)
5435 The directory list will be added to command lines
5436 through the automatically-generated
5438 construction variable,
5439 which is constructed by
5440 appending the values of the
5441 $INCPREFIX and $INCSUFFIX
5442 construction variables
5443 to the beginning and end
5444 of each directory in $FORTRANPATH.
5445 Any command lines you define that need
5446 the FORTRANPATH directory list should
5447 include $_FORTRANINCFLAGS:
5450 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5454 The command line used to compile a Fortran source file to an object file
5455 after first running the file through the C preprocessor.
5456 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5457 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5458 construction variables are included on this command line.
5461 The list of suffixes of files that will be scanned
5462 for Fortran implicit dependencies
5463 (INCLUDE lines & USE statements).
5464 The default list is:
5467 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5468 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5472 A function that converts a file name into a File instance relative to the
5476 The Ghostscript program used to convert PostScript to PDF files.
5479 General options passed to the Ghostscript program
5480 when converting PostScript to PDF files.
5483 The Ghostscript command line used to convert PostScript to PDF files.
5486 The string displayed when
5487 Ghostscript is used to convert
5488 a PostScript file to a PDF file.
5489 If this is not set, then $GSCOM (the command line) is displayed.
5492 The list of suffixes of files that will be scanned
5493 for IDL implicit dependencies
5494 (#include or import lines).
5495 The default list is:
5502 The prefix used to specify an include directory on the C compiler command
5504 This will be appended to the beginning of each directory
5505 in the $CPPPATH and $FORTRANPATH construction variables
5506 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5507 variables are automatically generated.
5510 The suffix used to specify an include directory on the C compiler command
5512 This will be appended to the end of each directory
5513 in the $CPPPATH and $FORTRANPATH construction variables
5514 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5515 variables are automatically generated.
5518 A function to be called to install a file into a
5519 destination file name.
5520 The default function copies the file into the destination
5521 (and sets the destination file's mode and permission bits
5522 to match the source file's).
5523 The function takes the following arguments:
5526 def install(dest, source, env):
5530 is the path name of the destination file.
5532 is the path name of the source file.
5534 is the construction environment
5535 (a dictionary of construction values)
5536 in force for this file installation.
5538 .IP INTEL_C_COMPILER_VERSION
5539 Set by the "intelc" Tool
5540 to the major version number of the Intel C compiler
5544 The Java archive tool.
5547 The directory to which the Java archive tool should change
5553 The command line used to call the Java archive tool.
5556 The string displayed when the Java archive tool
5558 If this is not set, then $JARCOM (the command line) is displayed.
5561 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5565 General options passed to the Java archive tool.
5566 By default this is set to
5568 to create the necessary
5573 The suffix for Java archives:
5581 The command line used to compile a directory tree containing
5582 Java source files to
5583 corresponding Java class files.
5584 Any options specified in the $JAVACFLAGS construction variable
5585 are included on this command line.
5588 The string displayed when compiling
5589 a directory tree of Java source files to
5590 corresponding Java class files.
5591 If this is not set, then $JAVACCOM (the command line) is displayed.
5594 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5598 General options that are passed to the Java compiler.
5601 The directory in which Java class files may be found.
5602 This is stripped from the beginning of any Java .class
5603 file names supplied to the
5608 The suffix for Java class files;
5613 The Java generator for C header and stub files.
5616 The command line used to generate C header and stub files
5618 Any options specified in the $JAVAHFLAGS construction variable
5619 are included on this command line.
5622 The string displayed when C header and stub files
5623 are generated from Java classes.
5624 If this is not set, then $JAVAHCOM (the command line) is displayed.
5627 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5631 General options passed to the C header and stub file generator
5635 The suffix for Java files;
5640 The LaTeX structured formatter and typesetter.
5643 The command line used to call the LaTeX structured formatter and typesetter.
5646 The string displayed when calling
5647 the LaTeX structured formatter and typesetter.
5648 If this is not set, then $LATEXCOM (the command line) is displayed.
5651 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5655 General options passed to the LaTeX structured formatter and typesetter.
5658 The lexical analyzer generator.
5661 General options passed to the lexical analyzer generator.
5664 The command line used to call the lexical analyzer generator
5665 to generate a source file.
5668 The string displayed when generating a source file
5669 using the lexical analyzer generator.
5670 If this is not set, then $LEXCOM (the command line) is displayed.
5673 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5677 An automatically-generated construction variable
5678 containing the linker command-line options
5679 for specifying directories to be searched for library.
5680 The value of $_LIBDIRFLAGS is created
5681 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5682 to the beginning and end
5683 of each directory in $LIBPATH.
5686 The prefix used to specify a library directory on the linker command line.
5687 This will be appended to the beginning of each directory
5688 in the $LIBPATH construction variable
5689 when the $_LIBDIRFLAGS variable is automatically generated.
5692 The suffix used to specify a library directory on the linker command line.
5693 This will be appended to the end of each directory
5694 in the $LIBPATH construction variable
5695 when the $_LIBDIRFLAGS variable is automatically generated.
5698 An automatically-generated construction variable
5699 containing the linker command-line options
5700 for specifying libraries to be linked with the resulting target.
5701 The value of $_LIBFLAGS is created
5702 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5703 to the beginning and end
5704 of each directory in $LIBS.
5707 The prefix used to specify a library to link on the linker command line.
5708 This will be appended to the beginning of each library
5709 in the $LIBS construction variable
5710 when the $_LIBFLAGS variable is automatically generated.
5713 The suffix used to specify a library to link on the linker command line.
5714 This will be appended to the end of each library
5715 in the $LIBS construction variable
5716 when the $_LIBFLAGS variable is automatically generated.
5719 The list of directories that will be searched for libraries.
5720 The implicit dependency scanner will search these
5721 directories for include files. Don't explicitly put include directory
5722 arguments in $LINKFLAGS or $SHLINKFLAGS
5723 because the result will be non-portable
5724 and the directories will not be searched by the dependency scanner. Note:
5725 directory names in LIBPATH will be looked-up relative to the SConscript
5726 directory when they are used in a command. To force
5728 to look-up a directory relative to the root of the source tree use #:
5731 env = Environment(LIBPATH='#/libs')
5735 The directory look-up can also be forced using the
5741 env = Environment(LIBPATH=libs)
5745 The directory list will be added to command lines
5746 through the automatically-generated
5748 construction variable,
5749 which is constructed by
5750 appending the values of the
5751 $LIBDIRPREFIX and $LIBDIRSUFFIX
5752 construction variables
5753 to the beginning and end
5754 of each directory in $LIBPATH.
5755 Any command lines you define that need
5756 the LIBPATH directory list should
5757 include $_LIBDIRFLAGS:
5760 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5764 The prefix used for (static) library file names.
5765 A default value is set for each platform
5766 (posix, win32, os2, etc.),
5767 but the value is overridden by individual tools
5768 (ar, mslib, sgiar, sunar, tlib, etc.)
5769 to reflect the names of the libraries they create.
5772 An array of legal prefixes for library file names.
5775 A list of one or more libraries
5776 that will be linked with
5777 any executable programs
5778 created by this environment.
5781 The library list will be added to command lines
5782 through the automatically-generated
5784 construction variable,
5785 which is constructed by
5786 appending the values of the
5787 $LIBLINKPREFIX and $LIBLINKSUFFIX
5788 construction variables
5789 to the beginning and end
5790 of each directory in $LIBS.
5791 Any command lines you define that need
5792 the LIBS library list should
5796 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
5800 The suffix used for (static) library file names.
5801 A default value is set for each platform
5802 (posix, win32, os2, etc.),
5803 but the value is overridden by individual tools
5804 (ar, mslib, sgiar, sunar, tlib, etc.)
5805 to reflect the names of the libraries they create.
5808 An array of legal suffixes for library file names.
5814 General user options passed to the linker.
5815 Note that this variable should
5819 (or similar) options for linking with the libraries listed in $LIBS,
5822 (or similar) library search path options
5823 that scons generates automatically from $LIBPATH.
5827 for the variable that expands to library-link options,
5831 for the variable that expands to library search path options.
5834 The command line used to link object files into an executable.
5837 The string displayed when object files
5838 are linked into an executable.
5839 If this is not set, then $LINKCOM (the command line) is displayed.
5842 env = Environment(LINKCOMSTR = "Linking $TARGET")
5846 The M4 macro preprocessor.
5849 General options passed to the M4 macro preprocessor.
5852 The command line used to pass files through the M4 macro preprocessor.
5855 The string displayed when
5856 a file is passed through the M4 macro preprocessor.
5857 If this is not set, then $M4COM (the command line) is displayed.
5860 The maximum number of characters allowed on an external command line.
5862 link lines longer than this many characters
5863 are linke via a temporary file name.
5866 When the Microsoft Visual Studio tools are initialized, they set up
5867 this dictionary with the following keys:
5870 the version of MSVS being used (can be set via
5874 the available versions of MSVS installed
5877 installed directory of Visual C++
5880 installed directory of Visual Studio
5883 installed directory of the .NET framework
5885 .B FRAMEWORKVERSIONS:
5886 list of installed versions of the .NET framework, sorted latest to oldest.
5888 .B FRAMEWORKVERSION:
5889 latest installed version of the .NET framework
5892 installed location of the .NET SDK.
5895 installed location of the Platform SDK.
5897 .B PLATFORMSDK_MODULES:
5898 dictionary of installed Platform SDK modules,
5899 where the dictionary keys are keywords for the various modules, and
5900 the values are 2-tuples where the first is the release date, and the
5901 second is the version number.
5903 If a value isn't set, it wasn't available in the registry.
5905 .IP MSVS_IGNORE_IDE_PATHS
5906 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
5907 instead of the settings from the IDE.
5909 For Visual Studio, SCons will (by default) automatically determine
5910 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
5911 set by the IDE. You can override this behavior by setting these
5912 variables after Environment initialization, or by setting
5913 .B MSVS_IGNORE_IDE_PATHS = 1
5914 in the Environment initialization.
5915 Specifying this will not leave these unset, but will set them to a
5916 minimal set of paths needed to run the tools successfully.
5919 For VS6, the mininimal set is:
5920 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
5921 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
5922 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
5924 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
5925 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
5926 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
5930 Where '<VSDir>' is the installed location of Visual Studio.
5932 .IP MSVS_USE_MFC_DIRS
5933 Tells the MS Visual Studio tool(s) to use
5934 the MFC directories in its default paths
5935 for compiling and linking.
5936 Under MSVS version 6,
5938 .B MSVS_USE_MFC_DIRS
5947 external environment variable,
5953 external environment variable.
5954 Under MSVS version 7,
5956 .B MSVS_USE_MFC_DIRS
5959 .B "atlmfc\\\\include"
5960 directory to the default
5962 external environment variable,
5965 directory to the default
5967 external environment variable.
5968 The current default value is
5970 which means these directories
5971 are added to the paths by default.
5972 This default value is likely to change
5973 in a future release,
5974 so users who want the ATL and MFC
5975 values included in their paths
5976 are encouraged to enable the
5977 .B MSVS_USE_MFC_DIRS
5979 to avoid future incompatibility.
5980 This variable has no effect if the
5984 environment variables are set explictly.
5987 Sets the preferred version of MSVS to use.
5989 SCons will (by default) select the latest version of MSVS
5990 installed on your machine. So, if you have version 6 and version 7
5991 (MSVS .NET) installed, it will prefer version 7. You can override this by
5994 variable in the Environment initialization, setting it to the
5995 appropriate version ('6.0' or '7.0', for example).
5996 If the given version isn't installed, tool initialization will fail.
5999 The action used to generate Microsoft Visual Studio
6000 project and solution files.
6002 .IP MSVSPROJECTSUFFIX
6003 The suffix used for Microsoft Visual Studio project (DSP) files.
6004 The default value is
6006 when using Visual Studio version 7.x (.NET),
6009 when using earlier versions of Visual Studio.
6011 .IP MSVSSOLUTIONSUFFIX
6012 The suffix used for Microsoft Visual Studio solution (DSW) files.
6013 The default value is
6015 when using Visual Studio version 7.x (.NET),
6018 when using earlier versions of Visual Studio.
6021 The version number of the MetroWerks CodeWarrior C compiler
6025 A list of installed versions of the MetroWerks CodeWarrior C compiler
6029 When set to non-zero,
6030 suppresses creation of a corresponding Win32 static import lib by the
6032 builder when used with
6033 MinGW or Microsoft Visual Studio.
6034 This also suppresses creation
6035 of an export (.exp) file
6036 when using Microsoft Visual Studio.
6039 The prefix used for (static) object file names.
6042 The suffix used for (static) object file names.
6045 The Perforce executable.
6048 The command line used to
6049 fetch source files from Perforce.
6052 The string displayed when
6053 fetching a source file from Perforce.
6054 If this is not set, then $P4COM (the command line) is displayed.
6057 General options that are passed to Perforce.
6060 The Microsoft Visual C++ precompiled header that will be used when compiling
6061 object files. This variable is ignored by tools other than Microsoft Visual C++.
6062 When this variable is
6063 defined SCons will add options to the compiler command line to
6064 cause it to use the precompiled header, and will also set up the
6065 dependencies for the PCH file. Example:
6068 env['PCH'] = 'StdAfx.pch'
6072 The command line used by the
6074 builder to generated a precompiled header.
6077 The string displayed when generating a precompiled header.
6078 If this is not set, then $PCHCOM (the command line) is displayed.
6081 This variable specifies how much of a source file is precompiled. This
6082 variable is ignored by tools other than Microsoft Visual C++, or when
6083 the PCH variable is not being used. When this variable is define it
6084 must be a string that is the name of the header that
6085 is included at the end of the precompiled portion of the source files, or
6086 the empty string if the "#pragma hrdstop" construct is being used:
6089 env['PCHSTOP'] = 'StdAfx.h'
6093 The Microsoft Visual C++ PDB file that will store debugging information for
6094 object files, shared libraries, and programs. This variable is ignored by
6095 tools other than Microsoft Visual C++.
6096 When this variable is
6097 defined SCons will add options to the compiler and linker command line to
6098 cause them to generate external debugging information, and will also set up the
6099 dependencies for the PDB file. Example:
6102 env['PDB'] = 'hello.pdb'
6106 A deprecated synonym for $DVIPDFCOM.
6109 The prefix used for PDF file names.
6112 The suffix used for PDF file names.
6115 The name of the platform used to create the Environment. If no platform is
6116 specified when the Environment is created,
6118 autodetects the platform.
6121 env = Environment(tools = [])
6122 if env['PLATFORM'] == 'cygwin':
6128 .IP PRINT_CMD_LINE_FUNC
6129 A Python function used to print the command lines as they are executed
6130 (assuming command printing is not disabled by the
6134 options or their equivalents).
6135 The function should take four arguments:
6137 the command being executed (a string),
6139 the target being built (file node, list, or string name(s)),
6141 the source(s) used (file node, list, or string name(s)), and
6143 the environment being used.
6145 The function must do the printing itself. The default implementation,
6146 used if this variable is not set or is None, is:
6148 def print_cmd_line(s, target, source, env):
6149 sys.stdout.write(s + "\n")
6152 Here's an example of a more interesting function:
6154 def print_cmd_line(s, target, source, env):
6155 sys.stdout.write("Building %s -> %s...\n" %
6156 (' and '.join([str(x) for x in source]),
6157 ' and '.join([str(x) for x in target])))
6158 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6159 env.Program('foo', 'foo.c')
6162 This just prints "Building <targetname> from <sourcename>..." instead
6163 of the actual commands.
6164 Such a function could also log the actual commands to a log file,
6168 The prefix used for executable file names.
6171 The suffix used for executable file names.
6174 The command line used to convert TeX DVI files into a PostScript file.
6177 The string displayed when a TeX DVI file
6178 is converted into a PostScript file.
6179 If this is not set, then $PSCOM (the command line) is displayed.
6182 The prefix used for PostScript file names.
6185 The prefix used for PostScript file names.
6188 The qt tool tries to take this from os.environ.
6189 It also initializes all QT_*
6190 construction variables listed below.
6191 (Note that all paths are constructed
6192 with python's os.path.join() method,
6193 but are listed here with the '/' separator
6194 for easier reading.)
6195 In addition, the construction environment
6196 variables CPPPATH, LIBPATH and LIBS may be modified
6198 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6199 are modified. Because the build-performance is affected when using this tool,
6200 you have to explicitly specify it at Environment creation:
6203 Environment(tools=['default','qt'])
6206 The qt tool supports the following operations:
6208 .B Automatic moc file generation from header files.
6209 You do not have to specify moc files explicitly, the tool does it for you.
6210 However, there are a few preconditions to do so: Your header file must have
6211 the same filebase as your implementation file and must stay in the same
6212 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6213 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6214 See also the corresponding builder method
6217 .B Automatic moc file generation from cxx files.
6218 As stated in the qt documentation, include the moc file at the end of
6219 the cxx file. Note that you have to include the file, which is generated
6220 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6221 <basename>.moc. A warning is generated after building the moc file, if you
6222 do not include the correct file. If you are using BuildDir, you may
6223 need to specify duplicate=1. You can turn off automatic moc file generation
6224 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6227 .B Automatic handling of .ui files.
6228 The implementation files generated from .ui files are handled much the same
6229 as yacc or lex files. Each .ui file given as a source of Program, Library or
6230 SharedLibrary will generate three files, the declaration file, the
6231 implementation file and a moc file. Because there are also generated headers,
6232 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6236 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6237 specify files to run moc on.
6240 The path where the qt binaries are installed.
6241 The default value is '$QTDIR/bin'.
6244 The path where the qt header files are installed.
6245 The default value is '$QTDIR/include'.
6246 Note: If you set this variable to None, the tool won't change the CPPPATH
6247 construction variable.
6250 Prints lots of debugging information while scanning for moc files.
6253 The path where the qt libraries are installed.
6254 The default value is '$QTDIR/lib'.
6255 Note: If you set this variable to None, the tool won't change the LIBPATH
6256 construction variable.
6259 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6260 this variable to None, the tool won't change the LIBS variable.
6263 Default value is '$QT_BINPATH/moc'.
6266 Default value is ''. Prefix for moc output files, when source is a cxx file.
6269 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6272 .IP QT_MOCFROMCPPFLAGS
6273 Default value is '-i'. These flags are passed to moc, when moccing a
6276 .IP QT_MOCFROMCXXCOM
6277 Command to generate a moc file from a cpp file.
6279 .IP QT_MOCFROMCXXCOMSTR
6280 The string displayed when generating a moc file from a cpp file.
6281 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6284 Command to generate a moc file from a header.
6286 .IP QT_MOCFROMHCOMSTR
6287 The string displayed when generating a moc file from a cpp file.
6288 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6290 .IP QT_MOCFROMHFLAGS
6291 Default value is ''. These flags are passed to moc, when moccing a header
6295 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6298 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6302 Default value is '$QT_BINPATH/uic'.
6305 Command to generate header files from .ui files.
6308 The string displayed when generating header files from .ui files.
6309 If this is not set, then $QT_UICCOM (the command line) is displayed.
6312 Default value is ''. These flags are passed to uic, when creating a a h
6313 file from a .ui file.
6315 .IP QT_UICDECLPREFIX
6316 Default value is ''. Prefix for uic generated header files.
6318 .IP QT_UICDECLSUFFIX
6319 Default value is '.h'. Suffix for uic generated header files.
6322 Default value is ''. These flags are passed to uic, when creating a cxx
6323 file from a .ui file.
6325 .IP QT_UICIMPLPREFIX
6326 Default value is 'uic_'. Prefix for uic generated implementation files.
6328 .IP QT_UICIMPLSUFFIX
6329 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6333 Default value is '.ui'. Suffix of designer input files.
6336 The archive indexer.
6339 General options passed to the archive indexer.
6342 The resource compiler used by the RES builder.
6345 The command line used by the RES builder.
6348 The string displayed when invoking the resource compiler.
6349 If this is not set, then $RCCOM (the command line) is displayed.
6352 The flags passed to the resource compiler by the RES builder.
6356 Note that this variable is not actually used
6357 for the command to fetch source files from RCS;
6360 construction variable, below.
6363 The RCS "checkout" executable,
6364 used to fetch source files from RCS.
6367 The command line used to
6368 fetch (checkout) source files from RCS.
6371 The string displayed when fetching
6372 a source file from RCS.
6373 If this is not set, then $RCS_COCOM
6374 (the command line) is displayed.
6377 Options that are passed to the $RCS_CO command.
6380 The program used to register DLLs on Windows systems.
6383 The command line used to register a newly-built DLL file
6385 Invoked when the "register=1"
6386 keyword argument is passed to the
6391 The string displayed when registering a newly-built DLL file.
6392 If this is not set, then $REGSVRCOM (the command line) is displayed.
6395 A function that converts a file name into a list of Dir instances by
6396 searching the repositories.
6399 The Java RMI stub compiler.
6402 The command line used to compile stub
6403 and skeleton class files
6404 from Java classes that contain RMI implementations.
6405 Any options specified in the $RMICFLAGS construction variable
6406 are included on this command line.
6409 The string displayed when compiling
6410 stub and skeleton class files
6411 from Java classes that contain RMI implementations.
6412 If this is not set, then $RMICCOM (the command line) is displayed.
6415 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6419 General options passed to the Java RMI stub compiler.
6422 The RPC protocol compiler.
6424 .IP RPCGENCLIENTFLAGS
6425 Options passed to the RPC protocol compiler
6426 when generating client side stubs.
6427 These are in addition to any flags specified in the
6429 construction variable.
6432 General options passed to the RPC protocol compiler.
6434 .IP RPCGENHEADERFLAGS
6435 Options passed to the RPC protocol compiler
6436 when generating a header file.
6437 These are in addition to any flags specified in the
6439 construction variable.
6441 .IP RPCGENSERVICEFLAGS
6442 Options passed to the RPC protocol compiler
6443 when generating server side stubs.
6444 These are in addition to any flags specified in the
6446 construction variable.
6449 Options passed to the RPC protocol compiler
6450 when generating XDR routines.
6451 These are in addition to any flags specified in the
6453 construction variable.
6456 A list of paths to search for shared libraries when running programs.
6457 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6458 Ignored on platforms and toolchains that don't support it.
6459 Note that the paths added to RPATH
6460 are not transformed by
6462 in any way: if you want an absolute
6463 path, you must make it absolute yourself.
6466 A list of the available implicit dependency scanners.
6467 New file scanners may be added by
6468 appending to this list,
6469 although the more flexible approach
6470 is to associate scanners
6471 with a specific Builder.
6472 See the sections "Builder Objects"
6473 and "Scanner Objects,"
6474 below, for more information.
6477 The SCCS executable.
6480 The command line used to
6481 fetch source files from SCCS.
6484 The string displayed when fetching
6485 a source file from a CVS repository.
6486 If this is not set, then $SCCSCOM
6487 (the command line) is displayed.
6490 General options that are passed to SCCS.
6493 Options that are passed specifically to the SCCS "get" subcommand.
6494 This can be set, for example, to
6496 to check out editable files from SCCS.
6499 The C compiler used for generating shared-library objects.
6502 The command line used to compile a C source file
6503 to a shared-library object file.
6504 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6505 are included on this command line.
6508 The string displayed when a C source file
6509 is compiled to a shared object file.
6510 If this is not set, then $SHCCCOM (the command line) is displayed.
6513 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6517 Options that are passed to the C compiler
6518 to generate shared-library objects.
6521 The C++ compiler used for generating shared-library objects.
6524 The command line used to compile a C++ source file
6525 to a shared-library object file.
6526 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6527 are included on this command line.
6530 The string displayed when a C++ source file
6531 is compiled to a shared object file.
6532 If this is not set, then $SHCXXCOM (the command line) is displayed.
6535 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6539 Options that are passed to the C++ compiler
6540 to generate shared-library objects.
6543 A string naming the shell program that will be passed to the
6548 construction variable for more information.
6551 The Fortran 77 compiler used for generating shared-library objects.
6552 You should normally set the $SHFORTRANC variable,
6553 which specifies the default Fortran compiler
6554 for all Fortran versions.
6555 You only need to set $SHF77 if you need to use a specific compiler
6556 or compiler version for Fortran 77 files.
6559 The command line used to compile a Fortran 77 source file
6560 to a shared-library object file.
6561 You only need to set $SHF77COM if you need to use a specific
6562 command line for Fortran 77 files.
6563 You should normally set the $SHFORTRANCOM variable,
6564 which specifies the default command line
6565 for all Fortran versions.
6568 The string displayed when a Fortran 77 source file
6569 is compiled to a shared-library object file.
6570 If this is not set, then $SHF77COM or $SHFORTRANCOM
6571 (the command line) is displayed.
6574 Options that are passed to the Fortran 77 compiler
6575 to generated shared-library objects.
6576 You only need to set $SHF77FLAGS if you need to define specific
6577 user options for Fortran 77 files.
6578 You should normally set the $SHFORTRANFLAGS variable,
6579 which specifies the user-specified options
6580 passed to the default Fortran compiler
6581 for all Fortran versions.
6584 The command line used to compile a Fortran 77 source file to a
6585 shared-library object file
6586 after first running the file through the C preprocessor.
6587 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6588 are included on this command line.
6589 You only need to set $SHF77PPCOM if you need to use a specific
6590 C-preprocessor command line for Fortran 77 files.
6591 You should normally set the $SHFORTRANPPCOM variable,
6592 which specifies the default C-preprocessor command line
6593 for all Fortran versions.
6596 The Fortran 90 compiler used for generating shared-library objects.
6597 You should normally set the $SHFORTRANC variable,
6598 which specifies the default Fortran compiler
6599 for all Fortran versions.
6600 You only need to set $SHF90 if you need to use a specific compiler
6601 or compiler version for Fortran 90 files.
6604 The command line used to compile a Fortran 90 source file
6605 to a shared-library object file.
6606 You only need to set $SHF90COM if you need to use a specific
6607 command line for Fortran 90 files.
6608 You should normally set the $SHFORTRANCOM variable,
6609 which specifies the default command line
6610 for all Fortran versions.
6613 The string displayed when a Fortran 90 source file
6614 is compiled to a shared-library object file.
6615 If this is not set, then $SHF90COM or $SHFORTRANCOM
6616 (the command line) is displayed.
6619 Options that are passed to the Fortran 90 compiler
6620 to generated shared-library objects.
6621 You only need to set $SHF90FLAGS if you need to define specific
6622 user options for Fortran 90 files.
6623 You should normally set the $SHFORTRANFLAGS variable,
6624 which specifies the user-specified options
6625 passed to the default Fortran compiler
6626 for all Fortran versions.
6629 The command line used to compile a Fortran 90 source file to a
6630 shared-library object file
6631 after first running the file through the C preprocessor.
6632 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6633 are included on this command line.
6634 You only need to set $SHF90PPCOM if you need to use a specific
6635 C-preprocessor command line for Fortran 90 files.
6636 You should normally set the $SHFORTRANPPCOM variable,
6637 which specifies the default C-preprocessor command line
6638 for all Fortran versions.
6641 The Fortran 95 compiler used for generating shared-library objects.
6642 You should normally set the $SHFORTRANC variable,
6643 which specifies the default Fortran compiler
6644 for all Fortran versions.
6645 You only need to set $SHF95 if you need to use a specific compiler
6646 or compiler version for Fortran 95 files.
6649 The command line used to compile a Fortran 95 source file
6650 to a shared-library object file.
6651 You only need to set $SHF95COM if you need to use a specific
6652 command line for Fortran 95 files.
6653 You should normally set the $SHFORTRANCOM variable,
6654 which specifies the default command line
6655 for all Fortran versions.
6658 The string displayed when a Fortran 95 source file
6659 is compiled to a shared-library object file.
6660 If this is not set, then $SHF95COM or $SHFORTRANCOM
6661 (the command line) is displayed.
6664 Options that are passed to the Fortran 95 compiler
6665 to generated shared-library objects.
6666 You only need to set $SHF95FLAGS if you need to define specific
6667 user options for Fortran 95 files.
6668 You should normally set the $SHFORTRANFLAGS variable,
6669 which specifies the user-specified options
6670 passed to the default Fortran compiler
6671 for all Fortran versions.
6674 The command line used to compile a Fortran 95 source file to a
6675 shared-library object file
6676 after first running the file through the C preprocessor.
6677 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6678 are included on this command line.
6679 You only need to set $SHF95PPCOM if you need to use a specific
6680 C-preprocessor command line for Fortran 95 files.
6681 You should normally set the $SHFORTRANPPCOM variable,
6682 which specifies the default C-preprocessor command line
6683 for all Fortran versions.
6686 The default Fortran compiler used for generating shared-library objects.
6689 The command line used to compile a Fortran source file
6690 to a shared-library object file.
6693 The string displayed when a Fortran source file
6694 is compiled to a shared-library object file.
6695 If this is not set, then $SHFORTRANCOM
6696 (the command line) is displayed.
6699 Options that are passed to the Fortran compiler
6700 to generate shared-library objects.
6703 The command line used to compile a Fortran source file to a
6704 shared-library object file
6705 after first running the file through the C preprocessor.
6706 Any options specified
6707 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6708 are included on this command line.
6711 The prefix used for shared library file names.
6714 The suffix used for shared library file names.
6717 The linker for programs that use shared libraries.
6720 The command line used to link programs using shared libaries.
6723 The string displayed when programs using shared libraries are linked.
6724 If this is not set, then $SHLINKCOM (the command line) is displayed.
6727 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6731 General user options passed to the linker for programs using shared libraries.
6732 Note that this variable should
6736 (or similar) options for linking with the libraries listed in $LIBS,
6739 (or similar) include search path options
6740 that scons generates automatically from $LIBPATH.
6744 for the variable that expands to library-link options,
6748 for the variable that expands to library search path options.
6751 The prefix used for shared object file names.
6754 The suffix used for shared object file names.
6757 A reserved variable name
6758 that may not be set or used in a construction environment.
6759 (See "Variable Substitution," below.)
6762 A reserved variable name
6763 that may not be set or used in a construction environment.
6764 (See "Variable Substitution," below.)
6767 A command interpreter function that will be called to execute command line
6768 strings. The function must expect the following arguments:
6771 def spawn(shell, escape, cmd, args, env):
6775 is a string naming the shell program to use.
6777 is a function that can be called to escape shell special characters in
6780 is the path to the command to be executed.
6782 is the arguments to the command.
6784 is a dictionary of the environment variables
6785 in which the command should be executed.
6788 '\"The Subversion executable (usually named
6792 '\"The command line used to
6793 '\"fetch source files from a Subversion repository.
6796 '\"General options that are passed to Subversion.
6799 The scripting language wrapper and interface generator.
6802 The suffix that will be used for intermediate C
6803 source files generated by
6804 the scripting language wrapper and interface generator.
6805 The default value is
6806 .BR _wrap$CFILESUFFIX .
6807 By default, this value is used whenever the
6811 specified as part of the
6813 construction variable.
6816 The command line used to call
6817 the scripting language wrapper and interface generator.
6820 The string displayed when calling
6821 the scripting language wrapper and interface generator.
6822 If this is not set, then $SWIGCOM (the command line) is displayed.
6824 .IP SWIGCXXFILESUFFIX
6825 The suffix that will be used for intermediate C++
6826 source files generated by
6827 the scripting language wrapper and interface generator.
6828 The default value is
6829 .BR _wrap$CFILESUFFIX .
6830 By default, this value is used whenever the
6832 option is specified as part of the
6834 construction variable.
6837 General options passed to
6838 the scripting language wrapper and interface generator.
6839 This is where you should set
6843 or whatever other options you want to specify to SWIG.
6846 option in this variable,
6849 generate a C++ intermediate source file
6850 with the extension that is specified as the
6858 The command line used to call the tar archiver.
6861 The string displayed when archiving files
6862 using the tar archiver.
6863 If this is not set, then $TARCOM (the command line) is displayed.
6866 env = Environment(TARCOMSTR = "Archiving $TARGET")
6870 General options passed to the tar archiver.
6873 A reserved variable name
6874 that may not be set or used in a construction environment.
6875 (See "Variable Substitution," below.)
6878 A reserved variable name
6879 that may not be set or used in a construction environment.
6880 (See "Variable Substitution," below.)
6883 The suffix used for tar file names.
6886 The TeX formatter and typesetter.
6889 The command line used to call the TeX formatter and typesetter.
6892 The string displayed when calling
6893 the TeX formatter and typesetter.
6894 If this is not set, then $TEXCOM (the command line) is displayed.
6897 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
6901 General options passed to the TeX formatter and typesetter.
6904 A list of the names of the Tool specifications
6905 that are part of this construction environment.
6907 .IP WIN32_INSERT_DEF
6908 When this is set to true,
6909 a library build of a WIN32 shared library (.dll file)
6910 will also build a corresponding .def file at the same time,
6911 if a .def file is not already listed as a build target.
6912 The default is 0 (do not build a .def file).
6915 The prefix used for WIN32 .def file names.
6918 The suffix used for WIN32 .def file names.
6921 The parser generator.
6924 The command line used to call the parser generator
6925 to generate a source file.
6928 The string displayed when generating a source file
6929 using the parser generator.
6930 If this is not set, then $YACCCOM (the command line) is displayed.
6933 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
6937 General options passed to the parser generator.
6938 If $YACCFLAGS contains a \-d option,
6939 SCons assumes that the call will also create a .h file
6940 (if the yacc source file ends in a .y suffix)
6942 (if the yacc source file ends in a .yy suffix)
6945 The zip compression and file packaging utility.
6948 The command line used to call the zip utility,
6949 or the internal Python function used to create a
6953 The string displayed when archiving files
6954 using the zip utility.
6955 If this is not set, then $ZIPCOM
6956 (the command line or internal Python function) is displayed.
6959 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
6968 module used by the internal Python function
6969 to control whether the zip archive
6970 is compressed or not.
6971 The default value is
6972 .BR zipfile.ZIP_DEFLATED ,
6973 which creates a compressed zip archive.
6974 This value has no effect when using Python 1.5.2
6977 module is otherwise unavailable.
6980 General options passed to the zip utility.
6983 Construction variables can be retrieved and set using the
6985 method of the construction environment:
6988 dict = env.Dictionary()
6992 or using the [] operator:
6998 Construction variables can also be passed to the construction environment
7002 env = Environment(CC="cc")
7005 or when copying a construction environment using the
7010 env2 = env.Copy(CC="cl.exe")
7013 .SS Configure Contexts
7017 .I configure contexts,
7018 an integrated mechanism similar to the
7019 various AC_CHECK macros in GNU autoconf
7020 for testing for the existence of C header
7021 files, libraries, etc.
7022 In contrast to autoconf,
7024 does not maintain an explicit cache of the tested values,
7025 but uses its normal dependency tracking to keep the checked values
7026 up to date. However, users may override this behaviour with the
7028 command line option.
7030 The following methods can be used to perform checks:
7033 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7035 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7036 This creates a configure context, which can be used to perform checks.
7038 specifies the environment for building the tests.
7039 This environment may be modified when performing checks.
7041 is a dictionary containing custom tests.
7042 See also the section about custom tests below.
7043 By default, no custom tests are added to the configure context.
7045 specifies a directory where the test cases are built.
7046 Note that this directory is not used for building
7048 The default value is the directory
7051 specifies a file which collects the output from commands
7052 that are executed to check for the existence of header files, libraries, etc.
7053 The default is the file #/config.log.
7054 If you are using the
7057 you may want to specify a subdirectory under your build directory.
7059 specifies a C header file where the results of tests
7060 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7061 The default is to not write a
7064 You can specify the same
7066 file in multiple calls to Configure,
7069 will concatenate all results in the specified file.
7071 uses its normal dependency checking
7072 to decide if it's necessary to rebuild
7076 This means that the file is not necessarily re-built each
7078 but is only rebuilt if its contents will have changed
7079 and some target that depends on the
7081 file is being built.
7086 instance has the following associated methods:
7089 .RI Configure.Finish( self )
7090 This method should be called after configuration is done.
7091 It returns the environment as modified
7092 by the configuration checks performed.
7093 After this method is called, no further checks can be performed
7094 with this configuration context.
7095 However, you can create a new
7097 context to perform additional checks.
7098 Only one context should be active at a time.
7100 The following Checks are predefined.
7101 (This list will likely grow larger as time
7102 goes by and developers contribute new useful tests.)
7105 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7108 is usable in the specified language.
7111 in which case the last item in the list
7112 is the header file to be checked,
7113 and the previous list items are
7116 lines should precede the
7117 header line being checked for.
7118 The optional argument
7121 a two character string, where the first character denotes the opening
7122 quote and the second character denotes the closing quote.
7123 By default, both characters are " (double quote).
7124 The optional argument
7130 and selects the compiler to be used for the check.
7131 Returns 1 on success and 0 on failure.
7134 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7135 This is a wrapper around
7136 .B Configure.CheckHeader
7139 is usable in the C language.
7142 in which case the last item in the list
7143 is the header file to be checked,
7144 and the previous list items are
7147 lines should precede the
7148 header line being checked for.
7149 The optional argument
7152 a two character string, where the first character denotes the opening
7153 quote and the second character denotes the closing quote (both default
7155 Returns 1 on success and 0 on failure.
7158 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7159 This is a wrapper around
7160 .B Configure.CheckHeader
7163 is usable in the C++ language.
7166 in which case the last item in the list
7167 is the header file to be checked,
7168 and the previous list items are
7171 lines should precede the
7172 header line being checked for.
7173 The optional argument
7176 a two character string, where the first character denotes the opening
7177 quote and the second character denotes the closing quote (both default
7179 Returns 1 on success and 0 on failure.
7182 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7183 Checks if the specified
7184 C or C++ function is available.
7186 is the name of the function to check for.
7189 argument is a string
7193 that will be compiled
7194 to check if the function exists;
7200 char function_name();
7208 and selects the compiler to be used for the check;
7212 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
7219 is 1 and the library provides the specified
7221 appends the library to the LIBS construction environment variable.
7223 may also be None (the default),
7226 is checked with the current LIBS variable,
7227 or a list of library names,
7228 in which case each library in the list
7235 you can link against the specified
7243 and selects the compiler to be used for the check;
7245 The default value for
7248 It is assumed, that the C-language is used.
7249 This method returns 1 on success and 0 on error.
7252 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7255 .RI Configure.CheckLib
7256 call, this call provides a more sophisticated way to check against libraries.
7259 specifies the library or a list of libraries to check.
7261 specifies a header to check for.
7264 in which case the last item in the list
7265 is the header file to be checked,
7266 and the previous list items are
7269 lines should precede the
7270 header line being checked for.
7272 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7274 can be any valid expression (with a trailing ';'). The default is 'main();'.
7276 specifies whether to add the library to the environment (only if the check
7277 succeeds). This method returns 1 on success and 0 on error.
7280 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7281 Checks for the existence of a type defined by
7284 specifies the typedef name to check for.
7286 is a string containing one or more
7288 lines that will be inserted into the program
7289 that will be run to test for the existence of the type.
7296 and selects the compiler to be used for the check;
7300 Example of a typical Configure usage:
7304 conf = Configure( env )
7305 if not conf.CheckCHeader( 'math.h' ):
7306 print 'We really need math.h!'
7308 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7309 # do stuff for qt - usage, e.g.
7310 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7315 You can define your own custom checks.
7316 in addition to the predefined checks.
7317 These are passed in a dictionary to the Configure function.
7318 This dictionary maps the names of the checks
7319 to user defined Python callables
7320 (either Python functions or class instances implementing the
7323 The first argument of the call is always a
7325 instance followed by the arguments,
7326 which must be supplied by the user of the check.
7327 These CheckContext instances define the following methods:
7330 .RI CheckContext.Message( self ", " text )
7332 Usually called before the check is started.
7334 will be displayed to the user, e.g. 'Checking for library X...'
7337 .RI CheckContext.Result( self, ", " res )
7339 Usually called after the check is done.
7341 can be either an integer or a string. In the former case, 'ok' (res != 0)
7342 or 'failed' (res == 0) is displayed to the user, in the latter case the
7343 given string is displayed.
7346 .RI CheckContext.TryCompile( self ", " text ", " extension )
7347 Checks if a file with the specified
7349 (e.g. '.c') containing
7351 can be compiled using the environment's
7353 builder. Returns 1 on success and 0 on failure.
7356 .RI CheckContext.TryLink( self ", " text ", " extension )
7357 Checks, if a file with the specified
7359 (e.g. '.c') containing
7361 can be compiled using the environment's
7363 builder. Returns 1 on success and 0 on failure.
7366 .RI CheckContext.TryRun( self ", " text ", " extension )
7367 Checks, if a file with the specified
7369 (e.g. '.c') containing
7371 can be compiled using the environment's
7373 builder. On success, the program is run. If the program
7374 executes successfully
7375 (that is, its return status is 0),
7380 is the standard output of the
7382 If the program fails execution
7383 (its return status is non-zero),
7384 then (0, '') is returned.
7387 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7388 Checks if the specified
7390 with an optional source file (contents
7397 may be anything which can be converted to a
7404 is the content of the target file.
7410 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7411 Low level implementation for testing specific builds;
7412 the methods above are based on this method.
7413 Given the Builder instance
7417 of a source file with optional
7419 this method returns 1 on success and 0 on failure. In addition,
7421 is set to the build target node, if the build was successful.
7424 Example for implementing and using custom tests:
7427 def CheckQt(context, qtdir):
7428 context.Message( 'Checking for qt ...' )
7429 lastLIBS = context.env['LIBS']
7430 lastLIBPATH = context.env['LIBPATH']
7431 lastCPPPATH= context.env['CPPPATH']
7432 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7433 ret = context.TryLink("""
7435 int main(int argc, char **argv) {
7436 QApplication qapp(argc, argv);
7441 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7442 context.Result( ret )
7446 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7447 if not conf.CheckQt('/usr/lib/qt'):
7448 print 'We really need qt!'
7453 .SS Construction Variable Options
7455 Often when building software, various options need to be specified at build
7456 time that are not known when the SConstruct/SConscript files are
7457 written. For example, libraries needed for the build may be in non-standard
7458 locations, or site-specific compiler options may need to be passed to the
7461 provides a mechanism for overridding construction variables from the
7462 command line or a text-based SConscript file through an Options
7463 object. To create an Options object, call the Options() function:
7466 .RI Options([ files "], [" args ])
7467 This creates an Options object that will read construction variables from
7468 the file or list of filenames specified in
7470 If no files are specified,
7475 then no files will be read.
7476 The optional argument
7479 values that will override anything read from the specified files;
7480 it is primarily intended to be passed the
7482 dictionary that holds variables
7483 specified on the command line.
7487 opts = Options('custom.py')
7488 opts = Options('overrides.py', ARGUMENTS)
7489 opts = Options(None, {FOO:'expansion', BAR:7})
7492 Options objects have the following methods:
7495 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7496 This adds a customizable construction variable to the Options object.
7498 is the name of the variable.
7500 is the help text for the variable.
7502 is the default value of the variable;
7503 if the default value is
7505 and there is no explicit value specified,
7506 the construction variable will
7508 be added to the construction environment.
7510 is called to validate the value of the variable, and should take three
7511 arguments: key, value, and environment
7513 is called to convert the value before putting it in the environment, and
7514 should take a single argument: value. Example:
7517 opts.Add('CC', 'The C compiler')
7521 .RI AddOptions( list )
7522 A wrapper script that adds
7523 multiple customizable construction variables
7524 to an Options object.
7526 is a list of tuple or list objects
7527 that contain the arguments
7528 for an individual call to the
7535 ('CC', 'The C compiler'),
7536 ('VALIDATE', 'An option for testing validation',
7537 'notset', validator, None),
7542 .RI Update( env ", [" args ])
7543 This updates a construction environment
7545 with the customized construction variables. Normally this method is not
7546 called directly, but is called indirectly by passing the Options object to
7547 the Environment() function:
7550 env = Environment(options=opts)
7554 .RI Save( filename ", " env )
7555 This saves the currently set options into a script file named
7557 that can be used on the next invocation to automatically load the current
7558 settings. This method combined with the Options method can be used to
7559 support caching of options between runs.
7563 opts = Options(['options.cache', 'custom.py'])
7566 opts.Save('options.cache', env)
7570 .RI GenerateHelpText( env ", [" sort ])
7571 This generates help text documenting the customizable construction
7572 variables suitable to passing in to the Help() function.
7574 is the construction environment that will be used to get the actual values
7575 of customizable variables. Calling with
7579 will cause the output to be sorted
7580 by the specified argument.
7584 should take two arguments
7587 (like the standard Python
7592 Help(opts.GenerateHelpText(env))
7593 Help(opts.GenerateHelpText(env, sort=cmp))
7596 The text based SConscript file is executed as a Python script, and the
7597 global variables are queried for customizable construction
7604 To make it more convenient to work with customizable Options,
7606 provides a number of functions
7607 that make it easy to set up
7608 various types of Options:
7611 .RI BoolOption( key ", " help ", " default )
7612 Return a tuple of arguments
7613 to set up a Boolean option.
7617 have a default value of
7619 and display the specified
7622 The option will interpret the values
7644 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7645 Return a tuple of arguments
7647 whose value may be one
7648 of a specified list of legal enumerated values.
7652 have a default value of
7654 and display the specified
7657 The option will only support those
7663 argument is a dictionary
7664 that can be used to convert
7665 input values into specific legal values
7674 then the values are case-sensitive.
7679 then values will be matched
7685 then values will be matched
7687 and all input values will be
7688 converted to lower case.
7691 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
7692 Return a tuple of arguments
7694 whose value may be one or more
7695 of a specified list of legal enumerated values.
7699 have a default value of
7701 and display the specified
7704 The option will only support the values
7707 or the values in the
7710 More than one value may be specified,
7711 with all values separated by commas.
7712 The default may be a string of
7713 comma-separated default values,
7714 or a list of the default values.
7717 argument is a dictionary
7718 that can be used to convert
7719 input values into specific legal values
7725 .RI PackageOption( key ", " help ", " default )
7726 Return a tuple of arguments
7728 whose value is a path name
7729 of a package that may be
7730 enabled, disabled or
7731 given an explicit path name.
7735 have a default value of
7737 and display the specified
7740 The option will support the values
7747 in which case the specified
7750 or the option may be set to an
7752 (typically the path name to a package
7753 that is being enabled).
7754 The option will also support the values
7760 to disable use of the specified option.
7763 .RI PathOption( key ", " help ", " default ", [" validator ])
7764 Return a tuple of arguments
7766 whose value is expected to be a path name.
7770 have a default value of
7772 and display the specified
7778 that will be called to
7779 verify that the specified path
7782 following ready-made validators:
7783 .BR PathOption.PathExists
7785 which verifies that the specified path exists;
7786 .BR PathOption.PathIsFile ,
7787 which verifies that the specified path is an existing file;
7788 .BR PathOption.PathIsDir ,
7789 which verifies that the specified path is an existing directory;
7791 .BR PathOption.PathIsDirCreate ,
7792 which verifies that the specified path is a directory,
7793 and will create the specified directory if the path exist.
7794 You may supply your own
7797 which must take three arguments
7799 the name of the options variable to be set;
7801 the specified value being checked;
7804 the construction environment)
7805 and should raise an exception
7806 if the specified value is not acceptable.
7809 These functions make it
7810 convenient to create a number
7811 of options with consistent behavior
7812 in a single call to the
7818 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7819 EnumOption('debug', 'debug output and symbols', 'no'
7820 allowed_values=('yes', 'no', 'full'),
7821 map={}, ignorecase=0), # case sensitive
7822 ListOption('shared',
7823 'libraries to build as shared libraries',
7825 names = list_of_libs),
7826 PackageOption('x11',
7827 'use X11 installed here (yes = search some places)',
7829 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7830 PathOption('foopath', 'where the foo library is installed', foopath,
7831 PathOption.PathIsDir),
7836 .SS File and Directory Nodes
7846 Nodes, respectively.
7847 python objects, respectively.
7848 Those objects have several user-visible attributes
7849 and methods that are often useful:
7855 This path is relative to the top-level directory
7859 The build path is the same as the source path if
7864 The absolute build path of the given file or directory.
7874 object representing the
7883 # Get the current build dir's path, relative to top.
7885 # Current dir's absolute path
7887 # Next line is always '.', because it is the top dir's path relative to itself.
7889 File('foo.c').srcnode().path # source path of the given source file.
7891 # Builders also return File objects:
7892 foo = env.Program('foo.c')
7893 print "foo will be built in %s"%foo.path
7899 can be extended to build different types of targets
7900 by adding new Builder objects
7901 to a construction environment.
7903 you should only need to add a new Builder object
7904 when you want to build a new type of file or other external target.
7905 If you just want to invoke a different compiler or other tool
7906 to build a Program, Object, Library, or any other
7907 type of output file for which
7909 already has an existing Builder,
7910 it is generally much easier to
7911 use those existing Builders
7912 in a construction environment
7913 that sets the appropriate construction variables
7916 Builder objects are created
7922 function accepts the following arguments:
7925 The command line string used to build the target from the source.
7928 a list of strings representing the command
7929 to be executed and its arguments
7930 (suitable for enclosing white space in an argument),
7932 mapping source file name suffixes to
7933 any combination of command line strings
7934 (if the builder should accept multiple source file extensions),
7937 (see the next section);
7938 or a list of any of the above.
7941 takes three arguments:
7943 - a list of source nodes,
7945 - a list of target nodes,
7947 - the construction environment.
7950 The prefix that will be prepended to the target file name.
7951 This may be specified as a:
7961 - a function or other callable that takes
7962 two arguments (a construction environment and a list of sources)
7963 and returns a prefix,
7968 - specifies a mapping from a specific source suffix (of the first
7969 source specified) to a corresponding target prefix. Both the source
7970 suffix and target prefix specifications may use environment variable
7971 substitution, and the target prefix (the 'value' entries in the
7972 dictionary) may also be a callable object. The default target prefix
7973 may be indicated by a dictionary entry with a key value of None.
7978 b = Builder("build_it < $SOURCE > $TARGET"
7981 def gen_prefix(env, sources):
7982 return "file-" + env['PLATFORM'] + '-'
7983 b = Builder("build_it < $SOURCE > $TARGET",
7984 prefix = gen_prefix)
7986 b = Builder("build_it < $SOURCE > $TARGET",
7987 suffix = { None: "file-",
7988 "$SRC_SFX_A": gen_prefix })
7992 The suffix that will be appended to the target file name.
7993 This may be specified in the same manner as the prefix above.
7994 If the suffix is a string, then
7996 will append a '.' to the beginning of the suffix if it's not already
7997 there. The string returned by callable object (or obtained from the
7998 dictionary) is untouched and must append its own '.' to the beginning
8002 b = Builder("build_it < $SOURCE > $TARGET"
8005 def gen_suffix(env, sources):
8006 return "." + env['PLATFORM'] + "-file"
8007 b = Builder("build_it < $SOURCE > $TARGET",
8008 suffix = gen_suffix)
8010 b = Builder("build_it < $SOURCE > $TARGET",
8011 suffix = { None: ".sfx1",
8012 "$SRC_SFX_A": gen_suffix })
8016 The expected source file name suffix. This may be a string or a list
8020 A Scanner object that
8021 will be invoked to find
8022 implicit dependencies for this target file.
8023 This keyword argument should be used
8024 for Scanner objects that find
8025 implicit dependencies
8026 based only on the target file
8027 and the construction environment,
8030 (See the section "Scanner Objects," below,
8031 for information about creating Scanner objects.)
8034 A Scanner object that
8036 find implicit dependences in
8038 used to build this target file.
8039 This is where you would
8040 specify a scanner to
8043 lines in source files.
8044 (See the section "Scanner Objects," below,
8045 for information about creating Scanner objects.)
8048 A factory function that the Builder will use
8049 to turn any targets specified as strings into SCons Nodes.
8051 SCons assumes that all targets are files.
8052 Other useful target_factory
8055 for when a Builder creates a directory target,
8058 for when a Builder can create either a file
8059 or directory target.
8064 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8066 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8067 env.MakeDirectory('new_directory', [])
8071 A factory function that the Builder will use
8072 to turn any sources specified as strings into SCons Nodes.
8074 SCons assumes that all source are files.
8075 Other useful source_factory
8078 for when a Builder uses a directory as a source,
8081 for when a Builder can use files
8082 or directories (or both) as sources.
8087 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8089 env.Append(BUILDERS = {'Collect':CollectBuilder})
8090 env.Collect('archive', ['directory_name', 'file_name'])
8094 A function or list of functions to manipulate the target and source
8095 lists before dependencies are established
8096 and the target(s) are actually built.
8098 can also be a string containing a construction variable to expand
8099 to an emitter function or list of functions,
8100 or a dictionary mapping source file suffixes
8101 to emitter functions.
8102 (Only the suffix of the first source file
8103 is used to select the actual emitter function
8104 from an emitter dictionary.)
8107 takes three arguments:
8109 - a list of source nodes,
8111 - a list of target nodes,
8113 - the construction environment.
8114 An emitter must return a tuple containing two lists,
8115 the list of targets to be built by this builder,
8116 and the list of sources for this builder.
8121 def e(target, source, env):
8122 return (target + ['foo.foo'], source + ['foo.src'])
8124 # Simple association of an emitter function with a Builder.
8125 b = Builder("my_build < $TARGET > $SOURCE",
8128 def e2(target, source, env):
8129 return (target + ['bar.foo'], source + ['bar.src'])
8131 # Simple association of a list of emitter functions with a Builder.
8132 b = Builder("my_build < $TARGET > $SOURCE",
8135 # Calling an emitter function through a construction variable.
8136 env = Environment(MY_EMITTER = e)
8137 b = Builder("my_build < $TARGET > $SOURCE",
8138 emitter = '$MY_EMITTER')
8140 # Calling a list of emitter functions through a construction variable.
8141 env = Environment(EMITTER_LIST = [e, e2])
8142 b = Builder("my_build < $TARGET > $SOURCE",
8143 emitter = '$EMITTER_LIST')
8145 # Associating multiple emitters with different file
8146 # suffixes using a dictionary.
8147 def e_suf1(target, source, env):
8148 return (target + ['another_target_file'], source)
8149 def e_suf2(target, source, env):
8150 return (target, source + ['another_source_file'])
8151 b = Builder("my_build < $TARGET > $SOURCE",
8152 emitter = {'.suf1' : e_suf1,
8160 arguments must not both be used for the same Builder.
8163 Specifies whether this builder is allowed to be called multiple times for
8164 the same target file(s). The default is 0, which means the builder
8165 can not be called multiple times for the same target file(s). Calling a
8166 builder multiple times for the same target simply adds additional source
8167 files to the target; it is not allowed to change the environment associated
8168 with the target, specify addition environment overrides, or associate a different
8169 builder with the target.
8172 A construction environment that can be used
8173 to fetch source code using this Builder.
8174 (Note that this environment is
8176 used for normal builds of normal target files,
8177 which use the environment that was
8178 used to call the Builder for the target file.)
8181 A function that returns a list of actions that will be executed to build
8182 the target(s) from the source(s).
8183 The returned action(s) may be
8184 an Action object, or anything that
8185 can be converted into an Action object
8186 (see the next section).
8188 The generator function
8189 takes four arguments:
8191 - a list of source nodes,
8193 - a list of target nodes,
8195 - the construction environment,
8197 - a Boolean value that specifies
8198 whether the generator is being called
8199 for generating a build signature
8200 (as opposed to actually executing the command).
8204 def g(source, target, env, for_signature):
8205 return [["gcc", "-c", "-o"] + target + source]
8207 b = Builder(generator=g)
8211 Specifies a builder to use when a source file name suffix does not match
8212 any of the suffixes of the builder. Using this argument produces a
8213 multi-stage builder.
8216 Specifies that this builder expects exactly one source file per call. Giving
8217 more than one source files without target files results in implicitely calling
8218 the builder multiple times (once for each source given). Giving multiple
8219 source files together with target files results in a UserError exception.
8227 arguments must not both be used for the same Builder.
8230 A construction environment that can be used
8231 to fetch source code using this Builder.
8232 (Note that this environment is
8234 used for normal builds of normal target files,
8235 which use the environment that was
8236 used to call the Builder for the target file.)
8239 b = Builder(action="build < $SOURCE > $TARGET")
8240 env = Environment(BUILDERS = {'MyBuild' : b})
8241 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8245 A directory from which scons
8252 a string or a directory Node,
8253 scons will change to the specified directory.
8256 is not a string or Node
8258 then scons will change to the
8259 target file's directory.
8261 Note that scons will
8263 automatically modify
8265 construction variables like
8269 when using the chdir
8270 keyword argument--that is,
8271 the expanded file names
8272 will still be relative to
8273 the top-level SConstruct directory,
8274 and consequently incorrect
8275 relative to the chdir directory.
8276 Builders created using chdir keyword argument,
8277 will need to use construction variable
8282 to use just the filename portion of the
8286 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8288 env = Environment(BUILDERS = {'MyBuild' : b})
8289 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8293 Any additional keyword arguments supplied
8294 when a Builder object is created
8295 (that is, when the Builder() function is called)
8296 will be set in the executing construction
8297 environment when the Builder object is called.
8298 The canonical example here would be
8299 to set a construction variable to
8300 the repository of a source code system.
8302 Any additional keyword arguments supplied
8306 will only be associated with the target
8307 created by that particular Builder call
8308 (and any other files built as a
8309 result of the call).
8311 These extra keyword arguments are passed to the
8312 following functions:
8313 command generator functions,
8315 and emitter functions.
8321 function will turn its
8323 keyword argument into an appropriate
8324 internal Action object.
8325 You can also explicity create Action objects
8329 which can then be passed to the
8332 This can be used to configure
8333 an Action object more flexibly,
8334 or it may simply be more efficient
8335 than letting each separate Builder object
8336 create a separate Action
8338 Builder objects need to do the same thing.
8343 returns an appropriate object for the action
8344 represented by the type of the first argument:
8347 If the first argument is already an Action object,
8348 the object is simply returned.
8351 If the first argument is a string,
8352 a command-line Action is returned.
8355 Action('$CC -c -o $TARGET $SOURCES')
8358 .\" XXX From Gary Ruben, 23 April 2002:
8359 .\" What would be useful is a discussion of how you execute command
8360 .\" shell commands ie. what is the process used to spawn the shell, pass
8361 .\" environment variables to it etc., whether there is one shell per
8362 .\" environment or one per command etc. It might help to look at the Gnu
8363 .\" make documentation to see what they think is important to discuss about
8364 .\" a build system. I'm sure you can do a better job of organising the
8365 .\" documentation than they have :-)
8369 If the first argument is a list,
8370 then a list of Action objects is returned.
8371 An Action object is created as necessary
8372 for each element in the list.
8375 the list is itself a list,
8376 the internal list is the
8377 command and arguments to be executed via
8379 This allows white space to be enclosed
8380 in an argument by defining
8381 a command in a list within a list:
8384 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8388 If the first argument is a Python function,
8389 a function Action is returned.
8390 The Python function takes three keyword arguments,
8392 (a Node object representing the target file),
8394 (a Node object representing the source file)
8397 (the construction environment
8398 used for building the target file).
8403 arguments may be lists of Node objects if there is
8404 more than one target file or source file.
8405 The actual target and source file name(s) may
8406 be retrieved from their Node objects
8407 via the built-in Python str() function:
8410 target_file_name = str(target)
8411 source_file_names = map(lambda x: str(x), source)
8414 The function should return
8418 to indicate a successful build of the target file(s).
8419 The function may raise an exception
8420 or return a non-zero exit status
8421 to indicate an unsuccessful build.
8424 def build_it(target = None, source = None, env = None):
8425 # build the target from the source
8428 a = Action(build_it)
8431 If the action argument is not one of the above,
8434 The second, optional argument
8435 is a Python function that returns
8436 a string to be printed to describe the action being executed.
8437 Like a function to build a file,
8438 this function takes three arguments:
8440 (a Node object representing the target file),
8442 (a Node object representing the source file)
8445 (a construction environment).
8450 arguments may be lists of Node objects if there is
8451 more than one target file or source file.
8455 def build_it(target, source, env):
8456 # build the target from the source
8459 def string_it(target, source, env):
8460 return "building '%s' from '%s'" % (target[0], source[0])
8462 # Use a positional argument.
8463 a = Action(build_it, string_it)
8465 # Alternatively, use a keyword argument.
8466 a = Action(build_it, strfunction=string_it)
8469 The third, also optional argument
8470 is a list of construction variables
8471 whose values will be included
8472 in the signature of the Action
8473 when deciding whether a target should
8474 be rebuilt because the action changed.
8475 This is necessary whenever you want a target to
8476 be rebuilt when a specific
8477 construction variable changes,
8478 because the underlying Python code for a function
8479 will not change when the value of the construction variable does.
8482 def build_it(target, source, env):
8483 # build the target from the 'XXX' construction variable
8484 open(target[0], 'w').write(env['XXX'])
8487 def string_it(target, source):
8488 return "building '%s' from '%s'" % (target[0], source[0])
8490 # Use positional arguments.
8491 a = Action(build_it, string_it, ['XXX'])
8493 # Alternatively, use a keyword argument.
8494 a = Action(build_it, varlist=['XXX'])
8504 which specifies that
8505 scons will execute the action
8506 after changing to the specified directory.
8507 If the chdir argument is
8508 a string or a directory Node,
8509 scons will change to the specified directory.
8510 If the chdir argument
8511 is not a string or Node
8513 then scons will change to the
8514 target file's directory.
8516 Note that scons will
8518 automatically modify
8520 construction variables like
8524 when using the chdir
8525 keyword argument--that is,
8526 the expanded file names
8527 will still be relative to
8528 the top-level SConstruct directory,
8529 and consequently incorrect
8530 relative to the chdir directory.
8531 Builders created using chdir keyword argument,
8532 will need to use construction variable
8537 to use just the filename portion of the
8541 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8545 .SS Miscellaneous Action Functions
8548 supplies a number of functions
8549 that arrange for various common
8550 file and directory manipulations
8552 These are similar in concept to "tasks" in the
8554 although the implementation is slightly different.
8555 These functions do not actually
8556 perform the specified action
8557 at the time the function is called,
8558 but instead return an Action object
8559 that can be executed at the
8561 (In Object-Oriented terminology,
8566 that return Action objects.)
8569 there are two natural ways
8572 are intended to be used.
8576 to perform the action
8577 at the time the SConscript
8581 global function to do so:
8583 Execute(Touch('file'))
8587 you can use these functions
8588 to supply Actions in a list
8592 This can allow you to
8593 perform more complicated
8594 sequences of file manipulation
8596 on platform-specific
8600 env = Environment(TMPBUILD = '/tmp/builddir')
8601 env.Command('foo.out', 'foo.in',
8602 [Mkdir('$TMPBUILD'),
8603 Copy('${SOURCE.dir}', '$TMPBUILD')
8604 "cd $TMPBUILD && make",
8605 Delete('$TMPBUILD')])
8609 .RI Chmod( dest ", " mode )
8610 Returns an Action object that
8611 changes the permissions on the specified
8613 file or directory to the specified
8618 Execute(Chmod('file', 0755))
8620 env.Command('foo.out', 'foo.in',
8621 [Copy('$TARGET', '$SOURCE'),
8622 Chmod('$TARGET', 0755)])
8626 .RI Copy( dest ", " src )
8627 Returns an Action object
8630 source file or directory to the
8632 destination file or directory.
8636 Execute(Copy('foo.output', 'foo.input'))
8638 env.Command('bar.out', 'bar.in',
8639 Copy('$TARGET', '$SOURCE'))
8643 .RI Delete( entry ", [" must_exist ])
8644 Returns an Action that
8645 deletes the specified
8647 which may be a file or a directory tree.
8648 If a directory is specified,
8649 the entire directory tree
8654 then a Python error will be thrown
8655 if the specified entry does not exist;
8658 that is, the Action will silently do nothing
8659 if the entry does not exist.
8663 Execute(Delete('/tmp/buildroot'))
8665 env.Command('foo.out', 'foo.in',
8666 [Delete('${TARGET.dir}'),
8669 Execute(Delete('file_that_must_exist', must_exist=1))
8675 that creates the specified
8681 Execute(Mkdir('/tmp/outputdir'))
8683 env.Command('foo.out', 'foo.in',
8684 [Mkdir('/tmp/builddir',
8685 Copy('$SOURCE', '/tmp/builddir')
8686 "cd /tmp/builddir && ])
8691 .RI Move( dest ", " src )
8693 that moves the specified
8695 file or directory to
8702 Execute(Move('file.destination', 'file.source'))
8704 env.Command('output_file', 'input_file',
8706 Move('$TARGET', 'file_created_by_MyBuildAction')])
8712 that updates the modification time
8718 Execute(Touch('file_to_be_touched'))
8720 env.Command('marker', 'input_file',
8725 .SS Variable Substitution
8727 Before executing a command,
8729 performs construction variable interpolation on the strings that make up
8730 the command line of builders.
8731 Variables are introduced by a
8734 Besides construction variables, scons provides the following
8735 variables for each command execution:
8738 The file name of the target being built, or the file name of the first
8739 target if multiple targets are being built.
8742 The file names of all targets being built.
8745 The file name of the source of the build command, or the file name of the
8746 first source if multiple sources are being built.
8749 The file names of the sources of the build command.
8751 (Note that the above variables are reserved
8752 and may not be set in a construction environment.)
8755 For example, given the construction variable CC='cc', targets=['foo'], and
8756 sources=['foo.c', 'bar.c']:
8759 action='$CC -c -o $TARGET $SOURCES'
8762 would produce the command line:
8765 cc -c -o foo foo.c bar.c
8768 Variable names may be surrounded by curly braces ({})
8769 to separate the name from the trailing characters.
8770 Within the curly braces, a variable name may have
8771 a Python slice subscript appended to select one
8772 or more items from a list.
8773 In the previous example, the string:
8785 Additionally, a variable name may
8786 have the following special
8787 modifiers appended within the enclosing curly braces
8788 to modify the interpolated string:
8791 The base path of the file name,
8792 including the directory path
8793 but excluding any suffix.
8796 The name of the directory in which the file exists.
8800 minus any directory portion.
8803 Just the basename of the file,
8805 and minus the directory.
8808 Just the file suffix.
8811 The absolute path name of the file.
8814 The POSIX form of the path,
8815 with directories separated by
8819 This is sometimes necessary on Win32 systems
8820 when a path references a file on other (POSIX) systems.
8823 The directory and file name to the source file linked to this file
8824 through BuildDir. If this file isn't linked, it just returns the
8825 directory and filename unchanged.
8828 The directory containing the source file linked to this file
8829 through BuildDir. If this file isn't linked, it just returns the
8830 directory part of the filename.
8833 The directory and file name to the source file linked to this file
8834 through BuildDir. If the file does not exist locally but exists in
8835 a Repository, the path in the Repository is returned.
8836 If this file isn't linked, it just returns the
8837 directory and filename unchanged.
8840 The Repository directory containing the source file linked to this file
8841 through BuildDir. If this file isn't linked, it just returns the
8842 directory part of the filename.
8845 For example, the specified target will
8846 expand as follows for the corresponding modifiers:
8849 $TARGET => sub/dir/file.x
8850 ${TARGET.base} => sub/dir/file
8851 ${TARGET.dir} => sub/dir
8852 ${TARGET.file} => file.x
8853 ${TARGET.filebase} => file
8854 ${TARGET.suffix} => .x
8855 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8857 BuildDir('sub/dir','src')
8858 $SOURCE => sub/dir/file.x
8859 ${SOURCE.srcpath} => src/file.x
8860 ${SOURCE.srcdir} => src
8862 Repository('/usr/repository')
8863 $SOURCE => sub/dir/file.x
8864 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8865 ${SOURCE.rsrcdir} => /usr/repository/src
8868 Lastly, a variable name
8869 may be a callable Python function
8871 construction variable in the environment.
8873 take four arguments:
8875 - a list of target nodes,
8877 - a list of source nodes,
8879 - the construction environment,
8881 - a Boolean value that specifies
8882 whether the function is being called
8883 for generating a build signature.
8884 SCons will insert whatever
8885 the called function returns
8886 into the expanded string:
8889 def foo(target, source, env, for_signature):
8892 # Will expand $BAR to "bar baz"
8893 env=Environment(FOO=foo, BAR="$FOO baz")
8896 You can use this feature to pass arguments to a
8897 Python function by creating a callable class
8898 that stores one or more arguments in an object,
8899 and then uses them when the
8902 Note that in this case,
8903 the entire variable expansion must
8904 be enclosed by curly braces
8905 so that the arguments will
8906 be associated with the
8907 instantiation of the class:
8911 def __init__(self, arg):
8914 def __call__(self, target, source, env, for_signature):
8917 # Will expand $BAR to "my argument bar baz"
8918 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8922 The special pseudo-variables
8926 may be used to surround parts of a command line
8929 causing a rebuild--that is,
8930 which are not included in the signature
8931 of target files built with this command.
8936 will be removed from the command line
8937 before it is added to file signatures,
8942 will be removed before the command is executed.
8943 For example, the command line:
8946 echo Last build occurred $( $TODAY $). > $TARGET
8950 would execute the command:
8953 echo Last build occurred $TODAY. > $TARGET
8957 but the command signature added to any target files would be:
8960 echo Last build occurred . > $TARGET
8963 SCons uses the following rules when converting construction variables into
8967 When the value is a string it is interpreted as a space delimited list of
8968 command line arguments.
8971 When the value is a list it is interpreted as a list of command line
8972 arguments. Each element of the list is converted to a string.
8975 Anything that is not a list or string is converted to a string and
8976 interpreted as a single command line argument.
8979 Newline characters (\\n) delimit lines. The newline parsing is done after
8980 all other parsing, so it is not possible for arguments (e.g. file names) to
8981 contain embedded newline characters. This limitation will likely go away in
8982 a future version of SCons.
8990 new file types for implicit dependencies.
8991 Scanner accepts the following arguments:
8994 A Python function that will process
8996 and return a list of strings (file names)
8997 representing the implicit
8998 dependencies found in the contents.
8999 The function takes three or four arguments:
9001 def scanner_function(node, env, path):
9003 def scanner_function(node, env, path, arg):
9007 argument is the internal
9008 SCons node representing the file.
9011 to fetch the name of the file, and
9012 .B node.get_contents()
9013 to fetch contents of the file.
9017 argument is the construction environment for the scan.
9018 Fetch values from it using the
9024 argument is a tuple (or list)
9025 of directories that can be searched
9027 This will usually be the tuple returned by the
9029 argument (see below).
9033 argument is the argument supplied
9034 when the scanner was created, if any.
9037 The name of the Scanner.
9039 to identify the Scanner internally.
9042 An optional argument that, if specified,
9043 will be passed to the scanner function
9045 and the path function
9049 An optional list that can be used to
9050 determine which scanner should be used for
9052 In the usual case of scanning for file names,
9053 this argument will be a list of suffixes
9054 for the different file types that this
9055 Scanner knows how to scan.
9056 If the argument is a string,
9057 then it will be expanded
9058 into a list by the current environment.
9061 A Python function that takes
9062 two or three arguments:
9063 a construction environment, directory Node,
9064 and optional argument supplied
9065 when the scanner was created.
9068 returns a tuple of directories
9069 that can be searched for files to be returned
9070 by this Scanner object.
9073 The class of Node that should be returned
9074 by this Scanner object.
9075 Any strings or other objects returned
9076 by the scanner function
9077 that are not of this class
9078 will be run through the
9083 A Python function that will take a string
9085 and turn it into the appropriate class of Node
9086 to be returned by this Scanner object.
9089 An optional Python function that takes two arguments,
9090 a Node (file) and a construction environment,
9091 and returns whether the
9092 Node should, in fact,
9093 be scanned for dependencies.
9094 This check can be used to eliminate unnecessary
9095 calls to the scanner function when,
9096 for example, the underlying file
9097 represented by a Node does not yet exist.
9100 An optional flag that
9101 specifies whether this scanner should be re-invoked
9102 on the dependency files returned by the scanner.
9103 When this flag is not set,
9104 the Node subsystem will
9105 only invoke the scanner on the file being scanned,
9106 and not (for example) also on the files
9107 specified by the #include lines
9108 in the file being scanned.
9110 .SH SYSTEM-SPECIFIC BEHAVIOR
9111 SCons and its configuration files are very portable,
9112 due largely to its implementation in Python.
9113 There are, however, a few portability
9114 issues waiting to trap the unwary.
9116 SCons handles the upper-case
9118 file suffix differently,
9119 depending on the capabilities of
9120 the underlying system.
9121 On a case-sensitive system
9122 such as Linux or UNIX,
9123 SCons treats a file with a
9125 suffix as a C++ source file.
9126 On a case-insensitive system
9128 SCons treats a file with a
9130 suffix as a C source file.
9132 SCons handles the upper-case
9134 file suffix differently,
9135 depending on the capabilities of
9136 the underlying system.
9137 On a case-sensitive system
9138 such as Linux or UNIX,
9139 SCons treats a file with a
9141 suffix as a Fortran source file
9142 that is to be first run through
9143 the standard C preprocessor.
9144 On a case-insensitive system
9146 SCons treats a file with a
9148 suffix as a Fortran source file that should
9150 be run through the C preprocessor.
9151 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9152 Cygwin supplies a set of tools and utilities
9153 that let users work on a
9154 Windows system using a more POSIX-like environment.
9155 The Cygwin tools, including Cygwin Python,
9157 by sharing an ability to interpret UNIX-like path names.
9158 For example, the Cygwin tools
9159 will internally translate a Cygwin path name
9160 like /cygdrive/c/mydir
9161 to an equivalent Windows pathname
9162 of C:/mydir (equivalent to C:\\mydir).
9165 that are built for native Windows execution,
9166 such as the python.org and ActiveState versions,
9167 do not have the Cygwin path name semantics.
9168 This means that using a native Windows version of Python
9169 to build compiled programs using Cygwin tools
9170 (such as gcc, bison, and flex)
9171 may yield unpredictable results.
9172 "Mixing and matching" in this way
9173 can be made to work,
9174 but it requires careful attention to the use of path names
9175 in your SConscript files.
9177 In practice, users can sidestep
9178 the issue by adopting the following rules:
9180 use the Cygwin-supplied Python interpreter
9182 when using Microsoft Visual C/C++
9183 (or some other Windows compiler)
9184 use the python.org or ActiveState version of Python
9186 .SS WIN32: scons.bat file
9188 SCons is executed via a wrapper
9191 This has (at least) two ramifications:
9193 First, Windows command-line users
9194 that want to use variable assignment
9196 may have to put double quotes
9197 around the assignments:
9200 scons "FOO=BAR" "BAZ=BLEH"
9203 Second, the Cygwin shell does not
9204 recognize this file as being the same
9207 command issued at the command-line prompt.
9208 You can work around this either by
9211 from the Cygwin command line,
9212 or by creating a wrapper shell
9218 The MinGW bin directory must be in your PATH environment variable or the
9219 PATH variable under the ENV construction variable for SCons
9220 to detect and use the MinGW tools. When running under the native Windows
9221 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9222 tools, if they are both installed, regardless of the order of the bin
9223 directories in the PATH variable. If you have both MSVC and MinGW
9224 installed and you want to use MinGW instead of MSVC,
9225 then you must explictly tell SCons to use MinGW by passing
9231 to the Environment() function, because SCons will prefer the MSVC tools
9232 over the MinGW tools.
9236 To help you get started using SCons,
9237 this section contains a brief overview of some common tasks.
9239 .SS Basic Compilation From a Single Source File
9243 env.Program(target = 'foo', source = 'foo.c')
9246 Note: Build the file by specifying
9247 the target as an argument
9248 ("scons foo" or "scons foo.exe").
9249 or by specifying a dot ("scons .").
9251 .SS Basic Compilation From Multiple Source Files
9255 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9258 .SS Setting a Compilation Flag
9261 env = Environment(CCFLAGS = '-g')
9262 env.Program(target = 'foo', source = 'foo.c')
9265 .SS Search The Local Directory For .h Files
9269 need to set CCFLAGS to specify -I options by hand.
9270 SCons will construct the right -I options from CPPPATH.
9273 env = Environment(CPPPATH = ['.'])
9274 env.Program(target = 'foo', source = 'foo.c')
9277 .SS Search Multiple Directories For .h Files
9280 env = Environment(CPPPATH = ['include1', 'include2'])
9281 env.Program(target = 'foo', source = 'foo.c')
9284 .SS Building a Static Library
9288 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9289 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9292 .SS Building a Shared Library
9296 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9297 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9300 .SS Linking a Local Library Into a Program
9303 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9304 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9305 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9308 .SS Defining Your Own Builder Object
9310 Notice that when you invoke the Builder,
9311 you can leave off the target file suffix,
9312 and SCons will add it automatically.
9315 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9317 src_suffix = '.tex')
9318 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9319 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9321 # The following creates "bar.pdf" from "bar.tex"
9322 env.PDFBuilder(target = 'bar', source = 'bar')
9325 Note also that the above initialization
9326 overwrites the default Builder objects,
9327 so the Environment created above
9328 can not be used call Builders like env.Program(),
9329 env.Object(), env.StaticLibrary(), etc.
9331 .SS Adding Your Own Builder Object to an Environment
9334 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9336 src_suffix = '.tex')
9338 env.Append(BUILDERS = {'PDFBuilder' : bld})
9339 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9340 env.Program(target = 'bar', source = 'bar.c')
9343 You also can use other Pythonic techniques to add
9344 to the BUILDERS construction variable, such as:
9348 env['BUILDERS]['PDFBuilder'] = bld
9351 .SS Defining Your Own Scanner Object
9356 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9358 def kfile_scan(node, env, path, arg):
9359 contents = node.get_contents()
9360 includes = include_re.findall(contents)
9363 kscan = Scanner(name = 'kfile',
9364 function = kfile_scan,
9367 scanners = Environment().Dictionary('SCANNERS')
9368 env = Environment(SCANNERS = scanners + [kscan])
9370 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9372 bar_in = File('bar.in')
9373 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9374 bar_in.target_scanner = kscan
9377 .SS Creating a Hierarchical Build
9379 Notice that the file names specified in a subdirectory's
9381 file are relative to that subdirectory.
9387 env.Program(target = 'foo', source = 'foo.c')
9389 SConscript('sub/SConscript')
9394 # Builds sub/foo from sub/foo.c
9395 env.Program(target = 'foo', source = 'foo.c')
9397 SConscript('dir/SConscript')
9402 # Builds sub/dir/foo from sub/dir/foo.c
9403 env.Program(target = 'foo', source = 'foo.c')
9406 .SS Sharing Variables Between SConscript Files
9408 You must explicitly Export() and Import() variables that
9409 you want to share between SConscript files.
9415 env.Program(target = 'foo', source = 'foo.c')
9418 SConscript('subdirectory/SConscript')
9420 subdirectory/SConscript:
9423 env.Program(target = 'foo', source = 'foo.c')
9426 .SS Building Multiple Variants From the Same Source
9428 Use the BuildDir() method to establish
9429 one or more separate build directories for
9430 a given source directory,
9431 then use the SConscript() method
9432 to specify the SConscript files
9433 in the build directories:
9440 BuildDir('foo', 'src')
9441 SConscript('foo/SConscript')
9445 BuildDir('bar', 'src')
9446 SConscript('bar/SConscript')
9451 env = Environment(CCFLAGS = ccflags)
9452 env.Program(target = 'src', source = 'src.c')
9455 Note the use of the Export() method
9456 to set the "ccflags" variable to a different
9457 value for each variant build.
9459 .SS Hierarchical Build of Two Libraries Linked With a Program
9464 env = Environment(LIBPATH = ['#libA', '#libB'])
9466 SConscript('libA/SConscript')
9467 SConscript('libB/SConscript')
9468 SConscript('Main/SConscript')
9473 env.Library('a', Split('a1.c a2.c a3.c'))
9478 env.Library('b', Split('b1.c b2.c b3.c'))
9483 e = env.Copy(LIBS = ['a', 'b'])
9484 e.Program('foo', Split('m1.c m2.c m3.c'))
9487 The '#' in the LIBPATH directories specify that they're relative to the
9488 top-level directory, so they don't turn into "Main/libA" when they're
9489 used in Main/SConscript.
9491 Specifying only 'a' and 'b' for the library names
9492 allows SCons to append the appropriate library
9493 prefix and suffix for the current platform
9494 (for example, 'liba.a' on POSIX systems,
9495 'a.lib' on Windows).
9497 .SS Customizing contruction variables from the command line.
9499 The following would allow the C compiler to be specified on the command
9500 line or in the file custom.py.
9503 opts = Options('custom.py')
9504 opts.Add('CC', 'The C compiler.')
9505 env = Environment(options=opts)
9506 Help(opts.GenerateHelpText(env))
9509 The user could specify the C compiler on the command line:
9515 or in the custom.py file:
9521 or get documentation on the options:
9532 .SS Using Microsoft Visual C++ precompiled headers
9534 Since windows.h includes everything and the kitchen sink, it can take quite
9535 some time to compile it over and over again for a bunch of object files, so
9536 Microsoft provides a mechanism to compile a set of headers once and then
9537 include the previously compiled headers in any object file. This
9538 technology is called precompiled headers. The general recipe is to create a
9539 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9540 then include every header you want to precompile in "StdAfx.h", and finally
9541 include "StdAfx.h" as the first header in all the source files you are
9542 compiling to object files. For example:
9546 #include <windows.h>
9547 #include <my_big_header.h>
9566 /* do some other stuff */
9572 env['PCHSTOP'] = 'StdAfx.h'
9573 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9574 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9577 For more information see the document for the PCH builder, and the PCH and
9578 PCHSTOP construction variables. To learn about the details of precompiled
9579 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9581 .SS Using Microsoft Visual C++ external debugging information
9583 Since including debugging information in programs and shared libraries can
9584 cause their size to increase significantly, Microsoft provides a mechanism
9585 for including the debugging information in an external file called a PDB
9586 file. SCons supports PDB files through the PDB construction
9592 env['PDB'] = 'MyApp.pdb'
9593 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9596 For more information see the document for the PDB construction variable.
9601 Specifies the directory that contains the SCons Python module directory
9602 (e.g. /home/aroach/scons-src-0.01/src/engine).
9605 A string of options that will be used by scons in addition to those passed
9606 on the command line.
9617 Steven Knight <knight@baldmt.com>
9619 Anthony Roach <aroach@electriceyeball.com>