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 This variable specifies how much of a source file is precompiled. This
6073 variable is ignored by tools other than Microsoft Visual C++, or when
6074 the PCH variable is not being used. When this variable is define it
6075 must be a string that is the name of the header that
6076 is included at the end of the precompiled portion of the source files, or
6077 the empty string if the "#pragma hrdstop" construct is being used:
6080 env['PCHSTOP'] = 'StdAfx.h'
6084 The Microsoft Visual C++ PDB file that will store debugging information for
6085 object files, shared libraries, and programs. This variable is ignored by
6086 tools other than Microsoft Visual C++.
6087 When this variable is
6088 defined SCons will add options to the compiler and linker command line to
6089 cause them to generate external debugging information, and will also set up the
6090 dependencies for the PDB file. Example:
6093 env['PDB'] = 'hello.pdb'
6097 A deprecated synonym for $DVIPDFCOM.
6100 The prefix used for PDF file names.
6103 The suffix used for PDF file names.
6106 The name of the platform used to create the Environment. If no platform is
6107 specified when the Environment is created,
6109 autodetects the platform.
6112 env = Environment(tools = [])
6113 if env['PLATFORM'] == 'cygwin':
6119 .IP PRINT_CMD_LINE_FUNC
6120 A Python function used to print the command lines as they are executed
6121 (assuming command printing is not disabled by the
6125 options or their equivalents).
6126 The function should take four arguments:
6128 the command being executed (a string),
6130 the target being built (file node, list, or string name(s)),
6132 the source(s) used (file node, list, or string name(s)), and
6134 the environment being used.
6136 The function must do the printing itself. The default implementation,
6137 used if this variable is not set or is None, is:
6139 def print_cmd_line(s, target, source, env):
6140 sys.stdout.write(s + "\n")
6143 Here's an example of a more interesting function:
6145 def print_cmd_line(s, target, source, env):
6146 sys.stdout.write("Building %s -> %s...\n" %
6147 (' and '.join([str(x) for x in source]),
6148 ' and '.join([str(x) for x in target])))
6149 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6150 env.Program('foo', 'foo.c')
6153 This just prints "Building <targetname> from <sourcename>..." instead
6154 of the actual commands.
6155 Such a function could also log the actual commands to a log file,
6159 The prefix used for executable file names.
6162 The suffix used for executable file names.
6165 The command line used to convert TeX DVI files into a PostScript file.
6168 The string displayed when a TeX DVI file
6169 is converted into a PostScript file.
6170 If this is not set, then $PSCOM (the command line) is displayed.
6173 The prefix used for PostScript file names.
6176 The prefix used for PostScript file names.
6179 The qt tool tries to take this from os.environ.
6180 It also initializes all QT_*
6181 construction variables listed below.
6182 (Note that all paths are constructed
6183 with python's os.path.join() method,
6184 but are listed here with the '/' separator
6185 for easier reading.)
6186 In addition, the construction environment
6187 variables CPPPATH, LIBPATH and LIBS may be modified
6189 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6190 are modified. Because the build-performance is affected when using this tool,
6191 you have to explicitly specify it at Environment creation:
6194 Environment(tools=['default','qt'])
6197 The qt tool supports the following operations:
6199 .B Automatic moc file generation from header files.
6200 You do not have to specify moc files explicitly, the tool does it for you.
6201 However, there are a few preconditions to do so: Your header file must have
6202 the same filebase as your implementation file and must stay in the same
6203 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6204 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6205 See also the corresponding builder method
6208 .B Automatic moc file generation from cxx files.
6209 As stated in the qt documentation, include the moc file at the end of
6210 the cxx file. Note that you have to include the file, which is generated
6211 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6212 <basename>.moc. A warning is generated after building the moc file, if you
6213 do not include the correct file. If you are using BuildDir, you may
6214 need to specify duplicate=1. You can turn off automatic moc file generation
6215 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6218 .B Automatic handling of .ui files.
6219 The implementation files generated from .ui files are handled much the same
6220 as yacc or lex files. Each .ui file given as a source of Program, Library or
6221 SharedLibrary will generate three files, the declaration file, the
6222 implementation file and a moc file. Because there are also generated headers,
6223 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6227 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6228 specify files to run moc on.
6231 The path where the qt binaries are installed.
6232 The default value is '$QTDIR/bin'.
6235 The path where the qt header files are installed.
6236 The default value is '$QTDIR/include'.
6237 Note: If you set this variable to None, the tool won't change the CPPPATH
6238 construction variable.
6241 Prints lots of debugging information while scanning for moc files.
6244 The path where the qt libraries are installed.
6245 The default value is '$QTDIR/lib'.
6246 Note: If you set this variable to None, the tool won't change the LIBPATH
6247 construction variable.
6250 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6251 this variable to None, the tool won't change the LIBS variable.
6254 Default value is '$QT_BINPATH/moc'.
6257 Default value is ''. Prefix for moc output files, when source is a cxx file.
6260 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6263 .IP QT_MOCFROMCPPFLAGS
6264 Default value is '-i'. These flags are passed to moc, when moccing a
6267 .IP QT_MOCFROMCXXCOM
6268 Command to generate a moc file from a cpp file.
6271 Command to generate a moc file from a header.
6273 .IP QT_MOCFROMHFLAGS
6274 Default value is ''. These flags are passed to moc, when moccing a header
6278 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6281 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6285 Default value is '$QT_BINPATH/uic'.
6288 Command to generate header files from .ui files.
6291 Default value is ''. These flags are passed to uic, when creating a a h
6292 file from a .ui file.
6294 .IP QT_UICDECLPREFIX
6295 Default value is ''. Prefix for uic generated header files.
6297 .IP QT_UICDECLSUFFIX
6298 Default value is '.h'. Suffix for uic generated header files.
6301 Command to generate cxx files from .ui files.
6304 Default value is ''. These flags are passed to uic, when creating a cxx
6305 file from a .ui file.
6307 .IP QT_UICIMPLPREFIX
6308 Default value is 'uic_'. Prefix for uic generated implementation files.
6310 .IP QT_UICIMPLSUFFIX
6311 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6315 Default value is '.ui'. Suffix of designer input files.
6318 The archive indexer.
6321 General options passed to the archive indexer.
6324 The resource compiler used by the RES builder.
6327 The command line used by the RES builder.
6330 The flags passed to the resource compiler by the RES builder.
6334 Note that this variable is not actually used
6335 for the command to fetch source files from RCS;
6338 construction variable, below.
6341 The RCS "checkout" executable,
6342 used to fetch source files from RCS.
6345 The command line used to
6346 fetch (checkout) source files from RCS.
6349 The string displayed when fetching
6350 a source file from RCS.
6351 If this is not set, then $RCS_COCOM
6352 (the command line) is displayed.
6355 Options that are passed to the $RCS_CO command.
6358 A function that converts a file name into a list of Dir instances by
6359 searching the repositories.
6362 The Java RMI stub compiler.
6365 The command line used to compile stub
6366 and skeleton class files
6367 from Java classes that contain RMI implementations.
6368 Any options specified in the $RMICFLAGS construction variable
6369 are included on this command line.
6372 The string displayed when compiling
6373 stub and skeleton class files
6374 from Java classes that contain RMI implementations.
6375 If this is not set, then $RMICCOM (the command line) is displayed.
6378 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6382 General options passed to the Java RMI stub compiler.
6385 The RPC protocol compiler.
6387 .IP RPCGENCLIENTFLAGS
6388 Options passed to the RPC protocol compiler
6389 when generating client side stubs.
6390 These are in addition to any flags specified in the
6392 construction variable.
6395 General options passed to the RPC protocol compiler.
6397 .IP RPCGENHEADERFLAGS
6398 Options passed to the RPC protocol compiler
6399 when generating a header file.
6400 These are in addition to any flags specified in the
6402 construction variable.
6404 .IP RPCGENSERVICEFLAGS
6405 Options passed to the RPC protocol compiler
6406 when generating server side stubs.
6407 These are in addition to any flags specified in the
6409 construction variable.
6412 Options passed to the RPC protocol compiler
6413 when generating XDR routines.
6414 These are in addition to any flags specified in the
6416 construction variable.
6419 A list of paths to search for shared libraries when running programs.
6420 Currently only used in the GNU linker (gnulink) and IRIX linker (sgilink).
6421 Ignored on platforms and toolchains that don't support it.
6422 Note that the paths added to RPATH
6423 are not transformed by
6425 in any way: if you want an absolute
6426 path, you must make it absolute yourself.
6429 A list of the available implicit dependency scanners.
6430 New file scanners may be added by
6431 appending to this list,
6432 although the more flexible approach
6433 is to associate scanners
6434 with a specific Builder.
6435 See the sections "Builder Objects"
6436 and "Scanner Objects,"
6437 below, for more information.
6440 The SCCS executable.
6443 The command line used to
6444 fetch source files from SCCS.
6447 The string displayed when fetching
6448 a source file from a CVS repository.
6449 If this is not set, then $SCCSCOM
6450 (the command line) is displayed.
6453 General options that are passed to SCCS.
6456 Options that are passed specifically to the SCCS "get" subcommand.
6457 This can be set, for example, to
6459 to check out editable files from SCCS.
6462 The C compiler used for generating shared-library objects.
6465 The command line used to compile a C source file
6466 to a shared-library object file.
6467 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6468 are included on this command line.
6471 The string displayed when a C source file
6472 is compiled to a shared object file.
6473 If this is not set, then $SHCCCOM (the command line) is displayed.
6476 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6480 Options that are passed to the C compiler
6481 to generate shared-library objects.
6484 The C++ compiler used for generating shared-library objects.
6487 The command line used to compile a C++ source file
6488 to a shared-library object file.
6489 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6490 are included on this command line.
6493 The string displayed when a C++ source file
6494 is compiled to a shared object file.
6495 If this is not set, then $SHCXXCOM (the command line) is displayed.
6498 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6502 Options that are passed to the C++ compiler
6503 to generate shared-library objects.
6506 A string naming the shell program that will be passed to the
6511 construction variable for more information.
6514 The Fortran 77 compiler used for generating shared-library objects.
6515 You should normally set the $SHFORTRANC variable,
6516 which specifies the default Fortran compiler
6517 for all Fortran versions.
6518 You only need to set $SHF77 if you need to use a specific compiler
6519 or compiler version for Fortran 77 files.
6522 The command line used to compile a Fortran 77 source file
6523 to a shared-library object file.
6524 You only need to set $SHF77COM if you need to use a specific
6525 command line for Fortran 77 files.
6526 You should normally set the $SHFORTRANCOM variable,
6527 which specifies the default command line
6528 for all Fortran versions.
6531 The string displayed when a Fortran 77 source file
6532 is compiled to a shared-library object file.
6533 If this is not set, then $SHF77COM or $SHFORTRANCOM
6534 (the command line) is displayed.
6537 Options that are passed to the Fortran 77 compiler
6538 to generated shared-library objects.
6539 You only need to set $SHF77FLAGS if you need to define specific
6540 user options for Fortran 77 files.
6541 You should normally set the $SHFORTRANFLAGS variable,
6542 which specifies the user-specified options
6543 passed to the default Fortran compiler
6544 for all Fortran versions.
6547 The command line used to compile a Fortran 77 source file to a
6548 shared-library object file
6549 after first running the file through the C preprocessor.
6550 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6551 are included on this command line.
6552 You only need to set $SHF77PPCOM if you need to use a specific
6553 C-preprocessor command line for Fortran 77 files.
6554 You should normally set the $SHFORTRANPPCOM variable,
6555 which specifies the default C-preprocessor command line
6556 for all Fortran versions.
6559 The Fortran 90 compiler used for generating shared-library objects.
6560 You should normally set the $SHFORTRANC variable,
6561 which specifies the default Fortran compiler
6562 for all Fortran versions.
6563 You only need to set $SHF90 if you need to use a specific compiler
6564 or compiler version for Fortran 90 files.
6567 The command line used to compile a Fortran 90 source file
6568 to a shared-library object file.
6569 You only need to set $SHF90COM if you need to use a specific
6570 command line for Fortran 90 files.
6571 You should normally set the $SHFORTRANCOM variable,
6572 which specifies the default command line
6573 for all Fortran versions.
6576 The string displayed when a Fortran 90 source file
6577 is compiled to a shared-library object file.
6578 If this is not set, then $SHF90COM or $SHFORTRANCOM
6579 (the command line) is displayed.
6582 Options that are passed to the Fortran 90 compiler
6583 to generated shared-library objects.
6584 You only need to set $SHF90FLAGS if you need to define specific
6585 user options for Fortran 90 files.
6586 You should normally set the $SHFORTRANFLAGS variable,
6587 which specifies the user-specified options
6588 passed to the default Fortran compiler
6589 for all Fortran versions.
6592 The command line used to compile a Fortran 90 source file to a
6593 shared-library object file
6594 after first running the file through the C preprocessor.
6595 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6596 are included on this command line.
6597 You only need to set $SHF90PPCOM if you need to use a specific
6598 C-preprocessor command line for Fortran 90 files.
6599 You should normally set the $SHFORTRANPPCOM variable,
6600 which specifies the default C-preprocessor command line
6601 for all Fortran versions.
6604 The Fortran 95 compiler used for generating shared-library objects.
6605 You should normally set the $SHFORTRANC variable,
6606 which specifies the default Fortran compiler
6607 for all Fortran versions.
6608 You only need to set $SHF95 if you need to use a specific compiler
6609 or compiler version for Fortran 95 files.
6612 The command line used to compile a Fortran 95 source file
6613 to a shared-library object file.
6614 You only need to set $SHF95COM if you need to use a specific
6615 command line for Fortran 95 files.
6616 You should normally set the $SHFORTRANCOM variable,
6617 which specifies the default command line
6618 for all Fortran versions.
6621 The string displayed when a Fortran 95 source file
6622 is compiled to a shared-library object file.
6623 If this is not set, then $SHF95COM or $SHFORTRANCOM
6624 (the command line) is displayed.
6627 Options that are passed to the Fortran 95 compiler
6628 to generated shared-library objects.
6629 You only need to set $SHF95FLAGS if you need to define specific
6630 user options for Fortran 95 files.
6631 You should normally set the $SHFORTRANFLAGS variable,
6632 which specifies the user-specified options
6633 passed to the default Fortran compiler
6634 for all Fortran versions.
6637 The command line used to compile a Fortran 95 source file to a
6638 shared-library object file
6639 after first running the file through the C preprocessor.
6640 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6641 are included on this command line.
6642 You only need to set $SHF95PPCOM if you need to use a specific
6643 C-preprocessor command line for Fortran 95 files.
6644 You should normally set the $SHFORTRANPPCOM variable,
6645 which specifies the default C-preprocessor command line
6646 for all Fortran versions.
6649 The default Fortran compiler used for generating shared-library objects.
6652 The command line used to compile a Fortran source file
6653 to a shared-library object file.
6656 The string displayed when a Fortran source file
6657 is compiled to a shared-library object file.
6658 If this is not set, then $SHFORTRANCOM
6659 (the command line) is displayed.
6662 Options that are passed to the Fortran compiler
6663 to generate shared-library objects.
6666 The command line used to compile a Fortran source file to a
6667 shared-library object file
6668 after first running the file through the C preprocessor.
6669 Any options specified
6670 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
6671 are included on this command line.
6674 The prefix used for shared library file names.
6677 The suffix used for shared library file names.
6680 The linker for programs that use shared libraries.
6683 The command line used to link programs using shared libaries.
6686 The string displayed when programs using shared libraries are linked.
6687 If this is not set, then $SHLINKCOM (the command line) is displayed.
6690 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
6694 General user options passed to the linker for programs using shared libraries.
6695 Note that this variable should
6699 (or similar) options for linking with the libraries listed in $LIBS,
6702 (or similar) include search path options
6703 that scons generates automatically from $LIBPATH.
6707 for the variable that expands to library-link options,
6711 for the variable that expands to library search path options.
6714 The prefix used for shared object file names.
6717 The suffix used for shared object file names.
6720 A reserved variable name
6721 that may not be set or used in a construction environment.
6722 (See "Variable Substitution," below.)
6725 A reserved variable name
6726 that may not be set or used in a construction environment.
6727 (See "Variable Substitution," below.)
6730 A command interpreter function that will be called to execute command line
6731 strings. The function must expect the following arguments:
6734 def spawn(shell, escape, cmd, args, env):
6738 is a string naming the shell program to use.
6740 is a function that can be called to escape shell special characters in
6743 is the path to the command to be executed.
6745 is the arguments to the command.
6747 is a dictionary of the environment variables
6748 in which the command should be executed.
6751 '\"The Subversion executable (usually named
6755 '\"The command line used to
6756 '\"fetch source files from a Subversion repository.
6759 '\"General options that are passed to Subversion.
6762 The scripting language wrapper and interface generator.
6765 The suffix that will be used for intermediate C
6766 source files generated by
6767 the scripting language wrapper and interface generator.
6768 The default value is
6769 .BR _wrap$CFILESUFFIX .
6770 By default, this value is used whenever the
6774 specified as part of the
6776 construction variable.
6779 The command line used to call
6780 the scripting language wrapper and interface generator.
6783 The string displayed when calling
6784 the scripting language wrapper and interface generator.
6785 If this is not set, then $SWIGCOM (the command line) is displayed.
6787 .IP SWIGCXXFILESUFFIX
6788 The suffix that will be used for intermediate C++
6789 source files generated by
6790 the scripting language wrapper and interface generator.
6791 The default value is
6792 .BR _wrap$CFILESUFFIX .
6793 By default, this value is used whenever the
6795 option is specified as part of the
6797 construction variable.
6800 General options passed to
6801 the scripting language wrapper and interface generator.
6802 This is where you should set
6806 or whatever other options you want to specify to SWIG.
6809 option in this variable,
6812 generate a C++ intermediate source file
6813 with the extension that is specified as the
6821 The command line used to call the tar archiver.
6824 The string displayed when archiving files
6825 using the tar archiver.
6826 If this is not set, then $TARCOM (the command line) is displayed.
6829 env = Environment(TARCOMSTR = "Archiving $TARGET")
6833 General options passed to the tar archiver.
6836 A reserved variable name
6837 that may not be set or used in a construction environment.
6838 (See "Variable Substitution," below.)
6841 A reserved variable name
6842 that may not be set or used in a construction environment.
6843 (See "Variable Substitution," below.)
6846 The suffix used for tar file names.
6849 The TeX formatter and typesetter.
6852 The command line used to call the TeX formatter and typesetter.
6855 The string displayed when calling
6856 the TeX formatter and typesetter.
6857 If this is not set, then $TEXCOM (the command line) is displayed.
6860 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
6864 General options passed to the TeX formatter and typesetter.
6867 A list of the names of the Tool specifications
6868 that are part of this construction environment.
6870 .IP WIN32_INSERT_DEF
6871 When this is set to true,
6872 a library build of a WIN32 shared library (.dll file)
6873 will also build a corresponding .def file at the same time,
6874 if a .def file is not already listed as a build target.
6875 The default is 0 (do not build a .def file).
6878 The prefix used for WIN32 .def file names.
6881 The suffix used for WIN32 .def file names.
6884 The parser generator.
6887 The command line used to call the parser generator
6888 to generate a source file.
6891 The string displayed when generating a source file
6892 using the parser generator.
6893 If this is not set, then $YACCCOM (the command line) is displayed.
6896 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
6900 General options passed to the parser generator.
6901 If $YACCFLAGS contains a \-d option,
6902 SCons assumes that the call will also create a .h file
6903 (if the yacc source file ends in a .y suffix)
6905 (if the yacc source file ends in a .yy suffix)
6908 The zip compression and file packaging utility.
6911 The command line used to call the zip utility,
6912 or the internal Python function used to create a
6916 The string displayed when archiving files
6917 using the zip utility.
6918 If this is not set, then $ZIPCOM
6919 (the command line or internal Python function) is displayed.
6922 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
6931 module used by the internal Python function
6932 to control whether the zip archive
6933 is compressed or not.
6934 The default value is
6935 .BR zipfile.ZIP_DEFLATED ,
6936 which creates a compressed zip archive.
6937 This value has no effect when using Python 1.5.2
6940 module is otherwise unavailable.
6943 General options passed to the zip utility.
6946 Construction variables can be retrieved and set using the
6948 method of the construction environment:
6951 dict = env.Dictionary()
6955 or using the [] operator:
6961 Construction variables can also be passed to the construction environment
6965 env = Environment(CC="cc")
6968 or when copying a construction environment using the
6973 env2 = env.Copy(CC="cl.exe")
6976 .SS Configure Contexts
6980 .I configure contexts,
6981 an integrated mechanism similar to the
6982 various AC_CHECK macros in GNU autoconf
6983 for testing for the existence of C header
6984 files, libraries, etc.
6985 In contrast to autoconf,
6987 does not maintain an explicit cache of the tested values,
6988 but uses its normal dependency tracking to keep the checked values
6989 up to date. However, users may override this behaviour with the
6991 command line option.
6993 The following methods can be used to perform checks:
6996 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
6998 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
6999 This creates a configure context, which can be used to perform checks.
7001 specifies the environment for building the tests.
7002 This environment may be modified when performing checks.
7004 is a dictionary containing custom tests.
7005 See also the section about custom tests below.
7006 By default, no custom tests are added to the configure context.
7008 specifies a directory where the test cases are built.
7009 Note that this directory is not used for building
7011 The default value is the directory
7014 specifies a file which collects the output from commands
7015 that are executed to check for the existence of header files, libraries, etc.
7016 The default is the file #/config.log.
7017 If you are using the
7020 you may want to specify a subdirectory under your build directory.
7022 specifies a C header file where the results of tests
7023 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7024 The default is to not write a
7027 You can specify the same
7029 file in multiple calls to Configure,
7032 will concatenate all results in the specified file.
7034 uses its normal dependency checking
7035 to decide if it's necessary to rebuild
7039 This means that the file is not necessarily re-built each
7041 but is only rebuilt if its contents will have changed
7042 and some target that depends on the
7044 file is being built.
7049 instance has the following associated methods:
7052 .RI Configure.Finish( self )
7053 This method should be called after configuration is done.
7054 It returns the environment as modified
7055 by the configuration checks performed.
7056 After this method is called, no further checks can be performed
7057 with this configuration context.
7058 However, you can create a new
7060 context to perform additional checks.
7061 Only one context should be active at a time.
7063 The following Checks are predefined.
7064 (This list will likely grow larger as time
7065 goes by and developers contribute new useful tests.)
7068 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7071 is usable in the specified language.
7074 in which case the last item in the list
7075 is the header file to be checked,
7076 and the previous list items are
7079 lines should precede the
7080 header line being checked for.
7081 The optional argument
7084 a two character string, where the first character denotes the opening
7085 quote and the second character denotes the closing quote.
7086 By default, both characters are " (double quote).
7087 The optional argument
7093 and selects the compiler to be used for the check.
7094 Returns 1 on success and 0 on failure.
7097 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7098 This is a wrapper around
7099 .B Configure.CheckHeader
7102 is usable in the C language.
7105 in which case the last item in the list
7106 is the header file to be checked,
7107 and the previous list items are
7110 lines should precede the
7111 header line being checked for.
7112 The optional argument
7115 a two character string, where the first character denotes the opening
7116 quote and the second character denotes the closing quote (both default
7118 Returns 1 on success and 0 on failure.
7121 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7122 This is a wrapper around
7123 .B Configure.CheckHeader
7126 is usable in the C++ language.
7129 in which case the last item in the list
7130 is the header file to be checked,
7131 and the previous list items are
7134 lines should precede the
7135 header line being checked for.
7136 The optional argument
7139 a two character string, where the first character denotes the opening
7140 quote and the second character denotes the closing quote (both default
7142 Returns 1 on success and 0 on failure.
7145 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7146 Checks if the specified
7147 C or C++ function is available.
7149 is the name of the function to check for.
7152 argument is a string
7156 that will be compiled
7157 to check if the function exists;
7163 char function_name();
7171 and selects the compiler to be used for the check;
7175 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd ])
7182 is 1 and the library provides the specified
7184 appends the library to the LIBS construction environment variable.
7186 may also be None (the default),
7189 is checked with the current LIBS variable,
7190 or a list of library names,
7191 in which case each library in the list
7198 you can link against the specified
7206 and selects the compiler to be used for the check;
7208 The default value for
7211 It is assumed, that the C-language is used.
7212 This method returns 1 on success and 0 on error.
7215 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7218 .RI Configure.CheckLib
7219 call, this call provides a more sophisticated way to check against libraries.
7222 specifies the library or a list of libraries to check.
7224 specifies a header to check for.
7227 in which case the last item in the list
7228 is the header file to be checked,
7229 and the previous list items are
7232 lines should precede the
7233 header line being checked for.
7235 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7237 can be any valid expression (with a trailing ';'). The default is 'main();'.
7239 specifies whether to add the library to the environment (only if the check
7240 succeeds). This method returns 1 on success and 0 on error.
7243 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7244 Checks for the existence of a type defined by
7247 specifies the typedef name to check for.
7249 is a string containing one or more
7251 lines that will be inserted into the program
7252 that will be run to test for the existence of the type.
7259 and selects the compiler to be used for the check;
7263 Example of a typical Configure usage:
7267 conf = Configure( env )
7268 if not conf.CheckCHeader( 'math.h' ):
7269 print 'We really need math.h!'
7271 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7272 # do stuff for qt - usage, e.g.
7273 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7278 You can define your own custom checks.
7279 in addition to the predefined checks.
7280 These are passed in a dictionary to the Configure function.
7281 This dictionary maps the names of the checks
7282 to user defined Python callables
7283 (either Python functions or class instances implementing the
7286 The first argument of the call is always a
7288 instance followed by the arguments,
7289 which must be supplied by the user of the check.
7290 These CheckContext instances define the following methods:
7293 .RI CheckContext.Message( self ", " text )
7295 Usually called before the check is started.
7297 will be displayed to the user, e.g. 'Checking for library X...'
7300 .RI CheckContext.Result( self, ", " res )
7302 Usually called after the check is done.
7304 can be either an integer or a string. In the former case, 'ok' (res != 0)
7305 or 'failed' (res == 0) is displayed to the user, in the latter case the
7306 given string is displayed.
7309 .RI CheckContext.TryCompile( self ", " text ", " extension )
7310 Checks if a file with the specified
7312 (e.g. '.c') containing
7314 can be compiled using the environment's
7316 builder. Returns 1 on success and 0 on failure.
7319 .RI CheckContext.TryLink( self ", " text ", " extension )
7320 Checks, if a file with the specified
7322 (e.g. '.c') containing
7324 can be compiled using the environment's
7326 builder. Returns 1 on success and 0 on failure.
7329 .RI CheckContext.TryRun( self ", " text ", " extension )
7330 Checks, if a file with the specified
7332 (e.g. '.c') containing
7334 can be compiled using the environment's
7336 builder. On success, the program is run. If the program
7337 executes successfully
7338 (that is, its return status is 0),
7343 is the standard output of the
7345 If the program fails execution
7346 (its return status is non-zero),
7347 then (0, '') is returned.
7350 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7351 Checks if the specified
7353 with an optional source file (contents
7360 may be anything which can be converted to a
7367 is the content of the target file.
7373 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7374 Low level implementation for testing specific builds;
7375 the methods above are based on this method.
7376 Given the Builder instance
7380 of a source file with optional
7382 this method returns 1 on success and 0 on failure. In addition,
7384 is set to the build target node, if the build was successful.
7387 Example for implementing and using custom tests:
7390 def CheckQt(context, qtdir):
7391 context.Message( 'Checking for qt ...' )
7392 lastLIBS = context.env['LIBS']
7393 lastLIBPATH = context.env['LIBPATH']
7394 lastCPPPATH= context.env['CPPPATH']
7395 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7396 ret = context.TryLink("""
7398 int main(int argc, char **argv) {
7399 QApplication qapp(argc, argv);
7404 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7405 context.Result( ret )
7409 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7410 if not conf.CheckQt('/usr/lib/qt'):
7411 print 'We really need qt!'
7416 .SS Construction Variable Options
7418 Often when building software, various options need to be specified at build
7419 time that are not known when the SConstruct/SConscript files are
7420 written. For example, libraries needed for the build may be in non-standard
7421 locations, or site-specific compiler options may need to be passed to the
7424 provides a mechanism for overridding construction variables from the
7425 command line or a text-based SConscript file through an Options
7426 object. To create an Options object, call the Options() function:
7429 .RI Options([ files "], [" args ])
7430 This creates an Options object that will read construction variables from
7431 the file or list of filenames specified in
7433 If no files are specified,
7438 then no files will be read.
7439 The optional argument
7442 values that will override anything read from the specified files;
7443 it is primarily intended to be passed the
7445 dictionary that holds variables
7446 specified on the command line.
7450 opts = Options('custom.py')
7451 opts = Options('overrides.py', ARGUMENTS)
7452 opts = Options(None, {FOO:'expansion', BAR:7})
7455 Options objects have the following methods:
7458 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7459 This adds a customizable construction variable to the Options object.
7461 is the name of the variable.
7463 is the help text for the variable.
7465 is the default value of the variable;
7466 if the default value is
7468 and there is no explicit value specified,
7469 the construction variable will
7471 be added to the construction environment.
7473 is called to validate the value of the variable, and should take three
7474 arguments: key, value, and environment
7476 is called to convert the value before putting it in the environment, and
7477 should take a single argument: value. Example:
7480 opts.Add('CC', 'The C compiler')
7484 .RI AddOptions( list )
7485 A wrapper script that adds
7486 multiple customizable construction variables
7487 to an Options object.
7489 is a list of tuple or list objects
7490 that contain the arguments
7491 for an individual call to the
7498 ('CC', 'The C compiler'),
7499 ('VALIDATE', 'An option for testing validation',
7500 'notset', validator, None),
7505 .RI Update( env ", [" args ])
7506 This updates a construction environment
7508 with the customized construction variables. Normally this method is not
7509 called directly, but is called indirectly by passing the Options object to
7510 the Environment() function:
7513 env = Environment(options=opts)
7517 .RI Save( filename ", " env )
7518 This saves the currently set options into a script file named
7520 that can be used on the next invocation to automatically load the current
7521 settings. This method combined with the Options method can be used to
7522 support caching of options between runs.
7526 opts = Options(['options.cache', 'custom.py'])
7529 opts.Save('options.cache', env)
7533 .RI GenerateHelpText( env ", [" sort ])
7534 This generates help text documenting the customizable construction
7535 variables suitable to passing in to the Help() function.
7537 is the construction environment that will be used to get the actual values
7538 of customizable variables. Calling with
7542 will cause the output to be sorted
7543 by the specified argument.
7547 should take two arguments
7550 (like the standard Python
7555 Help(opts.GenerateHelpText(env))
7556 Help(opts.GenerateHelpText(env, sort=cmp))
7559 The text based SConscript file is executed as a Python script, and the
7560 global variables are queried for customizable construction
7567 To make it more convenient to work with customizable Options,
7569 provides a number of functions
7570 that make it easy to set up
7571 various types of Options:
7574 .RI BoolOption( key ", " help ", " default )
7575 Return a tuple of arguments
7576 to set up a Boolean option.
7580 have a default value of
7582 and display the specified
7585 The option will interpret the values
7607 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7608 Return a tuple of arguments
7610 whose value may be one
7611 of a specified list of legal enumerated values.
7615 have a default value of
7617 and display the specified
7620 The option will only support those
7626 argument is a dictionary
7627 that can be used to convert
7628 input values into specific legal values
7637 then the values are case-sensitive.
7642 then values will be matched
7648 then values will be matched
7650 and all input values will be
7651 converted to lower case.
7654 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
7655 Return a tuple of arguments
7657 whose value may be one or more
7658 of a specified list of legal enumerated values.
7662 have a default value of
7664 and display the specified
7667 The option will only support the values
7670 or the values in the
7673 More than one value may be specified,
7674 with all values separated by commas.
7675 The default may be a string of
7676 comma-separated default values,
7677 or a list of the default values.
7680 argument is a dictionary
7681 that can be used to convert
7682 input values into specific legal values
7688 .RI PackageOption( key ", " help ", " default )
7689 Return a tuple of arguments
7691 whose value is a path name
7692 of a package that may be
7693 enabled, disabled or
7694 given an explicit path name.
7698 have a default value of
7700 and display the specified
7703 The option will support the values
7710 in which case the specified
7713 or the option may be set to an
7715 (typically the path name to a package
7716 that is being enabled).
7717 The option will also support the values
7723 to disable use of the specified option.
7726 .RI PathOption( key ", " help ", " default ", [" validator ])
7727 Return a tuple of arguments
7729 whose value is expected to be a path name.
7733 have a default value of
7735 and display the specified
7741 that will be called to
7742 verify that the specified path
7745 following ready-made validators:
7746 .BR PathOption.PathExists
7748 which verifies that the specified path exists;
7749 .BR PathOption.PathIsFile ,
7750 which verifies that the specified path is an existing file;
7751 .BR PathOption.PathIsDir ,
7752 which verifies that the specified path is an existing directory;
7754 .BR PathOption.PathIsDirCreate ,
7755 which verifies that the specified path is a directory,
7756 and will create the specified directory if the path exist.
7757 You may supply your own
7760 which must take three arguments
7762 the name of the options variable to be set;
7764 the specified value being checked;
7767 the construction environment)
7768 and should raise an exception
7769 if the specified value is not acceptable.
7772 These functions make it
7773 convenient to create a number
7774 of options with consistent behavior
7775 in a single call to the
7781 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
7782 EnumOption('debug', 'debug output and symbols', 'no'
7783 allowed_values=('yes', 'no', 'full'),
7784 map={}, ignorecase=0), # case sensitive
7785 ListOption('shared',
7786 'libraries to build as shared libraries',
7788 names = list_of_libs),
7789 PackageOption('x11',
7790 'use X11 installed here (yes = search some places)',
7792 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
7793 PathOption('foopath', 'where the foo library is installed', foopath,
7794 PathOption.PathIsDir),
7799 .SS File and Directory Nodes
7809 Nodes, respectively.
7810 python objects, respectively.
7811 Those objects have several user-visible attributes
7812 and methods that are often useful:
7818 This path is relative to the top-level directory
7822 The build path is the same as the source path if
7827 The absolute build path of the given file or directory.
7837 object representing the
7846 # Get the current build dir's path, relative to top.
7848 # Current dir's absolute path
7850 # Next line is always '.', because it is the top dir's path relative to itself.
7852 File('foo.c').srcnode().path # source path of the given source file.
7854 # Builders also return File objects:
7855 foo = env.Program('foo.c')
7856 print "foo will be built in %s"%foo.path
7862 can be extended to build different types of targets
7863 by adding new Builder objects
7864 to a construction environment.
7866 you should only need to add a new Builder object
7867 when you want to build a new type of file or other external target.
7868 If you just want to invoke a different compiler or other tool
7869 to build a Program, Object, Library, or any other
7870 type of output file for which
7872 already has an existing Builder,
7873 it is generally much easier to
7874 use those existing Builders
7875 in a construction environment
7876 that sets the appropriate construction variables
7879 Builder objects are created
7885 function accepts the following arguments:
7888 The command line string used to build the target from the source.
7891 a list of strings representing the command
7892 to be executed and its arguments
7893 (suitable for enclosing white space in an argument),
7895 mapping source file name suffixes to
7896 any combination of command line strings
7897 (if the builder should accept multiple source file extensions),
7900 (see the next section);
7901 or a list of any of the above.
7904 takes three arguments:
7906 - a list of source nodes,
7908 - a list of target nodes,
7910 - the construction environment.
7913 The prefix that will be prepended to the target file name.
7914 This may be specified as a:
7924 - a function or other callable that takes
7925 two arguments (a construction environment and a list of sources)
7926 and returns a prefix,
7931 - specifies a mapping from a specific source suffix (of the first
7932 source specified) to a corresponding target prefix. Both the source
7933 suffix and target prefix specifications may use environment variable
7934 substitution, and the target prefix (the 'value' entries in the
7935 dictionary) may also be a callable object. The default target prefix
7936 may be indicated by a dictionary entry with a key value of None.
7941 b = Builder("build_it < $SOURCE > $TARGET"
7944 def gen_prefix(env, sources):
7945 return "file-" + env['PLATFORM'] + '-'
7946 b = Builder("build_it < $SOURCE > $TARGET",
7947 prefix = gen_prefix)
7949 b = Builder("build_it < $SOURCE > $TARGET",
7950 suffix = { None: "file-",
7951 "$SRC_SFX_A": gen_prefix })
7955 The suffix that will be appended to the target file name.
7956 This may be specified in the same manner as the prefix above.
7957 If the suffix is a string, then
7959 will append a '.' to the beginning of the suffix if it's not already
7960 there. The string returned by callable object (or obtained from the
7961 dictionary) is untouched and must append its own '.' to the beginning
7965 b = Builder("build_it < $SOURCE > $TARGET"
7968 def gen_suffix(env, sources):
7969 return "." + env['PLATFORM'] + "-file"
7970 b = Builder("build_it < $SOURCE > $TARGET",
7971 suffix = gen_suffix)
7973 b = Builder("build_it < $SOURCE > $TARGET",
7974 suffix = { None: ".sfx1",
7975 "$SRC_SFX_A": gen_suffix })
7979 The expected source file name suffix. This may be a string or a list
7983 A Scanner object that
7984 will be invoked to find
7985 implicit dependencies for this target file.
7986 This keyword argument should be used
7987 for Scanner objects that find
7988 implicit dependencies
7989 based only on the target file
7990 and the construction environment,
7993 (See the section "Scanner Objects," below,
7994 for information about creating Scanner objects.)
7997 A Scanner object that
7999 find implicit dependences in
8001 used to build this target file.
8002 This is where you would
8003 specify a scanner to
8006 lines in source files.
8007 (See the section "Scanner Objects," below,
8008 for information about creating Scanner objects.)
8011 A factory function that the Builder will use
8012 to turn any targets specified as strings into SCons Nodes.
8014 SCons assumes that all targets are files.
8015 Other useful target_factory
8018 for when a Builder creates a directory target,
8021 for when a Builder can create either a file
8022 or directory target.
8027 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8029 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8030 env.MakeDirectory('new_directory', [])
8034 A factory function that the Builder will use
8035 to turn any sources specified as strings into SCons Nodes.
8037 SCons assumes that all source are files.
8038 Other useful source_factory
8041 for when a Builder uses a directory as a source,
8044 for when a Builder can use files
8045 or directories (or both) as sources.
8050 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8052 env.Append(BUILDERS = {'Collect':CollectBuilder})
8053 env.Collect('archive', ['directory_name', 'file_name'])
8057 A function or list of functions to manipulate the target and source
8058 lists before dependencies are established
8059 and the target(s) are actually built.
8061 can also be a string containing a construction variable to expand
8062 to an emitter function or list of functions,
8063 or a dictionary mapping source file suffixes
8064 to emitter functions.
8065 (Only the suffix of the first source file
8066 is used to select the actual emitter function
8067 from an emitter dictionary.)
8070 takes three arguments:
8072 - a list of source nodes,
8074 - a list of target nodes,
8076 - the construction environment.
8077 An emitter must return a tuple containing two lists,
8078 the list of targets to be built by this builder,
8079 and the list of sources for this builder.
8084 def e(target, source, env):
8085 return (target + ['foo.foo'], source + ['foo.src'])
8087 # Simple association of an emitter function with a Builder.
8088 b = Builder("my_build < $TARGET > $SOURCE",
8091 def e2(target, source, env):
8092 return (target + ['bar.foo'], source + ['bar.src'])
8094 # Simple association of a list of emitter functions with a Builder.
8095 b = Builder("my_build < $TARGET > $SOURCE",
8098 # Calling an emitter function through a construction variable.
8099 env = Environment(MY_EMITTER = e)
8100 b = Builder("my_build < $TARGET > $SOURCE",
8101 emitter = '$MY_EMITTER')
8103 # Calling a list of emitter functions through a construction variable.
8104 env = Environment(EMITTER_LIST = [e, e2])
8105 b = Builder("my_build < $TARGET > $SOURCE",
8106 emitter = '$EMITTER_LIST')
8108 # Associating multiple emitters with different file
8109 # suffixes using a dictionary.
8110 def e_suf1(target, source, env):
8111 return (target + ['another_target_file'], source)
8112 def e_suf2(target, source, env):
8113 return (target, source + ['another_source_file'])
8114 b = Builder("my_build < $TARGET > $SOURCE",
8115 emitter = {'.suf1' : e_suf1,
8123 arguments must not both be used for the same Builder.
8126 Specifies whether this builder is allowed to be called multiple times for
8127 the same target file(s). The default is 0, which means the builder
8128 can not be called multiple times for the same target file(s). Calling a
8129 builder multiple times for the same target simply adds additional source
8130 files to the target; it is not allowed to change the environment associated
8131 with the target, specify addition environment overrides, or associate a different
8132 builder with the target.
8135 A construction environment that can be used
8136 to fetch source code using this Builder.
8137 (Note that this environment is
8139 used for normal builds of normal target files,
8140 which use the environment that was
8141 used to call the Builder for the target file.)
8144 A function that returns a list of actions that will be executed to build
8145 the target(s) from the source(s).
8146 The returned action(s) may be
8147 an Action object, or anything that
8148 can be converted into an Action object
8149 (see the next section).
8151 The generator function
8152 takes four arguments:
8154 - a list of source nodes,
8156 - a list of target nodes,
8158 - the construction environment,
8160 - a Boolean value that specifies
8161 whether the generator is being called
8162 for generating a build signature
8163 (as opposed to actually executing the command).
8167 def g(source, target, env, for_signature):
8168 return [["gcc", "-c", "-o"] + target + source]
8170 b = Builder(generator=g)
8174 Specifies a builder to use when a source file name suffix does not match
8175 any of the suffixes of the builder. Using this argument produces a
8176 multi-stage builder.
8179 Specifies that this builder expects exactly one source file per call. Giving
8180 more than one source files without target files results in implicitely calling
8181 the builder multiple times (once for each source given). Giving multiple
8182 source files together with target files results in a UserError exception.
8190 arguments must not both be used for the same Builder.
8193 A construction environment that can be used
8194 to fetch source code using this Builder.
8195 (Note that this environment is
8197 used for normal builds of normal target files,
8198 which use the environment that was
8199 used to call the Builder for the target file.)
8202 b = Builder(action="build < $SOURCE > $TARGET")
8203 env = Environment(BUILDERS = {'MyBuild' : b})
8204 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8208 A directory from which scons
8215 a string or a directory Node,
8216 scons will change to the specified directory.
8219 is not a string or Node
8221 then scons will change to the
8222 target file's directory.
8224 Note that scons will
8226 automatically modify
8228 construction variables like
8232 when using the chdir
8233 keyword argument--that is,
8234 the expanded file names
8235 will still be relative to
8236 the top-level SConstruct directory,
8237 and consequently incorrect
8238 relative to the chdir directory.
8239 Builders created using chdir keyword argument,
8240 will need to use construction variable
8245 to use just the filename portion of the
8249 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8251 env = Environment(BUILDERS = {'MyBuild' : b})
8252 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8256 Any additional keyword arguments supplied
8257 when a Builder object is created
8258 (that is, when the Builder() function is called)
8259 will be set in the executing construction
8260 environment when the Builder object is called.
8261 The canonical example here would be
8262 to set a construction variable to
8263 the repository of a source code system.
8265 Any additional keyword arguments supplied
8269 will only be associated with the target
8270 created by that particular Builder call
8271 (and any other files built as a
8272 result of the call).
8274 These extra keyword arguments are passed to the
8275 following functions:
8276 command generator functions,
8278 and emitter functions.
8284 function will turn its
8286 keyword argument into an appropriate
8287 internal Action object.
8288 You can also explicity create Action objects
8292 which can then be passed to the
8295 This can be used to configure
8296 an Action object more flexibly,
8297 or it may simply be more efficient
8298 than letting each separate Builder object
8299 create a separate Action
8301 Builder objects need to do the same thing.
8306 returns an appropriate object for the action
8307 represented by the type of the first argument:
8310 If the first argument is already an Action object,
8311 the object is simply returned.
8314 If the first argument is a string,
8315 a command-line Action is returned.
8318 Action('$CC -c -o $TARGET $SOURCES')
8321 .\" XXX From Gary Ruben, 23 April 2002:
8322 .\" What would be useful is a discussion of how you execute command
8323 .\" shell commands ie. what is the process used to spawn the shell, pass
8324 .\" environment variables to it etc., whether there is one shell per
8325 .\" environment or one per command etc. It might help to look at the Gnu
8326 .\" make documentation to see what they think is important to discuss about
8327 .\" a build system. I'm sure you can do a better job of organising the
8328 .\" documentation than they have :-)
8332 If the first argument is a list,
8333 then a list of Action objects is returned.
8334 An Action object is created as necessary
8335 for each element in the list.
8338 the list is itself a list,
8339 the internal list is the
8340 command and arguments to be executed via
8342 This allows white space to be enclosed
8343 in an argument by defining
8344 a command in a list within a list:
8347 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8351 If the first argument is a Python function,
8352 a function Action is returned.
8353 The Python function takes three keyword arguments,
8355 (a Node object representing the target file),
8357 (a Node object representing the source file)
8360 (the construction environment
8361 used for building the target file).
8366 arguments may be lists of Node objects if there is
8367 more than one target file or source file.
8368 The actual target and source file name(s) may
8369 be retrieved from their Node objects
8370 via the built-in Python str() function:
8373 target_file_name = str(target)
8374 source_file_names = map(lambda x: str(x), source)
8377 The function should return
8381 to indicate a successful build of the target file(s).
8382 The function may raise an exception
8383 or return a non-zero exit status
8384 to indicate an unsuccessful build.
8387 def build_it(target = None, source = None, env = None):
8388 # build the target from the source
8391 a = Action(build_it)
8394 If the action argument is not one of the above,
8397 The second, optional argument
8398 is a Python function that returns
8399 a string to be printed to describe the action being executed.
8400 Like a function to build a file,
8401 this function takes three arguments:
8403 (a Node object representing the target file),
8405 (a Node object representing the source file)
8408 (a construction environment).
8413 arguments may be lists of Node objects if there is
8414 more than one target file or source file.
8418 def build_it(target, source, env):
8419 # build the target from the source
8422 def string_it(target, source, env):
8423 return "building '%s' from '%s'" % (target[0], source[0])
8425 # Use a positional argument.
8426 a = Action(build_it, string_it)
8428 # Alternatively, use a keyword argument.
8429 a = Action(build_it, strfunction=string_it)
8432 The third, also optional argument
8433 is a list of construction variables
8434 whose values will be included
8435 in the signature of the Action
8436 when deciding whether a target should
8437 be rebuilt because the action changed.
8438 This is necessary whenever you want a target to
8439 be rebuilt when a specific
8440 construction variable changes,
8441 because the underlying Python code for a function
8442 will not change when the value of the construction variable does.
8445 def build_it(target, source, env):
8446 # build the target from the 'XXX' construction variable
8447 open(target[0], 'w').write(env['XXX'])
8450 def string_it(target, source):
8451 return "building '%s' from '%s'" % (target[0], source[0])
8453 # Use positional arguments.
8454 a = Action(build_it, string_it, ['XXX'])
8456 # Alternatively, use a keyword argument.
8457 a = Action(build_it, varlist=['XXX'])
8467 which specifies that
8468 scons will execute the action
8469 after changing to the specified directory.
8470 If the chdir argument is
8471 a string or a directory Node,
8472 scons will change to the specified directory.
8473 If the chdir argument
8474 is not a string or Node
8476 then scons will change to the
8477 target file's directory.
8479 Note that scons will
8481 automatically modify
8483 construction variables like
8487 when using the chdir
8488 keyword argument--that is,
8489 the expanded file names
8490 will still be relative to
8491 the top-level SConstruct directory,
8492 and consequently incorrect
8493 relative to the chdir directory.
8494 Builders created using chdir keyword argument,
8495 will need to use construction variable
8500 to use just the filename portion of the
8504 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8508 .SS Miscellaneous Action Functions
8511 supplies a number of functions
8512 that arrange for various common
8513 file and directory manipulations
8515 These are similar in concept to "tasks" in the
8517 although the implementation is slightly different.
8518 These functions do not actually
8519 perform the specified action
8520 at the time the function is called,
8521 but instead return an Action object
8522 that can be executed at the
8524 (In Object-Oriented terminology,
8529 that return Action objects.)
8532 there are two natural ways
8535 are intended to be used.
8539 to perform the action
8540 at the time the SConscript
8544 global function to do so:
8546 Execute(Touch('file'))
8550 you can use these functions
8551 to supply Actions in a list
8555 This can allow you to
8556 perform more complicated
8557 sequences of file manipulation
8559 on platform-specific
8563 env = Environment(TMPBUILD = '/tmp/builddir')
8564 env.Command('foo.out', 'foo.in',
8565 [Mkdir('$TMPBUILD'),
8566 Copy('${SOURCE.dir}', '$TMPBUILD')
8567 "cd $TMPBUILD && make",
8568 Delete('$TMPBUILD')])
8572 .RI Chmod( dest ", " mode )
8573 Returns an Action object that
8574 changes the permissions on the specified
8576 file or directory to the specified
8581 Execute(Chmod('file', 0755))
8583 env.Command('foo.out', 'foo.in',
8584 [Copy('$TARGET', '$SOURCE'),
8585 Chmod('$TARGET', 0755)])
8589 .RI Copy( dest ", " src )
8590 Returns an Action object
8593 source file or directory to the
8595 destination file or directory.
8599 Execute(Copy('foo.output', 'foo.input'))
8601 env.Command('bar.out', 'bar.in',
8602 Copy('$TARGET', '$SOURCE'))
8606 .RI Delete( entry ", [" must_exist ])
8607 Returns an Action that
8608 deletes the specified
8610 which may be a file or a directory tree.
8611 If a directory is specified,
8612 the entire directory tree
8617 then a Python error will be thrown
8618 if the specified entry does not exist;
8621 that is, the Action will silently do nothing
8622 if the entry does not exist.
8626 Execute(Delete('/tmp/buildroot'))
8628 env.Command('foo.out', 'foo.in',
8629 [Delete('${TARGET.dir}'),
8632 Execute(Delete('file_that_must_exist', must_exist=1))
8638 that creates the specified
8644 Execute(Mkdir('/tmp/outputdir'))
8646 env.Command('foo.out', 'foo.in',
8647 [Mkdir('/tmp/builddir',
8648 Copy('$SOURCE', '/tmp/builddir')
8649 "cd /tmp/builddir && ])
8654 .RI Move( dest ", " src )
8656 that moves the specified
8658 file or directory to
8665 Execute(Move('file.destination', 'file.source'))
8667 env.Command('output_file', 'input_file',
8669 Move('$TARGET', 'file_created_by_MyBuildAction')])
8675 that updates the modification time
8681 Execute(Touch('file_to_be_touched'))
8683 env.Command('marker', 'input_file',
8688 .SS Variable Substitution
8690 Before executing a command,
8692 performs construction variable interpolation on the strings that make up
8693 the command line of builders.
8694 Variables are introduced by a
8697 Besides construction variables, scons provides the following
8698 variables for each command execution:
8701 The file name of the target being built, or the file name of the first
8702 target if multiple targets are being built.
8705 The file names of all targets being built.
8708 The file name of the source of the build command, or the file name of the
8709 first source if multiple sources are being built.
8712 The file names of the sources of the build command.
8714 (Note that the above variables are reserved
8715 and may not be set in a construction environment.)
8718 For example, given the construction variable CC='cc', targets=['foo'], and
8719 sources=['foo.c', 'bar.c']:
8722 action='$CC -c -o $TARGET $SOURCES'
8725 would produce the command line:
8728 cc -c -o foo foo.c bar.c
8731 Variable names may be surrounded by curly braces ({})
8732 to separate the name from the trailing characters.
8733 Within the curly braces, a variable name may have
8734 a Python slice subscript appended to select one
8735 or more items from a list.
8736 In the previous example, the string:
8748 Additionally, a variable name may
8749 have the following special
8750 modifiers appended within the enclosing curly braces
8751 to modify the interpolated string:
8754 The base path of the file name,
8755 including the directory path
8756 but excluding any suffix.
8759 The name of the directory in which the file exists.
8763 minus any directory portion.
8766 Just the basename of the file,
8768 and minus the directory.
8771 Just the file suffix.
8774 The absolute path name of the file.
8777 The POSIX form of the path,
8778 with directories separated by
8782 This is sometimes necessary on Win32 systems
8783 when a path references a file on other (POSIX) systems.
8786 The directory and file name to the source file linked to this file
8787 through BuildDir. If this file isn't linked, it just returns the
8788 directory and filename unchanged.
8791 The directory containing the source file linked to this file
8792 through BuildDir. If this file isn't linked, it just returns the
8793 directory part of the filename.
8796 The directory and file name to the source file linked to this file
8797 through BuildDir. If the file does not exist locally but exists in
8798 a Repository, the path in the Repository is returned.
8799 If this file isn't linked, it just returns the
8800 directory and filename unchanged.
8803 The Repository directory containing the source file linked to this file
8804 through BuildDir. If this file isn't linked, it just returns the
8805 directory part of the filename.
8808 For example, the specified target will
8809 expand as follows for the corresponding modifiers:
8812 $TARGET => sub/dir/file.x
8813 ${TARGET.base} => sub/dir/file
8814 ${TARGET.dir} => sub/dir
8815 ${TARGET.file} => file.x
8816 ${TARGET.filebase} => file
8817 ${TARGET.suffix} => .x
8818 ${TARGET.abspath} => /top/dir/sub/dir/file.x
8820 BuildDir('sub/dir','src')
8821 $SOURCE => sub/dir/file.x
8822 ${SOURCE.srcpath} => src/file.x
8823 ${SOURCE.srcdir} => src
8825 Repository('/usr/repository')
8826 $SOURCE => sub/dir/file.x
8827 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
8828 ${SOURCE.rsrcdir} => /usr/repository/src
8831 Lastly, a variable name
8832 may be a callable Python function
8834 construction variable in the environment.
8836 take four arguments:
8838 - a list of target nodes,
8840 - a list of source nodes,
8842 - the construction environment,
8844 - a Boolean value that specifies
8845 whether the function is being called
8846 for generating a build signature.
8847 SCons will insert whatever
8848 the called function returns
8849 into the expanded string:
8852 def foo(target, source, env, for_signature):
8855 # Will expand $BAR to "bar baz"
8856 env=Environment(FOO=foo, BAR="$FOO baz")
8859 You can use this feature to pass arguments to a
8860 Python function by creating a callable class
8861 that stores one or more arguments in an object,
8862 and then uses them when the
8865 Note that in this case,
8866 the entire variable expansion must
8867 be enclosed by curly braces
8868 so that the arguments will
8869 be associated with the
8870 instantiation of the class:
8874 def __init__(self, arg):
8877 def __call__(self, target, source, env, for_signature):
8880 # Will expand $BAR to "my argument bar baz"
8881 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
8885 The special pseudo-variables
8889 may be used to surround parts of a command line
8892 causing a rebuild--that is,
8893 which are not included in the signature
8894 of target files built with this command.
8899 will be removed from the command line
8900 before it is added to file signatures,
8905 will be removed before the command is executed.
8906 For example, the command line:
8909 echo Last build occurred $( $TODAY $). > $TARGET
8913 would execute the command:
8916 echo Last build occurred $TODAY. > $TARGET
8920 but the command signature added to any target files would be:
8923 echo Last build occurred . > $TARGET
8926 SCons uses the following rules when converting construction variables into
8930 When the value is a string it is interpreted as a space delimited list of
8931 command line arguments.
8934 When the value is a list it is interpreted as a list of command line
8935 arguments. Each element of the list is converted to a string.
8938 Anything that is not a list or string is converted to a string and
8939 interpreted as a single command line argument.
8942 Newline characters (\\n) delimit lines. The newline parsing is done after
8943 all other parsing, so it is not possible for arguments (e.g. file names) to
8944 contain embedded newline characters. This limitation will likely go away in
8945 a future version of SCons.
8953 new file types for implicit dependencies.
8954 Scanner accepts the following arguments:
8957 A Python function that will process
8959 and return a list of strings (file names)
8960 representing the implicit
8961 dependencies found in the contents.
8962 The function takes three or four arguments:
8964 def scanner_function(node, env, path):
8966 def scanner_function(node, env, path, arg):
8970 argument is the internal
8971 SCons node representing the file.
8974 to fetch the name of the file, and
8975 .B node.get_contents()
8976 to fetch contents of the file.
8980 argument is the construction environment for the scan.
8981 Fetch values from it using the
8987 argument is a tuple (or list)
8988 of directories that can be searched
8990 This will usually be the tuple returned by the
8992 argument (see below).
8996 argument is the argument supplied
8997 when the scanner was created, if any.
9000 The name of the Scanner.
9002 to identify the Scanner internally.
9005 An optional argument that, if specified,
9006 will be passed to the scanner function
9008 and the path function
9012 An optional list that can be used to
9013 determine which scanner should be used for
9015 In the usual case of scanning for file names,
9016 this argument will be a list of suffixes
9017 for the different file types that this
9018 Scanner knows how to scan.
9019 If the argument is a string,
9020 then it will be expanded
9021 into a list by the current environment.
9024 A Python function that takes
9025 two or three arguments:
9026 a construction environment, directory Node,
9027 and optional argument supplied
9028 when the scanner was created.
9031 returns a tuple of directories
9032 that can be searched for files to be returned
9033 by this Scanner object.
9036 The class of Node that should be returned
9037 by this Scanner object.
9038 Any strings or other objects returned
9039 by the scanner function
9040 that are not of this class
9041 will be run through the
9046 A Python function that will take a string
9048 and turn it into the appropriate class of Node
9049 to be returned by this Scanner object.
9052 An optional Python function that takes two arguments,
9053 a Node (file) and a construction environment,
9054 and returns whether the
9055 Node should, in fact,
9056 be scanned for dependencies.
9057 This check can be used to eliminate unnecessary
9058 calls to the scanner function when,
9059 for example, the underlying file
9060 represented by a Node does not yet exist.
9063 An optional flag that
9064 specifies whether this scanner should be re-invoked
9065 on the dependency files returned by the scanner.
9066 When this flag is not set,
9067 the Node subsystem will
9068 only invoke the scanner on the file being scanned,
9069 and not (for example) also on the files
9070 specified by the #include lines
9071 in the file being scanned.
9073 .SH SYSTEM-SPECIFIC BEHAVIOR
9074 SCons and its configuration files are very portable,
9075 due largely to its implementation in Python.
9076 There are, however, a few portability
9077 issues waiting to trap the unwary.
9079 SCons handles the upper-case
9081 file suffix differently,
9082 depending on the capabilities of
9083 the underlying system.
9084 On a case-sensitive system
9085 such as Linux or UNIX,
9086 SCons treats a file with a
9088 suffix as a C++ source file.
9089 On a case-insensitive system
9091 SCons treats a file with a
9093 suffix as a C source file.
9095 SCons handles the upper-case
9097 file suffix differently,
9098 depending on the capabilities of
9099 the underlying system.
9100 On a case-sensitive system
9101 such as Linux or UNIX,
9102 SCons treats a file with a
9104 suffix as a Fortran source file
9105 that is to be first run through
9106 the standard C preprocessor.
9107 On a case-insensitive system
9109 SCons treats a file with a
9111 suffix as a Fortran source file that should
9113 be run through the C preprocessor.
9114 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9115 Cygwin supplies a set of tools and utilities
9116 that let users work on a
9117 Windows system using a more POSIX-like environment.
9118 The Cygwin tools, including Cygwin Python,
9120 by sharing an ability to interpret UNIX-like path names.
9121 For example, the Cygwin tools
9122 will internally translate a Cygwin path name
9123 like /cygdrive/c/mydir
9124 to an equivalent Windows pathname
9125 of C:/mydir (equivalent to C:\\mydir).
9128 that are built for native Windows execution,
9129 such as the python.org and ActiveState versions,
9130 do not have the Cygwin path name semantics.
9131 This means that using a native Windows version of Python
9132 to build compiled programs using Cygwin tools
9133 (such as gcc, bison, and flex)
9134 may yield unpredictable results.
9135 "Mixing and matching" in this way
9136 can be made to work,
9137 but it requires careful attention to the use of path names
9138 in your SConscript files.
9140 In practice, users can sidestep
9141 the issue by adopting the following rules:
9143 use the Cygwin-supplied Python interpreter
9145 when using Microsoft Visual C/C++
9146 (or some other Windows compiler)
9147 use the python.org or ActiveState version of Python
9149 .SS WIN32: scons.bat file
9151 SCons is executed via a wrapper
9154 This has (at least) two ramifications:
9156 First, Windows command-line users
9157 that want to use variable assignment
9159 may have to put double quotes
9160 around the assignments:
9163 scons "FOO=BAR" "BAZ=BLEH"
9166 Second, the Cygwin shell does not
9167 recognize this file as being the same
9170 command issued at the command-line prompt.
9171 You can work around this either by
9174 from the Cygwin command line,
9175 or by creating a wrapper shell
9181 The MinGW bin directory must be in your PATH environment variable or the
9182 PATH variable under the ENV construction variable for SCons
9183 to detect and use the MinGW tools. When running under the native Windows
9184 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9185 tools, if they are both installed, regardless of the order of the bin
9186 directories in the PATH variable. If you have both MSVC and MinGW
9187 installed and you want to use MinGW instead of MSVC,
9188 then you must explictly tell SCons to use MinGW by passing
9194 to the Environment() function, because SCons will prefer the MSVC tools
9195 over the MinGW tools.
9199 To help you get started using SCons,
9200 this section contains a brief overview of some common tasks.
9202 .SS Basic Compilation From a Single Source File
9206 env.Program(target = 'foo', source = 'foo.c')
9209 Note: Build the file by specifying
9210 the target as an argument
9211 ("scons foo" or "scons foo.exe").
9212 or by specifying a dot ("scons .").
9214 .SS Basic Compilation From Multiple Source Files
9218 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9221 .SS Setting a Compilation Flag
9224 env = Environment(CCFLAGS = '-g')
9225 env.Program(target = 'foo', source = 'foo.c')
9228 .SS Search The Local Directory For .h Files
9232 need to set CCFLAGS to specify -I options by hand.
9233 SCons will construct the right -I options from CPPPATH.
9236 env = Environment(CPPPATH = ['.'])
9237 env.Program(target = 'foo', source = 'foo.c')
9240 .SS Search Multiple Directories For .h Files
9243 env = Environment(CPPPATH = ['include1', 'include2'])
9244 env.Program(target = 'foo', source = 'foo.c')
9247 .SS Building a Static Library
9251 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9252 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9255 .SS Building a Shared Library
9259 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9260 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9263 .SS Linking a Local Library Into a Program
9266 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9267 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9268 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9271 .SS Defining Your Own Builder Object
9273 Notice that when you invoke the Builder,
9274 you can leave off the target file suffix,
9275 and SCons will add it automatically.
9278 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9280 src_suffix = '.tex')
9281 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9282 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9284 # The following creates "bar.pdf" from "bar.tex"
9285 env.PDFBuilder(target = 'bar', source = 'bar')
9288 Note also that the above initialization
9289 overwrites the default Builder objects,
9290 so the Environment created above
9291 can not be used call Builders like env.Program(),
9292 env.Object(), env.StaticLibrary(), etc.
9294 .SS Adding Your Own Builder Object to an Environment
9297 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9299 src_suffix = '.tex')
9301 env.Append(BUILDERS = {'PDFBuilder' : bld})
9302 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9303 env.Program(target = 'bar', source = 'bar.c')
9306 You also can use other Pythonic techniques to add
9307 to the BUILDERS construction variable, such as:
9311 env['BUILDERS]['PDFBuilder'] = bld
9314 .SS Defining Your Own Scanner Object
9319 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9321 def kfile_scan(node, env, path, arg):
9322 contents = node.get_contents()
9323 includes = include_re.findall(contents)
9326 kscan = Scanner(name = 'kfile',
9327 function = kfile_scan,
9330 scanners = Environment().Dictionary('SCANNERS')
9331 env = Environment(SCANNERS = scanners + [kscan])
9333 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9335 bar_in = File('bar.in')
9336 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9337 bar_in.target_scanner = kscan
9340 .SS Creating a Hierarchical Build
9342 Notice that the file names specified in a subdirectory's
9344 file are relative to that subdirectory.
9350 env.Program(target = 'foo', source = 'foo.c')
9352 SConscript('sub/SConscript')
9357 # Builds sub/foo from sub/foo.c
9358 env.Program(target = 'foo', source = 'foo.c')
9360 SConscript('dir/SConscript')
9365 # Builds sub/dir/foo from sub/dir/foo.c
9366 env.Program(target = 'foo', source = 'foo.c')
9369 .SS Sharing Variables Between SConscript Files
9371 You must explicitly Export() and Import() variables that
9372 you want to share between SConscript files.
9378 env.Program(target = 'foo', source = 'foo.c')
9381 SConscript('subdirectory/SConscript')
9383 subdirectory/SConscript:
9386 env.Program(target = 'foo', source = 'foo.c')
9389 .SS Building Multiple Variants From the Same Source
9391 Use the BuildDir() method to establish
9392 one or more separate build directories for
9393 a given source directory,
9394 then use the SConscript() method
9395 to specify the SConscript files
9396 in the build directories:
9403 BuildDir('foo', 'src')
9404 SConscript('foo/SConscript')
9408 BuildDir('bar', 'src')
9409 SConscript('bar/SConscript')
9414 env = Environment(CCFLAGS = ccflags)
9415 env.Program(target = 'src', source = 'src.c')
9418 Note the use of the Export() method
9419 to set the "ccflags" variable to a different
9420 value for each variant build.
9422 .SS Hierarchical Build of Two Libraries Linked With a Program
9427 env = Environment(LIBPATH = ['#libA', '#libB'])
9429 SConscript('libA/SConscript')
9430 SConscript('libB/SConscript')
9431 SConscript('Main/SConscript')
9436 env.Library('a', Split('a1.c a2.c a3.c'))
9441 env.Library('b', Split('b1.c b2.c b3.c'))
9446 e = env.Copy(LIBS = ['a', 'b'])
9447 e.Program('foo', Split('m1.c m2.c m3.c'))
9450 The '#' in the LIBPATH directories specify that they're relative to the
9451 top-level directory, so they don't turn into "Main/libA" when they're
9452 used in Main/SConscript.
9454 Specifying only 'a' and 'b' for the library names
9455 allows SCons to append the appropriate library
9456 prefix and suffix for the current platform
9457 (for example, 'liba.a' on POSIX systems,
9458 'a.lib' on Windows).
9460 .SS Customizing contruction variables from the command line.
9462 The following would allow the C compiler to be specified on the command
9463 line or in the file custom.py.
9466 opts = Options('custom.py')
9467 opts.Add('CC', 'The C compiler.')
9468 env = Environment(options=opts)
9469 Help(opts.GenerateHelpText(env))
9472 The user could specify the C compiler on the command line:
9478 or in the custom.py file:
9484 or get documentation on the options:
9495 .SS Using Microsoft Visual C++ precompiled headers
9497 Since windows.h includes everything and the kitchen sink, it can take quite
9498 some time to compile it over and over again for a bunch of object files, so
9499 Microsoft provides a mechanism to compile a set of headers once and then
9500 include the previously compiled headers in any object file. This
9501 technology is called precompiled headers. The general recipe is to create a
9502 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9503 then include every header you want to precompile in "StdAfx.h", and finally
9504 include "StdAfx.h" as the first header in all the source files you are
9505 compiling to object files. For example:
9509 #include <windows.h>
9510 #include <my_big_header.h>
9529 /* do some other stuff */
9535 env['PCHSTOP'] = 'StdAfx.h'
9536 env['PCH'] = env.PCH('StdAfx.cpp')[0]
9537 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9540 For more information see the document for the PCH builder, and the PCH and
9541 PCHSTOP construction variables. To learn about the details of precompiled
9542 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
9544 .SS Using Microsoft Visual C++ external debugging information
9546 Since including debugging information in programs and shared libraries can
9547 cause their size to increase significantly, Microsoft provides a mechanism
9548 for including the debugging information in an external file called a PDB
9549 file. SCons supports PDB files through the PDB construction
9555 env['PDB'] = 'MyApp.pdb'
9556 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
9559 For more information see the document for the PDB construction variable.
9564 Specifies the directory that contains the SCons Python module directory
9565 (e.g. /home/aroach/scons-src-0.01/src/engine).
9568 A string of options that will be used by scons in addition to those passed
9569 on the command line.
9580 Steven Knight <knight@baldmt.com>
9582 Anthony Roach <aroach@electriceyeball.com>