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 "January 2005"
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 how many objects are created
514 of the various classes used internally by SCons
515 before and after reading the SConscript files
516 and before and after building targets.
517 This only works when run under Python 2.1 or later.
521 Print the dependency tree
522 after each top-level target is built. This prints out only derived files.
526 Instruct the scanner that searches for libraries
527 to print a message about each potential library
528 name it is searching for,
529 and about the actual libraries it finds.
533 Print the include tree after each top-level target is built.
534 This is generally used to find out what files are included by the sources
535 of a given derived file:
538 $ scons --debug=includes foo.o
543 Prints a summary of hits and misses in the Memoizer,
544 the internal SCons subsystem for caching
545 various values in memory instead of
546 recomputing them each time they're needed.
550 Prints how much memory SCons uses
551 before and after reading the SConscript files
552 and before and after building targets.
556 Disables use of the Memoizer,
557 the internal SCons subsystem for caching
558 various values in memory instead of
559 recomputing them each time they're needed.
560 This provides more accurate counts of the
561 underlying function calls in the
562 Python profiler output when using the
565 (When the Memoizer is used,
566 the profiler counts all
567 memoized functions as being executed
568 by the Memoizer's wrapper calls.)
572 Prints a list of the various objects
573 of the various classes used internally by SCons.
574 This only works when run under Python 2.1 or later.
578 Re-run SCons under the control of the
584 Print the raw command line used to build each target
585 before the construction environment variables are substituted.
586 Also shows which targets are being built by this command.
587 Output looks something like this:
589 $ scons --debug=presub
590 Building myprog.o with action(s):
591 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
597 Prints an internal Python stack trace
598 when encountering an otherwise unexplained error.
602 Print the dependency tree along with status information. This is the
603 same as the debug=tree option, but additional status information is
604 provided for each node in the tree.
608 Prints various time profiling information: the time spent
609 executing each build command, the total build time, the total time spent
610 executing build commands, the total time spent executing SConstruct and
611 SConscript files, and the total time spent executing SCons itself.
615 Print the dependency tree
616 after each top-level target is built. This prints out the complete
617 dependency tree including implicit dependencies and ignored
621 .RI --diskcheck= types
622 Enable specific checks for
623 whether or not there is a file on disk
624 where the SCons configuration expects a directory
626 and whether or not RCS or SCCS sources exist
627 when searching for source and include files.
630 argument can be set to:
632 to enable all checks explicitly
633 (the default behavior);
635 to disable all such checks;
637 to check that files and directories on disk
638 match SCons' expected configuration;
640 to check for the existence of an RCS source
641 for any missing source or include files;
643 to check for the existence of an SCCS source
644 for any missing source or include files.
645 Multiple checks can be specified separated by commas;
647 .B --diskcheck=sccs,rcs
648 would still check for SCCS and RCS sources,
649 but disable the check for on-disk matches of files and directories.
650 Disabling some or all of these checks
651 can provide a performance boost for large configurations,
652 or when the configuration will check for files and/or directories
653 across networked or shared file systems,
654 at the slight increased risk of an incorrect build
655 or of not handling errors gracefully
656 (if include files really should be
657 found in SCCS or RCS, for example,
658 or if a file really does exist
659 where the SCons configuration expects a directory).
662 .\" -e, --environment-overrides
663 .\" Variables from the execution environment override construction
664 .\" variables from the SConscript files.
667 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
670 as the initial SConscript file.
674 Print a local help message for this build, if one is defined in
675 the SConscript file(s), plus a line that describes the
677 option for command-line option help. If no local help message
678 is defined, prints the standard help message about command-line
679 options. Exits after displaying the appropriate message.
683 Print the standard help message about command-line options and
688 Ignore all errors from commands executed to rebuild files.
691 .RI -I " directory" ", --include-dir=" directory
695 imported Python modules. If several
698 are used, the directories are searched in the order specified.
702 Cache implicit dependencies. This can cause
704 to miss changes in the implicit dependencies in cases where a new implicit
705 dependency is added earlier in the implicit dependency search path
706 (e.g. CPPPATH) than a current implicit dependency with the same name.
709 --implicit-deps-changed
710 Force SCons to ignore the cached implicit dependencies. This causes the
711 implicit dependencies to be rescanned and recached. This implies
712 .BR --implicit-cache .
715 --implicit-deps-unchanged
716 Force SCons to ignore changes in the implicit dependencies.
717 This causes cached implicit dependencies to always be used.
719 .BR --implicit-cache .
722 .RI -j " N" ", --jobs=" N
723 Specifies the number of jobs (commands) to run simultaneously.
724 If there is more than one
726 option, the last one is effective.
730 .\" is specified without an argument,
732 .\" will not limit the number of
733 .\" simultaneous jobs.
737 Continue as much as possible after an error. The target that
738 failed and those that depend on it will not be remade, but other
739 targets specified on the command line will still be processed.
742 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
743 .\" No new jobs (commands) will be started if
744 .\" there are other jobs running and the system load
745 .\" average is at least
747 .\" (a floating-point number).
750 .RI --duplicate= ORDER
751 There are three ways to duplicate files in a build tree: hard links,
752 soft (symbolic) links and copies. The default behaviour of SCons is to
753 prefer hard links to soft links to copies. You can specify different
754 behaviours with this option.
764 SCons will attempt to duplicate files using
765 the mechanisms in the specified order.
770 .\" List derived files (targets, dependencies) that would be built,
771 .\" but do not build them.
772 .\" [XXX This can probably go away with the right
773 .\" combination of other options. Revisit this issue.]
777 .\" List derived files that would be built, with the actions
778 .\" (commands) that build them. Does not build the files.
779 .\" [XXX This can probably go away with the right
780 .\" combination of other options. Revisit this issue.]
784 .\" List derived files that would be built, plus where the file is
785 .\" defined (file name and line number). Does not build the files.
786 .\" [XXX This can probably go away with the right
787 .\" combination of other options. Revisit this issue.]
791 Ignored for compatibility with non-GNU versions of
795 .RI --max-drift= SECONDS
796 Set the maximum expected drift in the modification time of files to
798 This value determines how long a file must be unmodified
799 before its cached content signature
800 will be used instead of
801 calculating a new content signature (MD5 checksum)
802 of the file's contents.
803 The default value is 2 days, which means a file must have a
804 modification time of at least two days ago in order to have its
805 cached content signature used.
806 A negative value means to never cache the content
807 signature and to ignore the cached value if there already is one. A value
808 of 0 means to always use the cached signature,
809 no matter how old the file is.
812 -n, --just-print, --dry-run, --recon
813 No execute. Print the commands that would be executed to build
814 any out-of-date target files, but do not execute the commands.
817 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
821 .\" not rebuild anything due to changes in the contents of
824 .\" .RI --override " file"
825 .\" Read values to override specific build environment variables
826 .\" from the specified
830 .\" Print the data base (construction environments,
831 .\" Builder and Scanner objects) that are defined
832 .\" after reading the SConscript files.
833 .\" After printing, a normal build is performed
834 .\" as usual, as specified by other command-line options.
835 .\" This also prints version information
840 .\" To print the database without performing a build do:
848 Run SCons under the Python profiler
849 and save the results in the specified
851 The results may be analyzed using the Python
855 Do not run any commands, or print anything. Just return an exit
856 status that is zero if the specified targets are already up to
857 date, non-zero otherwise.
860 Quiets SCons status messages about
861 reading SConscript files,
863 and entering directories.
864 Commands that are executed
865 to rebuild target files are still printed.
868 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
869 .\" Clear the default construction variables. Construction
870 .\" environments that are created will be completely empty.
874 Build dependencies in a random order. This is useful when
875 building multiple trees simultaneously with caching enabled,
876 to prevent multiple builds from simultaneously trying to build
877 or retrieve the same target files.
880 -s, --silent, --quiet
881 Silent. Do not print commands that are executed to rebuild
883 Also suppresses SCons status messages.
886 -S, --no-keep-going, --stop
887 Ignored for compatibility with GNU
892 Ignored for compatibility with GNU
894 (Touching a file to make it
895 appear up-to-date is unnecessary when using
899 -u, --up, --search-up
900 Walks up the directory structure until an
905 file is found, and uses that
906 as the top of the directory tree.
907 If no targets are specified on the command line,
908 only targets at or below the
909 current directory will be built.
913 Works exactly the same way as the
915 option except for the way default targets are handled.
916 When this option is used and no targets are specified on the command line,
917 all default targets that are defined in the SConscript(s) in the current
918 directory are built, regardless of what directory the resultant targets end
925 version, copyright information,
926 list of authors, and any other relevant information.
930 -w, --print-directory
931 Print a message containing the working directory before and
932 after other processing.
935 .RI --warn= type ", --warn=no-" type
936 Enable or disable warnings.
938 specifies the type of warnings to be enabled or disabled:
941 --warn=all, --warn=no-all
942 Enables or disables all warnings.
945 --warn=dependency, --warn=no-dependency
946 Enables or disables warnings about dependencies.
947 These warnings are disabled by default.
950 --warn=deprecated, --warn=no-deprecated
951 Enables or disables warnings about use of deprecated features.
952 These warnings are enabled by default.
955 --warn=missing-sconscript, --warn=no-missing-sconscript
956 Enables or disables warnings about missing SConscript files.
957 These warnings are enabled by default.
961 Turn off -w, even if it was turned on implicitly.
964 .\" .RI --write-filenames= file
965 .\" Write all filenames considered into
969 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
970 .\" Pretend that the target
973 .\" modified. When used with the
976 .\" show you what would be rebuilt if you were to modify that file.
982 .\" --warn-undefined-variables
983 .\" Warn when an undefined variable is referenced.
986 .RI -Y " repository" ", --repository=" repository
987 Search the specified repository for any input and target
988 files not found in the local directory hierarchy. Multiple
990 options may specified, in which case the
991 repositories are searched in the order specified.
993 .SH CONFIGURATION FILE REFERENCE
994 .\" .SS Python Basics
995 .\" XXX Adding this in the future would be a help.
996 .SS Construction Environments
997 A construction environment is the basic means by which the SConscript
998 files communicate build information to
1000 A new construction environment is created using the
1008 By default, a new construction environment is
1009 initialized with a set of builder methods
1010 and construction variables that are appropriate
1011 for the current platform.
1012 An optional platform keyword argument may be
1013 used to specify that an environment should
1014 be initialized for a different platform:
1017 env = Environment(platform = 'cygwin')
1018 env = Environment(platform = 'os2')
1019 env = Environment(platform = 'posix')
1020 env = Environment(platform = 'win32')
1023 Specifying a platform initializes the appropriate
1024 construction variables in the environment
1025 to use and generate file names with prefixes
1026 and suffixes appropriate for the platform.
1032 variable from the user's external environment
1033 to the construction environment's
1036 This is so that any executed commands
1037 that use sockets to connect with other systems
1038 (such as fetching source files from
1039 external CVS repository specifications like
1040 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1041 will work on Win32 systems.
1043 The platform argument may be function or callable object,
1044 in which case the Environment() method
1045 will call the specified argument to update
1046 the new construction environment:
1049 def my_platform(env):
1050 env['VAR'] = 'xyzzy'
1052 env = Environment(platform = my_platform)
1055 Additionally, a specific set of tools
1056 with which to initialize the environment
1057 may specified as an optional keyword argument:
1060 env = Environment(tools = ['msvc', 'lex'])
1063 Non-built-in tools may be specified using the toolpath argument:
1066 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1069 This looks for a tool specification in tools/foo.py (as well as
1070 using the ordinary default tools for the platform). foo.py should
1071 have two functions: generate(env, **kw) and exists(env).
1075 modifies the passed-in environment
1076 to set up variables so that the tool
1078 it may use any keyword arguments
1079 that the user supplies (see below)
1080 to vary its initialization.
1083 function should return a true
1084 value if the tool is available.
1085 Tools in the toolpath are used before
1086 any of the built-in ones. For example, adding gcc.py to the toolpath
1087 would override the built-in gcc tool.
1088 Also note that the toolpath is
1089 stored in the environment for use
1097 base = Environment(toolpath=['custom_path'])
1098 derived = base.Copy(tools=['custom_tool'])
1099 derived.CustomBuilder()
1102 The elements of the tools list may also
1103 be functions or callable objects,
1104 in which case the Environment() method
1105 will call the specified elements
1106 to update the new construction environment:
1110 env['XYZZY'] = 'xyzzy'
1112 env = Environment(tools = [my_tool])
1115 The individual elements of the tools list
1116 may also themselves be two-element lists of the form
1117 .RI ( toolname ", " kw_dict ).
1118 SCons searches for the
1120 specification file as described above, and
1123 which must be a dictionary, as keyword arguments to the tool's
1128 function can use the arguments to modify the tool's behavior
1129 by setting up the environment in different ways
1130 or otherwise changing its initialization.
1133 # in tools/my_tool.py:
1134 def generate(env, **kw):
1135 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1136 env['MY_TOOL'] = kw.get('arg1', '1')
1141 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1145 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1146 the environment it receives to customize the tool for different platforms.
1148 If no tool list is specified, then SCons will auto-detect the installed
1149 tools using the PATH variable in the ENV construction variable and the
1150 platform name when the Environment is constructed. Changing the PATH
1151 variable after the Environment is constructed will not cause the tools to
1154 SCons supports the following tool specifications out of the box:
1230 Additionally, there is a "tool" named
1232 which configures the
1233 environment with a default set of tools for the current platform.
1235 On posix and cygwin platforms
1236 the GNU tools (e.g. gcc) are preferred by SCons,
1237 on win32 the Microsoft tools (e.g. msvc)
1238 followed by MinGW are preferred by SCons,
1239 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1243 Build rules are specified by calling a construction
1244 environment's builder methods.
1245 The arguments to the builder methods are
1247 (a list of target files)
1250 (a list of source files).
1252 Because long lists of file names
1253 can lead to a lot of quoting,
1258 and a same-named environment method
1259 that split a single string
1260 into a list, separated on
1261 strings of white-space characters.
1262 (These are similar to the
1263 string.split() method
1264 from the standard Python library,
1265 but work even if the input isn't a string.)
1267 Like all Python arguments,
1268 the target and source arguments to a builder method
1269 can be specified either with or without
1270 the "target" and "source" keywords.
1271 When the keywords are omitted,
1272 the target is first,
1273 followed by the source.
1274 The following are equivalent examples of calling the Program builder method:
1277 env.Program('bar', ['bar.c', 'foo.c'])
1278 env.Program('bar', Split('bar.c foo.c'))
1279 env.Program('bar', env.Split('bar.c foo.c'))
1280 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1281 env.Program(target = 'bar', Split('bar.c foo.c'))
1282 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1283 env.Program('bar', source = string.split('bar.c foo.c'))
1286 When the target shares the same base name
1287 as the source and only the suffix varies,
1288 and if the builder method has a suffix defined for the target file type,
1289 then the target argument may be omitted completely,
1292 will deduce the target file name from
1293 the source file name.
1294 The following examples all build the
1300 (on Windows systems)
1301 from the bar.c source file:
1304 env.Program(target = 'bar', source = 'bar.c')
1305 env.Program('bar', source = 'bar.c')
1306 env.Program(source = 'bar.c')
1307 env.Program('bar.c')
1310 It is possible to override or add construction variables when calling a
1311 builder method by passing additional keyword arguments.
1312 These overridden or added
1313 variables will only be in effect when building the target, so they will not
1314 affect other parts of the build. For example, if you want to add additional
1315 libraries for just one program:
1318 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1321 or generate a shared library with a nonstandard suffix:
1324 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1327 Although the builder methods defined by
1330 methods of a construction environment object,
1331 they may also be called without an explicit environment:
1334 Program('hello', 'hello.c')
1335 SharedLibrary('word', 'word.cpp')
1339 the methods are called internally using a default construction
1340 environment that consists of the tools and values that
1342 has determined are appropriate for the local system.
1344 Builder methods that can be called without an explicit
1345 environment may be called from custom Python modules that you
1346 import into an SConscript file by adding the following
1347 to the Python module:
1350 from SCons.Script import *
1353 All builder methods return a list of Nodes
1354 that represent the target or targets that will be built.
1357 is an internal SCons object
1359 build targets or sources.
1361 The returned Node(s)
1362 can be passed to other builder methods as source(s)
1363 or passed to any SCons function or method
1364 where a filename would normally be accepted.
1365 For example, if it were necessary
1368 flag when compiling one specific object file:
1371 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1372 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1375 Using a Node in this way
1376 makes for a more portable build
1377 by avoiding having to specify
1378 a platform-specific object suffix
1379 when calling the Program() builder method.
1381 Note that Builder calls will automatically "flatten"
1382 the source and target file lists,
1383 so it's all right to have the bar_obj list
1384 return by the StaticObject() call
1385 in the middle of the source file list.
1386 If you need to manipulate a list of lists returned by Builders
1387 directly using Python,
1388 you can either build the list by hand:
1391 foo = Object('foo.c')
1392 bar = Object('bar.c')
1393 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1394 for object in objects:
1401 to create a list containing just the Nodes,
1402 which may be more convenient:
1405 foo = Object('foo.c')
1406 bar = Object('bar.c')
1407 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1408 for object in objects:
1412 The path name for a Node's file may be used
1413 by passing the Node to the Python-builtin
1418 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1419 print "The path to bar_obj is:", str(bar_obj_list[0])
1422 Note again that because the Builder call returns a list,
1423 we have to access the first element in the list
1424 .B (bar_obj_list[0])
1425 to get at the Node that actually represents
1428 Builder calls support a
1430 keyword argument that
1431 specifies that the Builder's action(s)
1433 after changing directory.
1437 a string or a directory Node,
1438 scons will change to the specified directory.
1441 is not a string or Node
1443 then scons will change to the
1444 target file's directory.
1447 # scons will change to the "sub" subdirectory
1448 # before executing the "cp" command.
1449 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1450 "cp dir/foo.in dir/foo.out",
1453 # Because chdir is not a string, scons will change to the
1454 # target's directory ("sub/dir") before executing the
1456 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1457 "cp foo.in foo.out",
1461 Note that scons will
1463 automatically modify
1465 construction variables like
1469 when using the chdir
1470 keyword argument--that is,
1471 the expanded file names
1472 will still be relative to
1473 the top-level SConstruct directory,
1474 and consequently incorrect
1475 relative to the chdir directory.
1476 If you use the chdir keyword argument,
1477 you will typically need to supply a different
1483 to use just the filename portion of the
1487 provides the following builder methods:
1489 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1492 Builds a C source file given a lex (.l) or yacc (.y) input file.
1493 The suffix specified by the $CFILESUFFIX construction variable
1495 is automatically added to the target
1496 if it is not already present. Example:
1500 env.CFile(target = 'foo.c', source = 'foo.l')
1502 env.CFile(target = 'bar', source = 'bar.y')
1505 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1508 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1510 The suffix specified by the $CXXFILESUFFIX construction variable
1512 is automatically added to the target
1513 if it is not already present. Example:
1517 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1519 env.CXXFile(target = 'bar', source = 'bar.yy')
1522 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1525 Builds a .dvi file from a .tex, .ltx or .latex input file.
1526 If the source file suffix is .tex,
1528 will examine the contents of the file;
1533 is found, the file is assumed to be a LaTeX file and
1534 the target is built by invoking the $LATEXCOM command line;
1535 otherwise, the $TEXCOM command line is used.
1536 If the file is a LaTeX file,
1539 builder method will also examine the contents
1542 and invoke the $BIBTEX command line
1546 and will examine the contents
1548 file and re-run the $LATEXCOM command
1549 if the log file says it is necessary.
1552 (hard-coded within TeX itself)
1553 is automatically added to the target
1554 if it is not already present. Examples:
1557 # builds from aaa.tex
1558 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1560 env.DVI(target = 'bbb', source = 'bbb.ltx')
1561 # builds from ccc.latex
1562 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1565 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1568 Builds a Java archive (.jar) file
1569 from a source tree of .class files.
1570 If the $JARCHDIR value is set, the
1572 command will change to the specified directory using the
1575 If the contents any of the source files begin with the string
1576 .BR Manifest-Version ,
1577 the file is assumed to be a manifest
1578 and is passed to the
1585 env.Jar(target = 'foo.jar', source = 'classes')
1588 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1591 Builds one or more Java class files
1592 from one or more source trees of .java files.
1593 The class files will be placed underneath
1594 the specified target directory.
1595 SCons will parse each source .java file
1597 (including inner classes)
1598 defined within that file,
1599 and from that figure out the
1600 target .class files that will be created.
1601 SCons will also search each Java file
1602 for the Java package name,
1603 which it assumes can be found on a line
1604 beginning with the string
1606 in the first column;
1607 the resulting .class files
1608 will be placed in a directory reflecting
1609 the specified package name.
1613 defining a single public
1616 containing a package name of
1618 will generate a corresponding
1619 .IR sub/dir/Foo.class
1625 env.Java(target = 'classes', source = 'src')
1626 env.Java(target = 'classes', source = ['src1', 'src2'])
1629 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1632 Builds C header and source files for
1633 implementing Java native methods.
1634 The target can be either a directory
1635 in which the header files will be written,
1636 or a header file name which
1637 will contain all of the definitions.
1638 The source can be either the names of .class files,
1639 or the objects returned from the
1643 If the construction variable
1645 is set, either in the environment
1646 or in the call to the
1648 builder method itself,
1649 then the value of the variable
1650 will be stripped from the
1651 beginning of any .class file names.
1656 # builds java_native.h
1657 classes = env.Java(target = 'classdir', source = 'src')
1658 env.JavaH(target = 'java_native.h', source = classes)
1660 # builds include/package_foo.h and include/package_bar.h
1661 env.JavaH(target = 'include',
1662 source = ['package/foo.class', 'package/bar.class'])
1664 # builds export/foo.h and export/bar.h
1665 env.JavaH(target = 'export',
1666 source = ['classes/foo.class', 'classes/bar.class'],
1667 JAVACLASSDIR = 'classes')
1670 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1677 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1678 .IP LoadableModule()
1679 .IP env.LoadableModule()
1682 .BR SharedLibrary ().
1683 On Mac OS X (Darwin) platforms,
1684 this creates a loadable module bundle.
1687 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1690 Builds an output file from an M4 input file.
1691 This uses a default $M4FLAGS value of
1693 which considers all warnings to be fatal
1694 and stops on the first warning
1695 when using the GNU version of m4.
1699 env.M4(target = 'foo.c', source = 'foo.c.m4')
1702 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1705 Builds an output file from a moc input file. Moc input files are either
1706 header files or cxx files. This builder is only available after using the
1707 tool 'qt'. See the QTDIR variable for more information.
1711 env.Moc('foo.h') # generates moc_foo.cc
1712 env.Moc('foo.cpp') # generates foo.moc
1715 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1717 .IP env.MSVSProject()
1718 Builds Microsoft Visual Studio project files.
1719 This builds a Visual Studio project file, based on the version of
1720 Visual Studio that is configured (either the latest installed version,
1721 or the version set by
1723 in the Environment constructor).
1724 For VS 6, it will generate
1728 files, for VS 7, it will
1735 It takes several lists of filenames to be placed into the project
1736 file, currently these are limited to
1737 .B srcs, incs, localincs, resources,
1740 These are pretty self explanatory, but it
1741 should be noted that the 'srcs' list is NOT added to the $SOURCES
1742 environment variable. This is because it represents a list of files
1743 to be added to the project file, not the source used to build the
1744 project file (in this case, the 'source' is the SConscript file used
1745 to call MSVSProject).
1747 In addition to these values (which are all optional, although not
1748 specifying any of them results in an empty project file), the
1749 following values must be specified:
1751 target: The name of the target .dsp or .vcproj file. The correct
1752 suffix for the version of Visual Studio must be used, but the value
1754 env['MSVSPROJECTSUFFIX']
1756 will be defined to the correct value (see example below).
1758 variant: The name of this particular variant. These are typically
1759 things like "Debug" or "Release", but really can be anything you want.
1760 Multiple calls to MSVSProject with different variants are allowed: all
1761 variants will be added to the project file with their appropriate
1762 build targets and sources.
1764 buildtarget: A list of SCons.Node.FS objects which is returned from
1765 the command which builds the target. This is used to tell SCons what
1766 to build when the 'build' button is pressed inside of the IDE.
1771 barsrcs = ['bar.cpp'],
1772 barincs = ['bar.h'],
1773 barlocalincs = ['StdAfx.h']
1774 barresources = ['bar.rc','resource.h']
1775 barmisc = ['bar_readme.txt']
1777 dll = local.SharedLibrary(target = 'bar.dll',
1780 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1783 localincs = barlocalincs,
1784 resources = barresources,
1787 variant = 'Release')
1790 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1797 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1800 Builds a Microsoft Visual C++ precompiled header.
1801 Calling this builder method
1802 returns a list of two targets: the PCH as the first element, and the object
1803 file as the second element. Normally the object file is ignored.
1804 This builder method is only
1805 provided when Microsoft Visual C++ is being used as the compiler.
1806 The PCH builder method is generally used in
1807 conjuction with the PCH construction variable to force object files to use
1808 the precompiled header:
1811 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1814 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1817 Builds a .pdf file from a .dvi input file
1818 (or, by extension, a .tex, .ltx, or .latex input file).
1819 The suffix specified by the $PDFSUFFIX construction variable
1821 is added automatically to the target
1822 if it is not already present. Example:
1825 # builds from aaa.tex
1826 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1827 # builds bbb.pdf from bbb.dvi
1828 env.PDF(target = 'bbb', source = 'bbb.dvi')
1831 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1833 .IP env.PostScript()
1834 Builds a .ps file from a .dvi input file
1835 (or, by extension, a .tex, .ltx, or .latex input file).
1836 The suffix specified by the $PSSUFFIX construction variable
1838 is added automatically to the target
1839 if it is not already present. Example:
1842 # builds from aaa.tex
1843 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1844 # builds bbb.ps from bbb.dvi
1845 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1848 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1851 Builds an executable given one or more object files
1852 or C, C++, D, or Fortran source files.
1853 If any C, C++, D or Fortran source files are specified,
1854 then they will be automatically
1855 compiled to object files using the
1858 see that builder method's description for
1859 a list of legal source file suffixes
1860 and how they are interpreted.
1861 The target executable file prefix
1862 (specified by the $PROGPREFIX construction variable; nothing by default)
1864 (specified by the $PROGSUFFIX construction variable;
1865 by default, .exe on Windows systems, nothing on POSIX systems)
1866 are automatically added to the target if not already present.
1870 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1873 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1876 Builds a Microsoft Visual C++ resource file.
1877 This builder method is only provided
1878 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1882 for MinGW) suffix is added to the target name if no other suffix is given. The source
1883 file is scanned for implicit dependencies as though it were a C file. Example:
1886 env.RES('resource.rc')
1889 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1892 Builds stub and skeleton class files
1894 from Java .class files.
1895 The target is a directory
1896 relative to which the stub
1897 and skeleton class files will be written.
1898 The source can be the names of .class files,
1899 or the objects return from the
1903 If the construction variable
1905 is set, either in the environment
1906 or in the call to the
1908 builder method itself,
1909 then the value of the variable
1910 will be stripped from the
1911 beginning of any .class file names.
1914 classes = env.Java(target = 'classdir', source = 'src')
1915 env.RMIC(target = 'outdir1', source = classes)
1917 env.RMIC(target = 'outdir2',
1918 source = ['package/foo.class', 'package/bar.class'])
1920 env.RMIC(target = 'outdir3',
1921 source = ['classes/foo.class', 'classes/bar.class'],
1922 JAVACLASSDIR = 'classes')
1925 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1927 .IP env.RPCGenClient()
1928 Generates an RPC client stub (_clnt.c) file
1929 from a specified RPC (.x) source file.
1930 Because rpcgen only builds output files
1931 in the local directory,
1932 the command will be executed
1933 in the source file's directory by default.
1936 # Builds src/rpcif_clnt.c
1937 env.RPCGenClient('src/rpcif.x')
1940 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1942 .IP env.RPCGenHeader()
1943 Generates an RPC header (.h) file
1944 from a specified RPC (.x) source file.
1945 Because rpcgen only builds output files
1946 in the local directory,
1947 the command will be executed
1948 in the source file's directory by default.
1951 # Builds src/rpcif.h
1952 env.RPCGenHeader('src/rpcif.x')
1955 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1957 .IP env.RPCGenService()
1958 Generates an RPC server-skeleton (_svc.c) file
1959 from a specified RPC (.x) source file.
1960 Because rpcgen only builds output files
1961 in the local directory,
1962 the command will be executed
1963 in the source file's directory by default.
1966 # Builds src/rpcif_svc.c
1967 env.RPCGenClient('src/rpcif.x')
1970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1973 Generates an RPC XDR routine (_xdr.c) file
1974 from a specified RPC (.x) source file.
1975 Because rpcgen only builds output files
1976 in the local directory,
1977 the command will be executed
1978 in the source file's directory by default.
1981 # Builds src/rpcif_xdr.c
1982 env.RPCGenClient('src/rpcif.x')
1985 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1987 .IP env.SharedLibrary()
1988 Builds a shared library
1989 (.so on a POSIX system, .dll on WIN32)
1990 given one or more object files
1991 or C, C++, D or Fortran source files.
1992 If any source files are given,
1993 then they will be automatically
1994 compiled to object files.
1995 The static library prefix and suffix (if any)
1996 are automatically added to the target.
1997 The target library file prefix
1998 (specified by the $SHLIBPREFIX construction variable;
1999 by default, lib on POSIX systems, nothing on Windows systems)
2001 (specified by the $SHLIBSUFFIX construction variable;
2002 by default, .dll on Windows systems, .so on POSIX systems)
2003 are automatically added to the target if not already present.
2007 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2010 On WIN32 systems, the
2012 builder method will always build an import (.lib) library
2013 in addition to the shared (.dll) library,
2014 adding a .lib library with the same basename
2015 if there is not already a .lib file explicitly
2016 listed in the targets.
2018 Any object files listed in the
2020 must have been built for a shared library
2025 will raise an error if there is any mismatch.
2027 On WIN32 systems, specifying "register=1" will cause the dll to be
2028 registered after it is built using REGSVR32. The command that is run
2029 ("regsvr32" by default) is determined by $REGSVR construction
2030 variable, and the flags passed are determined by $REGSVRFLAGS. By
2031 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
2032 up and requiring user attention when it is run. If you change
2033 $REGSVRFLAGS, be sure to include "/s". For example,
2036 env.SharedLibrary(target = 'bar',
2037 source = ['bar.cxx', 'foo.obj'],
2042 will register "bar.dll" as a COM object when it is done linking it.
2044 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2046 .IP env.SharedObject()
2047 Builds an object file for
2048 inclusion in a shared library.
2049 Source files must have one of the same set of extensions
2050 specified above for the
2053 On some platforms building a shared object requires additional
2054 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
2055 normal (static) object, but on some platforms there is no difference between a
2056 shared object and a normal (static) one. When there is a difference, SCons
2057 will only allow shared objects to be linked into a shared library, and will
2058 use a different suffix for shared objects. On platforms where there is no
2059 difference, SCons will allow both normal (static)
2060 and shared objects to be linked into a
2061 shared library, and will use the same suffix for shared and normal
2063 The target object file prefix
2064 (specified by the $SHOBJPREFIX construction variable;
2065 by default, the same as $OBJPREFIX)
2067 (specified by the $SHOBJSUFFIX construction variable)
2068 are automatically added to the target if not already present.
2072 env.SharedObject(target = 'ddd', source = 'ddd.c')
2073 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2074 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2077 Note that the source files will be scanned
2078 according to the suffix mappings in
2079 .B SourceFileScanner
2081 See the section "Scanner Objects,"
2082 below, for a more information.
2084 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2086 .IP env.StaticLibrary()
2087 Builds a static library given one or more object files
2088 or C, C++, D or Fortran source files.
2089 If any source files are given,
2090 then they will be automatically
2091 compiled to object files.
2092 The static library prefix and suffix (if any)
2093 are automatically added to the target.
2094 The target library file prefix
2095 (specified by the $LIBPREFIX construction variable;
2096 by default, lib on POSIX systems, nothing on Windows systems)
2098 (specified by the $LIBSUFFIX construction variable;
2099 by default, .lib on Windows systems, .a on POSIX systems)
2100 are automatically added to the target if not already present.
2104 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2108 Any object files listed in the
2110 must have been built for a static library
2115 will raise an error if there is any mismatch.
2117 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2119 .IP env.StaticObject()
2120 Builds a static object file
2121 from one or more C, C++, D, or Fortran source files.
2122 Source files must have one of the following extensions:
2125 .asm assembly language file
2126 .ASM assembly language file
2138 .F WIN32: Fortran file
2139 POSIX: Fortran file + C pre-processor
2142 .fpp Fortran file + C pre-processor
2143 .FPP Fortran file + C pre-processor
2145 .mm Objective C++ file
2146 .s assembly language file
2147 .S WIN32: assembly language file
2148 POSIX: assembly language file + C pre-processor
2149 .spp assembly language file + C pre-processor
2150 .SPP assembly language file + C pre-processor
2153 The target object file prefix
2154 (specified by the $OBJPREFIX construction variable; nothing by default)
2156 (specified by the $OBJSUFFIX construction variable;
2157 \.obj on Windows systems, .o on POSIX systems)
2158 are automatically added to the target if not already present.
2162 env.StaticObject(target = 'aaa', source = 'aaa.c')
2163 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2164 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2167 Note that the source files will be scanned
2168 according to the suffix mappings in
2169 .B SourceFileScanner
2171 See the section "Scanner Objects,"
2172 below, for a more information.
2174 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2177 Builds a tar archive of the specified files
2179 Unlike most builder methods,
2182 builder method may be called multiple times
2184 each additional call
2185 adds to the list of entries
2186 that will be built into the archive.
2187 Any source directories will
2188 be scanned for changes to
2190 regardless of whether or not
2192 knows about them from other Builder or function calls.
2195 env.Tar('src.tar', 'src')
2197 # Create the stuff.tar file.
2198 env.Tar('stuff', ['subdir1', 'subdir2'])
2199 # Also add "another" to the stuff.tar file.
2200 env.Tar('stuff', 'another')
2202 # Set TARFLAGS to create a gzip-filtered archive.
2203 env = Environment(TARFLAGS = '-c -z')
2204 env.Tar('foo.tar.gz', 'foo')
2206 # Also set the suffix to .tgz.
2207 env = Environment(TARFLAGS = '-c -z',
2212 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2214 .IP env.TypeLibrary()
2215 Builds a Windows type library (.tlb) file from and input IDL file
2216 (.idl). In addition, it will build the associated inteface stub and
2217 proxy source files. It names them according to the base name of the .idl file.
2222 env.TypeLibrary(source="foo.idl")
2225 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2227 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2230 Builds a header file, an implementation file and a moc file from an ui file.
2231 and returns the corresponding nodes in the above order.
2232 This builder is only available after using the tool 'qt'. Note: you can
2233 specify .ui files directly as inputs for Program, Library and SharedLibrary
2234 without using this builder. Using the builder lets you override the standard
2235 naming conventions (be careful: prefixes are always prepended to names of
2236 built files; if you don't want prefixes, you may set them to ``).
2237 See the QTDIR variable for more information.
2241 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2242 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2243 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2246 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2249 Builds a zip archive of the specified files
2251 Unlike most builder methods,
2254 builder method may be called multiple times
2256 each additional call
2257 adds to the list of entries
2258 that will be built into the archive.
2259 Any source directories will
2260 be scanned for changes to
2262 regardless of whether or not
2264 knows about them from other Builder or function calls.
2267 env.Zip('src.zip', 'src')
2269 # Create the stuff.zip file.
2270 env.Zip('stuff', ['subdir1', 'subdir2'])
2271 # Also add "another" to the stuff.tar file.
2272 env.Zip('stuff', 'another')
2276 targets of builder methods automatically depend on their sources.
2277 An explicit dependency can
2278 be specified using the
2280 method of a construction environment (see below).
2285 source files for various programming languages,
2286 so the dependencies do not need to be specified explicitly.
2287 By default, SCons can
2290 Fortran source files with
2292 (POSIX systems only),
2297 and assembly language files with
2299 (POSIX systems only),
2304 for C preprocessor dependencies.
2305 SCons also has default support
2306 for scanning D source files,
2307 You can also write your own Scanners
2308 to add support for additional source file types.
2309 These can be added to the default
2310 Scanner object used by
2316 Builders by adding them
2318 .B SourceFileScanner
2321 See the section "Scanner Objects,"
2322 below, for a more information about
2323 defining your own Scanner objects.
2325 .SS Methods and Functions to Do Things
2326 In addition to Builder methods,
2328 provides a number of other construction environment methods
2329 and global functions to
2330 manipulate the build configuration.
2332 Usually, a construction environment method
2333 and global function with the same name both exist
2334 so that you don't have to remember whether
2335 to a specific bit of functionality
2336 must be called with or without a construction environment.
2337 In the following list,
2338 if you call something as a global function
2341 .RI Function( arguments )
2343 and if you call something through a construction
2344 environment it looks like:
2346 .RI env.Function( arguments )
2348 If you can call the functionality in both ways,
2349 then both forms are listed.
2351 Global functions may be called from custom Python modules that you
2352 import into an SConscript file by adding the following
2353 to the Python module:
2356 from SCons.Script import *
2359 Except where otherwise noted,
2361 construction environment method
2363 provide the exact same functionality.
2364 The only difference is that,
2366 calling the functionality through a construction environment will
2367 substitute construction variables into
2368 any supplied strings.
2371 env = Environment(FOO = 'foo')
2375 the first call to the global
2377 function will actually add a target named
2379 to the list of default targets,
2380 while the second call to the
2382 construction environment method
2383 will expand the value
2384 and add a target named
2386 to the list of default targets.
2387 For more on construction variable expansion,
2388 see the next section on
2389 construction variables.
2391 Construction environment methods
2392 and global functions supported by
2396 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2398 .RI Action( action ", [" strfunction ", " varlist ])
2400 .RI env.Action( action ", [" strfunction ", " varlist ])
2401 Creates an Action object for
2404 See the section "Action Objects,"
2405 below, for a complete explanation of the arguments and behavior.
2407 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2409 .RI AddPostAction( target ", " action )
2411 .RI env.AddPostAction( target ", " action )
2412 Arranges for the specified
2418 The specified action(s) may be
2419 an Action object, or anything that
2420 can be converted into an Action object
2423 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2425 .RI AddPreAction( target ", " action )
2427 .RI env.AddPreAction( target ", " action )
2428 Arranges for the specified
2431 before the specified
2434 The specified action(s) may be
2435 an Action object, or anything that
2436 can be converted into an Action object
2439 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2441 .RI Alias( alias ", [" targets ", [" action ]])
2443 .RI env.Alias( alias ", [" targets ", [" action ]])
2444 Creates one or more phony targets that
2445 expand to one or more other targets.
2450 can be specified that will be executed
2451 whenever the any of the alias targets are out-of-date.
2452 Returns the Node object representing the alias,
2453 which exists outside of any file system.
2454 This Node object, or the alias name,
2455 may be used as a dependency of any other target,
2456 including another alias.
2458 can be called multiple times for the same
2459 alias to add additional targets to the alias,
2460 or additional actions to the list for this alias.
2464 Alias('install', '/usr/bin')
2465 Alias(['install', 'install-lib'], '/usr/local/lib')
2467 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2468 env.Alias('install', ['/usr/local/man'])
2470 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2473 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2475 .RI AlwaysBuild( target ", ...)"
2477 .RI env.AlwaysBuild( target ", ...)"
2480 so that it is always assumed to be out of date,
2481 and will always be rebuilt if needed.
2484 does not add its target(s) to the default target list,
2485 so the targets will only be built
2486 if they are specified on the command line,
2487 or are a dependent of a target specified on the command line--but
2490 be built if so specified.
2491 Multiple targets can be passed in to a single call to
2494 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2496 .RI env.Append( key = val ", [...])"
2497 Appends the specified keyword arguments
2498 to the end of construction variables in the environment.
2499 If the Environment does not have
2500 the specified construction variable,
2501 it is simply added to the environment.
2502 If the values of the construction variable
2503 and the keyword argument are the same type,
2504 then the two values will be simply added together.
2505 Otherwise, the construction variable
2506 and the value of the keyword argument
2507 are both coerced to lists,
2508 and the lists are added together.
2509 (See also the Prepend method, below.)
2512 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2515 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2517 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2518 This appends new path elements to the given path in the
2519 specified external environment
2523 any particular path once (leaving the last one it encounters and
2524 ignoring the rest, to preserve path order),
2525 and to help assure this,
2526 will normalize all paths (using
2529 .BR os.path.normcase ).
2530 This can also handle the
2531 case where the given old path variable is a list instead of a
2532 string, in which case a list will be returned instead of a string.
2536 print 'before:',env['ENV']['INCLUDE']
2537 include_path = '/foo/bar:/foo'
2538 env.PrependENVPath('INCLUDE', include_path)
2539 print 'after:',env['ENV']['INCLUDE']
2543 after: /biz:/foo/bar:/foo
2546 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2548 .RI env.AppendUnique( key = val ", [...])"
2549 Appends the specified keyword arguments
2550 to the end of construction variables in the environment.
2551 If the Environment does not have
2552 the specified construction variable,
2553 it is simply added to the environment.
2554 If the construction variable being appended to is a list,
2555 then any value(s) that already exist in the
2556 construction variable will
2558 be added again to the list.
2561 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2564 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2567 A factory function that
2568 returns a Builder object
2569 to be used to fetch source files
2571 The returned Builder
2572 is intended to be passed to the
2577 env.SourceCode('.', env.BitKeeper())
2580 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2582 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2584 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2585 This specifies a build directory
2587 in which to build all derived files
2588 that would normally be built under
2590 Multiple build directories can be set up for multiple build variants, for
2593 must be underneath the SConstruct file's directory,
2596 may not be underneath the
2599 The default behavior is for
2601 to duplicate all of the files in the tree underneath
2605 and then build the derived files within the copied tree.
2606 (The duplication is performed by
2608 depending on the platform; see also the
2611 This guarantees correct builds
2612 regardless of whether intermediate source files
2613 are generated during the build,
2614 where preprocessors or other scanners search
2616 or whether individual compilers or other invoked tools
2617 are hard-coded to put derived files in the same directory as source files.
2619 This behavior of making a complete copy of the source tree
2620 may be disabled by setting
2625 to invoke Builders using the
2626 path names of source files in
2628 and the path names of derived files within
2630 This is always more efficient than
2632 and is usually safe for most builds.
2636 may cause build problems
2637 if source files are generated during the build,
2638 if any invoked tools are hard-coded to
2639 put derived files in the same directory as the source files.
2641 Note that specifying a
2643 works most naturally
2644 with a subsidiary SConscript file
2645 in the source directory.
2647 you would then call the subsidiary SConscript file
2648 not in the source directory,
2653 had made a virtual copy of the source tree
2654 regardless of the value of
2656 This is how you tell
2658 which variant of a source tree to build.
2662 BuildDir('build-variant1', 'src')
2663 SConscript('build-variant1/SConscript')
2664 BuildDir('build-variant2', 'src')
2665 SConscript('build-variant2/SConscript')
2671 function, described below,
2673 specify a build directory
2674 in conjunction with calling a subsidiary
2677 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2679 .RI Builder( action ", [" arguments ])
2681 .RI env.Builder( action ", [" arguments ])
2682 Creates a Builder object for
2685 See the section "Builder Objects,"
2686 below, for a complete explanation of the arguments and behavior.
2688 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2690 .RI CacheDir( cache_dir )
2692 .RI env.CacheDir( cache_dir )
2695 will maintain a cache of derived files in
2697 The derived files in the cache will be shared
2698 among all the builds using the same
2706 finds a derived file that needs to be rebuilt,
2707 it will first look in the cache to see if a
2708 derived file has already been built
2709 from identical input files and an identical build action
2710 (as incorporated into the MD5 build signature).
2713 will retrieve the file from the cache.
2714 If the derived file is not present in the cache,
2717 then place a copy of the built file in the cache
2718 (identified by its MD5 build signature),
2719 so that it may be retrieved by other
2720 builds that need to build the same derived file
2721 from identical inputs.
2725 may be disabled for any invocation
2734 will place a copy of
2736 derived files in the cache,
2737 even if they already existed
2738 and were not built by this invocation.
2739 This is useful to populate a cache
2742 is added to a build,
2751 "Retrieved `file' from cache,"
2754 option is being used.
2759 will print the action that
2761 have been used to build the file,
2762 without any indication that
2763 the file was actually retrieved from the cache.
2764 This is useful to generate build logs
2765 that are equivalent regardless of whether
2766 a given derived file has been built in-place
2767 or retrieved from the cache.
2769 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2771 .RI Clean( targets ", " files_or_dirs )
2773 .RI env.Clean( targets ", " files_or_dirs )
2774 This specifies a list of files or directories which should be removed
2775 whenever the targets are specified with the
2777 command line option.
2778 The specified targets may be a list
2779 or an individual target.
2783 and create new targets or add files and directories to the
2784 clean list for the specified targets.
2786 Multiple files or directories should be specified
2787 either as separate arguments to the
2789 method, or as a list.
2791 will also accept the return value of any of the construction environment
2796 Clean('foo', ['bar', 'baz'])
2797 Clean('dist', env.Program('hello', 'hello.c'))
2798 Clean(['foo', 'bar'], 'something_else_to_clean')
2801 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2803 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2805 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2806 Executes a specific action
2807 (or list of actions)
2808 to build a target file or files.
2809 This is more convenient
2810 than defining a separate Builder object
2811 for a single special-case build.
2813 As a special case, the
2815 keyword argument can
2818 that will be used to scan the sources.
2822 if any of the sources will be directories
2823 that must be scanned on-disk for
2824 changes to files that aren't
2825 already specified in other Builder of function calls.)
2827 Any other keyword arguments specified override any
2828 same-named existing construction variables.
2830 An action can be an external command,
2831 specified as a string,
2832 or a callable Python object;
2833 see "Action Objects," below,
2834 for more complete information.
2835 Also note that a string specifying an external command
2836 may be preceded by an
2839 to suppress printing the command in question,
2843 to ignore the exit status of the external command.
2847 env.Command('foo.out', 'foo.in',
2848 "$FOO_BUILD < $SOURCES > $TARGET")
2850 env.Command('bar.out', 'bar.in',
2852 "$BAR_BUILD < $SOURCES > $TARGET"],
2853 ENV = {'PATH' : '/usr/local/bin/'})
2855 def rename(env, target, source):
2857 os.rename('.tmp', str(target[0]))
2859 env.Command('baz.out', 'baz.in',
2860 ["$BAZ_BUILD < $SOURCES > .tmp",
2864 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2866 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
2868 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
2869 Creates a Configure object for integrated
2870 functionality similar to GNU autoconf.
2871 See the section "Configure Contexts,"
2872 below, for a complete explanation of the arguments and behavior.
2874 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2876 .RI env.Copy([ key = val ", ...])"
2877 Return a separate copy of a construction environment.
2878 If there are any keyword arguments specified,
2879 they are added to the returned copy,
2880 overwriting any existing values
2885 env3 = env.Copy(CCFLAGS = '-g')
2888 Additionally, a list of tools and a toolpath may be specified, as in
2889 the Environment constructor:
2892 def MyTool(env): env['FOO'] = 'bar'
2893 env4 = env.Copy(tools = ['msvc', MyTool])
2896 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2898 .RI env.CVS( repository ", " module )
2899 A factory function that
2900 returns a Builder object
2901 to be used to fetch source files
2905 The returned Builder
2906 is intended to be passed to the
2910 The optional specified
2912 will be added to the beginning
2913 of all repository path names;
2914 this can be used, in essence,
2915 to strip initial directory names
2916 from the repository path names,
2917 so that you only have to
2918 replicate part of the repository
2919 directory hierarchy in your
2920 local build directory:
2923 # Will fetch foo/bar/src.c
2924 # from /usr/local/CVSROOT/foo/bar/src.c.
2925 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2927 # Will fetch bar/src.c
2928 # from /usr/local/CVSROOT/foo/bar/src.c.
2929 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2932 # from /usr/local/CVSROOT/foo/bar/src.c.
2933 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2936 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2938 .RI Default( targets )
2940 .RI env.Default( targets )
2941 This specifies a list of default targets,
2942 which will be built by
2944 if no explicit targets are given on the command line.
2948 and add to the list of default targets.
2950 Multiple targets should be specified as
2951 separate arguments to the
2953 method, or as a list.
2955 will also accept the Node returned by any
2956 of a construction environment's
2961 Default('foo', 'bar', 'baz')
2962 env.Default(['a', 'b', 'c'])
2963 hello = env.Program('hello', 'hello.c')
2971 will clear all default targets.
2974 will add to the (now empty) default-target list
2977 The current list of targets added using the
2979 function or method is available in the
2984 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2986 .RI DefaultEnvironment([ args ])
2987 Creates and returns a default construction environment object.
2988 This construction environment is used internally by SCons
2989 in order to execute many of the global functions in this list,
2990 and to fetch source files transparently
2991 from source code management systems.
2993 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2995 .RI Depends( target ", " dependency )
2997 .RI env.Depends( target ", " dependency )
2998 Specifies an explicit dependency;
2999 the target file(s) will be rebuilt
3000 whenever the dependency file(s) has changed.
3001 This should only be necessary
3002 for cases where the dependency
3003 is not caught by a Scanner
3007 env.Depends('foo', 'other-input-file-for-foo')
3010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3012 .RI env.Dictionary([ vars ])
3013 Returns a dictionary object
3014 containing copies of all of the
3015 construction variables in the environment.
3016 If there are any variable names specified,
3017 only the specified construction
3018 variables are returned in the dictionary.
3021 dict = env.Dictionary()
3022 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3025 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3027 .RI Dir( name ", [" directory ])
3029 .RI env.Dir( name ", [" directory ])
3030 This returns a Directory Node,
3031 an object that represents the specified directory
3034 can be a relative or absolute path.
3036 is an optional directory that will be used as the parent directory.
3039 is specified, the current script's directory is used as the parent.
3041 Directory Nodes can be used anywhere you
3042 would supply a string as a directory name
3043 to a Builder method or function.
3044 Directory Nodes have attributes and methods
3045 that are useful in many situations;
3046 see "File and Directory Nodes," below.
3048 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3050 .RI env.Dump([ key ])
3051 Returns a pretty printable representation of the environment.
3055 should be a string containing the name of the variable of interest.
3060 print env.Dump('CCCOM')
3064 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3074 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3077 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3084 .RI EnsurePythonVersion( major ", " minor )
3086 .RI env.EnsurePythonVersion( major ", " minor )
3087 Ensure that the Python version is at least
3090 print out an error message and exit SCons with a non-zero exit code if the
3091 actual Python version is not late enough.
3094 EnsurePythonVersion(2,2)
3097 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3099 .RI EnsureSConsVersion( major ", " minor )
3101 .RI env.EnsureSConsVersion( major ", " minor )
3102 Ensure that the SCons version is at least
3105 print out an error message and exit SCons with a non-zero exit code if the
3106 actual SCons version is not late enough.
3109 EnsureSConsVersion(0,9)
3112 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3114 .RI Environment([ key = value ", ...])"
3116 .RI env.Environment([ key = value ", ...])"
3117 Return a new construction environment
3118 initialized with the specified
3122 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3124 .RI Execute( action ", [" strfunction ", " varlist ])
3126 .RI env.Execute( action ", [" strfunction ", " varlist ])
3127 Executes an Action object.
3130 may be an Action object
3131 (see the section "Action Objects,"
3132 below, for a complete explanation of the arguments and behavior),
3133 or it may be a command-line string,
3135 or executable Python function,
3136 each of which will be converted
3137 into an Action object
3139 The exit value of the command
3140 or return value of the Python function
3143 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3147 .RI env.Exit([ value ])
3153 A default exit value of
3156 is used if no value is specified.
3158 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3162 .RI env.Export( vars )
3165 to export a list of variables from the current
3166 SConscript file to all other SConscript files.
3167 The exported variables are kept in a global collection,
3168 so subsequent calls to
3170 will over-write previous exports that have the same name.
3171 Multiple variable names can be passed to
3173 as separate arguments or as a list. A dictionary can be used to map
3174 variables to a different name when exported. Both local variables and
3175 global variables can be exported.
3180 # Make env available for all SConscript files to Import().
3184 # Make env and package available for all SConscript files:.
3185 Export("env", "package")
3187 # Make env and package available for all SConscript files:
3188 Export(["env", "package"])
3190 # Make env available using the name debug:.
3191 Export({"debug":env})
3197 function supports an
3199 argument that makes it easier to to export a variable or
3200 set of variables to a single SConscript file.
3201 See the description of the
3205 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3207 .RI File( name ", [" directory ])
3209 .RI env.File( name ", [" directory ])
3212 an object that represents the specified file
3215 can be a relative or absolute path.
3217 is an optional directory that will be used as the parent directory.
3219 File Nodes can be used anywhere you
3220 would supply a string as a file name
3221 to a Builder method or function.
3222 File Nodes have attributes and methods
3223 that are useful in many situations;
3224 see "File and Directory Nodes," below.
3226 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3228 .RI FindFile( file ", " dirs )
3230 .RI env.FindFile( file ", " dirs )
3233 in the path specified by
3236 may be a list of file names or a single file name. In addition to searching
3237 for files that exist in the filesytem, this function also searches for
3238 derived files that have not yet been built.
3241 foo = env.FindFile('foo', ['dir1', 'dir2'])
3244 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3246 .RI Flatten( sequence )
3248 .RI env.Flatten( sequence )
3249 Takes a sequence (that is, a Python list or tuple)
3250 that may contain nested sequences
3251 and returns a flattened list containing
3252 all of the individual elements in any sequence.
3253 This can be helpful for collecting
3254 the lists returned by calls to Builders;
3255 other Builders will automatically
3256 flatten lists specified as input,
3257 but direct Python manipulation of
3258 these lists does not:
3261 foo = Object('foo.c')
3262 bar = Object('bar.c')
3264 # Because `foo' and `bar' are lists returned by the Object() Builder,
3265 # `objects' will be a list containing nested lists:
3266 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3268 # Passing such a list to another Builder is all right because
3269 # the Builder will flatten the list automatically:
3270 Program(source = objects)
3272 # If you need to manipulate the list directly using Python, you need to
3273 # call Flatten() yourself, or otherwise handle nested lists:
3274 for object in Flatten(objects):
3278 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3280 .RI GetBuildPath( file ", [" ... ])
3282 .RI env.GetBuildPath( file ", [" ... ])
3285 path name (or names) for the specified
3293 Nodes or strings representing path names.
3295 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3299 .RI env.GetLaunchDir()
3300 Returns the absolute path name of the directory from which
3303 was initially invoked.
3304 This can be useful when using the
3309 options, which internally
3310 change to the directory in which the
3314 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3316 .RI GetOption( name )
3318 .RI env.GetOption( name )
3319 This function provides a way to query a select subset of the scons command line
3320 options from a SConscript file. See
3322 for a description of the options available.
3324 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3326 '\".RI GlobalBuilders( flag )
3330 '\"adds the names of the default builders
3331 '\"(Program, Library, etc.)
3332 '\"to the global name space
3333 '\"so they can be called without an explicit construction environment.
3334 '\"(This is the default.)
3338 '\"the names of the default builders are removed
3339 '\"from the global name space
3340 '\"so that an explicit construction environment is required
3341 '\"to call all builders.
3343 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3347 .RI env.Help( text )
3348 This specifies help text to be printed if the
3350 argument is given to
3354 is called multiple times, the text is appended together in the order
3359 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3361 .RI Ignore( target ", " dependency )
3363 .RI env.Ignore( target ", " dependency )
3364 The specified dependency file(s)
3365 will be ignored when deciding if
3366 the target file(s) need to be rebuilt.
3369 env.Ignore('foo', 'foo.c')
3370 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3373 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3377 .RI env.Import( vars )
3380 to import a list of variables into the current SConscript file. This
3381 will import variables that were exported with
3387 Variables exported by
3390 Multiple variable names can be passed to
3392 as separate arguments or as a list. The variable "*" can be used
3393 to import all variables.
3398 Import("env", "variable")
3399 Import(["env", "variable"])
3403 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3405 .RI Install( dir ", " source )
3407 .RI env.Install( dir ", " source )
3408 Installs one or more files in a destination directory.
3409 The file names remain the same.
3412 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3415 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3417 .RI InstallAs( target ", " source )
3419 .RI env.InstallAs( target ", " source )
3420 Installs one or more files as specific file names,
3421 allowing changing a file name as part of the
3423 It is an error if the target and source
3424 list different numbers of files.
3427 env.InstallAs(target = '/usr/local/bin/foo',
3428 source = 'foo_debug')
3429 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3430 source = ['libFOO.a', 'libBAR.a'])
3433 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3435 .RI Literal( string )
3437 .RI env.Literal( string )
3440 will be preserved as-is
3441 and not have construction variables expanded.
3443 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3445 .RI Local( targets )
3447 .RI env.Local( targets )
3450 will have copies made in the local tree,
3451 even if an already up-to-date copy
3452 exists in a repository.
3453 Returns a list of the target Node or Nodes.
3455 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3457 .RI env.ParseConfig( command ", [" function ", " unique ])
3460 to modify the environment as specified by the output of
3464 expects the output of a typical
3468 and adds the options
3469 to the appropriate construction variables.
3471 duplicate values are not
3472 added to any construction variables;
3495 construction variables,
3499 option gets added to both the
3506 option gets added to the
3509 Any other strings not associated with options
3510 are assumed to be the names of libraries
3513 construction variable.
3515 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3517 .RI ParseDepends( filename ", [" must_exist ])
3519 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3520 Parses the contents of the specified
3522 as a list of dependencies in the style of
3526 and explicitly establishes all of the listed dependencies.
3535 argument may be set to a non-zero
3538 throw an exception and
3539 generate an error if the file does not exist,
3540 or is otherwise inaccessible.
3544 argument may be set to a non-zero
3547 thrown an exception and
3549 if the file contains dependency
3550 information for more than one target.
3551 This can provide a small sanity check
3552 for files intended to be generated
3553 by, for example, the
3556 which should typically only
3557 write dependency information for
3558 one output file into a corresponding
3564 and all of the files listed therein
3565 will be interpreted relative to
3566 the directory of the
3568 file which calls the
3572 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3575 A factory function that
3576 returns a Builder object
3577 to be used to fetch source files
3578 from the Perforce source code management system.
3579 The returned Builder
3580 is intended to be passed to the
3585 env.SourceCode('.', env.Perforce())
3588 Perforce uses a number of external
3589 environment variables for its operation.
3590 Consequently, this function adds the
3591 following variables from the user's external environment
3592 to the construction environment's
3605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3607 .RI Platform( string )
3608 Returns a callable object
3609 that can be used to initialize
3610 a construction environment using the
3611 platform keyword of the Environment() method:
3614 env = Environment(platform = Platform('win32'))
3617 .RI env.Platform( string )
3618 Applies the callable object for the specified platform
3620 to the environment through which the method was called.
3623 env.Platform('posix')
3630 variable from the user's external environment
3631 to the construction environment's
3634 This is so that any executed commands
3635 that use sockets to connect with other systems
3636 (such as fetching source files from
3637 external CVS repository specifications like
3638 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3639 will work on Win32 systems.
3641 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3643 .RI Precious( target ", ...)"
3645 .RI env.Precious( target ", ...)"
3648 as precious so it is not deleted before it is rebuilt. Normally
3650 deletes a target before building it.
3651 Multiple targets can be passed in to a single call to
3654 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3656 .RI env.Prepend( key = val ", [...])"
3657 Appends the specified keyword arguments
3658 to the beginning of construction variables in the environment.
3659 If the Environment does not have
3660 the specified construction variable,
3661 it is simply added to the environment.
3662 If the values of the construction variable
3663 and the keyword argument are the same type,
3664 then the two values will be simply added together.
3665 Otherwise, the construction variable
3666 and the value of the keyword argument
3667 are both coerced to lists,
3668 and the lists are added together.
3669 (See also the Append method, above.)
3672 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3675 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3677 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3678 This appends new path elements to the given path in the
3679 specified external environment
3683 any particular path once (leaving the first one it encounters and
3684 ignoring the rest, to preserve path order),
3685 and to help assure this,
3686 will normalize all paths (using
3689 .BR os.path.normcase ).
3690 This can also handle the
3691 case where the given old path variable is a list instead of a
3692 string, in which case a list will be returned instead of a string.
3696 print 'before:',env['ENV']['INCLUDE']
3697 include_path = '/foo/bar:/foo'
3698 env.PrependENVPath('INCLUDE', include_path)
3699 print 'after:',env['ENV']['INCLUDE']
3703 after: /foo/bar:/foo:/biz
3706 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3708 .RI env.AppendUnique( key = val ", [...])"
3709 Appends the specified keyword arguments
3710 to the beginning of construction variables in the environment.
3711 If the Environment does not have
3712 the specified construction variable,
3713 it is simply added to the environment.
3714 If the construction variable being appended to is a list,
3715 then any value(s) that already exist in the
3716 construction variable will
3718 be added again to the list.
3721 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3724 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3727 A factory function that
3728 returns a Builder object
3729 to be used to fetch source files
3731 The returned Builder
3732 is intended to be passed to the
3737 env.SourceCode('.', env.RCS())
3742 will fetch source files
3743 from RCS subdirectories automatically,
3745 as demonstrated in the above example
3746 should only be necessary if
3747 you are fetching from
3750 directory as the source files,
3751 or if you need to explicitly specify RCS
3752 for a specific subdirectory.
3754 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3756 .RI env.Replace( key = val ", [...])"
3757 Replaces construction variables in the Environment
3758 with the specified keyword arguments.
3761 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3764 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3766 .RI Repository( directory )
3768 .RI env.Repository( directory )
3771 is a repository to be searched for files.
3775 and each one adds to the list of
3776 repositories that will be searched.
3780 a repository is a copy of the source tree,
3781 from the top-level directory on down,
3783 both source files and derived files
3784 that can be used to build targets in
3785 the local source tree.
3786 The canonical example would be an
3787 official source tree maintained by an integrator.
3788 If the repository contains derived files,
3789 then the derived files should have been built using
3791 so that the repository contains the necessary
3792 signature information to allow
3794 to figure out when it is appropriate to
3795 use the repository copy of a derived file,
3796 instead of building one locally.
3798 Note that if an up-to-date derived file
3799 already exists in a repository,
3803 make a copy in the local directory tree.
3804 In order to guarantee that a local copy
3810 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3815 what variable(s) to use as the return value(s) of the current SConscript
3816 file. These variables will be returned to the "calling" SConscript file
3817 as the return value(s) of
3819 Multiple variable names should be passed to
3825 Return(["foo", "bar"])
3828 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3830 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3832 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3833 Creates a Scanner object for
3836 See the section "Scanner Objects,"
3837 below, for a complete explanation of the arguments and behavior.
3839 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3842 A factory function that
3843 returns a Builder object
3844 to be used to fetch source files
3846 The returned Builder
3847 is intended to be passed to the
3852 env.SourceCode('.', env.SCCS())
3857 will fetch source files
3858 from SCCS subdirectories automatically,
3860 as demonstrated in the above example
3861 should only be necessary if
3862 you are fetching from
3865 directory as the source files,
3866 or if you need to explicitly specify SCCS
3867 for a specific subdirectory.
3869 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3871 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3873 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3875 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3877 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
3881 one or more subsidiary SConscript (configuration) files.
3882 There are two ways to call the
3886 The first way you can call
3888 is to explicitly specify one or more
3890 as the first argument.
3891 A single script may be specified as a string;
3892 multiple scripts must be specified as a list
3893 (either explicitly or as created by
3897 The second way you can call
3899 is to specify a list of (sub)directory names
3906 execute a subsidiary configuration file named
3908 in each of the specified directories.
3909 You may specify a name other than
3911 by supplying an optional
3917 argument provides a list of variable names or a dictionary of
3918 named values to export to the
3920 These variables are locally exported only to the specified
3922 and do not affect the
3923 global pool of variables used by
3927 '\"If multiple dirs are provided,
3928 '\"each script gets a fresh export.
3933 function to import the variables.
3937 argument specifies that all of the target files
3938 (for example, object files and executables)
3939 that would normally be built in the subdirectory in which
3941 resides should actually
3945 is interpreted relative to the directory
3946 of the calling SConscript file.
3950 argument specifies that the
3951 source files from which
3952 the target files should be built
3956 is interpreted relative to the directory
3957 of the calling SConscript file.
3961 will link or copy (depending on the platform)
3962 all the source files into the build directory.
3963 This behavior may be disabled by
3964 setting the optional
3967 (it is set to 1 by default),
3970 will refer directly to
3971 the source files in their source directory
3972 when building target files.
3975 is usually safe, and always more efficient
3978 but it may cause build problems in certain end-cases,
3979 such as compiling from source files that
3980 are generated by the build.)
3982 Any variables returned by
3986 will be returned by the call to
3992 SConscript('subdir/SConscript')
3993 foo = SConscript('sub/SConscript', exports='env')
3994 SConscript('dir/SConscript', exports=['env', 'variable'])
3995 SConscript('src/SConscript', build_dir='build', duplicate=0)
3996 SConscript('bld/SConscript', src_dir='src', exports='env variable')
3997 SConscript(dirs=['sub1', 'sub2'])
3998 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
4001 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4003 .RI SConscriptChdir( value )
4005 .RI env.SConscriptChdir( value )
4008 changes its working directory
4009 to the directory in which each
4010 subsidiary SConscript file lives.
4011 This behavior may be disabled
4012 by specifying either:
4016 env.SConscriptChdir(0)
4021 will stay in the top-level directory
4022 while reading all SConscript files.
4023 (This may be necessary when building from repositories,
4024 when all the directories in which SConscript files may be found
4025 don't necessarily exist locally.)
4027 You may enable and disable
4028 this ability by calling
4035 SConscript('foo/SConscript') # will not chdir to foo
4036 env.SConscriptChdir(1)
4037 SConscript('bar/SConscript') # will chdir to bar
4040 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4042 .RI SConsignFile([ file , dbm_module ])
4044 .RI env.SConsignFile([ file , dbm_module ])
4047 to store all file signatures
4048 in the specified database
4055 (The actual file name(s) stored on disk
4056 may have an appropriated suffix appended
4061 is not an absolute path name,
4062 the file is placed in the same directory as the top-level
4072 will store file signatures
4075 file in each directory,
4076 not in one global database file.
4077 (This was the default behavior
4078 prior to SCons 0.96.91 and 0.97.)
4082 argument can be used to specify
4083 which Python database module
4084 The default is to use a custom
4086 module that uses pickled
4087 Python data structures,
4088 and which works on all Python versions from 1.5.2 on.
4093 # Explicitly stores signatures in ".sconsign.dblite"
4094 # in the top-level SConstruct directory (the
4095 # default behavior).
4098 # Stores signatures in the file "etc/scons-signatures"
4099 # relative to the top-level SConstruct directory.
4100 SConsignFile("etc/scons-signatures")
4102 # Stores signatures in the specified absolute file name.
4103 SConsignFile("/home/me/SCons/signatures")
4105 # Stores signatures in a separate .sconsign file
4106 # in each directory.
4110 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4112 .RI env.SetDefault(key = val ", [...])"
4113 Sets construction variables to default values specified with the keyword
4114 arguments if (and only if) the variables are not already set.
4115 The following statements are equivalent:
4118 env.SetDefault(FOO = 'foo')
4120 if not env.has_key('FOO'): env['FOO'] = 'foo'
4123 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4125 .RI SetOption( name ", " value )
4127 .RI env.SetOption( name ", " value )
4128 This function provides a way to set a select subset of the scons command
4129 line options from a SConscript file. The options supported are:
4131 which corresponds to -c, --clean, and --remove;
4134 corresponds to --duplicate;
4136 which corresponds to --implicit-cache;
4138 which corresponds to --max-drift;
4140 which corresponds to -j and --jobs.
4141 See the documentation for the
4142 corresponding command line object for information about each specific
4146 SetOption('max_drift', 1)
4149 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4151 .RI SideEffect( side_effect ", " target )
4153 .RI env.SideEffect( side_effect ", " target )
4156 as a side effect of building
4162 can be a list, a file name, or a node.
4163 A side effect is a target that is created
4164 as a side effect of building other targets.
4165 For example, a Windows PDB
4166 file is created as a side effect of building the .obj
4167 files for a static library.
4168 If a target is a side effect of multiple build commands,
4170 will ensure that only one set of commands
4171 is executed at a time.
4172 Consequently, you only need to use this method
4173 for side-effect targets that are built as a result of
4174 multiple build commands.
4176 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4178 .RI SourceCode( entries ", " builder )
4180 .RI env.SourceCode( entries ", " builder )
4181 Arrange for non-existent source files to
4182 be fetched from a source code management system
4187 may be a Node, string or list of both,
4188 and may represent either individual
4189 source files or directories in which
4190 source files can be found.
4192 For any non-existent source files,
4194 will search up the directory tree
4204 will not use a builder to fetch
4205 source files for the specified
4209 builder has been specified
4210 for a directory higher up the tree.
4214 fetch files from SCCS or RCS subdirectories
4215 without explicit configuration.
4216 This takes some extra processing time
4217 to search for the necessary
4218 source code management files on disk.
4219 You can avoid these extra searches
4220 and speed up your build a little
4221 by disabling these searches as follows:
4224 env.SourceCode('.', None)
4228 Note that if the specified
4230 is one you create by hand,
4231 it must have an associated
4232 construction environment to use
4233 when fetching a source file.
4236 provides a set of canned factory
4237 functions that return appropriate
4238 Builders for various popular
4239 source code management systems.
4240 Canonical examples of invocation include:
4243 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4244 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4245 env.SourceCode('/', env.RCS())
4246 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4247 env.SourceCode('no_source.c', None)
4249 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4251 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4253 .RI env.subst( string )
4254 Performs construction variable interpolation
4255 on the specified string argument.
4258 print env.subst("The C compiler is: $CC")
4260 def compile(target, source, env):
4261 sourceDir = env.subst("${SOURCE.srcdir}")
4264 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4266 '\".RI Subversion( repository ", " module )
4267 '\"A factory function that
4268 '\"returns a Builder object
4269 '\"to be used to fetch source files
4270 '\"from the specified Subversion
4272 '\"The returned Builder
4273 '\"is intended to be passed to the
4277 '\"The optional specified
4279 '\"will be added to the beginning
4280 '\"of all repository path names;
4281 '\"this can be used, in essence,
4282 '\"to strip initial directory names
4283 '\"from the repository path names,
4284 '\"so that you only have to
4285 '\"replicate part of the repository
4286 '\"directory hierarchy in your
4287 '\"local build directory:
4290 '\"# Will fetch foo/bar/src.c
4291 '\"# from /usr/local/Subversion/foo/bar/src.c.
4292 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4294 '\"# Will fetch bar/src.c
4295 '\"# from /usr/local/Subversion/foo/bar/src.c.
4296 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4298 '\"# Will fetch src.c
4299 '\"# from /usr/local/Subversion/foo/bar/src.c.
4300 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4303 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4305 .RI SourceSignatures( type )
4307 .RI env.SourceSignatures( type )
4308 This function tells SCons what type of signature to use for source files:
4312 If the environment method is used,
4313 the specified type of source signature
4314 is only used when deciding whether targets
4315 built with that environment are up-to-date or must be rebuilt.
4316 If the global function is used,
4317 the specified type of source signature becomes the default
4318 used for all decisions
4319 about whether targets are up-to-date.
4321 "MD5" means the signature of a source file
4322 is the MD5 checksum of its contents.
4323 "timestamp" means the signature of a source file
4324 is its timestamp (modification time).
4325 There is no different between the two behaviors
4329 "MD5" signatures take longer to compute,
4330 but are more accurate than "timestamp" signatures.
4331 The default is "MD5".
4333 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4337 .RI env.Split( arg )
4338 Returns a list of file names or other objects.
4340 it will be split on strings of white-space characters
4342 making it easier to write long lists of file names.
4343 If arg is already a list,
4344 the list will be returned untouched.
4345 If arg is any other type of object,
4346 it will be returned as a list
4347 containing just the object.
4350 files = Split("f1.c f2.c f3.c")
4351 files = env.Split("f4.c f5.c f6.c")
4359 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4361 .RI TargetSignatures( type )
4363 .RI env.TargetSignatures( type )
4364 This function tells SCons what type of signatures to use
4369 If the environment method is used,
4370 the specified type of signature is only used
4371 for targets built with that environment.
4372 If the global function is used,
4373 the specified type of signature becomes the default
4374 used for all target files that
4375 don't have an explicit target signature type
4376 specified for their environments.
4378 "build" means the signature of a target file
4379 is made by concatenating all of the
4380 signatures of all its source files.
4381 "content" means the signature of a target
4382 file is an MD5 checksum of its contents.
4383 "build" signatures are usually faster to compute,
4384 but "content" signatures can prevent unnecessary rebuilds
4385 when a target file is rebuilt to the exact same contents
4386 as the previous build.
4387 The default is "build".
4389 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4391 .RI Tool( string [, toolpath ", " **kw ])
4392 Returns a callable object
4393 that can be used to initialize
4394 a construction environment using the
4395 tools keyword of the Environment() method.
4396 The object may be called with a construction
4397 environment as an argument,
4398 in which case the object will
4399 add the necessary variables
4400 to the construction environment
4401 and the name of the tool will be added to the
4403 construction variable.
4405 Additional keyword arguments are passed to the tool's
4410 env = Environment(tools = [ Tool('msvc') ])
4414 t(env) # adds 'msvc' to the TOOLS variable
4415 u = Tool('opengl', toolpath = ['tools'])
4416 u(env) # adds 'opengl' to the TOOLS variable
4419 .RI env.Tool( string [, toolpath ", " **kw ])
4420 Applies the callable object for the specified tool
4422 to the environment through which the method was called.
4424 Additional keyword arguments are passed to the tool's
4430 env.Tool('opengl', toolpath = ['build/tools'])
4433 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4437 .RI env.Value( value )
4438 Returns a Node object representing the specified Python value. Value
4439 nodes can be used as dependencies of targets. If the result of
4442 changes between SCons runs, any targets depending on
4444 will be rebuilt. When using timestamp source signatures, Value nodes'
4445 timestamps are equal to the system time when the node is created.
4448 def create(target, source, env):
4449 f = open(str(target[0]), 'wb')
4450 f.write('prefix=' + source[0].get_contents())
4452 prefix = ARGUMENTS.get('prefix', '/usr/local')
4454 env['BUILDERS']['Config'] = Builder(action = create)
4455 env.Config(target = 'package-config', source = Value(prefix))
4458 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4460 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4462 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4464 Searches for the specified executable
4466 returning the full path name to the program
4468 and returning None if not.
4469 Searches the specified
4471 the value of the calling environment's PATH
4472 (env['ENV']['PATH']),
4473 or the user's current external PATH
4474 (os.environ['PATH'])
4476 On Win32 systems, searches for executable
4477 programs with any of the file extensions
4478 listed in the specified
4480 the calling environment's PATHEXT
4481 (env['ENV']['PATHEXT'])
4482 or the user's current PATHEXT
4483 (os.environ['PATHEXT'])
4491 .SS SConscript Variables
4492 In addition to the global functions and methods,
4494 supports a number of Python variables
4495 that can be used in SConscript files
4496 to affect how you want the build to be performed.
4497 These variables may be accessed from custom Python modules that you
4498 import into an SConscript file by adding the following
4499 to the Python module:
4502 from SCons.Script import *
4505 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4510 arguments specified on the command line.
4511 Each element in the list is a tuple
4513 .RI ( keyword , value )
4519 elements of the tuple
4521 subscripting for element
4525 of the tuple, respectively.
4528 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4529 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4530 third_tuple = ARGLIST[2]
4531 print "third keyword, value =", third_tuple[0], third_tuple[1]
4532 for key, value in ARGLIST:
4533 # process key and value
4536 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4539 A dictionary of all the
4541 arguments specified on the command line.
4542 The dictionary is not in order,
4543 and if a given keyword has
4544 more than one value assigned to it
4545 on the command line,
4546 the last (right-most) value is
4552 if ARGUMENTS.get('debug', 0):
4553 env = Environment(CCFLAGS = '-g')
4558 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4561 A list of the targets which
4563 will actually try to build,
4564 regardless of whether they were specified on
4565 the command line or via the
4568 The elements of this list may be strings
4570 nodes, so you should run the list through the Python
4572 function to make sure any Node path names
4573 are converted to strings.
4575 Because this list may be taken from the
4576 list of targets specified using the
4579 the contents of the list may change
4580 on each successive call to
4585 for additional information.
4588 if 'foo' in BUILD_TARGETS:
4589 print "Don't forget to test the `foo' program!"
4590 if 'special/program' in BUILD_TARGETS:
4591 SConscript('special')
4596 list only contains targets expected listed
4597 on the command line or via calls to the
4602 contain all dependent targets that will be built as
4603 a result of making the sure the explicitly-specified
4604 targets are up to date.
4606 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4608 COMMAND_LINE_TARGETS
4609 A list of the targets explicitly specified on
4611 If there are no targets specified on the command line,
4613 This can be used, for example,
4614 to take specific actions only
4615 when a certain target or targets
4616 is explicitly being built:
4619 if 'foo' in COMMAND_LINE_TARGETS:
4620 print "Don't forget to test the `foo' program!"
4621 if 'special/program' in COMMAND_LINE_TARGETS:
4622 SConscript('special')
4625 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4628 A list of the target
4630 that have been specified using the
4633 The elements of the list are nodes,
4634 so you need to run them through the Python
4636 function to get at the path name for each Node.
4639 print str(DEFAULT_TARGETS[0])
4640 if 'foo' in map(str, DEFAULT_TARGETS):
4641 print "Don't forget to test the `foo' program!"
4646 list change on on each successive call to the
4651 print map(str, DEFAULT_TARGETS) # originally []
4653 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4655 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4657 print map(str, DEFAULT_TARGETS) # back to []
4660 Consequently, be sure to use
4662 only after you've made all of your
4665 or else simply be careful of the order
4666 of these statements in your SConscript files
4667 so that you don't look for a specific
4668 default target before it's actually been added to the list.
4670 .SS Construction Variables
4671 .\" XXX From Gary Ruben, 23 April 2002:
4672 .\" I think it would be good to have an example with each construction
4673 .\" variable description in the documentation.
4675 .\" CC The C compiler
4676 .\" Example: env["CC"] = "c68x"
4677 .\" Default: env["CC"] = "cc"
4679 .\" CCCOM The command line ...
4681 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4682 .\" env["CC"] = "c68x"
4683 .\" env["CFLAGS"] = "-ps -qq -mr"
4684 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4686 .\" (I dunno what this is ;-)
4687 A construction environment has an associated dictionary of
4688 .I construction variables
4689 that are used by built-in or user-supplied build rules.
4690 Construction variables must follow the same rules for
4692 the initial character must be an underscore or letter,
4693 followed by any number of underscores, letters, or digits.
4695 A number of useful construction variables are automatically defined by
4696 scons for each supported platform, and additional construction variables
4697 can be defined by the user. The following is a list of the automatically
4698 defined construction variables:
4701 The static library archiver.
4704 The command line used to generate a static library from object files.
4707 The string displayed when an object file
4708 is generated from an assembly-language source file.
4709 If this is not set, then $ARCOM (the command line) is displayed.
4712 env = Environment(ARCOMSTR = "Archiving $TARGET")
4716 General options passed to the static library archiver.
4722 The command line used to generate an object file
4723 from an assembly-language source file.
4726 The string displayed when an object file
4727 is generated from an assembly-language source file.
4728 If this is not set, then $ASCOM (the command line) is displayed.
4731 env = Environment(ASCOMSTR = "Assembling $TARGET")
4735 General options passed to the assembler.
4738 The command line used to assemble an assembly-language
4739 source file into an object file
4740 after first running the file through the C preprocessor.
4741 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4742 are included on this command line.
4745 The string displayed when an object file
4746 is generated from an assembly-language source file
4747 after first running the file through the C preprocessor.
4748 If this is not set, then $ASPPCOM (the command line) is displayed.
4751 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4755 General options when an assembling an assembly-language
4756 source file into an object file
4757 after first running the file through the C preprocessor.
4758 The default is to use the value of $ASFLAGS.
4761 The bibliography generator for the TeX formatter and typesetter and the
4762 LaTeX structured formatter and typesetter.
4765 The command line used to call the bibliography generator for the
4766 TeX formatter and typesetter and the LaTeX structured formatter and
4770 The string displayed when generating a bibliography
4772 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4775 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4780 General options passed to the bibliography generator for the TeX formatter
4781 and typesetter and the LaTeX structured formatter and typesetter.
4784 The BitKeeper executable.
4787 The command line for
4788 fetching source files using BitKeeper.
4791 The string displayed when fetching
4792 a source file using BitKeeper.
4793 If this is not set, then $BITKEEPERCOM
4794 (the command line) is displayed.
4797 The command ($BITKEEPER) and subcommand
4798 for fetching source files using BitKeeper.
4800 .IP BITKEEPERGETFLAGS
4801 Options that are passed to the BitKeeper
4806 A dictionary mapping the names of the builders
4807 available through this environment
4808 to underlying Builder objects.
4810 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
4811 are available by default.
4812 If you initialize this variable when an
4813 Environment is created:
4816 env = Environment(BUILDERS = {'NewBuilder' : foo})
4819 the default Builders will no longer be available.
4820 To use a new Builder object in addition to the default Builders,
4821 add your new Builder object like this:
4825 env.Append(BUILDERS = {'NewBuilder' : foo})
4832 env['BUILDERS]['NewBuilder'] = foo
4839 The command line used to compile a C source file to a (static) object file.
4840 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
4841 are included on this command line.
4844 The string displayed when a C source file
4845 is compiled to a (static) object file.
4846 If this is not set, then $CCCOM (the command line) is displayed.
4849 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
4853 General options that are passed to the C compiler.
4856 The suffix for C source files.
4857 This is used by the internal CFile builder
4858 when generating C files from Lex (.l) or YACC (.y) input files.
4859 The default suffix, of course, is
4862 On case-insensitive systems (like Win32),
4869 The version number of the C compiler.
4870 This may or may not be set,
4871 depending on the specific C compiler being used.
4874 A function used to produce variables like $_CPPINCFLAGS. It takes
4876 arguments: a prefix to concatenate onto each element, a list of
4877 elements, a suffix to concatenate onto each element, an environment
4878 for variable interpolation, and an optional function that will be
4879 called to transform the list before concatenation.
4882 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
4886 A platform independent specification of C preprocessor definitions.
4887 The definitions will be added to command lines
4888 through the automatically-generated
4889 $_CPPDEFFLAGS construction variable (see below),
4890 which is constructed according to
4891 the type of value of $CPPDEFINES:
4894 If $CPPDEFINES is a string,
4896 $CPPDEFPREFIX and $CPPDEFSUFFIX
4897 construction variables
4898 will be added to the beginning and end.
4901 # Will add -Dxyz to POSIX compiler command lines,
4902 # and /Dxyz to Microsoft Visual C++ command lines.
4903 env = Environment(CPPDEFINES='xyz')
4907 If $CPPDEFINES is a list,
4909 $CPPDEFPREFIX and $CPPDEFSUFFIX
4910 construction variables
4911 will be appended to the beginning and end
4912 of each element in the list.
4913 If any element is a list or tuple,
4914 then the first item is the name being
4915 defined and the second item is its value:
4918 # Will add -DB=2 -DA to POSIX compiler command lines,
4919 # and /DB=2 /DA to Microsoft Visual C++ command lines.
4920 env = Environment(CPPDEFINES=[('B', 2), 'A'])
4924 If $CPPDEFINES is a dictionary,
4926 $CPPDEFPREFIX and $CPPDEFSUFFIX
4927 construction variables
4928 will be appended to the beginning and end
4929 of each item from the dictionary.
4930 The key of each dictionary item
4931 is a name being defined
4932 to the dictionary item's corresponding value;
4935 then the name is defined without an explicit value.
4936 Note that the resulting flags are sorted by keyword
4937 to ensure that the order of the options on the
4938 command line is consistent each time
4943 # Will add -DA -DB=2 to POSIX compiler command lines,
4944 # and /DA /DB=2 to Microsoft Visual C++ command lines.
4945 env = Environment(CPPDEFINES={'B':2, 'A':None})
4949 An automatically-generated construction variable
4950 containing the C preprocessor command-line options
4952 The value of $_CPPDEFFLAGS is created
4953 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
4954 to the beginning and end
4955 of each directory in $CPPDEFINES.
4958 The prefix used to specify preprocessor definitions
4959 on the C compiler command line.
4960 This will be appended to the beginning of each definition
4961 in the $CPPDEFINES construction variable
4962 when the $_CPPDEFFLAGS variable is automatically generated.
4965 The suffix used to specify preprocessor definitions
4966 on the C compiler command line.
4967 This will be appended to the end of each definition
4968 in the $CPPDEFINES construction variable
4969 when the $_CPPDEFFLAGS variable is automatically generated.
4972 User-specified C preprocessor options.
4973 These will be included in any command that uses the C preprocessor,
4974 including not just compilation of C and C++ source files
4975 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
4976 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
4977 $F77PPCOM and $SHF77PPCOM command lines
4978 used to compile a Fortran source file,
4979 and the $ASPPCOM command line
4980 used to assemble an assembly language source file,
4981 after first running each file through the C preprocessor.
4982 Note that this variable does
4986 (or similar) include search path options
4987 that scons generates automatically from $CPPPATH.
4991 for the variable that expands to those options.
4994 An automatically-generated construction variable
4995 containing the C preprocessor command-line options
4996 for specifying directories to be searched for include files.
4997 The value of $_CPPINCFLAGS is created
4998 by appending $INCPREFIX and $INCSUFFIX
4999 to the beginning and end
5000 of each directory in $CPPPATH.
5003 The list of directories that the C preprocessor will search for include
5004 directories. The C/C++ implicit dependency scanner will search these
5005 directories for include files. Don't explicitly put include directory
5006 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
5007 and the directories will not be searched by the dependency scanner. Note:
5008 directory names in CPPPATH will be looked-up relative to the SConscript
5009 directory when they are used in a command. To force
5011 to look-up a directory relative to the root of the source tree use #:
5014 env = Environment(CPPPATH='#/include')
5018 The directory look-up can also be forced using the
5023 include = Dir('include')
5024 env = Environment(CPPPATH=include)
5028 The directory list will be added to command lines
5029 through the automatically-generated
5031 construction variable,
5032 which is constructed by
5033 appending the values of the
5034 $INCPREFIX and $INCSUFFIX
5035 construction variables
5036 to the beginning and end
5037 of each directory in $CPPPATH.
5038 Any command lines you define that need
5039 the CPPPATH directory list should
5040 include $_CPPINCFLAGS:
5043 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5047 The list of suffixes of files that will be scanned
5048 for C preprocessor implicit dependencies
5050 The default list is:
5053 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5054 ".h", ".H", ".hxx", ".hpp", ".hh",
5055 ".F", ".fpp", ".FPP",
5057 ".S", ".spp", ".SPP"]
5064 Options that are passed to the CVS checkout subcommand.
5067 The command line used to
5068 fetch source files from a CVS repository.
5071 The string displayed when fetching
5072 a source file from a CVS repository.
5073 If this is not set, then $CVSCOM
5074 (the command line) is displayed.
5077 General options that are passed to CVS.
5078 By default, this is set to
5080 to specify from where the files must be fetched.
5083 The path to the CVS repository.
5084 This is referenced in the default
5091 The suffix for C++ source files.
5092 This is used by the internal CXXFile builder
5093 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
5094 The default suffix is
5096 SCons also treats files with the suffixes
5105 suffixes as Objective C++ files.
5106 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5113 The command line used to compile a C++ source file to an object file.
5114 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
5115 are included on this command line.
5118 The string displayed when a C++ source file
5119 is compiled to a (static) object file.
5120 If this is not set, then $CXXCOM (the command line) is displayed.
5123 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5127 General options that are passed to the C++ compiler.
5128 By default, this includes the value of $CCFLAGS,
5129 so that setting $CCFLAGS affects both C and C++ compilation.
5130 If you want to add C++-specific flags,
5131 you must set or override the value of $CXXFLAGS.
5134 The version number of the C++ compiler.
5135 This may or may not be set,
5136 depending on the specific C++ compiler being used.
5139 A function that converts a file name into a Dir instance relative to the
5143 The list of suffixes of files that will be scanned
5144 for imported D package files.
5145 The default list is:
5152 The TeX DVI file to PDF file converter.
5155 General options passed to the TeX DVI file to PDF file converter.
5158 The command line used to convert TeX DVI files into a PDF file.
5161 The string displayed when a TeX DVI file
5162 is converted into a PDF file.
5163 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5166 The TeX DVI file to PostScript converter.
5169 General options passed to the TeX DVI file to PostScript converter.
5172 A dictionary of environment variables
5173 to use when invoking commands. When ENV is used in a command all list
5174 values will be joined using the path separator and any other non-string
5175 values will simply be coerced to a string.
5176 Note that, by default,
5180 propagate the environment in force when you
5183 to the commands used to build target files.
5184 This is so that builds will be guaranteed
5185 repeatable regardless of the environment
5186 variables set at the time
5190 If you want to propagate your
5191 environment variables
5192 to the commands executed
5193 to build target files,
5194 you must do so explicitly:
5198 env = Environment(ENV = os.environ)
5202 Note that you can choose only to propagate
5203 certain environment variables.
5207 environment variable,
5210 uses the same utilities
5211 as the invoking shell (or other process):
5216 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5220 A function that will be called to escape shell special characters in
5221 command lines. The function should take one argument: the command line
5222 string to escape; and should return the escaped command line.
5225 The Fortran 77 compiler.
5226 You should normally set the $FORTRAN variable,
5227 which specifies the default Fortran compiler
5228 for all Fortran versions.
5229 You only need to set $F77 if you need to use a specific compiler
5230 or compiler version for Fortran 77 files.
5233 The command line used to compile a Fortran 77 source file to an object file.
5234 You only need to set $F77COM if you need to use a specific
5235 command line for Fortran 77 files.
5236 You should normally set the $FORTRANCOM variable,
5237 which specifies the default command line
5238 for all Fortran versions.
5241 The string displayed when a Fortran 77 source file
5242 is compiled to an object file.
5243 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5246 General user-specified options that are passed to the Fortran 77 compiler.
5247 Note that this variable does
5251 (or similar) include search path options
5252 that scons generates automatically from $F77PATH.
5256 for the variable that expands to those options.
5257 You only need to set $F77FLAGS if you need to define specific
5258 user options for Fortran 77 files.
5259 You should normally set the $FORTRANFLAGS variable,
5260 which specifies the user-specified options
5261 passed to the default Fortran compiler
5262 for all Fortran versions.
5265 An automatically-generated construction variable
5266 containing the Fortran 77 compiler command-line options
5267 for specifying directories to be searched for include files.
5268 The value of $_F77INCFLAGS is created
5269 by appending $INCPREFIX and $INCSUFFIX
5270 to the beginning and end
5271 of each directory in $F77PATH.
5274 The list of directories that the Fortran 77 compiler will search for include
5275 directories. The implicit dependency scanner will search these
5276 directories for include files. Don't explicitly put include directory
5277 arguments in $F77FLAGS because the result will be non-portable
5278 and the directories will not be searched by the dependency scanner. Note:
5279 directory names in $F77PATH will be looked-up relative to the SConscript
5280 directory when they are used in a command. To force
5282 to look-up a directory relative to the root of the source tree use #:
5283 You only need to set $F77PATH if you need to define a specific
5284 include path for Fortran 77 files.
5285 You should normally set the $FORTRANPATH variable,
5286 which specifies the include path
5287 for the default Fortran compiler
5288 for all Fortran versions.
5291 env = Environment(F77PATH='#/include')
5295 The directory look-up can also be forced using the
5300 include = Dir('include')
5301 env = Environment(F77PATH=include)
5305 The directory list will be added to command lines
5306 through the automatically-generated
5308 construction variable,
5309 which is constructed by
5310 appending the values of the
5311 $INCPREFIX and $INCSUFFIX
5312 construction variables
5313 to the beginning and end
5314 of each directory in $F77PATH.
5315 Any command lines you define that need
5316 the F77PATH directory list should
5317 include $_F77INCFLAGS:
5320 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5324 The command line used to compile a Fortran 77 source file to an object file
5325 after first running the file through the C preprocessor.
5326 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5327 are included on this command line.
5328 You only need to set $F77PPCOM if you need to use a specific
5329 C-preprocessor command line for Fortran 77 files.
5330 You should normally set the $FORTRANPPCOM variable,
5331 which specifies the default C-preprocessor command line
5332 for all Fortran versions.
5335 The Fortran 90 compiler.
5336 You should normally set the $FORTRAN variable,
5337 which specifies the default Fortran compiler
5338 for all Fortran versions.
5339 You only need to set $F90 if you need to use a specific compiler
5340 or compiler version for Fortran 90 files.
5343 The command line used to compile a Fortran 90 source file to an object file.
5344 You only need to set $F90COM if you need to use a specific
5345 command line for Fortran 90 files.
5346 You should normally set the $FORTRANCOM variable,
5347 which specifies the default command line
5348 for all Fortran versions.
5351 The string displayed when a Fortran 90 source file
5352 is compiled to an object file.
5353 If this is not set, then $F90COM or $FORTRANCOM
5354 (the command line) is displayed.
5357 General user-specified options that are passed to the Fortran 90 compiler.
5358 Note that this variable does
5362 (or similar) include search path options
5363 that scons generates automatically from $F90PATH.
5367 for the variable that expands to those options.
5368 You only need to set $F90FLAGS if you need to define specific
5369 user options for Fortran 90 files.
5370 You should normally set the $FORTRANFLAGS variable,
5371 which specifies the user-specified options
5372 passed to the default Fortran compiler
5373 for all Fortran versions.
5376 An automatically-generated construction variable
5377 containing the Fortran 90 compiler command-line options
5378 for specifying directories to be searched for include files.
5379 The value of $_F90INCFLAGS is created
5380 by appending $INCPREFIX and $INCSUFFIX
5381 to the beginning and end
5382 of each directory in $F90PATH.
5385 The list of directories that the Fortran 90 compiler will search for include
5386 directories. The implicit dependency scanner will search these
5387 directories for include files. Don't explicitly put include directory
5388 arguments in $F90FLAGS because the result will be non-portable
5389 and the directories will not be searched by the dependency scanner. Note:
5390 directory names in $F90PATH will be looked-up relative to the SConscript
5391 directory when they are used in a command. To force
5393 to look-up a directory relative to the root of the source tree use #:
5394 You only need to set $F90PATH if you need to define a specific
5395 include path for Fortran 90 files.
5396 You should normally set the $FORTRANPATH variable,
5397 which specifies the include path
5398 for the default Fortran compiler
5399 for all Fortran versions.
5402 env = Environment(F90PATH='#/include')
5406 The directory look-up can also be forced using the
5411 include = Dir('include')
5412 env = Environment(F90PATH=include)
5416 The directory list will be added to command lines
5417 through the automatically-generated
5419 construction variable,
5420 which is constructed by
5421 appending the values of the
5422 $INCPREFIX and $INCSUFFIX
5423 construction variables
5424 to the beginning and end
5425 of each directory in $F90PATH.
5426 Any command lines you define that need
5427 the F90PATH directory list should
5428 include $_F90INCFLAGS:
5431 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5435 The command line used to compile a Fortran 90 source file to an object file
5436 after first running the file through the C preprocessor.
5437 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5438 are included on this command line.
5439 You only need to set $F90PPCOM if you need to use a specific
5440 C-preprocessor command line for Fortran 90 files.
5441 You should normally set the $FORTRANPPCOM variable,
5442 which specifies the default C-preprocessor command line
5443 for all Fortran versions.
5446 The Fortran 95 compiler.
5447 You should normally set the $FORTRAN variable,
5448 which specifies the default Fortran compiler
5449 for all Fortran versions.
5450 You only need to set $F95 if you need to use a specific compiler
5451 or compiler version for Fortran 95 files.
5454 The command line used to compile a Fortran 95 source file to an object file.
5455 You only need to set $F95COM if you need to use a specific
5456 command line for Fortran 95 files.
5457 You should normally set the $FORTRANCOM variable,
5458 which specifies the default command line
5459 for all Fortran versions.
5462 The string displayed when a Fortran 95 source file
5463 is compiled to an object file.
5464 If this is not set, then $F95COM or $FORTRANCOM
5465 (the command line) is displayed.
5468 General user-specified options that are passed to the Fortran 95 compiler.
5469 Note that this variable does
5473 (or similar) include search path options
5474 that scons generates automatically from $F95PATH.
5478 for the variable that expands to those options.
5479 You only need to set $F95FLAGS if you need to define specific
5480 user options for Fortran 95 files.
5481 You should normally set the $FORTRANFLAGS variable,
5482 which specifies the user-specified options
5483 passed to the default Fortran compiler
5484 for all Fortran versions.
5487 An automatically-generated construction variable
5488 containing the Fortran 95 compiler command-line options
5489 for specifying directories to be searched for include files.
5490 The value of $_F95INCFLAGS is created
5491 by appending $INCPREFIX and $INCSUFFIX
5492 to the beginning and end
5493 of each directory in $F95PATH.
5496 The list of directories that the Fortran 95 compiler will search for include
5497 directories. The implicit dependency scanner will search these
5498 directories for include files. Don't explicitly put include directory
5499 arguments in $F95FLAGS because the result will be non-portable
5500 and the directories will not be searched by the dependency scanner. Note:
5501 directory names in $F95PATH will be looked-up relative to the SConscript
5502 directory when they are used in a command. To force
5504 to look-up a directory relative to the root of the source tree use #:
5505 You only need to set $F95PATH if you need to define a specific
5506 include path for Fortran 95 files.
5507 You should normally set the $FORTRANPATH variable,
5508 which specifies the include path
5509 for the default Fortran compiler
5510 for all Fortran versions.
5513 env = Environment(F95PATH='#/include')
5517 The directory look-up can also be forced using the
5522 include = Dir('include')
5523 env = Environment(F95PATH=include)
5527 The directory list will be added to command lines
5528 through the automatically-generated
5530 construction variable,
5531 which is constructed by
5532 appending the values of the
5533 $INCPREFIX and $INCSUFFIX
5534 construction variables
5535 to the beginning and end
5536 of each directory in $F95PATH.
5537 Any command lines you define that need
5538 the F95PATH directory list should
5539 include $_F95INCFLAGS:
5542 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5546 The command line used to compile a Fortran 95 source file to an object file
5547 after first running the file through the C preprocessor.
5548 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5549 are included on this command line.
5550 You only need to set $F95PPCOM if you need to use a specific
5551 C-preprocessor command line for Fortran 95 files.
5552 You should normally set the $FORTRANPPCOM variable,
5553 which specifies the default C-preprocessor command line
5554 for all Fortran versions.
5557 The default Fortran compiler
5558 for all versions of Fortran.
5561 The command line used to compile a Fortran source file to an object file.
5562 By default, any options specified
5563 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5564 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5565 are included on this command line.
5568 The string displayed when a Fortran source file
5569 is compiled to an object file.
5570 If this is not set, then $FORTRANCOM
5571 (the command line) is displayed.
5574 General user-specified options that are passed to the Fortran compiler.
5575 Note that this variable does
5579 (or similar) include or module search path options
5580 that scons generates automatically from $FORTRANPATH.
5582 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5584 for the variables that expand those options.
5586 .IP _FORTRANINCFLAGS
5587 An automatically-generated construction variable
5588 containing the Fortran compiler command-line options
5589 for specifying directories to be searched for include
5590 files and module files.
5591 The value of $_FORTRANINCFLAGS is created
5592 by prepending/appending $INCPREFIX and $INCSUFFIX
5593 to the beginning and end
5594 of each directory in $FORTRANPATH.
5597 Directory location where the Fortran compiler should place
5598 any module files it generates. This variable is empty, by default. Some
5599 Fortran compilers will internally append this directory in the search path
5600 for module files, as well
5602 .IP FORTRANMODDIRPREFIX
5603 The prefix used to specify a module directory on the Fortran compiler command
5605 This will be appended to the beginning of the directory
5606 in the $FORTRANMODDIR construction variables
5607 when the $_FORTRANMODFLAG variables is automatically generated.
5609 .IP FORTRANMODDIRSUFFIX
5610 The suffix used to specify a module directory on the Fortran compiler command
5612 This will be appended to the beginning of the directory
5613 in the $FORTRANMODDIR construction variables
5614 when the $_FORTRANMODFLAG variables is automatically generated.
5617 An automatically-generated construction variable
5618 containing the Fortran compiler command-line option
5619 for specifying the directory location where the Fortran
5620 compiler should place any module files that happen to get
5621 generated during compilation.
5622 The value of $_FORTRANMODFLAG is created
5623 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5624 to the beginning and end of the directory in $FORTRANMODDIR.
5626 .IP FORTRANMODPREFIX
5627 The module file prefix used by the Fortran compiler. SCons assumes that
5628 the Fortran compiler follows the quasi-standard naming convention for
5630 .I <module_name>.mod.
5631 As a result, this variable is left empty, by default. For situations in
5632 which the compiler does not necessarily follow the normal convention,
5633 the user may use this variable. Its value will be appended to every
5634 module file name as scons attempts to resolve dependencies.
5636 .IP FORTRANMODSUFFIX
5637 The module file suffix used by the Fortran compiler. SCons assumes that
5638 the Fortran compiler follows the quasi-standard naming convention for
5640 .I <module_name>.mod.
5641 As a result, this variable is set to ".mod", by default. For situations
5642 in which the compiler does not necessarily follow the normal convention,
5643 the user may use this variable. Its value will be appended to every
5644 module file name as scons attempts to resolve dependencies.
5647 The list of directories that the Fortran compiler will search for
5648 include files and (for some compilers) module files. The Fortran implicit
5649 dependency scanner will search these directories for include files (but
5650 not module files since they are autogenerated and, as such, may not
5651 actually exist at the time the scan takes place). Don't explicitly put
5652 include directory arguments in FORTRANFLAGS because the result will be
5653 non-portable and the directories will not be searched by the dependency
5654 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5655 to the SConscript directory when they are used in a command. To force
5657 to look-up a directory relative to the root of the source tree use #:
5660 env = Environment(FORTRANPATH='#/include')
5664 The directory look-up can also be forced using the
5669 include = Dir('include')
5670 env = Environment(FORTRANPATH=include)
5674 The directory list will be added to command lines
5675 through the automatically-generated
5677 construction variable,
5678 which is constructed by
5679 appending the values of the
5680 $INCPREFIX and $INCSUFFIX
5681 construction variables
5682 to the beginning and end
5683 of each directory in $FORTRANPATH.
5684 Any command lines you define that need
5685 the FORTRANPATH directory list should
5686 include $_FORTRANINCFLAGS:
5689 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5693 The command line used to compile a Fortran source file to an object file
5694 after first running the file through the C preprocessor.
5695 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5696 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5697 construction variables are included on this command line.
5700 The list of suffixes of files that will be scanned
5701 for Fortran implicit dependencies
5702 (INCLUDE lines & USE statements).
5703 The default list is:
5706 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5707 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5711 A function that converts a file name into a File instance relative to the
5716 frameworks options to be added at
5717 the end of a command
5718 line building a loadable module.
5721 The Ghostscript program used to convert PostScript to PDF files.
5724 General options passed to the Ghostscript program
5725 when converting PostScript to PDF files.
5728 The Ghostscript command line used to convert PostScript to PDF files.
5731 The string displayed when
5732 Ghostscript is used to convert
5733 a PostScript file to a PDF file.
5734 If this is not set, then $GSCOM (the command line) is displayed.
5737 The list of suffixes of files that will be scanned
5738 for IDL implicit dependencies
5739 (#include or import lines).
5740 The default list is:
5747 The prefix used to specify an include directory on the C compiler command
5749 This will be appended to the beginning of each directory
5750 in the $CPPPATH and $FORTRANPATH construction variables
5751 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5752 variables are automatically generated.
5755 The suffix used to specify an include directory on the C compiler command
5757 This will be appended to the end of each directory
5758 in the $CPPPATH and $FORTRANPATH construction variables
5759 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
5760 variables are automatically generated.
5763 A function to be called to install a file into a
5764 destination file name.
5765 The default function copies the file into the destination
5766 (and sets the destination file's mode and permission bits
5767 to match the source file's).
5768 The function takes the following arguments:
5771 def install(dest, source, env):
5775 is the path name of the destination file.
5777 is the path name of the source file.
5779 is the construction environment
5780 (a dictionary of construction values)
5781 in force for this file installation.
5783 .IP INTEL_C_COMPILER_VERSION
5784 Set by the "intelc" Tool
5785 to the major version number of the Intel C compiler
5789 The Java archive tool.
5792 The directory to which the Java archive tool should change
5798 The command line used to call the Java archive tool.
5801 The string displayed when the Java archive tool
5803 If this is not set, then $JARCOM (the command line) is displayed.
5806 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
5810 General options passed to the Java archive tool.
5811 By default this is set to
5813 to create the necessary
5818 The suffix for Java archives:
5826 The command line used to compile a directory tree containing
5827 Java source files to
5828 corresponding Java class files.
5829 Any options specified in the $JAVACFLAGS construction variable
5830 are included on this command line.
5833 The string displayed when compiling
5834 a directory tree of Java source files to
5835 corresponding Java class files.
5836 If this is not set, then $JAVACCOM (the command line) is displayed.
5839 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
5843 General options that are passed to the Java compiler.
5846 The directory in which Java class files may be found.
5847 This is stripped from the beginning of any Java .class
5848 file names supplied to the
5853 The suffix for Java class files;
5858 The Java generator for C header and stub files.
5861 The command line used to generate C header and stub files
5863 Any options specified in the $JAVAHFLAGS construction variable
5864 are included on this command line.
5867 The string displayed when C header and stub files
5868 are generated from Java classes.
5869 If this is not set, then $JAVAHCOM (the command line) is displayed.
5872 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
5876 General options passed to the C header and stub file generator
5880 The suffix for Java files;
5885 The LaTeX structured formatter and typesetter.
5888 The command line used to call the LaTeX structured formatter and typesetter.
5891 The string displayed when calling
5892 the LaTeX structured formatter and typesetter.
5893 If this is not set, then $LATEXCOM (the command line) is displayed.
5896 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
5900 General options passed to the LaTeX structured formatter and typesetter.
5903 The linker for building loadable modules.
5904 By default, this is the same as $SHLINK.
5907 The command line for building loadable modules.
5908 On Mac OS X, this uses the $LDMODULE,
5909 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
5910 On other systems, this is the same as $SHLINK.
5913 The string displayed when building loadable modules.
5914 If this is not set, then $LDMODULECOM (the command line) is displayed.
5917 General user options passed to the linker for building loadable modules.
5920 The prefix used for loadable module file names.
5921 On Mac OS X, this is null;
5922 on other systems, this is
5923 the same as $SHLIBPREFIX.
5926 The suffix used for loadable module file names.
5927 On Mac OS X, this is null;
5928 on other systems, this is
5929 the same as $SHLIBSUFFIX.
5932 The lexical analyzer generator.
5935 General options passed to the lexical analyzer generator.
5938 The command line used to call the lexical analyzer generator
5939 to generate a source file.
5942 The string displayed when generating a source file
5943 using the lexical analyzer generator.
5944 If this is not set, then $LEXCOM (the command line) is displayed.
5947 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
5951 An automatically-generated construction variable
5952 containing the linker command-line options
5953 for specifying directories to be searched for library.
5954 The value of $_LIBDIRFLAGS is created
5955 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
5956 to the beginning and end
5957 of each directory in $LIBPATH.
5960 The prefix used to specify a library directory on the linker command line.
5961 This will be appended to the beginning of each directory
5962 in the $LIBPATH construction variable
5963 when the $_LIBDIRFLAGS variable is automatically generated.
5966 The suffix used to specify a library directory on the linker command line.
5967 This will be appended to the end of each directory
5968 in the $LIBPATH construction variable
5969 when the $_LIBDIRFLAGS variable is automatically generated.
5972 An automatically-generated construction variable
5973 containing the linker command-line options
5974 for specifying libraries to be linked with the resulting target.
5975 The value of $_LIBFLAGS is created
5976 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
5977 to the beginning and end
5978 of each filename in $LIBS.
5981 The prefix used to specify a library to link on the linker command line.
5982 This will be appended to the beginning of each library
5983 in the $LIBS construction variable
5984 when the $_LIBFLAGS variable is automatically generated.
5987 The suffix used to specify a library to link on the linker command line.
5988 This will be appended to the end of each library
5989 in the $LIBS construction variable
5990 when the $_LIBFLAGS variable is automatically generated.
5993 The list of directories that will be searched for libraries.
5994 The implicit dependency scanner will search these
5995 directories for include files. Don't explicitly put include directory
5996 arguments in $LINKFLAGS or $SHLINKFLAGS
5997 because the result will be non-portable
5998 and the directories will not be searched by the dependency scanner. Note:
5999 directory names in LIBPATH will be looked-up relative to the SConscript
6000 directory when they are used in a command. To force
6002 to look-up a directory relative to the root of the source tree use #:
6005 env = Environment(LIBPATH='#/libs')
6009 The directory look-up can also be forced using the
6015 env = Environment(LIBPATH=libs)
6019 The directory list will be added to command lines
6020 through the automatically-generated
6022 construction variable,
6023 which is constructed by
6024 appending the values of the
6025 $LIBDIRPREFIX and $LIBDIRSUFFIX
6026 construction variables
6027 to the beginning and end
6028 of each directory in $LIBPATH.
6029 Any command lines you define that need
6030 the LIBPATH directory list should
6031 include $_LIBDIRFLAGS:
6034 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6038 The prefix used for (static) library file names.
6039 A default value is set for each platform
6040 (posix, win32, os2, etc.),
6041 but the value is overridden by individual tools
6042 (ar, mslib, sgiar, sunar, tlib, etc.)
6043 to reflect the names of the libraries they create.
6046 An array of legal prefixes for library file names.
6049 A list of one or more libraries
6050 that will be linked with
6051 any executable programs
6052 created by this environment.
6055 The library list will be added to command lines
6056 through the automatically-generated
6058 construction variable,
6059 which is constructed by
6060 appending the values of the
6061 $LIBLINKPREFIX and $LIBLINKSUFFIX
6062 construction variables
6063 to the beginning and end
6064 of each filename in $LIBS.
6065 Any command lines you define that need
6066 the LIBS library list should
6070 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6078 list, the name of that file will be added to
6080 and thus the link line, as is, without
6086 env.Append(LIBS=File('/tmp/mylib.so'))
6090 In all cases, scons will add dependencies from the executable program to
6091 all the libraries in this list.
6094 The suffix used for (static) library file names.
6095 A default value is set for each platform
6096 (posix, win32, os2, etc.),
6097 but the value is overridden by individual tools
6098 (ar, mslib, sgiar, sunar, tlib, etc.)
6099 to reflect the names of the libraries they create.
6102 An array of legal suffixes for library file names.
6108 General user options passed to the linker.
6109 Note that this variable should
6113 (or similar) options for linking with the libraries listed in $LIBS,
6116 (or similar) library search path options
6117 that scons generates automatically from $LIBPATH.
6121 for the variable that expands to library-link options,
6125 for the variable that expands to library search path options.
6128 The command line used to link object files into an executable.
6131 The string displayed when object files
6132 are linked into an executable.
6133 If this is not set, then $LINKCOM (the command line) is displayed.
6136 env = Environment(LINKCOMSTR = "Linking $TARGET")
6140 The M4 macro preprocessor.
6143 General options passed to the M4 macro preprocessor.
6146 The command line used to pass files through the M4 macro preprocessor.
6149 The string displayed when
6150 a file is passed through the M4 macro preprocessor.
6151 If this is not set, then $M4COM (the command line) is displayed.
6154 The maximum number of characters allowed on an external command line.
6156 link lines longer than this many characters
6157 are linke via a temporary file name.
6160 When the Microsoft Visual Studio tools are initialized, they set up
6161 this dictionary with the following keys:
6164 the version of MSVS being used (can be set via
6168 the available versions of MSVS installed
6171 installed directory of Visual C++
6174 installed directory of Visual Studio
6177 installed directory of the .NET framework
6179 .B FRAMEWORKVERSIONS:
6180 list of installed versions of the .NET framework, sorted latest to oldest.
6182 .B FRAMEWORKVERSION:
6183 latest installed version of the .NET framework
6186 installed location of the .NET SDK.
6189 installed location of the Platform SDK.
6191 .B PLATFORMSDK_MODULES:
6192 dictionary of installed Platform SDK modules,
6193 where the dictionary keys are keywords for the various modules, and
6194 the values are 2-tuples where the first is the release date, and the
6195 second is the version number.
6197 If a value isn't set, it wasn't available in the registry.
6199 .IP MSVS_IGNORE_IDE_PATHS
6200 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6201 instead of the settings from the IDE.
6203 For Visual Studio, SCons will (by default) automatically determine
6204 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6205 set by the IDE. You can override this behavior by setting these
6206 variables after Environment initialization, or by setting
6207 .B MSVS_IGNORE_IDE_PATHS = 1
6208 in the Environment initialization.
6209 Specifying this will not leave these unset, but will set them to a
6210 minimal set of paths needed to run the tools successfully.
6213 For VS6, the mininimal set is:
6214 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6215 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6216 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6218 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6219 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6220 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6224 Where '<VSDir>' is the installed location of Visual Studio.
6226 .IP MSVS_USE_MFC_DIRS
6227 Tells the MS Visual Studio tool(s) to use
6228 the MFC directories in its default paths
6229 for compiling and linking.
6230 Under MSVS version 6,
6232 .B MSVS_USE_MFC_DIRS
6241 external environment variable,
6247 external environment variable.
6248 Under MSVS version 7,
6250 .B MSVS_USE_MFC_DIRS
6253 .B "atlmfc\\\\include"
6254 directory to the default
6256 external environment variable,
6259 directory to the default
6261 external environment variable.
6262 The current default value is
6264 which means these directories
6265 are added to the paths by default.
6266 This default value is likely to change
6267 in a future release,
6268 so users who want the ATL and MFC
6269 values included in their paths
6270 are encouraged to enable the
6271 .B MSVS_USE_MFC_DIRS
6273 to avoid future incompatibility.
6274 This variable has no effect if the
6278 environment variables are set explictly.
6281 Sets the preferred version of MSVS to use.
6283 SCons will (by default) select the latest version of MSVS
6284 installed on your machine. So, if you have version 6 and version 7
6285 (MSVS .NET) installed, it will prefer version 7. You can override this by
6288 variable in the Environment initialization, setting it to the
6289 appropriate version ('6.0' or '7.0', for example).
6290 If the given version isn't installed, tool initialization will fail.
6293 The action used to generate Microsoft Visual Studio
6294 project and solution files.
6296 .IP MSVSPROJECTSUFFIX
6297 The suffix used for Microsoft Visual Studio project (DSP) files.
6298 The default value is
6300 when using Visual Studio version 7.x (.NET),
6303 when using earlier versions of Visual Studio.
6305 .IP MSVSSOLUTIONSUFFIX
6306 The suffix used for Microsoft Visual Studio solution (DSW) files.
6307 The default value is
6309 when using Visual Studio version 7.x (.NET),
6312 when using earlier versions of Visual Studio.
6315 The version number of the MetroWerks CodeWarrior C compiler
6319 A list of installed versions of the MetroWerks CodeWarrior C compiler
6323 When set to non-zero,
6324 suppresses creation of a corresponding Win32 static import lib by the
6326 builder when used with
6327 MinGW or Microsoft Visual Studio.
6328 This also suppresses creation
6329 of an export (.exp) file
6330 when using Microsoft Visual Studio.
6333 The prefix used for (static) object file names.
6336 The suffix used for (static) object file names.
6339 The Perforce executable.
6342 The command line used to
6343 fetch source files from Perforce.
6346 The string displayed when
6347 fetching a source file from Perforce.
6348 If this is not set, then $P4COM (the command line) is displayed.
6351 General options that are passed to Perforce.
6354 The Microsoft Visual C++ precompiled header that will be used when compiling
6355 object files. This variable is ignored by tools other than Microsoft Visual C++.
6356 When this variable is
6357 defined SCons will add options to the compiler command line to
6358 cause it to use the precompiled header, and will also set up the
6359 dependencies for the PCH file. Example:
6362 env['PCH'] = 'StdAfx.pch'
6366 The command line used by the
6368 builder to generated a precompiled header.
6371 The string displayed when generating a precompiled header.
6372 If this is not set, then $PCHCOM (the command line) is displayed.
6375 This variable specifies how much of a source file is precompiled. This
6376 variable is ignored by tools other than Microsoft Visual C++, or when
6377 the PCH variable is not being used. When this variable is define it
6378 must be a string that is the name of the header that
6379 is included at the end of the precompiled portion of the source files, or
6380 the empty string if the "#pragma hrdstop" construct is being used:
6383 env['PCHSTOP'] = 'StdAfx.h'
6387 The Microsoft Visual C++ PDB file that will store debugging information for
6388 object files, shared libraries, and programs. This variable is ignored by
6389 tools other than Microsoft Visual C++.
6390 When this variable is
6391 defined SCons will add options to the compiler and linker command line to
6392 cause them to generate external debugging information, and will also set up the
6393 dependencies for the PDB file. Example:
6396 env['PDB'] = 'hello.pdb'
6400 A deprecated synonym for $DVIPDFCOM.
6403 The prefix used for PDF file names.
6406 The suffix used for PDF file names.
6409 The name of the platform used to create the Environment. If no platform is
6410 specified when the Environment is created,
6412 autodetects the platform.
6415 env = Environment(tools = [])
6416 if env['PLATFORM'] == 'cygwin':
6422 .IP PRINT_CMD_LINE_FUNC
6423 A Python function used to print the command lines as they are executed
6424 (assuming command printing is not disabled by the
6428 options or their equivalents).
6429 The function should take four arguments:
6431 the command being executed (a string),
6433 the target being built (file node, list, or string name(s)),
6435 the source(s) used (file node, list, or string name(s)), and
6437 the environment being used.
6439 The function must do the printing itself. The default implementation,
6440 used if this variable is not set or is None, is:
6442 def print_cmd_line(s, target, source, env):
6443 sys.stdout.write(s + "\n")
6446 Here's an example of a more interesting function:
6448 def print_cmd_line(s, target, source, env):
6449 sys.stdout.write("Building %s -> %s...\n" %
6450 (' and '.join([str(x) for x in source]),
6451 ' and '.join([str(x) for x in target])))
6452 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6453 env.Program('foo', 'foo.c')
6456 This just prints "Building <targetname> from <sourcename>..." instead
6457 of the actual commands.
6458 Such a function could also log the actual commands to a log file,
6462 The prefix used for executable file names.
6465 The suffix used for executable file names.
6468 The command line used to convert TeX DVI files into a PostScript file.
6471 The string displayed when a TeX DVI file
6472 is converted into a PostScript file.
6473 If this is not set, then $PSCOM (the command line) is displayed.
6476 The prefix used for PostScript file names.
6479 The prefix used for PostScript file names.
6482 The qt tool tries to take this from os.environ.
6483 It also initializes all QT_*
6484 construction variables listed below.
6485 (Note that all paths are constructed
6486 with python's os.path.join() method,
6487 but are listed here with the '/' separator
6488 for easier reading.)
6489 In addition, the construction environment
6490 variables CPPPATH, LIBPATH and LIBS may be modified
6492 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6493 are modified. Because the build-performance is affected when using this tool,
6494 you have to explicitly specify it at Environment creation:
6497 Environment(tools=['default','qt'])
6500 The qt tool supports the following operations:
6502 .B Automatic moc file generation from header files.
6503 You do not have to specify moc files explicitly, the tool does it for you.
6504 However, there are a few preconditions to do so: Your header file must have
6505 the same filebase as your implementation file and must stay in the same
6506 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6507 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6508 See also the corresponding builder method
6511 .B Automatic moc file generation from cxx files.
6512 As stated in the qt documentation, include the moc file at the end of
6513 the cxx file. Note that you have to include the file, which is generated
6514 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6515 <basename>.moc. A warning is generated after building the moc file, if you
6516 do not include the correct file. If you are using BuildDir, you may
6517 need to specify duplicate=1. You can turn off automatic moc file generation
6518 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6521 .B Automatic handling of .ui files.
6522 The implementation files generated from .ui files are handled much the same
6523 as yacc or lex files. Each .ui file given as a source of Program, Library or
6524 SharedLibrary will generate three files, the declaration file, the
6525 implementation file and a moc file. Because there are also generated headers,
6526 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6530 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6531 specify files to run moc on.
6534 The path where the qt binaries are installed.
6535 The default value is '$QTDIR/bin'.
6538 The path where the qt header files are installed.
6539 The default value is '$QTDIR/include'.
6540 Note: If you set this variable to None, the tool won't change the CPPPATH
6541 construction variable.
6544 Prints lots of debugging information while scanning for moc files.
6547 The path where the qt libraries are installed.
6548 The default value is '$QTDIR/lib'.
6549 Note: If you set this variable to None, the tool won't change the LIBPATH
6550 construction variable.
6553 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6554 this variable to None, the tool won't change the LIBS variable.
6557 Default value is '$QT_BINPATH/moc'.
6560 Default value is ''. Prefix for moc output files, when source is a cxx file.
6563 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6566 .IP QT_MOCFROMCPPFLAGS
6567 Default value is '-i'. These flags are passed to moc, when moccing a
6570 .IP QT_MOCFROMCXXCOM
6571 Command to generate a moc file from a cpp file.
6573 .IP QT_MOCFROMCXXCOMSTR
6574 The string displayed when generating a moc file from a cpp file.
6575 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
6578 Command to generate a moc file from a header.
6580 .IP QT_MOCFROMHCOMSTR
6581 The string displayed when generating a moc file from a cpp file.
6582 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
6584 .IP QT_MOCFROMHFLAGS
6585 Default value is ''. These flags are passed to moc, when moccing a header
6589 Default value is 'moc_'. Prefix for moc output files, when source is a header.
6592 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
6596 Default value is '$QT_BINPATH/uic'.
6599 Command to generate header files from .ui files.
6602 The string displayed when generating header files from .ui files.
6603 If this is not set, then $QT_UICCOM (the command line) is displayed.
6606 Default value is ''. These flags are passed to uic, when creating a a h
6607 file from a .ui file.
6609 .IP QT_UICDECLPREFIX
6610 Default value is ''. Prefix for uic generated header files.
6612 .IP QT_UICDECLSUFFIX
6613 Default value is '.h'. Suffix for uic generated header files.
6616 Default value is ''. These flags are passed to uic, when creating a cxx
6617 file from a .ui file.
6619 .IP QT_UICIMPLPREFIX
6620 Default value is 'uic_'. Prefix for uic generated implementation files.
6622 .IP QT_UICIMPLSUFFIX
6623 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
6627 Default value is '.ui'. Suffix of designer input files.
6630 The archive indexer.
6633 General options passed to the archive indexer.
6636 The resource compiler used by the RES builder.
6639 The command line used by the RES builder.
6642 The string displayed when invoking the resource compiler.
6643 If this is not set, then $RCCOM (the command line) is displayed.
6646 The flags passed to the resource compiler by the RES builder.
6650 Note that this variable is not actually used
6651 for the command to fetch source files from RCS;
6654 construction variable, below.
6657 The RCS "checkout" executable,
6658 used to fetch source files from RCS.
6661 The command line used to
6662 fetch (checkout) source files from RCS.
6665 The string displayed when fetching
6666 a source file from RCS.
6667 If this is not set, then $RCS_COCOM
6668 (the command line) is displayed.
6671 Options that are passed to the $RCS_CO command.
6674 The program used to register DLLs on Windows systems.
6677 The command line used to register a newly-built DLL file
6679 Invoked when the "register=1"
6680 keyword argument is passed to the
6685 The string displayed when registering a newly-built DLL file.
6686 If this is not set, then $REGSVRCOM (the command line) is displayed.
6689 A function that converts a file name into a list of Dir instances by
6690 searching the repositories.
6693 The Java RMI stub compiler.
6696 The command line used to compile stub
6697 and skeleton class files
6698 from Java classes that contain RMI implementations.
6699 Any options specified in the $RMICFLAGS construction variable
6700 are included on this command line.
6703 The string displayed when compiling
6704 stub and skeleton class files
6705 from Java classes that contain RMI implementations.
6706 If this is not set, then $RMICCOM (the command line) is displayed.
6709 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
6713 General options passed to the Java RMI stub compiler.
6716 The RPC protocol compiler.
6718 .IP RPCGENCLIENTFLAGS
6719 Options passed to the RPC protocol compiler
6720 when generating client side stubs.
6721 These are in addition to any flags specified in the
6723 construction variable.
6726 General options passed to the RPC protocol compiler.
6728 .IP RPCGENHEADERFLAGS
6729 Options passed to the RPC protocol compiler
6730 when generating a header file.
6731 These are in addition to any flags specified in the
6733 construction variable.
6735 .IP RPCGENSERVICEFLAGS
6736 Options passed to the RPC protocol compiler
6737 when generating server side stubs.
6738 These are in addition to any flags specified in the
6740 construction variable.
6743 Options passed to the RPC protocol compiler
6744 when generating XDR routines.
6745 These are in addition to any flags specified in the
6747 construction variable.
6750 A list of paths to search for shared libraries when running programs.
6751 Currently only used in the GNU (gnulink),
6752 IRIX (sgilink) and Sun (sunlink) linkers.
6753 Ignored on platforms and toolchains that don't support it.
6754 Note that the paths added to RPATH
6755 are not transformed by
6757 in any way: if you want an absolute
6758 path, you must make it absolute yourself.
6761 A list of the available implicit dependency scanners.
6762 New file scanners may be added by
6763 appending to this list,
6764 although the more flexible approach
6765 is to associate scanners
6766 with a specific Builder.
6767 See the sections "Builder Objects"
6768 and "Scanner Objects,"
6769 below, for more information.
6772 The SCCS executable.
6775 The command line used to
6776 fetch source files from SCCS.
6779 The string displayed when fetching
6780 a source file from a CVS repository.
6781 If this is not set, then $SCCSCOM
6782 (the command line) is displayed.
6785 General options that are passed to SCCS.
6788 Options that are passed specifically to the SCCS "get" subcommand.
6789 This can be set, for example, to
6791 to check out editable files from SCCS.
6794 The C compiler used for generating shared-library objects.
6797 The command line used to compile a C source file
6798 to a shared-library object file.
6799 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
6800 are included on this command line.
6803 The string displayed when a C source file
6804 is compiled to a shared object file.
6805 If this is not set, then $SHCCCOM (the command line) is displayed.
6808 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
6812 Options that are passed to the C compiler
6813 to generate shared-library objects.
6816 The C++ compiler used for generating shared-library objects.
6819 The command line used to compile a C++ source file
6820 to a shared-library object file.
6821 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
6822 are included on this command line.
6825 The string displayed when a C++ source file
6826 is compiled to a shared object file.
6827 If this is not set, then $SHCXXCOM (the command line) is displayed.
6830 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
6834 Options that are passed to the C++ compiler
6835 to generate shared-library objects.
6838 A string naming the shell program that will be passed to the
6843 construction variable for more information.
6846 The Fortran 77 compiler used for generating shared-library objects.
6847 You should normally set the $SHFORTRANC variable,
6848 which specifies the default Fortran compiler
6849 for all Fortran versions.
6850 You only need to set $SHF77 if you need to use a specific compiler
6851 or compiler version for Fortran 77 files.
6854 The command line used to compile a Fortran 77 source file
6855 to a shared-library object file.
6856 You only need to set $SHF77COM if you need to use a specific
6857 command line for Fortran 77 files.
6858 You should normally set the $SHFORTRANCOM variable,
6859 which specifies the default command line
6860 for all Fortran versions.
6863 The string displayed when a Fortran 77 source file
6864 is compiled to a shared-library object file.
6865 If this is not set, then $SHF77COM or $SHFORTRANCOM
6866 (the command line) is displayed.
6869 Options that are passed to the Fortran 77 compiler
6870 to generated shared-library objects.
6871 You only need to set $SHF77FLAGS if you need to define specific
6872 user options for Fortran 77 files.
6873 You should normally set the $SHFORTRANFLAGS variable,
6874 which specifies the user-specified options
6875 passed to the default Fortran compiler
6876 for all Fortran versions.
6879 The command line used to compile a Fortran 77 source file to a
6880 shared-library object file
6881 after first running the file through the C preprocessor.
6882 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
6883 are included on this command line.
6884 You only need to set $SHF77PPCOM if you need to use a specific
6885 C-preprocessor command line for Fortran 77 files.
6886 You should normally set the $SHFORTRANPPCOM variable,
6887 which specifies the default C-preprocessor command line
6888 for all Fortran versions.
6891 The Fortran 90 compiler used for generating shared-library objects.
6892 You should normally set the $SHFORTRANC variable,
6893 which specifies the default Fortran compiler
6894 for all Fortran versions.
6895 You only need to set $SHF90 if you need to use a specific compiler
6896 or compiler version for Fortran 90 files.
6899 The command line used to compile a Fortran 90 source file
6900 to a shared-library object file.
6901 You only need to set $SHF90COM if you need to use a specific
6902 command line for Fortran 90 files.
6903 You should normally set the $SHFORTRANCOM variable,
6904 which specifies the default command line
6905 for all Fortran versions.
6908 The string displayed when a Fortran 90 source file
6909 is compiled to a shared-library object file.
6910 If this is not set, then $SHF90COM or $SHFORTRANCOM
6911 (the command line) is displayed.
6914 Options that are passed to the Fortran 90 compiler
6915 to generated shared-library objects.
6916 You only need to set $SHF90FLAGS if you need to define specific
6917 user options for Fortran 90 files.
6918 You should normally set the $SHFORTRANFLAGS variable,
6919 which specifies the user-specified options
6920 passed to the default Fortran compiler
6921 for all Fortran versions.
6924 The command line used to compile a Fortran 90 source file to a
6925 shared-library object file
6926 after first running the file through the C preprocessor.
6927 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
6928 are included on this command line.
6929 You only need to set $SHF90PPCOM if you need to use a specific
6930 C-preprocessor command line for Fortran 90 files.
6931 You should normally set the $SHFORTRANPPCOM variable,
6932 which specifies the default C-preprocessor command line
6933 for all Fortran versions.
6936 The Fortran 95 compiler used for generating shared-library objects.
6937 You should normally set the $SHFORTRANC variable,
6938 which specifies the default Fortran compiler
6939 for all Fortran versions.
6940 You only need to set $SHF95 if you need to use a specific compiler
6941 or compiler version for Fortran 95 files.
6944 The command line used to compile a Fortran 95 source file
6945 to a shared-library object file.
6946 You only need to set $SHF95COM if you need to use a specific
6947 command line for Fortran 95 files.
6948 You should normally set the $SHFORTRANCOM variable,
6949 which specifies the default command line
6950 for all Fortran versions.
6953 The string displayed when a Fortran 95 source file
6954 is compiled to a shared-library object file.
6955 If this is not set, then $SHF95COM or $SHFORTRANCOM
6956 (the command line) is displayed.
6959 Options that are passed to the Fortran 95 compiler
6960 to generated shared-library objects.
6961 You only need to set $SHF95FLAGS if you need to define specific
6962 user options for Fortran 95 files.
6963 You should normally set the $SHFORTRANFLAGS variable,
6964 which specifies the user-specified options
6965 passed to the default Fortran compiler
6966 for all Fortran versions.
6969 The command line used to compile a Fortran 95 source file to a
6970 shared-library object file
6971 after first running the file through the C preprocessor.
6972 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
6973 are included on this command line.
6974 You only need to set $SHF95PPCOM if you need to use a specific
6975 C-preprocessor command line for Fortran 95 files.
6976 You should normally set the $SHFORTRANPPCOM variable,
6977 which specifies the default C-preprocessor command line
6978 for all Fortran versions.
6981 The default Fortran compiler used for generating shared-library objects.
6984 The command line used to compile a Fortran source file
6985 to a shared-library object file.
6988 The string displayed when a Fortran source file
6989 is compiled to a shared-library object file.
6990 If this is not set, then $SHFORTRANCOM
6991 (the command line) is displayed.
6994 Options that are passed to the Fortran compiler
6995 to generate shared-library objects.
6998 The command line used to compile a Fortran source file to a
6999 shared-library object file
7000 after first running the file through the C preprocessor.
7001 Any options specified
7002 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
7003 are included on this command line.
7006 The prefix used for shared library file names.
7009 The suffix used for shared library file names.
7012 The linker for programs that use shared libraries.
7015 The command line used to link programs using shared libaries.
7018 The string displayed when programs using shared libraries are linked.
7019 If this is not set, then $SHLINKCOM (the command line) is displayed.
7022 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
7026 General user options passed to the linker for programs using shared libraries.
7027 Note that this variable should
7031 (or similar) options for linking with the libraries listed in $LIBS,
7034 (or similar) include search path options
7035 that scons generates automatically from $LIBPATH.
7039 for the variable that expands to library-link options,
7043 for the variable that expands to library search path options.
7046 The prefix used for shared object file names.
7049 The suffix used for shared object file names.
7052 A reserved variable name
7053 that may not be set or used in a construction environment.
7054 (See "Variable Substitution," below.)
7057 A reserved variable name
7058 that may not be set or used in a construction environment.
7059 (See "Variable Substitution," below.)
7062 A command interpreter function that will be called to execute command line
7063 strings. The function must expect the following arguments:
7066 def spawn(shell, escape, cmd, args, env):
7070 is a string naming the shell program to use.
7072 is a function that can be called to escape shell special characters in
7075 is the path to the command to be executed.
7077 is the arguments to the command.
7079 is a dictionary of the environment variables
7080 in which the command should be executed.
7083 '\"The Subversion executable (usually named
7087 '\"The command line used to
7088 '\"fetch source files from a Subversion repository.
7091 '\"General options that are passed to Subversion.
7094 The scripting language wrapper and interface generator.
7097 The suffix that will be used for intermediate C
7098 source files generated by
7099 the scripting language wrapper and interface generator.
7100 The default value is
7101 .BR _wrap$CFILESUFFIX .
7102 By default, this value is used whenever the
7106 specified as part of the
7108 construction variable.
7111 The command line used to call
7112 the scripting language wrapper and interface generator.
7115 The string displayed when calling
7116 the scripting language wrapper and interface generator.
7117 If this is not set, then $SWIGCOM (the command line) is displayed.
7119 .IP SWIGCXXFILESUFFIX
7120 The suffix that will be used for intermediate C++
7121 source files generated by
7122 the scripting language wrapper and interface generator.
7123 The default value is
7124 .BR _wrap$CFILESUFFIX .
7125 By default, this value is used whenever the
7127 option is specified as part of the
7129 construction variable.
7132 General options passed to
7133 the scripting language wrapper and interface generator.
7134 This is where you should set
7138 or whatever other options you want to specify to SWIG.
7141 option in this variable,
7144 generate a C++ intermediate source file
7145 with the extension that is specified as the
7153 The command line used to call the tar archiver.
7156 The string displayed when archiving files
7157 using the tar archiver.
7158 If this is not set, then $TARCOM (the command line) is displayed.
7161 env = Environment(TARCOMSTR = "Archiving $TARGET")
7165 General options passed to the tar archiver.
7168 A reserved variable name
7169 that may not be set or used in a construction environment.
7170 (See "Variable Substitution," below.)
7173 A reserved variable name
7174 that may not be set or used in a construction environment.
7175 (See "Variable Substitution," below.)
7178 The suffix used for tar file names.
7181 The TeX formatter and typesetter.
7184 The command line used to call the TeX formatter and typesetter.
7187 The string displayed when calling
7188 the TeX formatter and typesetter.
7189 If this is not set, then $TEXCOM (the command line) is displayed.
7192 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7196 General options passed to the TeX formatter and typesetter.
7199 A list of the names of the Tool specifications
7200 that are part of this construction environment.
7202 .IP WIN32_INSERT_DEF
7203 When this is set to true,
7204 a library build of a WIN32 shared library (.dll file)
7205 will also build a corresponding .def file at the same time,
7206 if a .def file is not already listed as a build target.
7207 The default is 0 (do not build a .def file).
7210 The prefix used for WIN32 .def file names.
7213 The suffix used for WIN32 .def file names.
7216 The parser generator.
7219 The command line used to call the parser generator
7220 to generate a source file.
7223 The string displayed when generating a source file
7224 using the parser generator.
7225 If this is not set, then $YACCCOM (the command line) is displayed.
7228 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7232 General options passed to the parser generator.
7233 If $YACCFLAGS contains a \-d option,
7234 SCons assumes that the call will also create a .h file
7235 (if the yacc source file ends in a .y suffix)
7237 (if the yacc source file ends in a .yy suffix)
7241 header file generated by the parser generator
7245 Note that setting this variable does not cause
7246 the parser generator to generate a header
7247 file with the specified suffix,
7248 it exists to allow you to specify
7249 what suffix the parser generator will use of its own accord.
7250 The default value is
7253 .IP YACCHXXFILESUFFIX
7254 The suffix of the C++
7255 header file generated by the parser generator
7259 Note that setting this variable does not cause
7260 the parser generator to generate a header
7261 file with the specified suffix,
7262 it exists to allow you to specify
7263 what suffix the parser generator will use of its own accord.
7264 The default value is
7268 The zip compression and file packaging utility.
7271 The command line used to call the zip utility,
7272 or the internal Python function used to create a
7276 The string displayed when archiving files
7277 using the zip utility.
7278 If this is not set, then $ZIPCOM
7279 (the command line or internal Python function) is displayed.
7282 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7291 module used by the internal Python function
7292 to control whether the zip archive
7293 is compressed or not.
7294 The default value is
7295 .BR zipfile.ZIP_DEFLATED ,
7296 which creates a compressed zip archive.
7297 This value has no effect when using Python 1.5.2
7300 module is otherwise unavailable.
7303 General options passed to the zip utility.
7306 Construction variables can be retrieved and set using the
7308 method of the construction environment:
7311 dict = env.Dictionary()
7315 or using the [] operator:
7321 Construction variables can also be passed to the construction environment
7325 env = Environment(CC="cc")
7328 or when copying a construction environment using the
7333 env2 = env.Copy(CC="cl.exe")
7336 .SS Configure Contexts
7340 .I configure contexts,
7341 an integrated mechanism similar to the
7342 various AC_CHECK macros in GNU autoconf
7343 for testing for the existence of C header
7344 files, libraries, etc.
7345 In contrast to autoconf,
7347 does not maintain an explicit cache of the tested values,
7348 but uses its normal dependency tracking to keep the checked values
7349 up to date. However, users may override this behaviour with the
7351 command line option.
7353 The following methods can be used to perform checks:
7356 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7358 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7359 This creates a configure context, which can be used to perform checks.
7361 specifies the environment for building the tests.
7362 This environment may be modified when performing checks.
7364 is a dictionary containing custom tests.
7365 See also the section about custom tests below.
7366 By default, no custom tests are added to the configure context.
7368 specifies a directory where the test cases are built.
7369 Note that this directory is not used for building
7371 The default value is the directory
7374 specifies a file which collects the output from commands
7375 that are executed to check for the existence of header files, libraries, etc.
7376 The default is the file #/config.log.
7377 If you are using the
7380 you may want to specify a subdirectory under your build directory.
7382 specifies a C header file where the results of tests
7383 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7384 The default is to not write a
7387 You can specify the same
7389 file in multiple calls to Configure,
7392 will concatenate all results in the specified file.
7394 uses its normal dependency checking
7395 to decide if it's necessary to rebuild
7399 This means that the file is not necessarily re-built each
7401 but is only rebuilt if its contents will have changed
7402 and some target that depends on the
7404 file is being built.
7409 instance has the following associated methods:
7412 .RI Configure.Finish( self )
7413 This method should be called after configuration is done.
7414 It returns the environment as modified
7415 by the configuration checks performed.
7416 After this method is called, no further checks can be performed
7417 with this configuration context.
7418 However, you can create a new
7420 context to perform additional checks.
7421 Only one context should be active at a time.
7423 The following Checks are predefined.
7424 (This list will likely grow larger as time
7425 goes by and developers contribute new useful tests.)
7428 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7431 is usable in the specified language.
7434 in which case the last item in the list
7435 is the header file to be checked,
7436 and the previous list items are
7439 lines should precede the
7440 header line being checked for.
7441 The optional argument
7444 a two character string, where the first character denotes the opening
7445 quote and the second character denotes the closing quote.
7446 By default, both characters are " (double quote).
7447 The optional argument
7453 and selects the compiler to be used for the check.
7454 Returns 1 on success and 0 on failure.
7457 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7458 This is a wrapper around
7459 .B Configure.CheckHeader
7462 is usable in the C language.
7465 in which case the last item in the list
7466 is the header file to be checked,
7467 and the previous list items are
7470 lines should precede the
7471 header line being checked for.
7472 The optional argument
7475 a two character string, where the first character denotes the opening
7476 quote and the second character denotes the closing quote (both default
7478 Returns 1 on success and 0 on failure.
7481 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7482 This is a wrapper around
7483 .B Configure.CheckHeader
7486 is usable in the C++ language.
7489 in which case the last item in the list
7490 is the header file to be checked,
7491 and the previous list items are
7494 lines should precede the
7495 header line being checked for.
7496 The optional argument
7499 a two character string, where the first character denotes the opening
7500 quote and the second character denotes the closing quote (both default
7502 Returns 1 on success and 0 on failure.
7505 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7506 Checks if the specified
7507 C or C++ function is available.
7509 is the name of the function to check for.
7512 argument is a string
7516 that will be compiled
7517 to check if the function exists;
7523 char function_name();
7531 and selects the compiler to be used for the check;
7535 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
7542 is 1 and the library provides the specified
7544 appends the library to the LIBS construction environment variable.
7546 may also be None (the default),
7549 is checked with the current LIBS variable,
7550 or a list of library names,
7551 in which case each library in the list
7558 you can link against the specified
7566 and selects the compiler to be used for the check;
7568 The default value for
7571 It is assumed, that the C-language is used.
7572 This method returns 1 on success and 0 on error.
7575 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
7578 .RI Configure.CheckLib
7579 call, this call provides a more sophisticated way to check against libraries.
7582 specifies the library or a list of libraries to check.
7584 specifies a header to check for.
7587 in which case the last item in the list
7588 is the header file to be checked,
7589 and the previous list items are
7592 lines should precede the
7593 header line being checked for.
7595 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
7597 can be any valid expression (with a trailing ';'). The default is 'main();'.
7599 specifies whether to add the library to the environment (only if the check
7600 succeeds). This method returns 1 on success and 0 on error.
7603 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
7604 Checks for the existence of a type defined by
7607 specifies the typedef name to check for.
7609 is a string containing one or more
7611 lines that will be inserted into the program
7612 that will be run to test for the existence of the type.
7619 and selects the compiler to be used for the check;
7623 Example of a typical Configure usage:
7627 conf = Configure( env )
7628 if not conf.CheckCHeader( 'math.h' ):
7629 print 'We really need math.h!'
7631 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
7632 # do stuff for qt - usage, e.g.
7633 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
7638 You can define your own custom checks.
7639 in addition to the predefined checks.
7640 These are passed in a dictionary to the Configure function.
7641 This dictionary maps the names of the checks
7642 to user defined Python callables
7643 (either Python functions or class instances implementing the
7646 The first argument of the call is always a
7648 instance followed by the arguments,
7649 which must be supplied by the user of the check.
7650 These CheckContext instances define the following methods:
7653 .RI CheckContext.Message( self ", " text )
7655 Usually called before the check is started.
7657 will be displayed to the user, e.g. 'Checking for library X...'
7660 .RI CheckContext.Result( self, ", " res )
7662 Usually called after the check is done.
7664 can be either an integer or a string. In the former case, 'ok' (res != 0)
7665 or 'failed' (res == 0) is displayed to the user, in the latter case the
7666 given string is displayed.
7669 .RI CheckContext.TryCompile( self ", " text ", " extension )
7670 Checks if a file with the specified
7672 (e.g. '.c') containing
7674 can be compiled using the environment's
7676 builder. Returns 1 on success and 0 on failure.
7679 .RI CheckContext.TryLink( self ", " text ", " extension )
7680 Checks, if a file with the specified
7682 (e.g. '.c') containing
7684 can be compiled using the environment's
7686 builder. Returns 1 on success and 0 on failure.
7689 .RI CheckContext.TryRun( self ", " text ", " extension )
7690 Checks, if a file with the specified
7692 (e.g. '.c') containing
7694 can be compiled using the environment's
7696 builder. On success, the program is run. If the program
7697 executes successfully
7698 (that is, its return status is 0),
7703 is the standard output of the
7705 If the program fails execution
7706 (its return status is non-zero),
7707 then (0, '') is returned.
7710 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
7711 Checks if the specified
7713 with an optional source file (contents
7720 may be anything which can be converted to a
7727 is the content of the target file.
7733 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
7734 Low level implementation for testing specific builds;
7735 the methods above are based on this method.
7736 Given the Builder instance
7740 of a source file with optional
7742 this method returns 1 on success and 0 on failure. In addition,
7744 is set to the build target node, if the build was successful.
7747 Example for implementing and using custom tests:
7750 def CheckQt(context, qtdir):
7751 context.Message( 'Checking for qt ...' )
7752 lastLIBS = context.env['LIBS']
7753 lastLIBPATH = context.env['LIBPATH']
7754 lastCPPPATH= context.env['CPPPATH']
7755 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
7756 ret = context.TryLink("""
7758 int main(int argc, char **argv) {
7759 QApplication qapp(argc, argv);
7764 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
7765 context.Result( ret )
7769 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
7770 if not conf.CheckQt('/usr/lib/qt'):
7771 print 'We really need qt!'
7776 .SS Construction Variable Options
7778 Often when building software, various options need to be specified at build
7779 time that are not known when the SConstruct/SConscript files are
7780 written. For example, libraries needed for the build may be in non-standard
7781 locations, or site-specific compiler options may need to be passed to the
7784 provides a mechanism for overridding construction variables from the
7785 command line or a text-based SConscript file through an Options
7786 object. To create an Options object, call the Options() function:
7789 .RI Options([ files "], [" args ])
7790 This creates an Options object that will read construction variables from
7791 the file or list of filenames specified in
7793 If no files are specified,
7798 then no files will be read.
7799 The optional argument
7802 values that will override anything read from the specified files;
7803 it is primarily intended to be passed the
7805 dictionary that holds variables
7806 specified on the command line.
7810 opts = Options('custom.py')
7811 opts = Options('overrides.py', ARGUMENTS)
7812 opts = Options(None, {FOO:'expansion', BAR:7})
7815 Options objects have the following methods:
7818 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
7819 This adds a customizable construction variable to the Options object.
7821 is the name of the variable.
7823 is the help text for the variable.
7825 is the default value of the variable;
7826 if the default value is
7828 and there is no explicit value specified,
7829 the construction variable will
7831 be added to the construction environment.
7833 is called to validate the value of the variable, and should take three
7834 arguments: key, value, and environment
7836 is called to convert the value before putting it in the environment, and
7837 should take a single argument: value. Example:
7840 opts.Add('CC', 'The C compiler')
7844 .RI AddOptions( list )
7845 A wrapper script that adds
7846 multiple customizable construction variables
7847 to an Options object.
7849 is a list of tuple or list objects
7850 that contain the arguments
7851 for an individual call to the
7858 ('CC', 'The C compiler'),
7859 ('VALIDATE', 'An option for testing validation',
7860 'notset', validator, None),
7865 .RI Update( env ", [" args ])
7866 This updates a construction environment
7868 with the customized construction variables. Normally this method is not
7869 called directly, but is called indirectly by passing the Options object to
7870 the Environment() function:
7873 env = Environment(options=opts)
7877 The text file(s) that were specified
7878 when the Options object was created
7879 are executed as Python scripts,
7880 and the values of (global) Python variables set in the file
7881 are added to the construction environment.
7889 .RI Save( filename ", " env )
7890 This saves the currently set options into a script file named
7892 that can be used on the next invocation to automatically load the current
7893 settings. This method combined with the Options method can be used to
7894 support caching of options between runs.
7898 opts = Options(['options.cache', 'custom.py'])
7901 opts.Save('options.cache', env)
7905 .RI GenerateHelpText( env ", [" sort ])
7906 This generates help text documenting the customizable construction
7907 variables suitable to passing in to the Help() function.
7909 is the construction environment that will be used to get the actual values
7910 of customizable variables. Calling with
7914 will cause the output to be sorted
7915 by the specified argument.
7919 should take two arguments
7922 (like the standard Python
7927 Help(opts.GenerateHelpText(env))
7928 Help(opts.GenerateHelpText(env, sort=cmp))
7932 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
7933 This method returns a formatted string
7934 containing the printable help text
7936 It is normally not called directly,
7937 but is called by the
7938 .IR GenerateHelpText ()
7939 method to create the returned help text.
7940 It may be overridden with your own
7941 function that takes the arguments specified above
7942 and returns a string of help text formatted to your liking.
7944 .IR GenerateHelpText ()
7945 will not put any blank lines or extra
7946 characters in between the entries,
7947 so you must add those characters to the returned
7948 string if you want the entries separated.
7951 def my_format(env, opt, help, default, actual):
7952 fmt = "\n%s: default=%s actual=%s (%s)\n"
7953 return fmt % (opt, default. actual, help)
7954 opts.FormatOptionHelpText = my_format
7957 To make it more convenient to work with customizable Options,
7959 provides a number of functions
7960 that make it easy to set up
7961 various types of Options:
7964 .RI BoolOption( key ", " help ", " default )
7965 Return a tuple of arguments
7966 to set up a Boolean option.
7970 have a default value of
7972 and display the specified
7975 The option will interpret the values
7997 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
7998 Return a tuple of arguments
8000 whose value may be one
8001 of a specified list of legal enumerated values.
8005 have a default value of
8007 and display the specified
8010 The option will only support those
8016 argument is a dictionary
8017 that can be used to convert
8018 input values into specific legal values
8027 then the values are case-sensitive.
8032 then values will be matched
8038 then values will be matched
8040 and all input values will be
8041 converted to lower case.
8044 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
8045 Return a tuple of arguments
8047 whose value may be one or more
8048 of a specified list of legal enumerated values.
8052 have a default value of
8054 and display the specified
8057 The option will only support the values
8060 or the values in the
8063 More than one value may be specified,
8064 with all values separated by commas.
8065 The default may be a string of
8066 comma-separated default values,
8067 or a list of the default values.
8070 argument is a dictionary
8071 that can be used to convert
8072 input values into specific legal values
8078 .RI PackageOption( key ", " help ", " default )
8079 Return a tuple of arguments
8081 whose value is a path name
8082 of a package that may be
8083 enabled, disabled or
8084 given an explicit path name.
8088 have a default value of
8090 and display the specified
8093 The option will support the values
8100 in which case the specified
8103 or the option may be set to an
8105 (typically the path name to a package
8106 that is being enabled).
8107 The option will also support the values
8113 to disable use of the specified option.
8116 .RI PathOption( key ", " help ", " default ", [" validator ])
8117 Return a tuple of arguments
8119 whose value is expected to be a path name.
8123 have a default value of
8125 and display the specified
8131 that will be called to
8132 verify that the specified path
8135 following ready-made validators:
8136 .BR PathOption.PathExists
8138 which verifies that the specified path exists;
8139 .BR PathOption.PathIsFile ,
8140 which verifies that the specified path is an existing file;
8141 .BR PathOption.PathIsDir ,
8142 which verifies that the specified path is an existing directory;
8144 .BR PathOption.PathIsDirCreate ,
8145 which verifies that the specified path is a directory,
8146 and will create the specified directory if the path does not exist.
8147 You may supply your own
8150 which must take three arguments
8152 the name of the options variable to be set;
8154 the specified value being checked;
8157 the construction environment)
8158 and should raise an exception
8159 if the specified value is not acceptable.
8162 These functions make it
8163 convenient to create a number
8164 of options with consistent behavior
8165 in a single call to the
8171 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
8172 EnumOption('debug', 'debug output and symbols', 'no'
8173 allowed_values=('yes', 'no', 'full'),
8174 map={}, ignorecase=0), # case sensitive
8175 ListOption('shared',
8176 'libraries to build as shared libraries',
8178 names = list_of_libs),
8179 PackageOption('x11',
8180 'use X11 installed here (yes = search some places)',
8182 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
8183 PathOption('foopath', 'where the foo library is installed', foopath,
8184 PathOption.PathIsDir),
8189 .SS File and Directory Nodes
8199 Nodes, respectively.
8200 python objects, respectively.
8201 Those objects have several user-visible attributes
8202 and methods that are often useful:
8208 This path is relative to the top-level directory
8212 The build path is the same as the source path if
8217 The absolute build path of the given file or directory.
8227 object representing the
8236 # Get the current build dir's path, relative to top.
8238 # Current dir's absolute path
8240 # Next line is always '.', because it is the top dir's path relative to itself.
8242 File('foo.c').srcnode().path # source path of the given source file.
8244 # Builders also return File objects:
8245 foo = env.Program('foo.c')
8246 print "foo will be built in %s"%foo.path
8252 can be extended to build different types of targets
8253 by adding new Builder objects
8254 to a construction environment.
8256 you should only need to add a new Builder object
8257 when you want to build a new type of file or other external target.
8258 If you just want to invoke a different compiler or other tool
8259 to build a Program, Object, Library, or any other
8260 type of output file for which
8262 already has an existing Builder,
8263 it is generally much easier to
8264 use those existing Builders
8265 in a construction environment
8266 that sets the appropriate construction variables
8269 Builder objects are created
8275 function accepts the following arguments:
8278 The command line string used to build the target from the source.
8281 a list of strings representing the command
8282 to be executed and its arguments
8283 (suitable for enclosing white space in an argument),
8285 mapping source file name suffixes to
8286 any combination of command line strings
8287 (if the builder should accept multiple source file extensions),
8290 (see the next section);
8291 or a list of any of the above.
8294 takes three arguments:
8296 - a list of source nodes,
8298 - a list of target nodes,
8300 - the construction environment.
8303 The prefix that will be prepended to the target file name.
8304 This may be specified as a:
8314 - a function or other callable that takes
8315 two arguments (a construction environment and a list of sources)
8316 and returns a prefix,
8321 - specifies a mapping from a specific source suffix (of the first
8322 source specified) to a corresponding target prefix. Both the source
8323 suffix and target prefix specifications may use environment variable
8324 substitution, and the target prefix (the 'value' entries in the
8325 dictionary) may also be a callable object. The default target prefix
8326 may be indicated by a dictionary entry with a key value of None.
8331 b = Builder("build_it < $SOURCE > $TARGET"
8334 def gen_prefix(env, sources):
8335 return "file-" + env['PLATFORM'] + '-'
8336 b = Builder("build_it < $SOURCE > $TARGET",
8337 prefix = gen_prefix)
8339 b = Builder("build_it < $SOURCE > $TARGET",
8340 suffix = { None: "file-",
8341 "$SRC_SFX_A": gen_prefix })
8345 The suffix that will be appended to the target file name.
8346 This may be specified in the same manner as the prefix above.
8347 If the suffix is a string, then
8349 will append a '.' to the beginning of the suffix if it's not already
8350 there. The string returned by callable object (or obtained from the
8351 dictionary) is untouched and must append its own '.' to the beginning
8355 b = Builder("build_it < $SOURCE > $TARGET"
8358 def gen_suffix(env, sources):
8359 return "." + env['PLATFORM'] + "-file"
8360 b = Builder("build_it < $SOURCE > $TARGET",
8361 suffix = gen_suffix)
8363 b = Builder("build_it < $SOURCE > $TARGET",
8364 suffix = { None: ".sfx1",
8365 "$SRC_SFX_A": gen_suffix })
8369 The expected source file name suffix. This may be a string or a list
8373 A Scanner object that
8374 will be invoked to find
8375 implicit dependencies for this target file.
8376 This keyword argument should be used
8377 for Scanner objects that find
8378 implicit dependencies
8379 based only on the target file
8380 and the construction environment,
8383 (See the section "Scanner Objects," below,
8384 for information about creating Scanner objects.)
8387 A Scanner object that
8389 find implicit dependences in
8391 used to build this target file.
8392 This is where you would
8393 specify a scanner to
8396 lines in source files.
8399 Scanner object may be used to
8400 indicate that this Builder
8401 should scan directory trees
8402 for on-disk changes to files
8405 does not know about from other Builder or function calls.
8406 (See the section "Scanner Objects," below,
8407 for information about creating your own Scanner objects.)
8410 A factory function that the Builder will use
8411 to turn any targets specified as strings into SCons Nodes.
8413 SCons assumes that all targets are files.
8414 Other useful target_factory
8417 for when a Builder creates a directory target,
8420 for when a Builder can create either a file
8421 or directory target.
8426 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8428 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8429 env.MakeDirectory('new_directory', [])
8432 Note that the call to the MakeDirectory Builder
8433 needs to specify an empty source list
8434 to make the string represent the builder's target;
8435 without that, it would assume the argument is the source,
8436 and would try to deduce the target name from it,
8437 which in the absence of an automatically-added prefix or suffix
8438 would lead to a matching target and source name
8439 and a circular dependency.
8442 A factory function that the Builder will use
8443 to turn any sources specified as strings into SCons Nodes.
8445 SCons assumes that all source are files.
8446 Other useful source_factory
8449 for when a Builder uses a directory as a source,
8452 for when a Builder can use files
8453 or directories (or both) as sources.
8458 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8460 env.Append(BUILDERS = {'Collect':CollectBuilder})
8461 env.Collect('archive', ['directory_name', 'file_name'])
8465 A function or list of functions to manipulate the target and source
8466 lists before dependencies are established
8467 and the target(s) are actually built.
8469 can also be a string containing a construction variable to expand
8470 to an emitter function or list of functions,
8471 or a dictionary mapping source file suffixes
8472 to emitter functions.
8473 (Only the suffix of the first source file
8474 is used to select the actual emitter function
8475 from an emitter dictionary.)
8478 takes three arguments:
8480 - a list of source nodes,
8482 - a list of target nodes,
8484 - the construction environment.
8485 An emitter must return a tuple containing two lists,
8486 the list of targets to be built by this builder,
8487 and the list of sources for this builder.
8492 def e(target, source, env):
8493 return (target + ['foo.foo'], source + ['foo.src'])
8495 # Simple association of an emitter function with a Builder.
8496 b = Builder("my_build < $TARGET > $SOURCE",
8499 def e2(target, source, env):
8500 return (target + ['bar.foo'], source + ['bar.src'])
8502 # Simple association of a list of emitter functions with a Builder.
8503 b = Builder("my_build < $TARGET > $SOURCE",
8506 # Calling an emitter function through a construction variable.
8507 env = Environment(MY_EMITTER = e)
8508 b = Builder("my_build < $TARGET > $SOURCE",
8509 emitter = '$MY_EMITTER')
8511 # Calling a list of emitter functions through a construction variable.
8512 env = Environment(EMITTER_LIST = [e, e2])
8513 b = Builder("my_build < $TARGET > $SOURCE",
8514 emitter = '$EMITTER_LIST')
8516 # Associating multiple emitters with different file
8517 # suffixes using a dictionary.
8518 def e_suf1(target, source, env):
8519 return (target + ['another_target_file'], source)
8520 def e_suf2(target, source, env):
8521 return (target, source + ['another_source_file'])
8522 b = Builder("my_build < $TARGET > $SOURCE",
8523 emitter = {'.suf1' : e_suf1,
8528 Specifies whether this builder is allowed to be called multiple times for
8529 the same target file(s). The default is 0, which means the builder
8530 can not be called multiple times for the same target file(s). Calling a
8531 builder multiple times for the same target simply adds additional source
8532 files to the target; it is not allowed to change the environment associated
8533 with the target, specify addition environment overrides, or associate a different
8534 builder with the target.
8537 A construction environment that can be used
8538 to fetch source code using this Builder.
8539 (Note that this environment is
8541 used for normal builds of normal target files,
8542 which use the environment that was
8543 used to call the Builder for the target file.)
8546 A function that returns a list of actions that will be executed to build
8547 the target(s) from the source(s).
8548 The returned action(s) may be
8549 an Action object, or anything that
8550 can be converted into an Action object
8551 (see the next section).
8553 The generator function
8554 takes four arguments:
8556 - a list of source nodes,
8558 - a list of target nodes,
8560 - the construction environment,
8562 - a Boolean value that specifies
8563 whether the generator is being called
8564 for generating a build signature
8565 (as opposed to actually executing the command).
8569 def g(source, target, env, for_signature):
8570 return [["gcc", "-c", "-o"] + target + source]
8572 b = Builder(generator=g)
8580 arguments must not both be used for the same Builder.
8583 Specifies a builder to use when a source file name suffix does not match
8584 any of the suffixes of the builder. Using this argument produces a
8585 multi-stage builder.
8588 Specifies that this builder expects exactly one source file per call. Giving
8589 more than one source files without target files results in implicitely calling
8590 the builder multiple times (once for each source given). Giving multiple
8591 source files together with target files results in a UserError exception.
8599 arguments must not both be used for the same Builder.
8602 A construction environment that can be used
8603 to fetch source code using this Builder.
8604 (Note that this environment is
8606 used for normal builds of normal target files,
8607 which use the environment that was
8608 used to call the Builder for the target file.)
8611 b = Builder(action="build < $SOURCE > $TARGET")
8612 env = Environment(BUILDERS = {'MyBuild' : b})
8613 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
8617 A directory from which scons
8624 a string or a directory Node,
8625 scons will change to the specified directory.
8628 is not a string or Node
8630 then scons will change to the
8631 target file's directory.
8633 Note that scons will
8635 automatically modify
8637 construction variables like
8641 when using the chdir
8642 keyword argument--that is,
8643 the expanded file names
8644 will still be relative to
8645 the top-level SConstruct directory,
8646 and consequently incorrect
8647 relative to the chdir directory.
8648 Builders created using chdir keyword argument,
8649 will need to use construction variable
8654 to use just the filename portion of the
8658 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
8660 env = Environment(BUILDERS = {'MyBuild' : b})
8661 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
8665 Any additional keyword arguments supplied
8666 when a Builder object is created
8667 (that is, when the Builder() function is called)
8668 will be set in the executing construction
8669 environment when the Builder object is called.
8670 The canonical example here would be
8671 to set a construction variable to
8672 the repository of a source code system.
8674 Any additional keyword arguments supplied
8678 will only be associated with the target
8679 created by that particular Builder call
8680 (and any other files built as a
8681 result of the call).
8683 These extra keyword arguments are passed to the
8684 following functions:
8685 command generator functions,
8687 and emitter functions.
8693 function will turn its
8695 keyword argument into an appropriate
8696 internal Action object.
8697 You can also explicity create Action objects
8701 which can then be passed to the
8704 This can be used to configure
8705 an Action object more flexibly,
8706 or it may simply be more efficient
8707 than letting each separate Builder object
8708 create a separate Action
8710 Builder objects need to do the same thing.
8715 returns an appropriate object for the action
8716 represented by the type of the first argument:
8719 If the first argument is already an Action object,
8720 the object is simply returned.
8723 If the first argument is a string,
8724 a command-line Action is returned.
8725 Note that the command line string
8726 may be preceded by an
8729 to suppress printing of the
8730 specified command line,
8734 to ignore the exit status from
8735 the specified command.
8739 Action('$CC -c -o $TARGET $SOURCES')
8741 # Doesn't print the line being executed.
8742 Action('@build $TARGET $SOURCES')
8745 Action('-build $TARGET $SOURCES')
8748 .\" XXX From Gary Ruben, 23 April 2002:
8749 .\" What would be useful is a discussion of how you execute command
8750 .\" shell commands ie. what is the process used to spawn the shell, pass
8751 .\" environment variables to it etc., whether there is one shell per
8752 .\" environment or one per command etc. It might help to look at the Gnu
8753 .\" make documentation to see what they think is important to discuss about
8754 .\" a build system. I'm sure you can do a better job of organising the
8755 .\" documentation than they have :-)
8759 If the first argument is a list,
8760 then a list of Action objects is returned.
8761 An Action object is created as necessary
8762 for each element in the list.
8765 the list is itself a list,
8766 the internal list is the
8767 command and arguments to be executed via
8769 This allows white space to be enclosed
8770 in an argument by defining
8771 a command in a list within a list:
8774 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
8778 If the first argument is a Python function,
8779 a function Action is returned.
8780 The Python function takes three keyword arguments,
8782 (a Node object representing the target file),
8784 (a Node object representing the source file)
8787 (the construction environment
8788 used for building the target file).
8793 arguments may be lists of Node objects if there is
8794 more than one target file or source file.
8795 The actual target and source file name(s) may
8796 be retrieved from their Node objects
8797 via the built-in Python str() function:
8800 target_file_name = str(target)
8801 source_file_names = map(lambda x: str(x), source)
8804 The function should return
8808 to indicate a successful build of the target file(s).
8809 The function may raise an exception
8810 or return a non-zero exit status
8811 to indicate an unsuccessful build.
8814 def build_it(target = None, source = None, env = None):
8815 # build the target from the source
8818 a = Action(build_it)
8821 If the action argument is not one of the above,
8824 The second, optional argument
8825 is a Python function that returns
8826 a string to be printed to describe the action being executed.
8827 Like a function to build a file,
8828 this function takes three arguments:
8830 (a Node object representing the target file),
8832 (a Node object representing the source file)
8835 (a construction environment).
8840 arguments may be lists of Node objects if there is
8841 more than one target file or source file.
8845 def build_it(target, source, env):
8846 # build the target from the source
8849 def string_it(target, source, env):
8850 return "building '%s' from '%s'" % (target[0], source[0])
8852 # Use a positional argument.
8853 a = Action(build_it, string_it)
8855 # Alternatively, use a keyword argument.
8856 a = Action(build_it, strfunction=string_it)
8859 The third, also optional argument
8860 is a list of construction variables
8861 whose values will be included
8862 in the signature of the Action
8863 when deciding whether a target should
8864 be rebuilt because the action changed.
8865 This is necessary whenever you want a target to
8866 be rebuilt when a specific
8867 construction variable changes,
8868 because the underlying Python code for a function
8869 will not change when the value of the construction variable does.
8872 def build_it(target, source, env):
8873 # build the target from the 'XXX' construction variable
8874 open(target[0], 'w').write(env['XXX'])
8877 def string_it(target, source):
8878 return "building '%s' from '%s'" % (target[0], source[0])
8880 # Use positional arguments.
8881 a = Action(build_it, string_it, ['XXX'])
8883 # Alternatively, use a keyword argument.
8884 a = Action(build_it, varlist=['XXX'])
8894 which specifies that
8895 scons will execute the action
8896 after changing to the specified directory.
8897 If the chdir argument is
8898 a string or a directory Node,
8899 scons will change to the specified directory.
8900 If the chdir argument
8901 is not a string or Node
8903 then scons will change to the
8904 target file's directory.
8906 Note that scons will
8908 automatically modify
8910 construction variables like
8914 when using the chdir
8915 keyword argument--that is,
8916 the expanded file names
8917 will still be relative to
8918 the top-level SConstruct directory,
8919 and consequently incorrect
8920 relative to the chdir directory.
8921 Builders created using chdir keyword argument,
8922 will need to use construction variable
8927 to use just the filename portion of the
8931 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8941 which specifies a function
8942 that is passed the exit status
8944 from the specified action
8945 and can return an arbitrary
8947 This can be used, for example,
8948 to specify that an Action object's
8949 return value should be ignored
8950 and SCons should, therefore,
8951 consider that the action always suceeds:
8954 def always_succeed(s):
8955 # Always return 0, which indicates success.
8957 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
8958 exitstatfunc=always_succeed)
8961 .SS Miscellaneous Action Functions
8964 supplies a number of functions
8965 that arrange for various common
8966 file and directory manipulations
8968 These are similar in concept to "tasks" in the
8970 although the implementation is slightly different.
8971 These functions do not actually
8972 perform the specified action
8973 at the time the function is called,
8974 but instead return an Action object
8975 that can be executed at the
8977 (In Object-Oriented terminology,
8982 that return Action objects.)
8985 there are two natural ways
8988 are intended to be used.
8992 to perform the action
8993 at the time the SConscript
8997 global function to do so:
8999 Execute(Touch('file'))
9003 you can use these functions
9004 to supply Actions in a list
9008 This can allow you to
9009 perform more complicated
9010 sequences of file manipulation
9012 on platform-specific
9016 env = Environment(TMPBUILD = '/tmp/builddir')
9017 env.Command('foo.out', 'foo.in',
9018 [Mkdir('$TMPBUILD'),
9019 Copy('$TMPBUILD', '${SOURCE.dir}')
9020 "cd $TMPBUILD && make",
9021 Delete('$TMPBUILD')])
9025 .RI Chmod( dest ", " mode )
9026 Returns an Action object that
9027 changes the permissions on the specified
9029 file or directory to the specified
9034 Execute(Chmod('file', 0755))
9036 env.Command('foo.out', 'foo.in',
9037 [Copy('$TARGET', '$SOURCE'),
9038 Chmod('$TARGET', 0755)])
9042 .RI Copy( dest ", " src )
9043 Returns an Action object
9046 source file or directory to the
9048 destination file or directory.
9052 Execute(Copy('foo.output', 'foo.input'))
9054 env.Command('bar.out', 'bar.in',
9055 Copy('$TARGET', '$SOURCE'))
9059 .RI Delete( entry ", [" must_exist ])
9060 Returns an Action that
9061 deletes the specified
9063 which may be a file or a directory tree.
9064 If a directory is specified,
9065 the entire directory tree
9070 then a Python error will be thrown
9071 if the specified entry does not exist;
9074 that is, the Action will silently do nothing
9075 if the entry does not exist.
9079 Execute(Delete('/tmp/buildroot'))
9081 env.Command('foo.out', 'foo.in',
9082 [Delete('${TARGET.dir}'),
9085 Execute(Delete('file_that_must_exist', must_exist=1))
9091 that creates the specified
9097 Execute(Mkdir('/tmp/outputdir'))
9099 env.Command('foo.out', 'foo.in',
9100 [Mkdir('/tmp/builddir',
9101 Copy('$SOURCE', '/tmp/builddir')
9102 "cd /tmp/builddir && ])
9107 .RI Move( dest ", " src )
9109 that moves the specified
9111 file or directory to
9118 Execute(Move('file.destination', 'file.source'))
9120 env.Command('output_file', 'input_file',
9122 Move('$TARGET', 'file_created_by_MyBuildAction')])
9128 that updates the modification time
9134 Execute(Touch('file_to_be_touched'))
9136 env.Command('marker', 'input_file',
9141 .SS Variable Substitution
9143 Before executing a command,
9145 performs construction variable interpolation on the strings that make up
9146 the command line of builders.
9147 Variables are introduced by a
9150 Besides construction variables, scons provides the following
9151 variables for each command execution:
9154 The file name of the target being built, or the file name of the first
9155 target if multiple targets are being built.
9158 The file names of all targets being built.
9161 The file name of the source of the build command, or the file name of the
9162 first source if multiple sources are being built.
9165 The file names of the sources of the build command.
9167 (Note that the above variables are reserved
9168 and may not be set in a construction environment.)
9171 For example, given the construction variable CC='cc', targets=['foo'], and
9172 sources=['foo.c', 'bar.c']:
9175 action='$CC -c -o $TARGET $SOURCES'
9178 would produce the command line:
9181 cc -c -o foo foo.c bar.c
9184 Variable names may be surrounded by curly braces ({})
9185 to separate the name from the trailing characters.
9186 Within the curly braces, a variable name may have
9187 a Python slice subscript appended to select one
9188 or more items from a list.
9189 In the previous example, the string:
9201 Additionally, a variable name may
9202 have the following special
9203 modifiers appended within the enclosing curly braces
9204 to modify the interpolated string:
9207 The base path of the file name,
9208 including the directory path
9209 but excluding any suffix.
9212 The name of the directory in which the file exists.
9216 minus any directory portion.
9219 Just the basename of the file,
9221 and minus the directory.
9224 Just the file suffix.
9227 The absolute path name of the file.
9230 The POSIX form of the path,
9231 with directories separated by
9235 This is sometimes necessary on Win32 systems
9236 when a path references a file on other (POSIX) systems.
9239 The directory and file name to the source file linked to this file
9240 through BuildDir. If this file isn't linked, it just returns the
9241 directory and filename unchanged.
9244 The directory containing the source file linked to this file
9245 through BuildDir. If this file isn't linked, it just returns the
9246 directory part of the filename.
9249 The directory and file name to the source file linked to this file
9250 through BuildDir. If the file does not exist locally but exists in
9251 a Repository, the path in the Repository is returned.
9252 If this file isn't linked, it just returns the
9253 directory and filename unchanged.
9256 The Repository directory containing the source file linked to this file
9257 through BuildDir. If this file isn't linked, it just returns the
9258 directory part of the filename.
9261 For example, the specified target will
9262 expand as follows for the corresponding modifiers:
9265 $TARGET => sub/dir/file.x
9266 ${TARGET.base} => sub/dir/file
9267 ${TARGET.dir} => sub/dir
9268 ${TARGET.file} => file.x
9269 ${TARGET.filebase} => file
9270 ${TARGET.suffix} => .x
9271 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9273 SConscript('src/SConscript', build_dir='sub/dir')
9274 $SOURCE => sub/dir/file.x
9275 ${SOURCE.srcpath} => src/file.x
9276 ${SOURCE.srcdir} => src
9278 Repository('/usr/repository')
9279 $SOURCE => sub/dir/file.x
9280 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9281 ${SOURCE.rsrcdir} => /usr/repository/src
9284 Lastly, a variable name
9285 may be a callable Python function
9287 construction variable in the environment.
9289 take four arguments:
9291 - a list of target nodes,
9293 - a list of source nodes,
9295 - the construction environment,
9297 - a Boolean value that specifies
9298 whether the function is being called
9299 for generating a build signature.
9300 SCons will insert whatever
9301 the called function returns
9302 into the expanded string:
9305 def foo(target, source, env, for_signature):
9308 # Will expand $BAR to "bar baz"
9309 env=Environment(FOO=foo, BAR="$FOO baz")
9312 You can use this feature to pass arguments to a
9313 Python function by creating a callable class
9314 that stores one or more arguments in an object,
9315 and then uses them when the
9318 Note that in this case,
9319 the entire variable expansion must
9320 be enclosed by curly braces
9321 so that the arguments will
9322 be associated with the
9323 instantiation of the class:
9327 def __init__(self, arg):
9330 def __call__(self, target, source, env, for_signature):
9333 # Will expand $BAR to "my argument bar baz"
9334 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9338 The special pseudo-variables
9342 may be used to surround parts of a command line
9345 causing a rebuild--that is,
9346 which are not included in the signature
9347 of target files built with this command.
9352 will be removed from the command line
9353 before it is added to file signatures,
9358 will be removed before the command is executed.
9359 For example, the command line:
9362 echo Last build occurred $( $TODAY $). > $TARGET
9366 would execute the command:
9369 echo Last build occurred $TODAY. > $TARGET
9373 but the command signature added to any target files would be:
9376 echo Last build occurred . > $TARGET
9379 SCons uses the following rules when converting construction variables into
9383 When the value is a string it is interpreted as a space delimited list of
9384 command line arguments.
9387 When the value is a list it is interpreted as a list of command line
9388 arguments. Each element of the list is converted to a string.
9391 Anything that is not a list or string is converted to a string and
9392 interpreted as a single command line argument.
9395 Newline characters (\\n) delimit lines. The newline parsing is done after
9396 all other parsing, so it is not possible for arguments (e.g. file names) to
9397 contain embedded newline characters. This limitation will likely go away in
9398 a future version of SCons.
9406 new file types for implicit dependencies.
9407 Scanner accepts the following arguments:
9410 A Python function that will process
9412 and return a list of strings (file names)
9413 representing the implicit
9414 dependencies found in the contents.
9415 The function takes three or four arguments:
9417 def scanner_function(node, env, path):
9419 def scanner_function(node, env, path, arg):
9423 argument is the internal
9424 SCons node representing the file.
9427 to fetch the name of the file, and
9428 .B node.get_contents()
9429 to fetch contents of the file.
9433 argument is the construction environment for the scan.
9434 Fetch values from it using the
9440 argument is a tuple (or list)
9441 of directories that can be searched
9443 This will usually be the tuple returned by the
9445 argument (see below).
9449 argument is the argument supplied
9450 when the scanner was created, if any.
9453 The name of the Scanner.
9455 to identify the Scanner internally.
9458 An optional argument that, if specified,
9459 will be passed to the scanner function
9461 and the path function
9465 An optional list that can be used to
9466 determine which scanner should be used for
9468 In the usual case of scanning for file names,
9469 this argument will be a list of suffixes
9470 for the different file types that this
9471 Scanner knows how to scan.
9472 If the argument is a string,
9473 then it will be expanded
9474 into a list by the current environment.
9477 A Python function that takes
9478 two or three arguments:
9479 a construction environment, directory Node,
9480 and optional argument supplied
9481 when the scanner was created.
9484 returns a tuple of directories
9485 that can be searched for files to be returned
9486 by this Scanner object.
9489 The class of Node that should be returned
9490 by this Scanner object.
9491 Any strings or other objects returned
9492 by the scanner function
9493 that are not of this class
9494 will be run through the
9499 A Python function that will take a string
9501 and turn it into the appropriate class of Node
9502 to be returned by this Scanner object.
9505 An optional Python function that takes two arguments,
9506 a Node (file) and a construction environment,
9507 and returns whether the
9508 Node should, in fact,
9509 be scanned for dependencies.
9510 This check can be used to eliminate unnecessary
9511 calls to the scanner function when,
9512 for example, the underlying file
9513 represented by a Node does not yet exist.
9516 An optional flag that
9517 specifies whether this scanner should be re-invoked
9518 on the dependency files returned by the scanner.
9519 When this flag is not set,
9520 the Node subsystem will
9521 only invoke the scanner on the file being scanned,
9522 and not (for example) also on the files
9523 specified by the #include lines
9524 in the file being scanned.
9526 may be a callable function,
9527 in which case it will be called with a list of
9529 should return a list of Nodes
9530 that should be scanned recursively;
9531 this can be used to select a specific subset of
9532 Nodes for additional scanning.
9537 .B SourceFileScanner
9538 object that is used by
9541 .BR SharedObject (),
9545 which scanner should be used
9546 for different file extensions.
9548 .BR SourceFileScanner.add_scanner ()
9549 method to add your own Scanner object
9553 that builds target programs or
9554 libraries from a list of
9555 source files of different types:
9558 def xyz_scan(node, env, path):
9559 contents = node.get_contents()
9560 # Scan the contents and return the included files.
9562 XYZScanner = Scanner(xyz_scan)
9564 SourceFileScanner.add_scanner('.xyx', XYZScanner)
9566 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
9569 .SH SYSTEM-SPECIFIC BEHAVIOR
9570 SCons and its configuration files are very portable,
9571 due largely to its implementation in Python.
9572 There are, however, a few portability
9573 issues waiting to trap the unwary.
9575 SCons handles the upper-case
9577 file suffix differently,
9578 depending on the capabilities of
9579 the underlying system.
9580 On a case-sensitive system
9581 such as Linux or UNIX,
9582 SCons treats a file with a
9584 suffix as a C++ source file.
9585 On a case-insensitive system
9587 SCons treats a file with a
9589 suffix as a C source file.
9591 SCons handles the upper-case
9593 file suffix differently,
9594 depending on the capabilities of
9595 the underlying system.
9596 On a case-sensitive system
9597 such as Linux or UNIX,
9598 SCons treats a file with a
9600 suffix as a Fortran source file
9601 that is to be first run through
9602 the standard C preprocessor.
9603 On a case-insensitive system
9605 SCons treats a file with a
9607 suffix as a Fortran source file that should
9609 be run through the C preprocessor.
9610 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
9611 Cygwin supplies a set of tools and utilities
9612 that let users work on a
9613 Windows system using a more POSIX-like environment.
9614 The Cygwin tools, including Cygwin Python,
9616 by sharing an ability to interpret UNIX-like path names.
9617 For example, the Cygwin tools
9618 will internally translate a Cygwin path name
9619 like /cygdrive/c/mydir
9620 to an equivalent Windows pathname
9621 of C:/mydir (equivalent to C:\\mydir).
9624 that are built for native Windows execution,
9625 such as the python.org and ActiveState versions,
9626 do not have the Cygwin path name semantics.
9627 This means that using a native Windows version of Python
9628 to build compiled programs using Cygwin tools
9629 (such as gcc, bison, and flex)
9630 may yield unpredictable results.
9631 "Mixing and matching" in this way
9632 can be made to work,
9633 but it requires careful attention to the use of path names
9634 in your SConscript files.
9636 In practice, users can sidestep
9637 the issue by adopting the following rules:
9639 use the Cygwin-supplied Python interpreter
9641 when using Microsoft Visual C/C++
9642 (or some other Windows compiler)
9643 use the python.org or ActiveState version of Python
9645 .SS WIN32: scons.bat file
9647 SCons is executed via a wrapper
9650 This has (at least) two ramifications:
9652 First, Windows command-line users
9653 that want to use variable assignment
9655 may have to put double quotes
9656 around the assignments:
9659 scons "FOO=BAR" "BAZ=BLEH"
9662 Second, the Cygwin shell does not
9663 recognize this file as being the same
9666 command issued at the command-line prompt.
9667 You can work around this either by
9670 from the Cygwin command line,
9671 or by creating a wrapper shell
9677 The MinGW bin directory must be in your PATH environment variable or the
9678 PATH variable under the ENV construction variable for SCons
9679 to detect and use the MinGW tools. When running under the native Windows
9680 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
9681 tools, if they are both installed, regardless of the order of the bin
9682 directories in the PATH variable. If you have both MSVC and MinGW
9683 installed and you want to use MinGW instead of MSVC,
9684 then you must explictly tell SCons to use MinGW by passing
9690 to the Environment() function, because SCons will prefer the MSVC tools
9691 over the MinGW tools.
9695 To help you get started using SCons,
9696 this section contains a brief overview of some common tasks.
9698 .SS Basic Compilation From a Single Source File
9702 env.Program(target = 'foo', source = 'foo.c')
9705 Note: Build the file by specifying
9706 the target as an argument
9707 ("scons foo" or "scons foo.exe").
9708 or by specifying a dot ("scons .").
9710 .SS Basic Compilation From Multiple Source Files
9714 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
9717 .SS Setting a Compilation Flag
9720 env = Environment(CCFLAGS = '-g')
9721 env.Program(target = 'foo', source = 'foo.c')
9724 .SS Search The Local Directory For .h Files
9728 need to set CCFLAGS to specify -I options by hand.
9729 SCons will construct the right -I options from CPPPATH.
9732 env = Environment(CPPPATH = ['.'])
9733 env.Program(target = 'foo', source = 'foo.c')
9736 .SS Search Multiple Directories For .h Files
9739 env = Environment(CPPPATH = ['include1', 'include2'])
9740 env.Program(target = 'foo', source = 'foo.c')
9743 .SS Building a Static Library
9747 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
9748 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
9751 .SS Building a Shared Library
9755 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
9756 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
9759 .SS Linking a Local Library Into a Program
9762 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
9763 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
9764 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
9767 .SS Defining Your Own Builder Object
9769 Notice that when you invoke the Builder,
9770 you can leave off the target file suffix,
9771 and SCons will add it automatically.
9774 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9776 src_suffix = '.tex')
9777 env = Environment(BUILDERS = {'PDFBuilder' : bld})
9778 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9780 # The following creates "bar.pdf" from "bar.tex"
9781 env.PDFBuilder(target = 'bar', source = 'bar')
9784 Note also that the above initialization
9785 overwrites the default Builder objects,
9786 so the Environment created above
9787 can not be used call Builders like env.Program(),
9788 env.Object(), env.StaticLibrary(), etc.
9790 .SS Adding Your Own Builder Object to an Environment
9793 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
9795 src_suffix = '.tex')
9797 env.Append(BUILDERS = {'PDFBuilder' : bld})
9798 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
9799 env.Program(target = 'bar', source = 'bar.c')
9802 You also can use other Pythonic techniques to add
9803 to the BUILDERS construction variable, such as:
9807 env['BUILDERS]['PDFBuilder'] = bld
9810 .SS Defining Your Own Scanner Object
9815 '\" Note: the \\ in the following are for the benefit of nroff/troff,
9816 '\" not inappropriate doubled escape characters within the r'' raw string.
9817 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
9819 def kfile_scan(node, env, path, arg):
9820 contents = node.get_contents()
9821 includes = include_re.findall(contents)
9824 kscan = Scanner(name = 'kfile',
9825 function = kfile_scan,
9828 scanners = Environment().Dictionary('SCANNERS')
9829 env = Environment(SCANNERS = scanners + [kscan])
9831 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
9833 bar_in = File('bar.in')
9834 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
9835 bar_in.target_scanner = kscan
9838 .SS Creating a Hierarchical Build
9840 Notice that the file names specified in a subdirectory's
9842 file are relative to that subdirectory.
9848 env.Program(target = 'foo', source = 'foo.c')
9850 SConscript('sub/SConscript')
9855 # Builds sub/foo from sub/foo.c
9856 env.Program(target = 'foo', source = 'foo.c')
9858 SConscript('dir/SConscript')
9863 # Builds sub/dir/foo from sub/dir/foo.c
9864 env.Program(target = 'foo', source = 'foo.c')
9867 .SS Sharing Variables Between SConscript Files
9869 You must explicitly Export() and Import() variables that
9870 you want to share between SConscript files.
9876 env.Program(target = 'foo', source = 'foo.c')
9879 SConscript('subdirectory/SConscript')
9881 subdirectory/SConscript:
9884 env.Program(target = 'foo', source = 'foo.c')
9887 .SS Building Multiple Variants From the Same Source
9889 Use the build_dir keyword argument to
9890 the SConscript function to establish
9891 one or more separate build directories for
9892 a given source directory:
9897 cppdefines = ['FOO']
9898 Export("cppdefines")
9899 SConscript('src/SConscript', build_dir='foo')
9901 cppdefines = ['BAR']
9902 Export("cppdefines")
9903 SConscript('src/SConscript', build_dir='bar')
9907 Import("cppdefines")
9908 env = Environment(CPPDEFINES = cppdefines)
9909 env.Program(target = 'src', source = 'src.c')
9912 Note the use of the Export() method
9913 to set the "cppdefines" variable to a different
9914 value each time we call the SConscript function.
9916 .SS Hierarchical Build of Two Libraries Linked With a Program
9921 env = Environment(LIBPATH = ['#libA', '#libB'])
9923 SConscript('libA/SConscript')
9924 SConscript('libB/SConscript')
9925 SConscript('Main/SConscript')
9930 env.Library('a', Split('a1.c a2.c a3.c'))
9935 env.Library('b', Split('b1.c b2.c b3.c'))
9940 e = env.Copy(LIBS = ['a', 'b'])
9941 e.Program('foo', Split('m1.c m2.c m3.c'))
9944 The '#' in the LIBPATH directories specify that they're relative to the
9945 top-level directory, so they don't turn into "Main/libA" when they're
9946 used in Main/SConscript.
9948 Specifying only 'a' and 'b' for the library names
9949 allows SCons to append the appropriate library
9950 prefix and suffix for the current platform
9951 (for example, 'liba.a' on POSIX systems,
9952 'a.lib' on Windows).
9954 .SS Customizing contruction variables from the command line.
9956 The following would allow the C compiler to be specified on the command
9957 line or in the file custom.py.
9960 opts = Options('custom.py')
9961 opts.Add('CC', 'The C compiler.')
9962 env = Environment(options=opts)
9963 Help(opts.GenerateHelpText(env))
9966 The user could specify the C compiler on the command line:
9972 or in the custom.py file:
9978 or get documentation on the options:
9989 .SS Using Microsoft Visual C++ precompiled headers
9991 Since windows.h includes everything and the kitchen sink, it can take quite
9992 some time to compile it over and over again for a bunch of object files, so
9993 Microsoft provides a mechanism to compile a set of headers once and then
9994 include the previously compiled headers in any object file. This
9995 technology is called precompiled headers. The general recipe is to create a
9996 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
9997 then include every header you want to precompile in "StdAfx.h", and finally
9998 include "StdAfx.h" as the first header in all the source files you are
9999 compiling to object files. For example:
10003 #include <windows.h>
10004 #include <my_big_header.h>
10009 #include <StdAfx.h>
10014 #include <StdAfx.h>
10016 /* do some stuff */
10021 #include <StdAfx.h>
10023 /* do some other stuff */
10029 env['PCHSTOP'] = 'StdAfx.h'
10030 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10031 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10034 For more information see the document for the PCH builder, and the PCH and
10035 PCHSTOP construction variables. To learn about the details of precompiled
10036 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10038 .SS Using Microsoft Visual C++ external debugging information
10040 Since including debugging information in programs and shared libraries can
10041 cause their size to increase significantly, Microsoft provides a mechanism
10042 for including the debugging information in an external file called a PDB
10043 file. SCons supports PDB files through the PDB construction
10049 env['PDB'] = 'MyApp.pdb'
10050 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10053 For more information see the document for the PDB construction variable.
10058 Specifies the directory that contains the SCons Python module directory
10059 (e.g. /home/aroach/scons-src-0.01/src/engine).
10062 A string of options that will be used by scons in addition to those passed
10063 on the command line.
10074 Steven Knight <knight@baldmt.com>
10076 Anthony Roach <aroach@electriceyeball.com>