3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be included
12 .\" in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
24 .\" ES - Example Start - indents and turns off line fill
29 .\" EE - Example End - ends indent and turns line fill back on
34 .TH SCONS 1 "October 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']})
152 Similarly, if the commands use external environment variables
153 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
154 these variables can also be explicitly propagated:
158 env = Environment(ENV = {'PATH' : os.environ['PATH'],
159 'HOME' : os.environ['HOME']})
162 Or you may explicitly propagate the invoking user's
163 complete external environment:
167 env = Environment(ENV = os.environ['PATH'])
170 This comes at the expense of making your build
171 dependent on the user's environment being set correctly,
172 but it may be more convenient for many configurations.
175 can scan known input files automatically for dependency
176 information (for example, #include statements
177 in C or C++ files) and will rebuild dependent files appropriately
178 whenever any "included" input file changes.
181 ability to define new scanners for unknown input file types.
184 knows how to fetch files automatically from
185 SCCS or RCS subdirectories
186 using SCCS, RCS or BitKeeper.
189 is normally executed in a top-level directory containing a
191 file, optionally specifying
192 as command-line arguments
193 the target file or files to be built.
195 By default, the command
201 will build all target files in or below the current directory.
202 Explicit default targets
203 (to be built when no targets are specified on the command line)
204 may be defined the SConscript file(s)
207 function, described below.
211 targets are specified in the SConscript file(s),
212 all target files in or below the current directory
213 may be built by explicitly specifying
214 the current directory (.)
215 as a command-line target:
221 Building all target files,
222 including any files outside of the current directory,
223 may be specified by supplying a command-line target
224 of the root directory (on POSIX systems):
230 or the path name(s) of the volume(s) in which all the targets
231 should be built (on Windows systems):
237 To build only specific targets,
238 supply them as command-line arguments:
244 in which case only the specified targets will be built
245 (along with any derived files on which they depend).
247 Specifying "cleanup" targets in SConscript files is not
250 flag removes all files
251 necessary to build the specified target:
257 to remove all target files, or:
260 scons -c build export
263 to remove target files under build and export.
264 Additional files or directories to remove can be specified using the
267 A subset of a hierarchical tree may be built by
268 remaining at the top-level directory (where the
270 file lives) and specifying the subdirectory as the target to be
277 or by changing directory and invoking scons with the
279 option, which traverses up the directory
280 hierarchy until it finds the
282 file, and then builds
283 targets relatively to the current subdirectory:
291 supports building multiple targets in parallel via a
293 option that takes, as its argument, the number
294 of simultaneous tasks that may be spawned:
300 builds four targets in parallel, for example.
303 can maintain a cache of target (derived) files that can
304 be shared between multiple builds. When caching is enabled in a
305 SConscript file, any target files built by
308 to the cache. If an up-to-date target file is found in the cache, it
309 will be retrieved from the cache instead of being rebuilt locally.
310 Caching behavior may be disabled and controlled in other ways by the
312 .BR --cache-disable ,
315 command-line options. The
317 option is useful to prevent multiple builds
318 from trying to update the cache simultaneously.
320 Values of variables to be passed to the SConscript file(s)
321 may be specified on the command line:
327 These variables are available in SConscript files
328 through the ARGUMENTS dictionary,
329 and can be used in the SConscript file(s) to modify
330 the build in any way:
333 if ARGUMENTS.get('debug', 0):
334 env = Environment(CCFLAGS = '-g')
339 The command-line variable arguments are also available
341 indexed by their order on the command line.
342 This allows you to process them in order rather than by name,
344 ARGLIST[0] returns a tuple
345 containing (argname, argvalue).
346 A Python exception is thrown if you
347 try to access a list member that
351 requires Python version 1.5.2 or later.
352 There should be no other dependencies or requirements to run
355 .\" The following paragraph reflects the default tool search orders
356 .\" currently in SCons/Tool/__init__.py. If any of those search orders
357 .\" change, this documentation should change, too.
360 knows how to search for available programming tools
364 searches in order for the
365 Microsoft Visual C++ tools,
366 the MinGW tool chain,
367 the Intel compiler tools,
368 and the PharLap ETS compiler.
371 searches in order for the
374 and the Microsoft Visual C++ tools,
375 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
377 searches for the native compiler tools
378 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
379 and the GCC tool chain.
380 On all other platforms,
381 including POSIX (Linux and UNIX) platforms,
384 for the GCC tool chain,
385 the Microsoft Visual C++ tools,
386 and the Intel compiler tools.
387 You may, of course, override these default values
388 by appropriate configuration of
389 Environment construction variables.
394 supports the same command-line options as GNU
396 and many of those supported by
401 Ignored for compatibility with non-GNU versions of
405 -c, --clean, --remove
406 Clean up by removing all target files for which a construction
407 command is specified.
408 Also remove any files or directories associated to the construction command
409 using the Clean() function.
412 --cache-disable, --no-cache
413 Disable the derived-file caching specified by
416 will neither retrieve files from the cache
417 nor copy files to the cache.
420 --cache-force, --cache-populate
423 populate a cache by copying any already-existing, up-to-date
424 derived files to the cache,
425 in addition to files built by this invocation.
426 This is useful to populate a new cache with
427 all the current derived files,
428 or to add to the cache any derived files
429 recently built with caching disabled via the
437 and retrieving a derived file from the cache,
439 that would have been executed to build the file,
440 instead of the usual report,
441 "Retrieved `file' from cache."
442 This will produce consistent output for build logs,
443 regardless of whether a target
444 file was rebuilt or retrieved from the cache.
448 This specifies how the
450 call should use or generate the
451 results of configuration tests.
452 The option should be specified from
453 among the following choices:
457 scons will use its normal dependency mechanisms
458 to decide if a test must be rebuilt or not.
459 This saves time by not running the same configuration tests
460 every time you invoke scons,
461 but will overlook changes in system header files
462 or external commands (such as compilers)
463 if you don't specify those dependecies explicitly.
464 This is the default behavior.
468 If this option is specified,
469 all configuration tests will be re-run
470 regardless of whether the
471 cached results are out of date.
472 This can be used to explicitly
473 force the configuration tests to be updated
474 in response to an otherwise unconfigured change
475 in a system header file or compiler.
479 If this option is specified,
480 no configuration tests will be rerun
481 and all results will be taken from cache.
482 Note that scons will still consider it an error
483 if --config=cache is specified
484 and a necessary test does not
485 yet have any results in the cache.
488 .RI "-C" " directory" ", --directory=" directory
489 Change to the specified
491 before searching for the
496 file, or doing anything
499 options are interpreted
500 relative to the previous one, and the right-most
502 option wins. (This option is nearly
504 .BR "-f directory/SConstruct" ,
505 except that it will search for
510 in the specified directory.)
514 .\" Display dependencies while building target files. Useful for
515 .\" figuring out why a specific file is being rebuilt, as well as
516 .\" general debugging of the build process.
520 Works exactly the same way as the
522 option except for the way default targets are handled.
523 When this option is used and no targets are specified on the command line,
524 all default targets are built, whether or not they are below the current
529 Debug the build process.
531 specifies what type of debugging:
535 Print how many objects are created
536 of the various classes used internally by SCons
537 before and after reading the SConscript files
538 and before and after building targets.
539 This only works when run under Python 2.1 or later.
543 Print the dependency tree
544 after each top-level target is built. This prints out only derived files.
548 Print an explanation of precisely why
550 is deciding to (re-)build any targets.
551 (Note: this does not print anything
558 Instruct the scanner that searches for libraries
559 to print a message about each potential library
560 name it is searching for,
561 and about the actual libraries it finds.
565 Print the include tree after each top-level target is built.
566 This is generally used to find out what files are included by the sources
567 of a given derived file:
570 $ scons --debug=includes foo.o
575 Prints a summary of hits and misses in the Memoizer,
576 the internal SCons subsystem for caching
577 various values in memory instead of
578 recomputing them each time they're needed.
582 Prints how much memory SCons uses
583 before and after reading the SConscript files
584 and before and after building targets.
588 Disables use of the Memoizer,
589 the internal SCons subsystem for caching
590 various values in memory instead of
591 recomputing them each time they're needed.
592 This provides more accurate counts of the
593 underlying function calls in the
594 Python profiler output when using the
597 (When the Memoizer is used,
598 the profiler counts all
599 memoized functions as being executed
600 by the Memoizer's wrapper calls.)
604 Prints a list of the various objects
605 of the various classes used internally by SCons.
606 This only works when run under Python 2.1 or later.
610 Re-run SCons under the control of the
616 Print the raw command line used to build each target
617 before the construction environment variables are substituted.
618 Also shows which targets are being built by this command.
619 Output looks something like this:
621 $ scons --debug=presub
622 Building myprog.o with action(s):
623 $SHCC $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
629 Prints an internal Python stack trace
630 when encountering an otherwise unexplained error.
634 Print the dependency tree along with status information. This is the
635 same as the debug=tree option, but additional status information is
636 provided for each node in the tree.
640 Prints various time profiling information: the time spent
641 executing each build command, the total build time, the total time spent
642 executing build commands, the total time spent executing SConstruct and
643 SConscript files, and the total time spent executing SCons itself.
647 Print the dependency tree
648 after each top-level target is built. This prints out the complete
649 dependency tree including implicit dependencies and ignored
653 .RI --diskcheck= types
654 Enable specific checks for
655 whether or not there is a file on disk
656 where the SCons configuration expects a directory
658 and whether or not RCS or SCCS sources exist
659 when searching for source and include files.
662 argument can be set to:
664 to enable all checks explicitly
665 (the default behavior);
667 to disable all such checks;
669 to check that files and directories on disk
670 match SCons' expected configuration;
672 to check for the existence of an RCS source
673 for any missing source or include files;
675 to check for the existence of an SCCS source
676 for any missing source or include files.
677 Multiple checks can be specified separated by commas;
679 .B --diskcheck=sccs,rcs
680 would still check for SCCS and RCS sources,
681 but disable the check for on-disk matches of files and directories.
682 Disabling some or all of these checks
683 can provide a performance boost for large configurations,
684 or when the configuration will check for files and/or directories
685 across networked or shared file systems,
686 at the slight increased risk of an incorrect build
687 or of not handling errors gracefully
688 (if include files really should be
689 found in SCCS or RCS, for example,
690 or if a file really does exist
691 where the SCons configuration expects a directory).
694 .\" -e, --environment-overrides
695 .\" Variables from the execution environment override construction
696 .\" variables from the SConscript files.
699 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
702 as the initial SConscript file.
706 Print a local help message for this build, if one is defined in
707 the SConscript file(s), plus a line that describes the
709 option for command-line option help. If no local help message
710 is defined, prints the standard help message about command-line
711 options. Exits after displaying the appropriate message.
715 Print the standard help message about command-line options and
720 Ignore all errors from commands executed to rebuild files.
723 .RI -I " directory" ", --include-dir=" directory
727 imported Python modules. If several
730 are used, the directories are searched in the order specified.
734 Cache implicit dependencies. This can cause
736 to miss changes in the implicit dependencies in cases where a new implicit
737 dependency is added earlier in the implicit dependency search path
738 (e.g. CPPPATH) than a current implicit dependency with the same name.
741 --implicit-deps-changed
742 Force SCons to ignore the cached implicit dependencies. This causes the
743 implicit dependencies to be rescanned and recached. This implies
744 .BR --implicit-cache .
747 --implicit-deps-unchanged
748 Force SCons to ignore changes in the implicit dependencies.
749 This causes cached implicit dependencies to always be used.
751 .BR --implicit-cache .
754 .RI -j " N" ", --jobs=" N
755 Specifies the number of jobs (commands) to run simultaneously.
756 If there is more than one
758 option, the last one is effective.
762 .\" is specified without an argument,
764 .\" will not limit the number of
765 .\" simultaneous jobs.
769 Continue as much as possible after an error. The target that
770 failed and those that depend on it will not be remade, but other
771 targets specified on the command line will still be processed.
774 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
775 .\" No new jobs (commands) will be started if
776 .\" there are other jobs running and the system load
777 .\" average is at least
779 .\" (a floating-point number).
782 .RI --duplicate= ORDER
783 There are three ways to duplicate files in a build tree: hard links,
784 soft (symbolic) links and copies. The default behaviour of SCons is to
785 prefer hard links to soft links to copies. You can specify different
786 behaviours with this option.
796 SCons will attempt to duplicate files using
797 the mechanisms in the specified order.
802 .\" List derived files (targets, dependencies) that would be built,
803 .\" but do not build them.
804 .\" [XXX This can probably go away with the right
805 .\" combination of other options. Revisit this issue.]
809 .\" List derived files that would be built, with the actions
810 .\" (commands) that build them. Does not build the files.
811 .\" [XXX This can probably go away with the right
812 .\" combination of other options. Revisit this issue.]
816 .\" List derived files that would be built, plus where the file is
817 .\" defined (file name and line number). Does not build the files.
818 .\" [XXX This can probably go away with the right
819 .\" combination of other options. Revisit this issue.]
823 Ignored for compatibility with non-GNU versions of
827 .RI --max-drift= SECONDS
828 Set the maximum expected drift in the modification time of files to
830 This value determines how long a file must be unmodified
831 before its cached content signature
832 will be used instead of
833 calculating a new content signature (MD5 checksum)
834 of the file's contents.
835 The default value is 2 days, which means a file must have a
836 modification time of at least two days ago in order to have its
837 cached content signature used.
838 A negative value means to never cache the content
839 signature and to ignore the cached value if there already is one. A value
840 of 0 means to always use the cached signature,
841 no matter how old the file is.
844 -n, --just-print, --dry-run, --recon
845 No execute. Print the commands that would be executed to build
846 any out-of-date target files, but do not execute the commands.
849 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
853 .\" not rebuild anything due to changes in the contents of
856 .\" .RI --override " file"
857 .\" Read values to override specific build environment variables
858 .\" from the specified
862 .\" Print the data base (construction environments,
863 .\" Builder and Scanner objects) that are defined
864 .\" after reading the SConscript files.
865 .\" After printing, a normal build is performed
866 .\" as usual, as specified by other command-line options.
867 .\" This also prints version information
872 .\" To print the database without performing a build do:
880 Run SCons under the Python profiler
881 and save the results in the specified
883 The results may be analyzed using the Python
887 Do not run any commands, or print anything. Just return an exit
888 status that is zero if the specified targets are already up to
889 date, non-zero otherwise.
892 Quiets SCons status messages about
893 reading SConscript files,
895 and entering directories.
896 Commands that are executed
897 to rebuild target files are still printed.
900 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
901 .\" Clear the default construction variables. Construction
902 .\" environments that are created will be completely empty.
906 Build dependencies in a random order. This is useful when
907 building multiple trees simultaneously with caching enabled,
908 to prevent multiple builds from simultaneously trying to build
909 or retrieve the same target files.
912 -s, --silent, --quiet
913 Silent. Do not print commands that are executed to rebuild
915 Also suppresses SCons status messages.
918 -S, --no-keep-going, --stop
919 Ignored for compatibility with GNU
924 Ignored for compatibility with GNU
926 (Touching a file to make it
927 appear up-to-date is unnecessary when using
931 -u, --up, --search-up
932 Walks up the directory structure until an
937 file is found, and uses that
938 as the top of the directory tree.
939 If no targets are specified on the command line,
940 only targets at or below the
941 current directory will be built.
945 Works exactly the same way as the
947 option except for the way default targets are handled.
948 When this option is used and no targets are specified on the command line,
949 all default targets that are defined in the SConscript(s) in the current
950 directory are built, regardless of what directory the resultant targets end
957 version, copyright information,
958 list of authors, and any other relevant information.
962 -w, --print-directory
963 Print a message containing the working directory before and
964 after other processing.
967 .RI --warn= type ", --warn=no-" type
968 Enable or disable warnings.
970 specifies the type of warnings to be enabled or disabled:
973 --warn=all, --warn=no-all
974 Enables or disables all warnings.
977 --warn=dependency, --warn=no-dependency
978 Enables or disables warnings about dependencies.
979 These warnings are disabled by default.
982 --warn=deprecated, --warn=no-deprecated
983 Enables or disables warnings about use of deprecated features.
984 These warnings are enabled by default.
987 --warn=missing-sconscript, --warn=no-missing-sconscript
988 Enables or disables warnings about missing SConscript files.
989 These warnings are enabled by default.
993 Turn off -w, even if it was turned on implicitly.
996 .\" .RI --write-filenames= file
997 .\" Write all filenames considered into
1001 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1002 .\" Pretend that the target
1005 .\" modified. When used with the
1008 .\" show you what would be rebuilt if you were to modify that file.
1014 .\" --warn-undefined-variables
1015 .\" Warn when an undefined variable is referenced.
1018 .RI -Y " repository" ", --repository=" repository
1019 Search the specified repository for any input and target
1020 files not found in the local directory hierarchy. Multiple
1022 options may specified, in which case the
1023 repositories are searched in the order specified.
1025 .SH CONFIGURATION FILE REFERENCE
1026 .\" .SS Python Basics
1027 .\" XXX Adding this in the future would be a help.
1028 .SS Construction Environments
1029 A construction environment is the basic means by which the SConscript
1030 files communicate build information to
1032 A new construction environment is created using the
1040 By default, a new construction environment is
1041 initialized with a set of builder methods
1042 and construction variables that are appropriate
1043 for the current platform.
1044 An optional platform keyword argument may be
1045 used to specify that an environment should
1046 be initialized for a different platform:
1049 env = Environment(platform = 'cygwin')
1050 env = Environment(platform = 'os2')
1051 env = Environment(platform = 'posix')
1052 env = Environment(platform = 'win32')
1055 Specifying a platform initializes the appropriate
1056 construction variables in the environment
1057 to use and generate file names with prefixes
1058 and suffixes appropriate for the platform.
1066 variables from the user's external environment
1067 to the construction environment's
1070 This is so that any executed commands
1071 that use sockets to connect with other systems
1072 (such as fetching source files from
1073 external CVS repository specifications like
1074 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1075 will work on Win32 systems.
1077 The platform argument may be function or callable object,
1078 in which case the Environment() method
1079 will call the specified argument to update
1080 the new construction environment:
1083 def my_platform(env):
1084 env['VAR'] = 'xyzzy'
1086 env = Environment(platform = my_platform)
1089 Additionally, a specific set of tools
1090 with which to initialize the environment
1091 may specified as an optional keyword argument:
1094 env = Environment(tools = ['msvc', 'lex'])
1097 Non-built-in tools may be specified using the toolpath argument:
1100 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1103 This looks for a tool specification in tools/foo.py (as well as
1104 using the ordinary default tools for the platform). foo.py should
1105 have two functions: generate(env, **kw) and exists(env).
1109 modifies the passed-in environment
1110 to set up variables so that the tool
1112 it may use any keyword arguments
1113 that the user supplies (see below)
1114 to vary its initialization.
1117 function should return a true
1118 value if the tool is available.
1119 Tools in the toolpath are used before
1120 any of the built-in ones. For example, adding gcc.py to the toolpath
1121 would override the built-in gcc tool.
1122 Also note that the toolpath is
1123 stored in the environment for use
1131 base = Environment(toolpath=['custom_path'])
1132 derived = base.Copy(tools=['custom_tool'])
1133 derived.CustomBuilder()
1136 The elements of the tools list may also
1137 be functions or callable objects,
1138 in which case the Environment() method
1139 will call the specified elements
1140 to update the new construction environment:
1144 env['XYZZY'] = 'xyzzy'
1146 env = Environment(tools = [my_tool])
1149 The individual elements of the tools list
1150 may also themselves be two-element lists of the form
1151 .RI ( toolname ", " kw_dict ).
1152 SCons searches for the
1154 specification file as described above, and
1157 which must be a dictionary, as keyword arguments to the tool's
1162 function can use the arguments to modify the tool's behavior
1163 by setting up the environment in different ways
1164 or otherwise changing its initialization.
1167 # in tools/my_tool.py:
1168 def generate(env, **kw):
1169 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1170 env['MY_TOOL'] = kw.get('arg1', '1')
1175 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1179 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1180 the environment it receives to customize the tool for different platforms.
1182 If no tool list is specified, then SCons will auto-detect the installed
1183 tools using the PATH variable in the ENV construction variable and the
1184 platform name when the Environment is constructed. Changing the PATH
1185 variable after the Environment is constructed will not cause the tools to
1188 SCons supports the following tool specifications out of the box:
1264 Additionally, there is a "tool" named
1266 which configures the
1267 environment with a default set of tools for the current platform.
1269 On posix and cygwin platforms
1270 the GNU tools (e.g. gcc) are preferred by SCons,
1271 on win32 the Microsoft tools (e.g. msvc)
1272 followed by MinGW are preferred by SCons,
1273 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1277 Build rules are specified by calling a construction
1278 environment's builder methods.
1279 The arguments to the builder methods are
1281 (a list of target files)
1284 (a list of source files).
1286 Because long lists of file names
1287 can lead to a lot of quoting,
1292 and a same-named environment method
1293 that split a single string
1294 into a list, separated on
1295 strings of white-space characters.
1296 (These are similar to the
1297 string.split() method
1298 from the standard Python library,
1299 but work even if the input isn't a string.)
1301 Like all Python arguments,
1302 the target and source arguments to a builder method
1303 can be specified either with or without
1304 the "target" and "source" keywords.
1305 When the keywords are omitted,
1306 the target is first,
1307 followed by the source.
1308 The following are equivalent examples of calling the Program builder method:
1311 env.Program('bar', ['bar.c', 'foo.c'])
1312 env.Program('bar', Split('bar.c foo.c'))
1313 env.Program('bar', env.Split('bar.c foo.c'))
1314 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1315 env.Program(target = 'bar', Split('bar.c foo.c'))
1316 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1317 env.Program('bar', source = string.split('bar.c foo.c'))
1320 When the target shares the same base name
1321 as the source and only the suffix varies,
1322 and if the builder method has a suffix defined for the target file type,
1323 then the target argument may be omitted completely,
1326 will deduce the target file name from
1327 the source file name.
1328 The following examples all build the
1334 (on Windows systems)
1335 from the bar.c source file:
1338 env.Program(target = 'bar', source = 'bar.c')
1339 env.Program('bar', source = 'bar.c')
1340 env.Program(source = 'bar.c')
1341 env.Program('bar.c')
1344 It is possible to override or add construction variables when calling a
1345 builder method by passing additional keyword arguments.
1346 These overridden or added
1347 variables will only be in effect when building the target, so they will not
1348 affect other parts of the build. For example, if you want to add additional
1349 libraries for just one program:
1352 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1355 or generate a shared library with a nonstandard suffix:
1358 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
1361 Although the builder methods defined by
1364 methods of a construction environment object,
1365 they may also be called without an explicit environment:
1368 Program('hello', 'hello.c')
1369 SharedLibrary('word', 'word.cpp')
1373 the methods are called internally using a default construction
1374 environment that consists of the tools and values that
1376 has determined are appropriate for the local system.
1378 Builder methods that can be called without an explicit
1379 environment may be called from custom Python modules that you
1380 import into an SConscript file by adding the following
1381 to the Python module:
1384 from SCons.Script import *
1387 All builder methods return a list of Nodes
1388 that represent the target or targets that will be built.
1391 is an internal SCons object
1393 build targets or sources.
1395 The returned Node(s)
1396 can be passed to other builder methods as source(s)
1397 or passed to any SCons function or method
1398 where a filename would normally be accepted.
1399 For example, if it were necessary
1402 flag when compiling one specific object file:
1405 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1406 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1409 Using a Node in this way
1410 makes for a more portable build
1411 by avoiding having to specify
1412 a platform-specific object suffix
1413 when calling the Program() builder method.
1415 Note that Builder calls will automatically "flatten"
1416 the source and target file lists,
1417 so it's all right to have the bar_obj list
1418 return by the StaticObject() call
1419 in the middle of the source file list.
1420 If you need to manipulate a list of lists returned by Builders
1421 directly using Python,
1422 you can either build the list by hand:
1425 foo = Object('foo.c')
1426 bar = Object('bar.c')
1427 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1428 for object in objects:
1435 to create a list containing just the Nodes,
1436 which may be more convenient:
1439 foo = Object('foo.c')
1440 bar = Object('bar.c')
1441 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1442 for object in objects:
1446 The path name for a Node's file may be used
1447 by passing the Node to the Python-builtin
1452 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1453 print "The path to bar_obj is:", str(bar_obj_list[0])
1456 Note again that because the Builder call returns a list,
1457 we have to access the first element in the list
1458 .B (bar_obj_list[0])
1459 to get at the Node that actually represents
1462 Builder calls support a
1464 keyword argument that
1465 specifies that the Builder's action(s)
1467 after changing directory.
1471 a string or a directory Node,
1472 scons will change to the specified directory.
1475 is not a string or Node
1477 then scons will change to the
1478 target file's directory.
1481 # scons will change to the "sub" subdirectory
1482 # before executing the "cp" command.
1483 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1484 "cp dir/foo.in dir/foo.out",
1487 # Because chdir is not a string, scons will change to the
1488 # target's directory ("sub/dir") before executing the
1490 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1491 "cp foo.in foo.out",
1495 Note that scons will
1497 automatically modify
1499 construction variables like
1503 when using the chdir
1504 keyword argument--that is,
1505 the expanded file names
1506 will still be relative to
1507 the top-level SConstruct directory,
1508 and consequently incorrect
1509 relative to the chdir directory.
1510 If you use the chdir keyword argument,
1511 you will typically need to supply a different
1517 to use just the filename portion of the
1521 provides the following builder methods:
1523 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1526 Builds a C source file given a lex (.l) or yacc (.y) input file.
1527 The suffix specified by the $CFILESUFFIX construction variable
1529 is automatically added to the target
1530 if it is not already present. Example:
1534 env.CFile(target = 'foo.c', source = 'foo.l')
1536 env.CFile(target = 'bar', source = 'bar.y')
1539 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1542 Builds a C++ source file given a lex (.ll) or yacc (.yy)
1544 The suffix specified by the $CXXFILESUFFIX construction variable
1546 is automatically added to the target
1547 if it is not already present. Example:
1551 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1553 env.CXXFile(target = 'bar', source = 'bar.yy')
1556 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1559 Builds a .dvi file from a .tex, .ltx or .latex input file.
1560 If the source file suffix is .tex,
1562 will examine the contents of the file;
1567 is found, the file is assumed to be a LaTeX file and
1568 the target is built by invoking the $LATEXCOM command line;
1569 otherwise, the $TEXCOM command line is used.
1570 If the file is a LaTeX file,
1573 builder method will also examine the contents
1576 and invoke the $BIBTEX command line
1580 and will examine the contents
1582 file and re-run the $LATEXCOM command
1583 if the log file says it is necessary.
1586 (hard-coded within TeX itself)
1587 is automatically added to the target
1588 if it is not already present. Examples:
1591 # builds from aaa.tex
1592 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1594 env.DVI(target = 'bbb', source = 'bbb.ltx')
1595 # builds from ccc.latex
1596 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1599 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1602 Builds a Java archive (.jar) file
1603 from a source tree of .class files.
1604 If the $JARCHDIR value is set, the
1606 command will change to the specified directory using the
1609 If the contents any of the source files begin with the string
1610 .BR Manifest-Version ,
1611 the file is assumed to be a manifest
1612 and is passed to the
1619 env.Jar(target = 'foo.jar', source = 'classes')
1622 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1625 Builds one or more Java class files
1626 from one or more source trees of .java files.
1627 The class files will be placed underneath
1628 the specified target directory.
1629 SCons will parse each source .java file
1631 (including inner classes)
1632 defined within that file,
1633 and from that figure out the
1634 target .class files that will be created.
1635 SCons will also search each Java file
1636 for the Java package name,
1637 which it assumes can be found on a line
1638 beginning with the string
1640 in the first column;
1641 the resulting .class files
1642 will be placed in a directory reflecting
1643 the specified package name.
1647 defining a single public
1650 containing a package name of
1652 will generate a corresponding
1653 .IR sub/dir/Foo.class
1659 env.Java(target = 'classes', source = 'src')
1660 env.Java(target = 'classes', source = ['src1', 'src2'])
1663 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1666 Builds C header and source files for
1667 implementing Java native methods.
1668 The target can be either a directory
1669 in which the header files will be written,
1670 or a header file name which
1671 will contain all of the definitions.
1672 The source can be either the names of .class files,
1673 or the objects returned from the
1677 If the construction variable
1679 is set, either in the environment
1680 or in the call to the
1682 builder method itself,
1683 then the value of the variable
1684 will be stripped from the
1685 beginning of any .class file names.
1690 # builds java_native.h
1691 classes = env.Java(target = 'classdir', source = 'src')
1692 env.JavaH(target = 'java_native.h', source = classes)
1694 # builds include/package_foo.h and include/package_bar.h
1695 env.JavaH(target = 'include',
1696 source = ['package/foo.class', 'package/bar.class'])
1698 # builds export/foo.h and export/bar.h
1699 env.JavaH(target = 'export',
1700 source = ['classes/foo.class', 'classes/bar.class'],
1701 JAVACLASSDIR = 'classes')
1704 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1711 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1712 .IP LoadableModule()
1713 .IP env.LoadableModule()
1716 .BR SharedLibrary ().
1717 On Mac OS X (Darwin) platforms,
1718 this creates a loadable module bundle.
1721 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1724 Builds an output file from an M4 input file.
1725 This uses a default $M4FLAGS value of
1727 which considers all warnings to be fatal
1728 and stops on the first warning
1729 when using the GNU version of m4.
1733 env.M4(target = 'foo.c', source = 'foo.c.m4')
1736 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1739 Builds an output file from a moc input file. Moc input files are either
1740 header files or cxx files. This builder is only available after using the
1741 tool 'qt'. See the QTDIR variable for more information.
1745 env.Moc('foo.h') # generates moc_foo.cc
1746 env.Moc('foo.cpp') # generates foo.moc
1749 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1751 .IP env.MSVSProject()
1752 Builds a Microsoft Visual Studio project file,
1753 and by default builds a solution file as well.
1755 This builds a Visual Studio project file, based on the version of
1756 Visual Studio that is configured (either the latest installed version,
1757 or the version specified by
1759 in the construction environment).
1760 For Visual Studio 6, it will generate a
1763 For Visual Studio 7 (.NET), it will
1769 this also generates a solution file
1770 for the specified project,
1773 file for Visual Studio 6
1776 file for Visual Studio 7 (.NET).
1777 This behavior may be disabled by specifying
1778 .B auto_build_solution=0
1781 in which case you presumably want to
1782 build the solution file(s)
1785 Builder (see below).
1787 It takes several lists of filenames to be placed into the project
1789 These are currently limited to
1796 These are pretty self-explanatory, but it should be noted that these
1797 lists are added to the $SOURCES construction variable as strings,
1798 NOT as SCons File Nodes. This is because they represent file
1799 names to be added to the project file, not the source files used to
1800 build the project file.
1802 In addition to the above lists of values (which are all optional,
1803 although not specifying any of them results in an empty project file),
1804 the following values may be specified:
1807 The name of the target
1813 suffix for the version of Visual Studio must be used, but the
1814 .B env['MSVSPROJECTSUFFIX']
1815 construction variable
1816 will be defined to the correct value (see example below).
1819 The name of this particular variant.
1820 For Visual Studio 7 projects,
1821 this can also be a list of variant names.
1822 These are typically things like "Debug" or "Release", but really
1823 can be anything you want.
1824 For Visual Studio 7 projects,
1825 they may also specify a target platform
1826 separated from the variant name by a
1831 The default target platform is Win32.
1834 with different variants are allowed;
1835 all variants will be added to the project file with their appropriate
1836 build targets and sources.
1839 An optional string, node, or list of strings or nodes
1840 (one per build variant), to tell the Visual Studio debugger
1841 what output target to use in what build variant.
1844 entries must match the number of
1851 barsrcs = ['bar.cpp'],
1852 barincs = ['bar.h'],
1853 barlocalincs = ['StdAfx.h']
1854 barresources = ['bar.rc','resource.h']
1855 barmisc = ['bar_readme.txt']
1857 dll = local.SharedLibrary(target = 'bar.dll',
1860 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1863 localincs = barlocalincs,
1864 resources = barresources,
1867 variant = 'Release')
1870 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1872 .IP env.MSVSSolution()
1873 Builds a Microsoft Visual Studio solution file.
1875 This builds a Visual Studio solution file,
1876 based on the version of Visual Studio that is configured
1877 (either the latest installed version,
1878 or the version specified by
1880 in the construction environment).
1881 For Visual Studio 6, it will generate a
1884 For Visual Studio 7 (.NET), it will
1889 The following values must be specified:
1892 The name of the target .dsw or .sln file. The correct
1893 suffix for the version of Visual Studio must be used, but the value
1894 .B env['MSVSSOLUTIONSUFFIX']
1895 will be defined to the correct value (see example below).
1898 The name of this particular variant, or a list of variant
1899 names (the latter is only supported for MSVS 7 solutions). These are
1900 typically things like "Debug" or "Release", but really can be anything
1901 you want. For MSVS 7 they may also specify target platform, like this
1902 "Debug|Xbox". Default platform is Win32.
1905 A list of project file names, or Project nodes returned by calls to the
1908 to be placed into the solution file.
1909 (NOTE: Currently only one project is supported per solution.)
1910 It should be noted that these file names are NOT added to the $SOURCES
1911 environment variable in form of files, but rather as strings. This
1912 is because they represent file names to be added to the solution file,
1913 not the source files used to build the solution file.
1918 local.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
1919 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
1920 variant = 'Release')
1923 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1930 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1933 Builds a Microsoft Visual C++ precompiled header.
1934 Calling this builder method
1935 returns a list of two targets: the PCH as the first element, and the object
1936 file as the second element. Normally the object file is ignored.
1937 This builder method is only
1938 provided when Microsoft Visual C++ is being used as the compiler.
1939 The PCH builder method is generally used in
1940 conjuction with the PCH construction variable to force object files to use
1941 the precompiled header:
1944 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1947 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1950 Builds a .pdf file from a .dvi input file
1951 (or, by extension, a .tex, .ltx, or .latex input file).
1952 The suffix specified by the $PDFSUFFIX construction variable
1954 is added automatically to the target
1955 if it is not already present. Example:
1958 # builds from aaa.tex
1959 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1960 # builds bbb.pdf from bbb.dvi
1961 env.PDF(target = 'bbb', source = 'bbb.dvi')
1964 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1966 .IP env.PostScript()
1967 Builds a .ps file from a .dvi input file
1968 (or, by extension, a .tex, .ltx, or .latex input file).
1969 The suffix specified by the $PSSUFFIX construction variable
1971 is added automatically to the target
1972 if it is not already present. Example:
1975 # builds from aaa.tex
1976 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1977 # builds bbb.ps from bbb.dvi
1978 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1981 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1984 Builds an executable given one or more object files
1985 or C, C++, D, or Fortran source files.
1986 If any C, C++, D or Fortran source files are specified,
1987 then they will be automatically
1988 compiled to object files using the
1991 see that builder method's description for
1992 a list of legal source file suffixes
1993 and how they are interpreted.
1994 The target executable file prefix
1995 (specified by the $PROGPREFIX construction variable; nothing by default)
1997 (specified by the $PROGSUFFIX construction variable;
1998 by default, .exe on Windows systems, nothing on POSIX systems)
1999 are automatically added to the target if not already present.
2003 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
2006 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2009 Builds a Microsoft Visual C++ resource file.
2010 This builder method is only provided
2011 when Microsoft Visual C++ or MinGW is being used as the compiler. The
2015 for MinGW) suffix is added to the target name if no other suffix is given. The source
2016 file is scanned for implicit dependencies as though it were a C file. Example:
2019 env.RES('resource.rc')
2022 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2025 Builds stub and skeleton class files
2027 from Java .class files.
2028 The target is a directory
2029 relative to which the stub
2030 and skeleton class files will be written.
2031 The source can be the names of .class files,
2032 or the objects return from the
2036 If the construction variable
2038 is set, either in the environment
2039 or in the call to the
2041 builder method itself,
2042 then the value of the variable
2043 will be stripped from the
2044 beginning of any .class file names.
2047 classes = env.Java(target = 'classdir', source = 'src')
2048 env.RMIC(target = 'outdir1', source = classes)
2050 env.RMIC(target = 'outdir2',
2051 source = ['package/foo.class', 'package/bar.class'])
2053 env.RMIC(target = 'outdir3',
2054 source = ['classes/foo.class', 'classes/bar.class'],
2055 JAVACLASSDIR = 'classes')
2058 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2060 .IP env.RPCGenClient()
2061 Generates an RPC client stub (_clnt.c) file
2062 from a specified RPC (.x) source file.
2063 Because rpcgen only builds output files
2064 in the local directory,
2065 the command will be executed
2066 in the source file's directory by default.
2069 # Builds src/rpcif_clnt.c
2070 env.RPCGenClient('src/rpcif.x')
2073 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2075 .IP env.RPCGenHeader()
2076 Generates an RPC header (.h) file
2077 from a specified RPC (.x) source file.
2078 Because rpcgen only builds output files
2079 in the local directory,
2080 the command will be executed
2081 in the source file's directory by default.
2084 # Builds src/rpcif.h
2085 env.RPCGenHeader('src/rpcif.x')
2088 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2090 .IP env.RPCGenService()
2091 Generates an RPC server-skeleton (_svc.c) file
2092 from a specified RPC (.x) source file.
2093 Because rpcgen only builds output files
2094 in the local directory,
2095 the command will be executed
2096 in the source file's directory by default.
2099 # Builds src/rpcif_svc.c
2100 env.RPCGenClient('src/rpcif.x')
2103 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2106 Generates an RPC XDR routine (_xdr.c) file
2107 from a specified RPC (.x) source file.
2108 Because rpcgen only builds output files
2109 in the local directory,
2110 the command will be executed
2111 in the source file's directory by default.
2114 # Builds src/rpcif_xdr.c
2115 env.RPCGenClient('src/rpcif.x')
2118 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2120 .IP env.SharedLibrary()
2121 Builds a shared library
2122 (.so on a POSIX system, .dll on WIN32)
2123 given one or more object files
2124 or C, C++, D or Fortran source files.
2125 If any source files are given,
2126 then they will be automatically
2127 compiled to object files.
2128 The static library prefix and suffix (if any)
2129 are automatically added to the target.
2130 The target library file prefix
2131 (specified by the $SHLIBPREFIX construction variable;
2132 by default, lib on POSIX systems, nothing on Windows systems)
2134 (specified by the $SHLIBSUFFIX construction variable;
2135 by default, .dll on Windows systems, .so on POSIX systems)
2136 are automatically added to the target if not already present.
2140 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2143 On WIN32 systems, the
2145 builder method will always build an import (.lib) library
2146 in addition to the shared (.dll) library,
2147 adding a .lib library with the same basename
2148 if there is not already a .lib file explicitly
2149 listed in the targets.
2151 Any object files listed in the
2153 must have been built for a shared library
2158 will raise an error if there is any mismatch.
2160 On WIN32 systems, specifying "register=1" will cause the dll to be
2161 registered after it is built using REGSVR32. The command that is run
2162 ("regsvr32" by default) is determined by $REGSVR construction
2163 variable, and the flags passed are determined by $REGSVRFLAGS. By
2164 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
2165 up and requiring user attention when it is run. If you change
2166 $REGSVRFLAGS, be sure to include "/s". For example,
2169 env.SharedLibrary(target = 'bar',
2170 source = ['bar.cxx', 'foo.obj'],
2175 will register "bar.dll" as a COM object when it is done linking it.
2177 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2179 .IP env.SharedObject()
2180 Builds an object file for
2181 inclusion in a shared library.
2182 Source files must have one of the same set of extensions
2183 specified above for the
2186 On some platforms building a shared object requires additional
2187 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
2188 normal (static) object, but on some platforms there is no difference between a
2189 shared object and a normal (static) one. When there is a difference, SCons
2190 will only allow shared objects to be linked into a shared library, and will
2191 use a different suffix for shared objects. On platforms where there is no
2192 difference, SCons will allow both normal (static)
2193 and shared objects to be linked into a
2194 shared library, and will use the same suffix for shared and normal
2196 The target object file prefix
2197 (specified by the $SHOBJPREFIX construction variable;
2198 by default, the same as $OBJPREFIX)
2200 (specified by the $SHOBJSUFFIX construction variable)
2201 are automatically added to the target if not already present.
2205 env.SharedObject(target = 'ddd', source = 'ddd.c')
2206 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2207 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2210 Note that the source files will be scanned
2211 according to the suffix mappings in
2212 .B SourceFileScanner
2214 See the section "Scanner Objects,"
2215 below, for a more information.
2217 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2219 .IP env.StaticLibrary()
2220 Builds a static library given one or more object files
2221 or C, C++, D or Fortran source files.
2222 If any source files are given,
2223 then they will be automatically
2224 compiled to object files.
2225 The static library prefix and suffix (if any)
2226 are automatically added to the target.
2227 The target library file prefix
2228 (specified by the $LIBPREFIX construction variable;
2229 by default, lib on POSIX systems, nothing on Windows systems)
2231 (specified by the $LIBSUFFIX construction variable;
2232 by default, .lib on Windows systems, .a on POSIX systems)
2233 are automatically added to the target if not already present.
2237 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2241 Any object files listed in the
2243 must have been built for a static library
2248 will raise an error if there is any mismatch.
2250 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2252 .IP env.StaticObject()
2253 Builds a static object file
2254 from one or more C, C++, D, or Fortran source files.
2255 Source files must have one of the following extensions:
2258 .asm assembly language file
2259 .ASM assembly language file
2271 .F WIN32: Fortran file
2272 POSIX: Fortran file + C pre-processor
2275 .fpp Fortran file + C pre-processor
2276 .FPP Fortran file + C pre-processor
2278 .mm Objective C++ file
2279 .s assembly language file
2280 .S WIN32: assembly language file
2281 POSIX: assembly language file + C pre-processor
2282 .spp assembly language file + C pre-processor
2283 .SPP assembly language file + C pre-processor
2286 The target object file prefix
2287 (specified by the $OBJPREFIX construction variable; nothing by default)
2289 (specified by the $OBJSUFFIX construction variable;
2290 \.obj on Windows systems, .o on POSIX systems)
2291 are automatically added to the target if not already present.
2295 env.StaticObject(target = 'aaa', source = 'aaa.c')
2296 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2297 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2300 Note that the source files will be scanned
2301 according to the suffix mappings in
2302 .B SourceFileScanner
2304 See the section "Scanner Objects,"
2305 below, for a more information.
2307 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2310 Builds a tar archive of the specified files
2312 Unlike most builder methods,
2315 builder method may be called multiple times
2317 each additional call
2318 adds to the list of entries
2319 that will be built into the archive.
2320 Any source directories will
2321 be scanned for changes to
2323 regardless of whether or not
2325 knows about them from other Builder or function calls.
2328 env.Tar('src.tar', 'src')
2330 # Create the stuff.tar file.
2331 env.Tar('stuff', ['subdir1', 'subdir2'])
2332 # Also add "another" to the stuff.tar file.
2333 env.Tar('stuff', 'another')
2335 # Set TARFLAGS to create a gzip-filtered archive.
2336 env = Environment(TARFLAGS = '-c -z')
2337 env.Tar('foo.tar.gz', 'foo')
2339 # Also set the suffix to .tgz.
2340 env = Environment(TARFLAGS = '-c -z',
2345 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2347 .IP env.TypeLibrary()
2348 Builds a Windows type library (.tlb) file from and input IDL file
2349 (.idl). In addition, it will build the associated inteface stub and
2350 proxy source files. It names them according to the base name of the .idl file.
2355 env.TypeLibrary(source="foo.idl")
2358 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2360 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2363 Builds a header file, an implementation file and a moc file from an ui file.
2364 and returns the corresponding nodes in the above order.
2365 This builder is only available after using the tool 'qt'. Note: you can
2366 specify .ui files directly as inputs for Program, Library and SharedLibrary
2367 without using this builder. Using the builder lets you override the standard
2368 naming conventions (be careful: prefixes are always prepended to names of
2369 built files; if you don't want prefixes, you may set them to ``).
2370 See the QTDIR variable for more information.
2374 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2375 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2376 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2379 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2382 Builds a zip archive of the specified files
2384 Unlike most builder methods,
2387 builder method may be called multiple times
2389 each additional call
2390 adds to the list of entries
2391 that will be built into the archive.
2392 Any source directories will
2393 be scanned for changes to
2395 regardless of whether or not
2397 knows about them from other Builder or function calls.
2400 env.Zip('src.zip', 'src')
2402 # Create the stuff.zip file.
2403 env.Zip('stuff', ['subdir1', 'subdir2'])
2404 # Also add "another" to the stuff.tar file.
2405 env.Zip('stuff', 'another')
2409 targets of builder methods automatically depend on their sources.
2410 An explicit dependency can
2411 be specified using the
2413 method of a construction environment (see below).
2418 source files for various programming languages,
2419 so the dependencies do not need to be specified explicitly.
2420 By default, SCons can
2423 Fortran source files with
2425 (POSIX systems only),
2430 and assembly language files with
2432 (POSIX systems only),
2437 for C preprocessor dependencies.
2438 SCons also has default support
2439 for scanning D source files,
2440 You can also write your own Scanners
2441 to add support for additional source file types.
2442 These can be added to the default
2443 Scanner object used by
2449 Builders by adding them
2451 .B SourceFileScanner
2454 See the section "Scanner Objects,"
2455 below, for a more information about
2456 defining your own Scanner objects.
2458 .SS Methods and Functions to Do Things
2459 In addition to Builder methods,
2461 provides a number of other construction environment methods
2462 and global functions to
2463 manipulate the build configuration.
2465 Usually, a construction environment method
2466 and global function with the same name both exist
2467 so that you don't have to remember whether
2468 to a specific bit of functionality
2469 must be called with or without a construction environment.
2470 In the following list,
2471 if you call something as a global function
2474 .RI Function( arguments )
2476 and if you call something through a construction
2477 environment it looks like:
2479 .RI env.Function( arguments )
2481 If you can call the functionality in both ways,
2482 then both forms are listed.
2484 Global functions may be called from custom Python modules that you
2485 import into an SConscript file by adding the following
2486 to the Python module:
2489 from SCons.Script import *
2492 Except where otherwise noted,
2494 construction environment method
2496 provide the exact same functionality.
2497 The only difference is that,
2499 calling the functionality through a construction environment will
2500 substitute construction variables into
2501 any supplied strings.
2504 env = Environment(FOO = 'foo')
2508 the first call to the global
2510 function will actually add a target named
2512 to the list of default targets,
2513 while the second call to the
2515 construction environment method
2516 will expand the value
2517 and add a target named
2519 to the list of default targets.
2520 For more on construction variable expansion,
2521 see the next section on
2522 construction variables.
2524 Construction environment methods
2525 and global functions supported by
2529 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2531 .RI Action( action ", [" strfunction ", " varlist ])
2533 .RI env.Action( action ", [" strfunction ", " varlist ])
2534 Creates an Action object for
2537 See the section "Action Objects,"
2538 below, for a complete explanation of the arguments and behavior.
2540 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2542 .RI AddPostAction( target ", " action )
2544 .RI env.AddPostAction( target ", " action )
2545 Arranges for the specified
2551 The specified action(s) may be
2552 an Action object, or anything that
2553 can be converted into an Action object
2556 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2558 .RI AddPreAction( target ", " action )
2560 .RI env.AddPreAction( target ", " action )
2561 Arranges for the specified
2564 before the specified
2567 The specified action(s) may be
2568 an Action object, or anything that
2569 can be converted into an Action object
2572 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2574 .RI Alias( alias ", [" targets ", [" action ]])
2576 .RI env.Alias( alias ", [" targets ", [" action ]])
2577 Creates one or more phony targets that
2578 expand to one or more other targets.
2583 can be specified that will be executed
2584 whenever the any of the alias targets are out-of-date.
2585 Returns the Node object representing the alias,
2586 which exists outside of any file system.
2587 This Node object, or the alias name,
2588 may be used as a dependency of any other target,
2589 including another alias.
2591 can be called multiple times for the same
2592 alias to add additional targets to the alias,
2593 or additional actions to the list for this alias.
2597 Alias('install', '/usr/bin')
2598 Alias(['install', 'install-lib'], '/usr/local/lib')
2600 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2601 env.Alias('install', ['/usr/local/man'])
2603 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2606 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2608 .RI AlwaysBuild( target ", ...)"
2610 .RI env.AlwaysBuild( target ", ...)"
2613 so that it is always assumed to be out of date,
2614 and will always be rebuilt if needed.
2617 does not add its target(s) to the default target list,
2618 so the targets will only be built
2619 if they are specified on the command line,
2620 or are a dependent of a target specified on the command line--but
2623 be built if so specified.
2624 Multiple targets can be passed in to a single call to
2627 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2629 .RI env.Append( key = val ", [...])"
2630 Appends the specified keyword arguments
2631 to the end of construction variables in the environment.
2632 If the Environment does not have
2633 the specified construction variable,
2634 it is simply added to the environment.
2635 If the values of the construction variable
2636 and the keyword argument are the same type,
2637 then the two values will be simply added together.
2638 Otherwise, the construction variable
2639 and the value of the keyword argument
2640 are both coerced to lists,
2641 and the lists are added together.
2642 (See also the Prepend method, below.)
2645 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2648 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2650 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2651 This appends new path elements to the given path in the
2652 specified external environment
2656 any particular path once (leaving the last one it encounters and
2657 ignoring the rest, to preserve path order),
2658 and to help assure this,
2659 will normalize all paths (using
2662 .BR os.path.normcase ).
2663 This can also handle the
2664 case where the given old path variable is a list instead of a
2665 string, in which case a list will be returned instead of a string.
2669 print 'before:',env['ENV']['INCLUDE']
2670 include_path = '/foo/bar:/foo'
2671 env.AppendENVPath('INCLUDE', include_path)
2672 print 'after:',env['ENV']['INCLUDE']
2676 after: /biz:/foo/bar:/foo
2679 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2681 .RI env.AppendUnique( key = val ", [...])"
2682 Appends the specified keyword arguments
2683 to the end of construction variables in the environment.
2684 If the Environment does not have
2685 the specified construction variable,
2686 it is simply added to the environment.
2687 If the construction variable being appended to is a list,
2688 then any value(s) that already exist in the
2689 construction variable will
2691 be added again to the list.
2694 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2697 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2700 A factory function that
2701 returns a Builder object
2702 to be used to fetch source files
2704 The returned Builder
2705 is intended to be passed to the
2710 env.SourceCode('.', env.BitKeeper())
2713 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2715 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2717 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2718 This specifies a build directory
2720 in which to build all derived files
2721 that would normally be built under
2723 Multiple build directories can be set up for multiple build variants, for
2726 must be underneath the SConstruct file's directory,
2729 may not be underneath the
2732 The default behavior is for
2734 to duplicate all of the files in the tree underneath
2738 and then build the derived files within the copied tree.
2739 (The duplication is performed by
2741 depending on the platform; see also the
2744 This guarantees correct builds
2745 regardless of whether intermediate source files
2746 are generated during the build,
2747 where preprocessors or other scanners search
2749 or whether individual compilers or other invoked tools
2750 are hard-coded to put derived files in the same directory as source files.
2752 This behavior of making a complete copy of the source tree
2753 may be disabled by setting
2758 to invoke Builders using the
2759 path names of source files in
2761 and the path names of derived files within
2763 This is always more efficient than
2765 and is usually safe for most builds.
2769 may cause build problems
2770 if source files are generated during the build,
2771 if any invoked tools are hard-coded to
2772 put derived files in the same directory as the source files.
2774 Note that specifying a
2776 works most naturally
2777 with a subsidiary SConscript file
2778 in the source directory.
2780 you would then call the subsidiary SConscript file
2781 not in the source directory,
2786 had made a virtual copy of the source tree
2787 regardless of the value of
2789 This is how you tell
2791 which variant of a source tree to build.
2795 BuildDir('build-variant1', 'src')
2796 SConscript('build-variant1/SConscript')
2797 BuildDir('build-variant2', 'src')
2798 SConscript('build-variant2/SConscript')
2804 function, described below,
2806 specify a build directory
2807 in conjunction with calling a subsidiary
2810 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2812 .RI Builder( action ", [" arguments ])
2814 .RI env.Builder( action ", [" arguments ])
2815 Creates a Builder object for
2818 See the section "Builder Objects,"
2819 below, for a complete explanation of the arguments and behavior.
2821 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2823 .RI CacheDir( cache_dir )
2825 .RI env.CacheDir( cache_dir )
2828 will maintain a cache of derived files in
2830 The derived files in the cache will be shared
2831 among all the builds using the same
2839 finds a derived file that needs to be rebuilt,
2840 it will first look in the cache to see if a
2841 derived file has already been built
2842 from identical input files and an identical build action
2843 (as incorporated into the MD5 build signature).
2846 will retrieve the file from the cache.
2847 If the derived file is not present in the cache,
2850 then place a copy of the built file in the cache
2851 (identified by its MD5 build signature),
2852 so that it may be retrieved by other
2853 builds that need to build the same derived file
2854 from identical inputs.
2858 may be disabled for any invocation
2867 will place a copy of
2869 derived files in the cache,
2870 even if they already existed
2871 and were not built by this invocation.
2872 This is useful to populate a cache
2875 is added to a build,
2884 "Retrieved `file' from cache,"
2887 option is being used.
2892 will print the action that
2894 have been used to build the file,
2895 without any indication that
2896 the file was actually retrieved from the cache.
2897 This is useful to generate build logs
2898 that are equivalent regardless of whether
2899 a given derived file has been built in-place
2900 or retrieved from the cache.
2902 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2904 .RI Clean( targets ", " files_or_dirs )
2906 .RI env.Clean( targets ", " files_or_dirs )
2907 This specifies a list of files or directories which should be removed
2908 whenever the targets are specified with the
2910 command line option.
2911 The specified targets may be a list
2912 or an individual target.
2916 and create new targets or add files and directories to the
2917 clean list for the specified targets.
2919 Multiple files or directories should be specified
2920 either as separate arguments to the
2922 method, or as a list.
2924 will also accept the return value of any of the construction environment
2929 Clean('foo', ['bar', 'baz'])
2930 Clean('dist', env.Program('hello', 'hello.c'))
2931 Clean(['foo', 'bar'], 'something_else_to_clean')
2934 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2936 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2938 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2939 Executes a specific action
2940 (or list of actions)
2941 to build a target file or files.
2942 This is more convenient
2943 than defining a separate Builder object
2944 for a single special-case build.
2946 As a special case, the
2948 keyword argument can
2951 that will be used to scan the sources.
2955 if any of the sources will be directories
2956 that must be scanned on-disk for
2957 changes to files that aren't
2958 already specified in other Builder of function calls.)
2960 Any other keyword arguments specified override any
2961 same-named existing construction variables.
2963 An action can be an external command,
2964 specified as a string,
2965 or a callable Python object;
2966 see "Action Objects," below,
2967 for more complete information.
2968 Also note that a string specifying an external command
2969 may be preceded by an
2972 to suppress printing the command in question,
2976 to ignore the exit status of the external command.
2980 env.Command('foo.out', 'foo.in',
2981 "$FOO_BUILD < $SOURCES > $TARGET")
2983 env.Command('bar.out', 'bar.in',
2985 "$BAR_BUILD < $SOURCES > $TARGET"],
2986 ENV = {'PATH' : '/usr/local/bin/'})
2988 def rename(env, target, source):
2990 os.rename('.tmp', str(target[0]))
2992 env.Command('baz.out', 'baz.in',
2993 ["$BAZ_BUILD < $SOURCES > .tmp",
2997 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2999 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3001 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3002 Creates a Configure object for integrated
3003 functionality similar to GNU autoconf.
3004 See the section "Configure Contexts,"
3005 below, for a complete explanation of the arguments and behavior.
3007 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3009 .RI env.Copy([ key = val ", ...])"
3010 Return a separate copy of a construction environment.
3011 If there are any keyword arguments specified,
3012 they are added to the returned copy,
3013 overwriting any existing values
3018 env3 = env.Copy(CCFLAGS = '-g')
3021 Additionally, a list of tools and a toolpath may be specified, as in
3022 the Environment constructor:
3025 def MyTool(env): env['FOO'] = 'bar'
3026 env4 = env.Copy(tools = ['msvc', MyTool])
3029 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3031 .RI env.CVS( repository ", " module )
3032 A factory function that
3033 returns a Builder object
3034 to be used to fetch source files
3038 The returned Builder
3039 is intended to be passed to the
3043 The optional specified
3045 will be added to the beginning
3046 of all repository path names;
3047 this can be used, in essence,
3048 to strip initial directory names
3049 from the repository path names,
3050 so that you only have to
3051 replicate part of the repository
3052 directory hierarchy in your
3053 local build directory:
3056 # Will fetch foo/bar/src.c
3057 # from /usr/local/CVSROOT/foo/bar/src.c.
3058 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3060 # Will fetch bar/src.c
3061 # from /usr/local/CVSROOT/foo/bar/src.c.
3062 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3065 # from /usr/local/CVSROOT/foo/bar/src.c.
3066 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3069 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3071 .RI Default( targets )
3073 .RI env.Default( targets )
3074 This specifies a list of default targets,
3075 which will be built by
3077 if no explicit targets are given on the command line.
3081 and add to the list of default targets.
3083 Multiple targets should be specified as
3084 separate arguments to the
3086 method, or as a list.
3088 will also accept the Node returned by any
3089 of a construction environment's
3094 Default('foo', 'bar', 'baz')
3095 env.Default(['a', 'b', 'c'])
3096 hello = env.Program('hello', 'hello.c')
3104 will clear all default targets.
3107 will add to the (now empty) default-target list
3110 The current list of targets added using the
3112 function or method is available in the
3117 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3119 .RI DefaultEnvironment([ args ])
3120 Creates and returns a default construction environment object.
3121 This construction environment is used internally by SCons
3122 in order to execute many of the global functions in this list,
3123 and to fetch source files transparently
3124 from source code management systems.
3126 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3128 .RI Depends( target ", " dependency )
3130 .RI env.Depends( target ", " dependency )
3131 Specifies an explicit dependency;
3132 the target file(s) will be rebuilt
3133 whenever the dependency file(s) has changed.
3134 This should only be necessary
3135 for cases where the dependency
3136 is not caught by a Scanner
3140 env.Depends('foo', 'other-input-file-for-foo')
3143 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3145 .RI env.Dictionary([ vars ])
3146 Returns a dictionary object
3147 containing copies of all of the
3148 construction variables in the environment.
3149 If there are any variable names specified,
3150 only the specified construction
3151 variables are returned in the dictionary.
3154 dict = env.Dictionary()
3155 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3158 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3160 .RI Dir( name ", [" directory ])
3162 .RI env.Dir( name ", [" directory ])
3163 This returns a Directory Node,
3164 an object that represents the specified directory
3167 can be a relative or absolute path.
3169 is an optional directory that will be used as the parent directory.
3172 is specified, the current script's directory is used as the parent.
3174 Directory Nodes can be used anywhere you
3175 would supply a string as a directory name
3176 to a Builder method or function.
3177 Directory Nodes have attributes and methods
3178 that are useful in many situations;
3179 see "File and Directory Nodes," below.
3181 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3183 .RI env.Dump([ key ])
3184 Returns a pretty printable representation of the environment.
3188 should be a string containing the name of the variable of interest.
3193 print env.Dump('CCCOM')
3197 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3207 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3210 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3215 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3217 .RI EnsurePythonVersion( major ", " minor )
3219 .RI env.EnsurePythonVersion( major ", " minor )
3220 Ensure that the Python version is at least
3223 print out an error message and exit SCons with a non-zero exit code if the
3224 actual Python version is not late enough.
3227 EnsurePythonVersion(2,2)
3230 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3232 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3234 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3235 Ensure that the SCons version is at least
3238 .IR major.minor.revision .
3243 print out an error message and exit SCons with a non-zero exit code if the
3244 actual SCons version is not late enough.
3247 EnsureSConsVersion(0,14)
3249 EnsureSConsVersion(0,96,90)
3252 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3254 .RI Environment([ key = value ", ...])"
3256 .RI env.Environment([ key = value ", ...])"
3257 Return a new construction environment
3258 initialized with the specified
3262 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3264 .RI Execute( action ", [" strfunction ", " varlist ])
3266 .RI env.Execute( action ", [" strfunction ", " varlist ])
3267 Executes an Action object.
3270 may be an Action object
3271 (see the section "Action Objects,"
3272 below, for a complete explanation of the arguments and behavior),
3273 or it may be a command-line string,
3275 or executable Python function,
3276 each of which will be converted
3277 into an Action object
3279 The exit value of the command
3280 or return value of the Python function
3283 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3287 .RI env.Exit([ value ])
3293 A default exit value of
3296 is used if no value is specified.
3298 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3302 .RI env.Export( vars )
3305 to export a list of variables from the current
3306 SConscript file to all other SConscript files.
3307 The exported variables are kept in a global collection,
3308 so subsequent calls to
3310 will over-write previous exports that have the same name.
3311 Multiple variable names can be passed to
3313 as separate arguments or as a list. A dictionary can be used to map
3314 variables to a different name when exported. Both local variables and
3315 global variables can be exported.
3320 # Make env available for all SConscript files to Import().
3324 # Make env and package available for all SConscript files:.
3325 Export("env", "package")
3327 # Make env and package available for all SConscript files:
3328 Export(["env", "package"])
3330 # Make env available using the name debug:.
3331 Export({"debug":env})
3337 function supports an
3339 argument that makes it easier to to export a variable or
3340 set of variables to a single SConscript file.
3341 See the description of the
3345 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3347 .RI File( name ", [" directory ])
3349 .RI env.File( name ", [" directory ])
3352 an object that represents the specified file
3355 can be a relative or absolute path.
3357 is an optional directory that will be used as the parent directory.
3359 File Nodes can be used anywhere you
3360 would supply a string as a file name
3361 to a Builder method or function.
3362 File Nodes have attributes and methods
3363 that are useful in many situations;
3364 see "File and Directory Nodes," below.
3366 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3368 .RI FindFile( file ", " dirs )
3370 .RI env.FindFile( file ", " dirs )
3373 in the path specified by
3376 may be a list of file names or a single file name. In addition to searching
3377 for files that exist in the filesytem, this function also searches for
3378 derived files that have not yet been built.
3381 foo = env.FindFile('foo', ['dir1', 'dir2'])
3384 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3386 .RI Flatten( sequence )
3388 .RI env.Flatten( sequence )
3389 Takes a sequence (that is, a Python list or tuple)
3390 that may contain nested sequences
3391 and returns a flattened list containing
3392 all of the individual elements in any sequence.
3393 This can be helpful for collecting
3394 the lists returned by calls to Builders;
3395 other Builders will automatically
3396 flatten lists specified as input,
3397 but direct Python manipulation of
3398 these lists does not:
3401 foo = Object('foo.c')
3402 bar = Object('bar.c')
3404 # Because `foo' and `bar' are lists returned by the Object() Builder,
3405 # `objects' will be a list containing nested lists:
3406 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3408 # Passing such a list to another Builder is all right because
3409 # the Builder will flatten the list automatically:
3410 Program(source = objects)
3412 # If you need to manipulate the list directly using Python, you need to
3413 # call Flatten() yourself, or otherwise handle nested lists:
3414 for object in Flatten(objects):
3418 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3420 .RI GetBuildPath( file ", [" ... ])
3422 .RI env.GetBuildPath( file ", [" ... ])
3425 path name (or names) for the specified
3433 Nodes or strings representing path names.
3435 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3439 .RI env.GetLaunchDir()
3440 Returns the absolute path name of the directory from which
3443 was initially invoked.
3444 This can be useful when using the
3449 options, which internally
3450 change to the directory in which the
3454 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3456 .RI GetOption( name )
3458 .RI env.GetOption( name )
3459 This function provides a way to query a select subset of the scons command line
3460 options from a SConscript file. See
3462 for a description of the options available.
3464 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3466 '\".RI GlobalBuilders( flag )
3470 '\"adds the names of the default builders
3471 '\"(Program, Library, etc.)
3472 '\"to the global name space
3473 '\"so they can be called without an explicit construction environment.
3474 '\"(This is the default.)
3478 '\"the names of the default builders are removed
3479 '\"from the global name space
3480 '\"so that an explicit construction environment is required
3481 '\"to call all builders.
3483 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3487 .RI env.Help( text )
3488 This specifies help text to be printed if the
3490 argument is given to
3494 is called multiple times, the text is appended together in the order
3499 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3501 .RI Ignore( target ", " dependency )
3503 .RI env.Ignore( target ", " dependency )
3504 The specified dependency file(s)
3505 will be ignored when deciding if
3506 the target file(s) need to be rebuilt.
3509 env.Ignore('foo', 'foo.c')
3510 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3517 .RI env.Import( vars )
3520 to import a list of variables into the current SConscript file. This
3521 will import variables that were exported with
3527 Variables exported by
3530 Multiple variable names can be passed to
3532 as separate arguments or as a list. The variable "*" can be used
3533 to import all variables.
3538 Import("env", "variable")
3539 Import(["env", "variable"])
3543 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3545 .RI Install( dir ", " source )
3547 .RI env.Install( dir ", " source )
3548 Installs one or more files in a destination directory.
3549 The file names remain the same.
3552 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3555 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3557 .RI InstallAs( target ", " source )
3559 .RI env.InstallAs( target ", " source )
3560 Installs one or more files as specific file names,
3561 allowing changing a file name as part of the
3563 It is an error if the target and source
3564 list different numbers of files.
3567 env.InstallAs(target = '/usr/local/bin/foo',
3568 source = 'foo_debug')
3569 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3570 source = ['libFOO.a', 'libBAR.a'])
3573 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3575 .RI Literal( string )
3577 .RI env.Literal( string )
3580 will be preserved as-is
3581 and not have construction variables expanded.
3583 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3585 .RI Local( targets )
3587 .RI env.Local( targets )
3590 will have copies made in the local tree,
3591 even if an already up-to-date copy
3592 exists in a repository.
3593 Returns a list of the target Node or Nodes.
3595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3597 .RI env.ParseConfig( command ", [" function ", " unique ])
3600 to modify the environment as specified by the output of
3604 expects the output of a typical
3608 and adds the options
3609 to the appropriate construction variables.
3611 duplicate values are not
3612 added to any construction variables;
3635 construction variables,
3639 option gets added to both the
3646 option gets added to the
3649 Any other strings not associated with options
3650 are assumed to be the names of libraries
3653 construction variable.
3655 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3657 .RI ParseDepends( filename ", [" must_exist ])
3659 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3660 Parses the contents of the specified
3662 as a list of dependencies in the style of
3666 and explicitly establishes all of the listed dependencies.
3675 argument may be set to a non-zero
3678 throw an exception and
3679 generate an error if the file does not exist,
3680 or is otherwise inaccessible.
3684 argument may be set to a non-zero
3687 thrown an exception and
3689 if the file contains dependency
3690 information for more than one target.
3691 This can provide a small sanity check
3692 for files intended to be generated
3693 by, for example, the
3696 which should typically only
3697 write dependency information for
3698 one output file into a corresponding
3704 and all of the files listed therein
3705 will be interpreted relative to
3706 the directory of the
3708 file which calls the
3712 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3715 A factory function that
3716 returns a Builder object
3717 to be used to fetch source files
3718 from the Perforce source code management system.
3719 The returned Builder
3720 is intended to be passed to the
3725 env.SourceCode('.', env.Perforce())
3728 Perforce uses a number of external
3729 environment variables for its operation.
3730 Consequently, this function adds the
3731 following variables from the user's external environment
3732 to the construction environment's
3745 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3747 .RI Platform( string )
3748 Returns a callable object
3749 that can be used to initialize
3750 a construction environment using the
3751 platform keyword of the Environment() method:
3754 env = Environment(platform = Platform('win32'))
3757 .RI env.Platform( string )
3758 Applies the callable object for the specified platform
3760 to the environment through which the method was called.
3763 env.Platform('posix')
3772 variables from the user's external environment
3773 to the construction environment's
3776 This is so that any executed commands
3777 that use sockets to connect with other systems
3778 (such as fetching source files from
3779 external CVS repository specifications like
3780 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3781 will work on Win32 systems.
3783 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3785 .RI Precious( target ", ...)"
3787 .RI env.Precious( target ", ...)"
3790 as precious so it is not deleted before it is rebuilt. Normally
3792 deletes a target before building it.
3793 Multiple targets can be passed in to a single call to
3796 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3798 .RI env.Prepend( key = val ", [...])"
3799 Appends the specified keyword arguments
3800 to the beginning of construction variables in the environment.
3801 If the Environment does not have
3802 the specified construction variable,
3803 it is simply added to the environment.
3804 If the values of the construction variable
3805 and the keyword argument are the same type,
3806 then the two values will be simply added together.
3807 Otherwise, the construction variable
3808 and the value of the keyword argument
3809 are both coerced to lists,
3810 and the lists are added together.
3811 (See also the Append method, above.)
3814 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3817 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3819 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3820 This appends new path elements to the given path in the
3821 specified external environment
3825 any particular path once (leaving the first one it encounters and
3826 ignoring the rest, to preserve path order),
3827 and to help assure this,
3828 will normalize all paths (using
3831 .BR os.path.normcase ).
3832 This can also handle the
3833 case where the given old path variable is a list instead of a
3834 string, in which case a list will be returned instead of a string.
3838 print 'before:',env['ENV']['INCLUDE']
3839 include_path = '/foo/bar:/foo'
3840 env.PrependENVPath('INCLUDE', include_path)
3841 print 'after:',env['ENV']['INCLUDE']
3845 after: /foo/bar:/foo:/biz
3848 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3850 .RI env.PrependUnique( key = val ", [...])"
3851 Appends the specified keyword arguments
3852 to the beginning of construction variables in the environment.
3853 If the Environment does not have
3854 the specified construction variable,
3855 it is simply added to the environment.
3856 If the construction variable being appended to is a list,
3857 then any value(s) that already exist in the
3858 construction variable will
3860 be added again to the list.
3863 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3866 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3869 A factory function that
3870 returns a Builder object
3871 to be used to fetch source files
3873 The returned Builder
3874 is intended to be passed to the
3879 env.SourceCode('.', env.RCS())
3884 will fetch source files
3885 from RCS subdirectories automatically,
3887 as demonstrated in the above example
3888 should only be necessary if
3889 you are fetching from
3892 directory as the source files,
3893 or if you need to explicitly specify RCS
3894 for a specific subdirectory.
3896 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3898 .RI env.Replace( key = val ", [...])"
3899 Replaces construction variables in the Environment
3900 with the specified keyword arguments.
3903 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3906 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3908 .RI Repository( directory )
3910 .RI env.Repository( directory )
3913 is a repository to be searched for files.
3917 and each one adds to the list of
3918 repositories that will be searched.
3922 a repository is a copy of the source tree,
3923 from the top-level directory on down,
3925 both source files and derived files
3926 that can be used to build targets in
3927 the local source tree.
3928 The canonical example would be an
3929 official source tree maintained by an integrator.
3930 If the repository contains derived files,
3931 then the derived files should have been built using
3933 so that the repository contains the necessary
3934 signature information to allow
3936 to figure out when it is appropriate to
3937 use the repository copy of a derived file,
3938 instead of building one locally.
3940 Note that if an up-to-date derived file
3941 already exists in a repository,
3945 make a copy in the local directory tree.
3946 In order to guarantee that a local copy
3952 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3957 what variable(s) to use as the return value(s) of the current SConscript
3958 file. These variables will be returned to the "calling" SConscript file
3959 as the return value(s) of
3961 Multiple variable names should be passed to
3967 Return(["foo", "bar"])
3970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3972 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3974 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3975 Creates a Scanner object for
3978 See the section "Scanner Objects,"
3979 below, for a complete explanation of the arguments and behavior.
3981 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3984 A factory function that
3985 returns a Builder object
3986 to be used to fetch source files
3988 The returned Builder
3989 is intended to be passed to the
3994 env.SourceCode('.', env.SCCS())
3999 will fetch source files
4000 from SCCS subdirectories automatically,
4002 as demonstrated in the above example
4003 should only be necessary if
4004 you are fetching from
4007 directory as the source files,
4008 or if you need to explicitly specify SCCS
4009 for a specific subdirectory.
4011 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4013 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
4015 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
4017 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
4019 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
4023 one or more subsidiary SConscript (configuration) files.
4024 There are two ways to call the
4028 The first way you can call
4030 is to explicitly specify one or more
4032 as the first argument.
4033 A single script may be specified as a string;
4034 multiple scripts must be specified as a list
4035 (either explicitly or as created by
4039 The second way you can call
4041 is to specify a list of (sub)directory names
4048 execute a subsidiary configuration file named
4050 in each of the specified directories.
4051 You may specify a name other than
4053 by supplying an optional
4059 argument provides a list of variable names or a dictionary of
4060 named values to export to the
4062 These variables are locally exported only to the specified
4064 and do not affect the
4065 global pool of variables used by
4069 '\"If multiple dirs are provided,
4070 '\"each script gets a fresh export.
4075 function to import the variables.
4079 argument specifies that all of the target files
4080 (for example, object files and executables)
4081 that would normally be built in the subdirectory in which
4083 resides should actually
4087 is interpreted relative to the directory
4088 of the calling SConscript file.
4092 argument specifies that the
4093 source files from which
4094 the target files should be built
4098 is interpreted relative to the directory
4099 of the calling SConscript file.
4103 will link or copy (depending on the platform)
4104 all the source files into the build directory.
4105 This behavior may be disabled by
4106 setting the optional
4109 (it is set to 1 by default),
4112 will refer directly to
4113 the source files in their source directory
4114 when building target files.
4117 is usually safe, and always more efficient
4120 but it may cause build problems in certain end-cases,
4121 such as compiling from source files that
4122 are generated by the build.)
4124 Any variables returned by
4128 will be returned by the call to
4134 SConscript('subdir/SConscript')
4135 foo = SConscript('sub/SConscript', exports='env')
4136 SConscript('dir/SConscript', exports=['env', 'variable'])
4137 SConscript('src/SConscript', build_dir='build', duplicate=0)
4138 SConscript('bld/SConscript', src_dir='src', exports='env variable')
4139 SConscript(dirs=['sub1', 'sub2'])
4140 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
4143 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4145 .RI SConscriptChdir( value )
4147 .RI env.SConscriptChdir( value )
4150 changes its working directory
4151 to the directory in which each
4152 subsidiary SConscript file lives.
4153 This behavior may be disabled
4154 by specifying either:
4158 env.SConscriptChdir(0)
4163 will stay in the top-level directory
4164 while reading all SConscript files.
4165 (This may be necessary when building from repositories,
4166 when all the directories in which SConscript files may be found
4167 don't necessarily exist locally.)
4169 You may enable and disable
4170 this ability by calling
4177 SConscript('foo/SConscript') # will not chdir to foo
4178 env.SConscriptChdir(1)
4179 SConscript('bar/SConscript') # will chdir to bar
4182 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4184 .RI SConsignFile([ file , dbm_module ])
4186 .RI env.SConsignFile([ file , dbm_module ])
4189 to store all file signatures
4190 in the specified database
4197 (The actual file name(s) stored on disk
4198 may have an appropriated suffix appended
4203 is not an absolute path name,
4204 the file is placed in the same directory as the top-level
4214 will store file signatures
4217 file in each directory,
4218 not in one global database file.
4219 (This was the default behavior
4220 prior to SCons 0.96.91 and 0.97.)
4224 argument can be used to specify
4225 which Python database module
4226 The default is to use a custom
4228 module that uses pickled
4229 Python data structures,
4230 and which works on all Python versions from 1.5.2 on.
4235 # Explicitly stores signatures in ".sconsign.dblite"
4236 # in the top-level SConstruct directory (the
4237 # default behavior).
4240 # Stores signatures in the file "etc/scons-signatures"
4241 # relative to the top-level SConstruct directory.
4242 SConsignFile("etc/scons-signatures")
4244 # Stores signatures in the specified absolute file name.
4245 SConsignFile("/home/me/SCons/signatures")
4247 # Stores signatures in a separate .sconsign file
4248 # in each directory.
4252 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4254 .RI env.SetDefault(key = val ", [...])"
4255 Sets construction variables to default values specified with the keyword
4256 arguments if (and only if) the variables are not already set.
4257 The following statements are equivalent:
4260 env.SetDefault(FOO = 'foo')
4262 if not env.has_key('FOO'): env['FOO'] = 'foo'
4265 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4267 .RI SetOption( name ", " value )
4269 .RI env.SetOption( name ", " value )
4270 This function provides a way to set a select subset of the scons command
4271 line options from a SConscript file. The options supported are:
4273 which corresponds to -c, --clean, and --remove;
4276 corresponds to --duplicate;
4278 which corresponds to --implicit-cache;
4280 which corresponds to --max-drift;
4282 which corresponds to -j and --jobs.
4283 See the documentation for the
4284 corresponding command line object for information about each specific
4288 SetOption('max_drift', 1)
4291 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4293 .RI SideEffect( side_effect ", " target )
4295 .RI env.SideEffect( side_effect ", " target )
4298 as a side effect of building
4304 can be a list, a file name, or a node.
4305 A side effect is a target that is created
4306 as a side effect of building other targets.
4307 For example, a Windows PDB
4308 file is created as a side effect of building the .obj
4309 files for a static library.
4310 If a target is a side effect of multiple build commands,
4312 will ensure that only one set of commands
4313 is executed at a time.
4314 Consequently, you only need to use this method
4315 for side-effect targets that are built as a result of
4316 multiple build commands.
4318 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4320 .RI SourceCode( entries ", " builder )
4322 .RI env.SourceCode( entries ", " builder )
4323 Arrange for non-existent source files to
4324 be fetched from a source code management system
4329 may be a Node, string or list of both,
4330 and may represent either individual
4331 source files or directories in which
4332 source files can be found.
4334 For any non-existent source files,
4336 will search up the directory tree
4346 will not use a builder to fetch
4347 source files for the specified
4351 builder has been specified
4352 for a directory higher up the tree.
4356 fetch files from SCCS or RCS subdirectories
4357 without explicit configuration.
4358 This takes some extra processing time
4359 to search for the necessary
4360 source code management files on disk.
4361 You can avoid these extra searches
4362 and speed up your build a little
4363 by disabling these searches as follows:
4366 env.SourceCode('.', None)
4370 Note that if the specified
4372 is one you create by hand,
4373 it must have an associated
4374 construction environment to use
4375 when fetching a source file.
4378 provides a set of canned factory
4379 functions that return appropriate
4380 Builders for various popular
4381 source code management systems.
4382 Canonical examples of invocation include:
4385 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4386 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4387 env.SourceCode('/', env.RCS())
4388 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4389 env.SourceCode('no_source.c', None)
4391 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4393 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4395 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
4396 Performs construction variable interpolation
4397 on the specified string argument.
4400 leading or trailing white space will
4401 be removed from the result.
4402 and all sequences of white space
4403 will be compressed to a single space character.
4408 character sequences will be stripped from the returned string,
4411 argument may be set to
4413 if you want to preserve white space and
4418 argument may be set to
4420 if you want to strip
4421 all characters between
4427 (as is done for signature calculation).
4434 must be set to lists of
4435 target and source nodes, respectively,
4442 to be available for expansion.
4443 This is usually necessary if you are
4446 from within a Python function used
4450 all returned values are converted
4451 to their string representation.
4455 may specify a conversion function
4456 that will be used in place of
4458 For example, if you want Python objects
4459 (including SCons Nodes)
4460 to be returned as Python objects,
4461 you can use the Python
4463 idiom to pass in an unnamed function
4464 that simply returns its unconverted argument.
4467 print env.subst("The C compiler is: $CC")
4469 def compile(target, source, env):
4470 sourceDir = env.subst("${SOURCE.srcdir}",
4474 source_nodes = env.subst('$EXPAND_TO_NODELIST',
4478 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4480 '\".RI Subversion( repository ", " module )
4481 '\"A factory function that
4482 '\"returns a Builder object
4483 '\"to be used to fetch source files
4484 '\"from the specified Subversion
4486 '\"The returned Builder
4487 '\"is intended to be passed to the
4491 '\"The optional specified
4493 '\"will be added to the beginning
4494 '\"of all repository path names;
4495 '\"this can be used, in essence,
4496 '\"to strip initial directory names
4497 '\"from the repository path names,
4498 '\"so that you only have to
4499 '\"replicate part of the repository
4500 '\"directory hierarchy in your
4501 '\"local build directory:
4504 '\"# Will fetch foo/bar/src.c
4505 '\"# from /usr/local/Subversion/foo/bar/src.c.
4506 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4508 '\"# Will fetch bar/src.c
4509 '\"# from /usr/local/Subversion/foo/bar/src.c.
4510 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4512 '\"# Will fetch src.c
4513 '\"# from /usr/local/Subversion/foo/bar/src.c.
4514 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4517 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4519 .RI SourceSignatures( type )
4521 .RI env.SourceSignatures( type )
4522 This function tells SCons what type of signature to use for source files:
4526 If the environment method is used,
4527 the specified type of source signature
4528 is only used when deciding whether targets
4529 built with that environment are up-to-date or must be rebuilt.
4530 If the global function is used,
4531 the specified type of source signature becomes the default
4532 used for all decisions
4533 about whether targets are up-to-date.
4535 "MD5" means the signature of a source file
4536 is the MD5 checksum of its contents.
4537 "timestamp" means the signature of a source file
4538 is its timestamp (modification time).
4539 There is no different between the two behaviors
4543 "MD5" signatures take longer to compute,
4544 but are more accurate than "timestamp" signatures.
4545 The default is "MD5".
4547 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4551 .RI env.Split( arg )
4552 Returns a list of file names or other objects.
4554 it will be split on strings of white-space characters
4556 making it easier to write long lists of file names.
4557 If arg is already a list,
4558 the list will be returned untouched.
4559 If arg is any other type of object,
4560 it will be returned as a list
4561 containing just the object.
4564 files = Split("f1.c f2.c f3.c")
4565 files = env.Split("f4.c f5.c f6.c")
4573 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4575 .RI TargetSignatures( type )
4577 .RI env.TargetSignatures( type )
4578 This function tells SCons what type of signatures to use
4583 If the environment method is used,
4584 the specified type of signature is only used
4585 for targets built with that environment.
4586 If the global function is used,
4587 the specified type of signature becomes the default
4588 used for all target files that
4589 don't have an explicit target signature type
4590 specified for their environments.
4592 "build" means the signature of a target file
4593 is made by concatenating all of the
4594 signatures of all its source files.
4595 "content" means the signature of a target
4596 file is an MD5 checksum of its contents.
4597 "build" signatures are usually faster to compute,
4598 but "content" signatures can prevent unnecessary rebuilds
4599 when a target file is rebuilt to the exact same contents
4600 as the previous build.
4601 The default is "build".
4603 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4605 .RI Tool( string [, toolpath ", " **kw ])
4606 Returns a callable object
4607 that can be used to initialize
4608 a construction environment using the
4609 tools keyword of the Environment() method.
4610 The object may be called with a construction
4611 environment as an argument,
4612 in which case the object will
4613 add the necessary variables
4614 to the construction environment
4615 and the name of the tool will be added to the
4617 construction variable.
4619 Additional keyword arguments are passed to the tool's
4624 env = Environment(tools = [ Tool('msvc') ])
4628 t(env) # adds 'msvc' to the TOOLS variable
4629 u = Tool('opengl', toolpath = ['tools'])
4630 u(env) # adds 'opengl' to the TOOLS variable
4633 .RI env.Tool( string [, toolpath ", " **kw ])
4634 Applies the callable object for the specified tool
4636 to the environment through which the method was called.
4638 Additional keyword arguments are passed to the tool's
4644 env.Tool('opengl', toolpath = ['build/tools'])
4647 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4651 .RI env.Value( value )
4652 Returns a Node object representing the specified Python value. Value
4653 nodes can be used as dependencies of targets. If the result of
4656 changes between SCons runs, any targets depending on
4658 will be rebuilt. When using timestamp source signatures, Value nodes'
4659 timestamps are equal to the system time when the node is created.
4662 def create(target, source, env):
4663 f = open(str(target[0]), 'wb')
4664 f.write('prefix=' + source[0].get_contents())
4666 prefix = ARGUMENTS.get('prefix', '/usr/local')
4668 env['BUILDERS']['Config'] = Builder(action = create)
4669 env.Config(target = 'package-config', source = Value(prefix))
4672 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4674 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4676 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4678 Searches for the specified executable
4680 returning the full path name to the program
4682 and returning None if not.
4683 Searches the specified
4685 the value of the calling environment's PATH
4686 (env['ENV']['PATH']),
4687 or the user's current external PATH
4688 (os.environ['PATH'])
4690 On Win32 systems, searches for executable
4691 programs with any of the file extensions
4692 listed in the specified
4694 the calling environment's PATHEXT
4695 (env['ENV']['PATHEXT'])
4696 or the user's current PATHEXT
4697 (os.environ['PATHEXT'])
4705 .SS SConscript Variables
4706 In addition to the global functions and methods,
4708 supports a number of Python variables
4709 that can be used in SConscript files
4710 to affect how you want the build to be performed.
4711 These variables may be accessed from custom Python modules that you
4712 import into an SConscript file by adding the following
4713 to the Python module:
4716 from SCons.Script import *
4719 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4724 arguments specified on the command line.
4725 Each element in the list is a tuple
4727 .RI ( keyword , value )
4733 elements of the tuple
4735 subscripting for element
4739 of the tuple, respectively.
4742 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4743 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4744 third_tuple = ARGLIST[2]
4745 print "third keyword, value =", third_tuple[0], third_tuple[1]
4746 for key, value in ARGLIST:
4747 # process key and value
4750 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4753 A dictionary of all the
4755 arguments specified on the command line.
4756 The dictionary is not in order,
4757 and if a given keyword has
4758 more than one value assigned to it
4759 on the command line,
4760 the last (right-most) value is
4766 if ARGUMENTS.get('debug', 0):
4767 env = Environment(CCFLAGS = '-g')
4772 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4775 A list of the targets which
4777 will actually try to build,
4778 regardless of whether they were specified on
4779 the command line or via the
4782 The elements of this list may be strings
4784 nodes, so you should run the list through the Python
4786 function to make sure any Node path names
4787 are converted to strings.
4789 Because this list may be taken from the
4790 list of targets specified using the
4793 the contents of the list may change
4794 on each successive call to
4799 for additional information.
4802 if 'foo' in BUILD_TARGETS:
4803 print "Don't forget to test the `foo' program!"
4804 if 'special/program' in BUILD_TARGETS:
4805 SConscript('special')
4810 list only contains targets expected listed
4811 on the command line or via calls to the
4816 contain all dependent targets that will be built as
4817 a result of making the sure the explicitly-specified
4818 targets are up to date.
4820 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4822 COMMAND_LINE_TARGETS
4823 A list of the targets explicitly specified on
4825 If there are no targets specified on the command line,
4827 This can be used, for example,
4828 to take specific actions only
4829 when a certain target or targets
4830 is explicitly being built:
4833 if 'foo' in COMMAND_LINE_TARGETS:
4834 print "Don't forget to test the `foo' program!"
4835 if 'special/program' in COMMAND_LINE_TARGETS:
4836 SConscript('special')
4839 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4842 A list of the target
4844 that have been specified using the
4847 The elements of the list are nodes,
4848 so you need to run them through the Python
4850 function to get at the path name for each Node.
4853 print str(DEFAULT_TARGETS[0])
4854 if 'foo' in map(str, DEFAULT_TARGETS):
4855 print "Don't forget to test the `foo' program!"
4860 list change on on each successive call to the
4865 print map(str, DEFAULT_TARGETS) # originally []
4867 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4869 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4871 print map(str, DEFAULT_TARGETS) # back to []
4874 Consequently, be sure to use
4876 only after you've made all of your
4879 or else simply be careful of the order
4880 of these statements in your SConscript files
4881 so that you don't look for a specific
4882 default target before it's actually been added to the list.
4884 .SS Construction Variables
4885 .\" XXX From Gary Ruben, 23 April 2002:
4886 .\" I think it would be good to have an example with each construction
4887 .\" variable description in the documentation.
4889 .\" CC The C compiler
4890 .\" Example: env["CC"] = "c68x"
4891 .\" Default: env["CC"] = "cc"
4893 .\" CCCOM The command line ...
4895 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4896 .\" env["CC"] = "c68x"
4897 .\" env["CFLAGS"] = "-ps -qq -mr"
4898 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4900 .\" (I dunno what this is ;-)
4901 A construction environment has an associated dictionary of
4902 .I construction variables
4903 that are used by built-in or user-supplied build rules.
4904 Construction variables must follow the same rules for
4906 the initial character must be an underscore or letter,
4907 followed by any number of underscores, letters, or digits.
4909 A number of useful construction variables are automatically defined by
4910 scons for each supported platform, and additional construction variables
4911 can be defined by the user. The following is a list of the automatically
4912 defined construction variables:
4915 The static library archiver.
4918 The command line used to generate a static library from object files.
4921 The string displayed when an object file
4922 is generated from an assembly-language source file.
4923 If this is not set, then $ARCOM (the command line) is displayed.
4926 env = Environment(ARCOMSTR = "Archiving $TARGET")
4930 General options passed to the static library archiver.
4936 The command line used to generate an object file
4937 from an assembly-language source file.
4940 The string displayed when an object file
4941 is generated from an assembly-language source file.
4942 If this is not set, then $ASCOM (the command line) is displayed.
4945 env = Environment(ASCOMSTR = "Assembling $TARGET")
4949 General options passed to the assembler.
4952 The command line used to assemble an assembly-language
4953 source file into an object file
4954 after first running the file through the C preprocessor.
4955 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4956 are included on this command line.
4959 The string displayed when an object file
4960 is generated from an assembly-language source file
4961 after first running the file through the C preprocessor.
4962 If this is not set, then $ASPPCOM (the command line) is displayed.
4965 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4969 General options when an assembling an assembly-language
4970 source file into an object file
4971 after first running the file through the C preprocessor.
4972 The default is to use the value of $ASFLAGS.
4975 The bibliography generator for the TeX formatter and typesetter and the
4976 LaTeX structured formatter and typesetter.
4979 The command line used to call the bibliography generator for the
4980 TeX formatter and typesetter and the LaTeX structured formatter and
4984 The string displayed when generating a bibliography
4986 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4989 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4994 General options passed to the bibliography generator for the TeX formatter
4995 and typesetter and the LaTeX structured formatter and typesetter.
4998 The BitKeeper executable.
5001 The command line for
5002 fetching source files using BitKeeper.
5005 The string displayed when fetching
5006 a source file using BitKeeper.
5007 If this is not set, then $BITKEEPERCOM
5008 (the command line) is displayed.
5011 The command ($BITKEEPER) and subcommand
5012 for fetching source files using BitKeeper.
5014 .IP BITKEEPERGETFLAGS
5015 Options that are passed to the BitKeeper
5020 A dictionary mapping the names of the builders
5021 available through this environment
5022 to underlying Builder objects.
5024 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
5025 are available by default.
5026 If you initialize this variable when an
5027 Environment is created:
5030 env = Environment(BUILDERS = {'NewBuilder' : foo})
5033 the default Builders will no longer be available.
5034 To use a new Builder object in addition to the default Builders,
5035 add your new Builder object like this:
5039 env.Append(BUILDERS = {'NewBuilder' : foo})
5046 env['BUILDERS]['NewBuilder'] = foo
5053 The command line used to compile a C source file to a (static) object file.
5054 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
5055 are included on this command line.
5058 The string displayed when a C source file
5059 is compiled to a (static) object file.
5060 If this is not set, then $CCCOM (the command line) is displayed.
5063 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
5067 General options that are passed to the C compiler.
5070 The suffix for C source files.
5071 This is used by the internal CFile builder
5072 when generating C files from Lex (.l) or YACC (.y) input files.
5073 The default suffix, of course, is
5076 On case-insensitive systems (like Win32),
5083 The version number of the C compiler.
5084 This may or may not be set,
5085 depending on the specific C compiler being used.
5088 A function used to produce variables like $_CPPINCFLAGS. It takes
5090 arguments: a prefix to concatenate onto each element, a list of
5091 elements, a suffix to concatenate onto each element, an environment
5092 for variable interpolation, and an optional function that will be
5093 called to transform the list before concatenation.
5096 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
5100 The name of the directory in which
5101 Configure context test files are written.
5104 in the top-level directory
5110 The name of the Configure context log file.
5113 in the top-level directory
5119 A platform independent specification of C preprocessor definitions.
5120 The definitions will be added to command lines
5121 through the automatically-generated
5122 $_CPPDEFFLAGS construction variable (see below),
5123 which is constructed according to
5124 the type of value of $CPPDEFINES:
5127 If $CPPDEFINES is a string,
5129 $CPPDEFPREFIX and $CPPDEFSUFFIX
5130 construction variables
5131 will be added to the beginning and end.
5134 # Will add -Dxyz to POSIX compiler command lines,
5135 # and /Dxyz to Microsoft Visual C++ command lines.
5136 env = Environment(CPPDEFINES='xyz')
5140 If $CPPDEFINES is a list,
5142 $CPPDEFPREFIX and $CPPDEFSUFFIX
5143 construction variables
5144 will be appended to the beginning and end
5145 of each element in the list.
5146 If any element is a list or tuple,
5147 then the first item is the name being
5148 defined and the second item is its value:
5151 # Will add -DB=2 -DA to POSIX compiler command lines,
5152 # and /DB=2 /DA to Microsoft Visual C++ command lines.
5153 env = Environment(CPPDEFINES=[('B', 2), 'A'])
5157 If $CPPDEFINES is a dictionary,
5159 $CPPDEFPREFIX and $CPPDEFSUFFIX
5160 construction variables
5161 will be appended to the beginning and end
5162 of each item from the dictionary.
5163 The key of each dictionary item
5164 is a name being defined
5165 to the dictionary item's corresponding value;
5168 then the name is defined without an explicit value.
5169 Note that the resulting flags are sorted by keyword
5170 to ensure that the order of the options on the
5171 command line is consistent each time
5176 # Will add -DA -DB=2 to POSIX compiler command lines,
5177 # and /DA /DB=2 to Microsoft Visual C++ command lines.
5178 env = Environment(CPPDEFINES={'B':2, 'A':None})
5182 An automatically-generated construction variable
5183 containing the C preprocessor command-line options
5185 The value of $_CPPDEFFLAGS is created
5186 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
5187 to the beginning and end
5188 of each directory in $CPPDEFINES.
5191 The prefix used to specify preprocessor definitions
5192 on the C compiler command line.
5193 This will be appended to the beginning of each definition
5194 in the $CPPDEFINES construction variable
5195 when the $_CPPDEFFLAGS variable is automatically generated.
5198 The suffix used to specify preprocessor definitions
5199 on the C compiler command line.
5200 This will be appended to the end of each definition
5201 in the $CPPDEFINES construction variable
5202 when the $_CPPDEFFLAGS variable is automatically generated.
5205 User-specified C preprocessor options.
5206 These will be included in any command that uses the C preprocessor,
5207 including not just compilation of C and C++ source files
5208 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
5209 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
5210 $F77PPCOM and $SHF77PPCOM command lines
5211 used to compile a Fortran source file,
5212 and the $ASPPCOM command line
5213 used to assemble an assembly language source file,
5214 after first running each file through the C preprocessor.
5215 Note that this variable does
5219 (or similar) include search path options
5220 that scons generates automatically from $CPPPATH.
5224 for the variable that expands to those options.
5227 An automatically-generated construction variable
5228 containing the C preprocessor command-line options
5229 for specifying directories to be searched for include files.
5230 The value of $_CPPINCFLAGS is created
5231 by appending $INCPREFIX and $INCSUFFIX
5232 to the beginning and end
5233 of each directory in $CPPPATH.
5236 The list of directories that the C preprocessor will search for include
5237 directories. The C/C++ implicit dependency scanner will search these
5238 directories for include files. Don't explicitly put include directory
5239 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
5240 and the directories will not be searched by the dependency scanner. Note:
5241 directory names in CPPPATH will be looked-up relative to the SConscript
5242 directory when they are used in a command. To force
5244 to look-up a directory relative to the root of the source tree use #:
5247 env = Environment(CPPPATH='#/include')
5251 The directory look-up can also be forced using the
5256 include = Dir('include')
5257 env = Environment(CPPPATH=include)
5261 The directory list will be added to command lines
5262 through the automatically-generated
5264 construction variable,
5265 which is constructed by
5266 appending the values of the
5267 $INCPREFIX and $INCSUFFIX
5268 construction variables
5269 to the beginning and end
5270 of each directory in $CPPPATH.
5271 Any command lines you define that need
5272 the CPPPATH directory list should
5273 include $_CPPINCFLAGS:
5276 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5280 The list of suffixes of files that will be scanned
5281 for C preprocessor implicit dependencies
5283 The default list is:
5286 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5287 ".h", ".H", ".hxx", ".hpp", ".hh",
5288 ".F", ".fpp", ".FPP",
5290 ".S", ".spp", ".SPP"]
5297 Options that are passed to the CVS checkout subcommand.
5300 The command line used to
5301 fetch source files from a CVS repository.
5304 The string displayed when fetching
5305 a source file from a CVS repository.
5306 If this is not set, then $CVSCOM
5307 (the command line) is displayed.
5310 General options that are passed to CVS.
5311 By default, this is set to
5313 to specify from where the files must be fetched.
5316 The path to the CVS repository.
5317 This is referenced in the default
5324 The suffix for C++ source files.
5325 This is used by the internal CXXFile builder
5326 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
5327 The default suffix is
5329 SCons also treats files with the suffixes
5338 suffixes as Objective C++ files.
5339 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5346 The command line used to compile a C++ source file to an object file.
5347 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
5348 are included on this command line.
5351 The string displayed when a C++ source file
5352 is compiled to a (static) object file.
5353 If this is not set, then $CXXCOM (the command line) is displayed.
5356 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5360 General options that are passed to the C++ compiler.
5361 By default, this includes the value of $CCFLAGS,
5362 so that setting $CCFLAGS affects both C and C++ compilation.
5363 If you want to add C++-specific flags,
5364 you must set or override the value of $CXXFLAGS.
5367 The version number of the C++ compiler.
5368 This may or may not be set,
5369 depending on the specific C++ compiler being used.
5372 A function that converts a string
5373 into a Dir instance relative to the target being built.
5376 A function that converts a list of strings
5377 into a list of Dir instances relative to the target being built.
5380 The list of suffixes of files that will be scanned
5381 for imported D package files.
5382 The default list is:
5389 The TeX DVI file to PDF file converter.
5392 General options passed to the TeX DVI file to PDF file converter.
5395 The command line used to convert TeX DVI files into a PDF file.
5398 The string displayed when a TeX DVI file
5399 is converted into a PDF file.
5400 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5403 The TeX DVI file to PostScript converter.
5406 General options passed to the TeX DVI file to PostScript converter.
5409 A dictionary of environment variables
5410 to use when invoking commands. When ENV is used in a command all list
5411 values will be joined using the path separator and any other non-string
5412 values will simply be coerced to a string.
5413 Note that, by default,
5417 propagate the environment in force when you
5420 to the commands used to build target files.
5421 This is so that builds will be guaranteed
5422 repeatable regardless of the environment
5423 variables set at the time
5427 If you want to propagate your
5428 environment variables
5429 to the commands executed
5430 to build target files,
5431 you must do so explicitly:
5435 env = Environment(ENV = os.environ)
5439 Note that you can choose only to propagate
5440 certain environment variables.
5444 environment variable,
5447 uses the same utilities
5448 as the invoking shell (or other process):
5453 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5457 A function that will be called to escape shell special characters in
5458 command lines. The function should take one argument: the command line
5459 string to escape; and should return the escaped command line.
5462 The Fortran 77 compiler.
5463 You should normally set the $FORTRAN variable,
5464 which specifies the default Fortran compiler
5465 for all Fortran versions.
5466 You only need to set $F77 if you need to use a specific compiler
5467 or compiler version for Fortran 77 files.
5470 The command line used to compile a Fortran 77 source file to an object file.
5471 You only need to set $F77COM if you need to use a specific
5472 command line for Fortran 77 files.
5473 You should normally set the $FORTRANCOM variable,
5474 which specifies the default command line
5475 for all Fortran versions.
5478 The string displayed when a Fortran 77 source file
5479 is compiled to an object file.
5480 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5483 General user-specified options that are passed to the Fortran 77 compiler.
5484 Note that this variable does
5488 (or similar) include search path options
5489 that scons generates automatically from $F77PATH.
5493 for the variable that expands to those options.
5494 You only need to set $F77FLAGS if you need to define specific
5495 user options for Fortran 77 files.
5496 You should normally set the $FORTRANFLAGS variable,
5497 which specifies the user-specified options
5498 passed to the default Fortran compiler
5499 for all Fortran versions.
5502 An automatically-generated construction variable
5503 containing the Fortran 77 compiler command-line options
5504 for specifying directories to be searched for include files.
5505 The value of $_F77INCFLAGS is created
5506 by appending $INCPREFIX and $INCSUFFIX
5507 to the beginning and end
5508 of each directory in $F77PATH.
5511 The list of directories that the Fortran 77 compiler will search for include
5512 directories. The implicit dependency scanner will search these
5513 directories for include files. Don't explicitly put include directory
5514 arguments in $F77FLAGS because the result will be non-portable
5515 and the directories will not be searched by the dependency scanner. Note:
5516 directory names in $F77PATH will be looked-up relative to the SConscript
5517 directory when they are used in a command. To force
5519 to look-up a directory relative to the root of the source tree use #:
5520 You only need to set $F77PATH if you need to define a specific
5521 include path for Fortran 77 files.
5522 You should normally set the $FORTRANPATH variable,
5523 which specifies the include path
5524 for the default Fortran compiler
5525 for all Fortran versions.
5528 env = Environment(F77PATH='#/include')
5532 The directory look-up can also be forced using the
5537 include = Dir('include')
5538 env = Environment(F77PATH=include)
5542 The directory list will be added to command lines
5543 through the automatically-generated
5545 construction variable,
5546 which is constructed by
5547 appending the values of the
5548 $INCPREFIX and $INCSUFFIX
5549 construction variables
5550 to the beginning and end
5551 of each directory in $F77PATH.
5552 Any command lines you define that need
5553 the F77PATH directory list should
5554 include $_F77INCFLAGS:
5557 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5561 The command line used to compile a Fortran 77 source file to an object file
5562 after first running the file through the C preprocessor.
5563 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5564 are included on this command line.
5565 You only need to set $F77PPCOM if you need to use a specific
5566 C-preprocessor command line for Fortran 77 files.
5567 You should normally set the $FORTRANPPCOM variable,
5568 which specifies the default C-preprocessor command line
5569 for all Fortran versions.
5572 The Fortran 90 compiler.
5573 You should normally set the $FORTRAN variable,
5574 which specifies the default Fortran compiler
5575 for all Fortran versions.
5576 You only need to set $F90 if you need to use a specific compiler
5577 or compiler version for Fortran 90 files.
5580 The command line used to compile a Fortran 90 source file to an object file.
5581 You only need to set $F90COM if you need to use a specific
5582 command line for Fortran 90 files.
5583 You should normally set the $FORTRANCOM variable,
5584 which specifies the default command line
5585 for all Fortran versions.
5588 The string displayed when a Fortran 90 source file
5589 is compiled to an object file.
5590 If this is not set, then $F90COM or $FORTRANCOM
5591 (the command line) is displayed.
5594 General user-specified options that are passed to the Fortran 90 compiler.
5595 Note that this variable does
5599 (or similar) include search path options
5600 that scons generates automatically from $F90PATH.
5604 for the variable that expands to those options.
5605 You only need to set $F90FLAGS if you need to define specific
5606 user options for Fortran 90 files.
5607 You should normally set the $FORTRANFLAGS variable,
5608 which specifies the user-specified options
5609 passed to the default Fortran compiler
5610 for all Fortran versions.
5613 An automatically-generated construction variable
5614 containing the Fortran 90 compiler command-line options
5615 for specifying directories to be searched for include files.
5616 The value of $_F90INCFLAGS is created
5617 by appending $INCPREFIX and $INCSUFFIX
5618 to the beginning and end
5619 of each directory in $F90PATH.
5622 The list of directories that the Fortran 90 compiler will search for include
5623 directories. The implicit dependency scanner will search these
5624 directories for include files. Don't explicitly put include directory
5625 arguments in $F90FLAGS because the result will be non-portable
5626 and the directories will not be searched by the dependency scanner. Note:
5627 directory names in $F90PATH will be looked-up relative to the SConscript
5628 directory when they are used in a command. To force
5630 to look-up a directory relative to the root of the source tree use #:
5631 You only need to set $F90PATH if you need to define a specific
5632 include path for Fortran 90 files.
5633 You should normally set the $FORTRANPATH variable,
5634 which specifies the include path
5635 for the default Fortran compiler
5636 for all Fortran versions.
5639 env = Environment(F90PATH='#/include')
5643 The directory look-up can also be forced using the
5648 include = Dir('include')
5649 env = Environment(F90PATH=include)
5653 The directory list will be added to command lines
5654 through the automatically-generated
5656 construction variable,
5657 which is constructed by
5658 appending the values of the
5659 $INCPREFIX and $INCSUFFIX
5660 construction variables
5661 to the beginning and end
5662 of each directory in $F90PATH.
5663 Any command lines you define that need
5664 the F90PATH directory list should
5665 include $_F90INCFLAGS:
5668 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5672 The command line used to compile a Fortran 90 source file to an object file
5673 after first running the file through the C preprocessor.
5674 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5675 are included on this command line.
5676 You only need to set $F90PPCOM if you need to use a specific
5677 C-preprocessor command line for Fortran 90 files.
5678 You should normally set the $FORTRANPPCOM variable,
5679 which specifies the default C-preprocessor command line
5680 for all Fortran versions.
5683 The Fortran 95 compiler.
5684 You should normally set the $FORTRAN variable,
5685 which specifies the default Fortran compiler
5686 for all Fortran versions.
5687 You only need to set $F95 if you need to use a specific compiler
5688 or compiler version for Fortran 95 files.
5691 The command line used to compile a Fortran 95 source file to an object file.
5692 You only need to set $F95COM if you need to use a specific
5693 command line for Fortran 95 files.
5694 You should normally set the $FORTRANCOM variable,
5695 which specifies the default command line
5696 for all Fortran versions.
5699 The string displayed when a Fortran 95 source file
5700 is compiled to an object file.
5701 If this is not set, then $F95COM or $FORTRANCOM
5702 (the command line) is displayed.
5705 General user-specified options that are passed to the Fortran 95 compiler.
5706 Note that this variable does
5710 (or similar) include search path options
5711 that scons generates automatically from $F95PATH.
5715 for the variable that expands to those options.
5716 You only need to set $F95FLAGS if you need to define specific
5717 user options for Fortran 95 files.
5718 You should normally set the $FORTRANFLAGS variable,
5719 which specifies the user-specified options
5720 passed to the default Fortran compiler
5721 for all Fortran versions.
5724 An automatically-generated construction variable
5725 containing the Fortran 95 compiler command-line options
5726 for specifying directories to be searched for include files.
5727 The value of $_F95INCFLAGS is created
5728 by appending $INCPREFIX and $INCSUFFIX
5729 to the beginning and end
5730 of each directory in $F95PATH.
5733 The list of directories that the Fortran 95 compiler will search for include
5734 directories. The implicit dependency scanner will search these
5735 directories for include files. Don't explicitly put include directory
5736 arguments in $F95FLAGS because the result will be non-portable
5737 and the directories will not be searched by the dependency scanner. Note:
5738 directory names in $F95PATH will be looked-up relative to the SConscript
5739 directory when they are used in a command. To force
5741 to look-up a directory relative to the root of the source tree use #:
5742 You only need to set $F95PATH if you need to define a specific
5743 include path for Fortran 95 files.
5744 You should normally set the $FORTRANPATH variable,
5745 which specifies the include path
5746 for the default Fortran compiler
5747 for all Fortran versions.
5750 env = Environment(F95PATH='#/include')
5754 The directory look-up can also be forced using the
5759 include = Dir('include')
5760 env = Environment(F95PATH=include)
5764 The directory list will be added to command lines
5765 through the automatically-generated
5767 construction variable,
5768 which is constructed by
5769 appending the values of the
5770 $INCPREFIX and $INCSUFFIX
5771 construction variables
5772 to the beginning and end
5773 of each directory in $F95PATH.
5774 Any command lines you define that need
5775 the F95PATH directory list should
5776 include $_F95INCFLAGS:
5779 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5783 The command line used to compile a Fortran 95 source file to an object file
5784 after first running the file through the C preprocessor.
5785 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5786 are included on this command line.
5787 You only need to set $F95PPCOM if you need to use a specific
5788 C-preprocessor command line for Fortran 95 files.
5789 You should normally set the $FORTRANPPCOM variable,
5790 which specifies the default C-preprocessor command line
5791 for all Fortran versions.
5794 The default Fortran compiler
5795 for all versions of Fortran.
5798 The command line used to compile a Fortran source file to an object file.
5799 By default, any options specified
5800 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5801 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5802 are included on this command line.
5805 The string displayed when a Fortran source file
5806 is compiled to an object file.
5807 If this is not set, then $FORTRANCOM
5808 (the command line) is displayed.
5811 General user-specified options that are passed to the Fortran compiler.
5812 Note that this variable does
5816 (or similar) include or module search path options
5817 that scons generates automatically from $FORTRANPATH.
5819 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5821 for the variables that expand those options.
5823 .IP _FORTRANINCFLAGS
5824 An automatically-generated construction variable
5825 containing the Fortran compiler command-line options
5826 for specifying directories to be searched for include
5827 files and module files.
5828 The value of $_FORTRANINCFLAGS is created
5829 by prepending/appending $INCPREFIX and $INCSUFFIX
5830 to the beginning and end
5831 of each directory in $FORTRANPATH.
5834 Directory location where the Fortran compiler should place
5835 any module files it generates. This variable is empty, by default. Some
5836 Fortran compilers will internally append this directory in the search path
5837 for module files, as well.
5839 .IP FORTRANMODDIRPREFIX
5840 The prefix used to specify a module directory on the Fortran compiler command
5842 This will be appended to the beginning of the directory
5843 in the $FORTRANMODDIR construction variables
5844 when the $_FORTRANMODFLAG variables is automatically generated.
5846 .IP FORTRANMODDIRSUFFIX
5847 The suffix used to specify a module directory on the Fortran compiler command
5849 This will be appended to the beginning of the directory
5850 in the $FORTRANMODDIR construction variables
5851 when the $_FORTRANMODFLAG variables is automatically generated.
5854 An automatically-generated construction variable
5855 containing the Fortran compiler command-line option
5856 for specifying the directory location where the Fortran
5857 compiler should place any module files that happen to get
5858 generated during compilation.
5859 The value of $_FORTRANMODFLAG is created
5860 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5861 to the beginning and end of the directory in $FORTRANMODDIR.
5863 .IP FORTRANMODPREFIX
5864 The module file prefix used by the Fortran compiler. SCons assumes that
5865 the Fortran compiler follows the quasi-standard naming convention for
5867 .I <module_name>.mod.
5868 As a result, this variable is left empty, by default. For situations in
5869 which the compiler does not necessarily follow the normal convention,
5870 the user may use this variable. Its value will be appended to every
5871 module file name as scons attempts to resolve dependencies.
5873 .IP FORTRANMODSUFFIX
5874 The module file suffix used by the Fortran compiler. SCons assumes that
5875 the Fortran compiler follows the quasi-standard naming convention for
5877 .I <module_name>.mod.
5878 As a result, this variable is set to ".mod", by default. For situations
5879 in which the compiler does not necessarily follow the normal convention,
5880 the user may use this variable. Its value will be appended to every
5881 module file name as scons attempts to resolve dependencies.
5884 The list of directories that the Fortran compiler will search for
5885 include files and (for some compilers) module files. The Fortran implicit
5886 dependency scanner will search these directories for include files (but
5887 not module files since they are autogenerated and, as such, may not
5888 actually exist at the time the scan takes place). Don't explicitly put
5889 include directory arguments in FORTRANFLAGS because the result will be
5890 non-portable and the directories will not be searched by the dependency
5891 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5892 to the SConscript directory when they are used in a command. To force
5894 to look-up a directory relative to the root of the source tree use #:
5897 env = Environment(FORTRANPATH='#/include')
5901 The directory look-up can also be forced using the
5906 include = Dir('include')
5907 env = Environment(FORTRANPATH=include)
5911 The directory list will be added to command lines
5912 through the automatically-generated
5914 construction variable,
5915 which is constructed by
5916 appending the values of the
5917 $INCPREFIX and $INCSUFFIX
5918 construction variables
5919 to the beginning and end
5920 of each directory in $FORTRANPATH.
5921 Any command lines you define that need
5922 the FORTRANPATH directory list should
5923 include $_FORTRANINCFLAGS:
5926 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5930 The command line used to compile a Fortran source file to an object file
5931 after first running the file through the C preprocessor.
5932 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5933 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5934 construction variables are included on this command line.
5937 The list of suffixes of files that will be scanned
5938 for Fortran implicit dependencies
5939 (INCLUDE lines & USE statements).
5940 The default list is:
5943 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5944 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5948 A function that converts a string into a File instance relative to the
5952 On Mac OS X with gcc,
5953 a list containing the paths to search for frameworks.
5954 Used by the compiler to find framework-style includes like
5955 #include <Fmwk/Header.h>.
5956 Used by the linker to find user-specified frameworks when linking (see
5960 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
5965 ... -Fmyframeworkdir
5968 to the compiler and linker command lines.
5971 On Mac OS X with gcc, an automatically-generated construction variable
5972 containing the linker command-line options corresponding to FRAMEWORKPATH.
5974 .IP FRAMEWORKPATHPREFIX
5975 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
5976 (see $FRAMEWORKPATH).
5977 The default value is
5981 On Mac OS X with gcc,
5982 the prefix to be used for linking in frameworks
5984 The default value is
5988 On Mac OS X with gcc, a list of the framework names to be linked into a
5989 program or shared library or bundle.
5990 The default value is the empty list.
5993 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
5997 On Mac OS X with gcc,
5998 an automatically-generated construction variable
5999 containing the linker command-line options
6000 for linking with FRAMEWORKS.
6003 On Mac OS X with gcc,
6004 general user-supplied frameworks options to be added at
6005 the end of a command
6006 line building a loadable module.
6007 (This has been largely superceded by
6008 the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX,
6009 $FRAMWORKPREFIX and $FRAMEWORKS variables
6013 The Ghostscript program used to convert PostScript to PDF files.
6016 General options passed to the Ghostscript program
6017 when converting PostScript to PDF files.
6020 The Ghostscript command line used to convert PostScript to PDF files.
6023 The string displayed when
6024 Ghostscript is used to convert
6025 a PostScript file to a PDF file.
6026 If this is not set, then $GSCOM (the command line) is displayed.
6029 The list of suffixes of files that will be scanned
6030 for IDL implicit dependencies
6031 (#include or import lines).
6032 The default list is:
6039 The prefix used to specify an include directory on the C compiler command
6041 This will be appended to the beginning of each directory
6042 in the $CPPPATH and $FORTRANPATH construction variables
6043 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
6044 variables are automatically generated.
6047 The suffix used to specify an include directory on the C compiler command
6049 This will be appended to the end of each directory
6050 in the $CPPPATH and $FORTRANPATH construction variables
6051 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
6052 variables are automatically generated.
6055 A function to be called to install a file into a
6056 destination file name.
6057 The default function copies the file into the destination
6058 (and sets the destination file's mode and permission bits
6059 to match the source file's).
6060 The function takes the following arguments:
6063 def install(dest, source, env):
6067 is the path name of the destination file.
6069 is the path name of the source file.
6071 is the construction environment
6072 (a dictionary of construction values)
6073 in force for this file installation.
6076 The string displayed when a file is
6077 installed into a destination file name.
6080 Install file: "$SOURCE" as "$TARGET"
6083 .IP INTEL_C_COMPILER_VERSION
6084 Set by the "intelc" Tool
6085 to the major version number of the Intel C compiler
6089 The Java archive tool.
6092 The directory to which the Java archive tool should change
6098 The command line used to call the Java archive tool.
6101 The string displayed when the Java archive tool
6103 If this is not set, then $JARCOM (the command line) is displayed.
6106 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
6110 General options passed to the Java archive tool.
6111 By default this is set to
6113 to create the necessary
6118 The suffix for Java archives:
6126 The command line used to compile a directory tree containing
6127 Java source files to
6128 corresponding Java class files.
6129 Any options specified in the $JAVACFLAGS construction variable
6130 are included on this command line.
6133 The string displayed when compiling
6134 a directory tree of Java source files to
6135 corresponding Java class files.
6136 If this is not set, then $JAVACCOM (the command line) is displayed.
6139 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
6143 General options that are passed to the Java compiler.
6146 The directory in which Java class files may be found.
6147 This is stripped from the beginning of any Java .class
6148 file names supplied to the
6153 The suffix for Java class files;
6158 The Java generator for C header and stub files.
6161 The command line used to generate C header and stub files
6163 Any options specified in the $JAVAHFLAGS construction variable
6164 are included on this command line.
6167 The string displayed when C header and stub files
6168 are generated from Java classes.
6169 If this is not set, then $JAVAHCOM (the command line) is displayed.
6172 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
6176 General options passed to the C header and stub file generator
6180 The suffix for Java files;
6185 The LaTeX structured formatter and typesetter.
6188 The command line used to call the LaTeX structured formatter and typesetter.
6191 The string displayed when calling
6192 the LaTeX structured formatter and typesetter.
6193 If this is not set, then $LATEXCOM (the command line) is displayed.
6196 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
6200 General options passed to the LaTeX structured formatter and typesetter.
6203 The linker for building loadable modules.
6204 By default, this is the same as $SHLINK.
6207 The command line for building loadable modules.
6208 On Mac OS X, this uses the $LDMODULE,
6209 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
6210 On other systems, this is the same as $SHLINK.
6213 The string displayed when building loadable modules.
6214 If this is not set, then $LDMODULECOM (the command line) is displayed.
6217 General user options passed to the linker for building loadable modules.
6220 The prefix used for loadable module file names.
6221 On Mac OS X, this is null;
6222 on other systems, this is
6223 the same as $SHLIBPREFIX.
6226 The suffix used for loadable module file names.
6227 On Mac OS X, this is null;
6228 on other systems, this is
6229 the same as $SHLIBSUFFIX.
6232 The lexical analyzer generator.
6235 General options passed to the lexical analyzer generator.
6238 The command line used to call the lexical analyzer generator
6239 to generate a source file.
6242 The string displayed when generating a source file
6243 using the lexical analyzer generator.
6244 If this is not set, then $LEXCOM (the command line) is displayed.
6247 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
6251 An automatically-generated construction variable
6252 containing the linker command-line options
6253 for specifying directories to be searched for library.
6254 The value of $_LIBDIRFLAGS is created
6255 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
6256 to the beginning and end
6257 of each directory in $LIBPATH.
6260 The prefix used to specify a library directory on the linker command line.
6261 This will be appended to the beginning of each directory
6262 in the $LIBPATH construction variable
6263 when the $_LIBDIRFLAGS variable is automatically generated.
6266 The suffix used to specify a library directory on the linker command line.
6267 This will be appended to the end of each directory
6268 in the $LIBPATH construction variable
6269 when the $_LIBDIRFLAGS variable is automatically generated.
6272 An automatically-generated construction variable
6273 containing the linker command-line options
6274 for specifying libraries to be linked with the resulting target.
6275 The value of $_LIBFLAGS is created
6276 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
6277 to the beginning and end
6278 of each filename in $LIBS.
6281 The prefix used to specify a library to link on the linker command line.
6282 This will be appended to the beginning of each library
6283 in the $LIBS construction variable
6284 when the $_LIBFLAGS variable is automatically generated.
6287 The suffix used to specify a library to link on the linker command line.
6288 This will be appended to the end of each library
6289 in the $LIBS construction variable
6290 when the $_LIBFLAGS variable is automatically generated.
6293 The list of directories that will be searched for libraries.
6294 The implicit dependency scanner will search these
6295 directories for include files. Don't explicitly put include directory
6296 arguments in $LINKFLAGS or $SHLINKFLAGS
6297 because the result will be non-portable
6298 and the directories will not be searched by the dependency scanner. Note:
6299 directory names in LIBPATH will be looked-up relative to the SConscript
6300 directory when they are used in a command. To force
6302 to look-up a directory relative to the root of the source tree use #:
6305 env = Environment(LIBPATH='#/libs')
6309 The directory look-up can also be forced using the
6315 env = Environment(LIBPATH=libs)
6319 The directory list will be added to command lines
6320 through the automatically-generated
6322 construction variable,
6323 which is constructed by
6324 appending the values of the
6325 $LIBDIRPREFIX and $LIBDIRSUFFIX
6326 construction variables
6327 to the beginning and end
6328 of each directory in $LIBPATH.
6329 Any command lines you define that need
6330 the LIBPATH directory list should
6331 include $_LIBDIRFLAGS:
6334 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6338 The prefix used for (static) library file names.
6339 A default value is set for each platform
6340 (posix, win32, os2, etc.),
6341 but the value is overridden by individual tools
6342 (ar, mslib, sgiar, sunar, tlib, etc.)
6343 to reflect the names of the libraries they create.
6346 An array of legal prefixes for library file names.
6349 A list of one or more libraries
6350 that will be linked with
6351 any executable programs
6352 created by this environment.
6355 The library list will be added to command lines
6356 through the automatically-generated
6358 construction variable,
6359 which is constructed by
6360 appending the values of the
6361 $LIBLINKPREFIX and $LIBLINKSUFFIX
6362 construction variables
6363 to the beginning and end
6364 of each filename in $LIBS.
6365 Any command lines you define that need
6366 the LIBS library list should
6370 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6378 list, the name of that file will be added to
6380 and thus the link line, as is, without
6386 env.Append(LIBS=File('/tmp/mylib.so'))
6390 In all cases, scons will add dependencies from the executable program to
6391 all the libraries in this list.
6394 The suffix used for (static) library file names.
6395 A default value is set for each platform
6396 (posix, win32, os2, etc.),
6397 but the value is overridden by individual tools
6398 (ar, mslib, sgiar, sunar, tlib, etc.)
6399 to reflect the names of the libraries they create.
6402 An array of legal suffixes for library file names.
6408 General user options passed to the linker.
6409 Note that this variable should
6413 (or similar) options for linking with the libraries listed in $LIBS,
6416 (or similar) library search path options
6417 that scons generates automatically from $LIBPATH.
6421 for the variable that expands to library-link options,
6425 for the variable that expands to library search path options.
6428 The command line used to link object files into an executable.
6431 The string displayed when object files
6432 are linked into an executable.
6433 If this is not set, then $LINKCOM (the command line) is displayed.
6436 env = Environment(LINKCOMSTR = "Linking $TARGET")
6440 The M4 macro preprocessor.
6443 General options passed to the M4 macro preprocessor.
6446 The command line used to pass files through the M4 macro preprocessor.
6449 The string displayed when
6450 a file is passed through the M4 macro preprocessor.
6451 If this is not set, then $M4COM (the command line) is displayed.
6454 The maximum number of characters allowed on an external command line.
6456 link lines longer than this many characters
6457 are linke via a temporary file name.
6460 When the Microsoft Visual Studio tools are initialized, they set up
6461 this dictionary with the following keys:
6464 the version of MSVS being used (can be set via
6468 the available versions of MSVS installed
6471 installed directory of Visual C++
6474 installed directory of Visual Studio
6477 installed directory of the .NET framework
6479 .B FRAMEWORKVERSIONS:
6480 list of installed versions of the .NET framework, sorted latest to oldest.
6482 .B FRAMEWORKVERSION:
6483 latest installed version of the .NET framework
6486 installed location of the .NET SDK.
6489 installed location of the Platform SDK.
6491 .B PLATFORMSDK_MODULES:
6492 dictionary of installed Platform SDK modules,
6493 where the dictionary keys are keywords for the various modules, and
6494 the values are 2-tuples where the first is the release date, and the
6495 second is the version number.
6497 If a value isn't set, it wasn't available in the registry.
6499 .IP MSVS_IGNORE_IDE_PATHS
6500 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6501 instead of the settings from the IDE.
6503 For Visual Studio, SCons will (by default) automatically determine
6504 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6505 set by the IDE. You can override this behavior by setting these
6506 variables after Environment initialization, or by setting
6507 .B MSVS_IGNORE_IDE_PATHS = 1
6508 in the Environment initialization.
6509 Specifying this will not leave these unset, but will set them to a
6510 minimal set of paths needed to run the tools successfully.
6513 For VS6, the mininimal set is:
6514 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6515 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6516 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6518 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6519 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6520 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6524 Where '<VSDir>' is the installed location of Visual Studio.
6526 .IP MSVS_PROJECT_BASE_PATH
6528 placed in a generated Microsoft Visual Studio solution file
6530 .B SccProjectFilePathRelativizedFromConnection0
6532 .B SccProjectFilePathRelativizedFromConnection1
6534 .B GlobalSection(SourceCodeControl)
6536 There is no default value.
6538 .IP MSVS_PROJECT_GUID
6540 placed in a generated Microsoft Visual Studio project file
6544 The string is also placed in the
6547 .B GlobalSection(SourceCodeControl)
6548 section of the Microsoft Visual Studio solution file.
6549 There is no default value.
6551 .IP MSVS_SCC_AUX_PATH
6553 placed in a generated Microsoft Visual Studio project file
6558 .I MSVS_SCC_PROVIDER
6559 construction variable is also set.
6560 There is no default value.
6562 .IP MSVS_SCC_LOCAL_PATH
6564 placed in a generated Microsoft Visual Studio project file
6569 .I MSVS_SCC_PROVIDER
6570 construction variable is also set.
6571 The path name is also placed in the
6576 .B GlobalSection(SourceCodeControl)
6577 section of the Microsoft Visual Studio solution file.
6578 There is no default value.
6580 .IP MSVS_SCC_PROJECT_NAME
6582 placed in a generated Microsoft Visual Studio project file
6586 There is no default value.
6588 .IP MSVS_SCC_PROVIDER
6590 placed in a generated Microsoft Visual Studio project file
6594 The string is also placed in the
6597 .B GlobalSection(SourceCodeControl)
6598 section of the Microsoft Visual Studio solution file.
6599 There is no default value.
6601 .IP MSVS_USE_MFC_DIRS
6602 Tells the MS Visual Studio tool(s) to use
6603 the MFC directories in its default paths
6604 for compiling and linking.
6605 Under MSVS version 6,
6607 .B MSVS_USE_MFC_DIRS
6616 external environment variable,
6622 external environment variable.
6623 Under MSVS version 7,
6625 .B MSVS_USE_MFC_DIRS
6628 .B "atlmfc\\\\include"
6629 directory to the default
6631 external environment variable,
6634 directory to the default
6636 external environment variable.
6637 The current default value is
6639 which means these directories
6640 are added to the paths by default.
6641 This default value is likely to change
6642 in a future release,
6643 so users who want the ATL and MFC
6644 values included in their paths
6645 are encouraged to enable the
6646 .B MSVS_USE_MFC_DIRS
6648 to avoid future incompatibility.
6649 This variable has no effect if the
6653 environment variables are set explictly.
6656 Sets the preferred version of MSVS to use.
6658 SCons will (by default) select the latest version of MSVS
6659 installed on your machine.
6660 So, if you have version 6 and version 7 (MSVS .NET) installed,
6661 it will prefer version 7.
6662 You can override this by
6665 variable in the Environment initialization, setting it to the
6666 appropriate version ('6.0' or '7.0', for example).
6667 If the given version isn't installed, tool initialization will fail.
6670 The build command line placed in
6671 a generated Microsoft Visual Studio project file.
6672 The default is to have Visual Studio invoke SCons with any specified
6676 The clean command line placed in
6677 a generated Microsoft Visual Studio project file.
6678 The default is to have Visual Studio invoke SCons with the -c option
6679 to remove any specified targets.
6682 The encoding string placed in
6683 a generated Microsoft Visual Studio project file.
6684 The default is encoding
6688 The action used to generate Microsoft Visual Studio project files.
6690 .IP MSVSPROJECTSUFFIX
6691 The suffix used for Microsoft Visual Studio project (DSP) files.
6692 The default value is
6694 when using Visual Studio version 7.x (.NET),
6697 when using earlier versions of Visual Studio.
6700 The rebuild command line placed in
6701 a generated Microsoft Visual Studio project file.
6702 The default is to have Visual Studio invoke SCons with any specified
6706 The SCons used in generated Microsoft Visual Studio project files.
6707 The default is the version of SCons being
6708 used to generate the project file.
6711 The SCons flags used in generated Microsoft Visual Studio
6715 The default SCons command used in generated Microsoft Visual Studio
6725 that will be invoked by Visual Studio
6730 The default is the same sconscript file
6731 that contains the call to
6733 to build the project file.
6736 The action used to generate Microsoft Visual Studio solution files.
6738 .IP MSVSSOLUTIONSUFFIX
6739 The suffix used for Microsoft Visual Studio solution (DSW) files.
6740 The default value is
6742 when using Visual Studio version 7.x (.NET),
6745 when using earlier versions of Visual Studio.
6748 The version number of the MetroWerks CodeWarrior C compiler
6752 A list of installed versions of the MetroWerks CodeWarrior C compiler
6756 When set to non-zero,
6757 suppresses creation of a corresponding Win32 static import lib by the
6759 builder when used with
6760 MinGW or Microsoft Visual Studio.
6761 This also suppresses creation
6762 of an export (.exp) file
6763 when using Microsoft Visual Studio.
6766 The prefix used for (static) object file names.
6769 The suffix used for (static) object file names.
6772 The Perforce executable.
6775 The command line used to
6776 fetch source files from Perforce.
6779 The string displayed when
6780 fetching a source file from Perforce.
6781 If this is not set, then $P4COM (the command line) is displayed.
6784 General options that are passed to Perforce.
6787 The Microsoft Visual C++ precompiled header that will be used when compiling
6788 object files. This variable is ignored by tools other than Microsoft Visual C++.
6789 When this variable is
6790 defined SCons will add options to the compiler command line to
6791 cause it to use the precompiled header, and will also set up the
6792 dependencies for the PCH file. Example:
6795 env['PCH'] = 'StdAfx.pch'
6799 The command line used by the
6801 builder to generated a precompiled header.
6804 The string displayed when generating a precompiled header.
6805 If this is not set, then $PCHCOM (the command line) is displayed.
6808 This variable specifies how much of a source file is precompiled. This
6809 variable is ignored by tools other than Microsoft Visual C++, or when
6810 the PCH variable is not being used. When this variable is define it
6811 must be a string that is the name of the header that
6812 is included at the end of the precompiled portion of the source files, or
6813 the empty string if the "#pragma hrdstop" construct is being used:
6816 env['PCHSTOP'] = 'StdAfx.h'
6820 The Microsoft Visual C++ PDB file that will store debugging information for
6821 object files, shared libraries, and programs. This variable is ignored by
6822 tools other than Microsoft Visual C++.
6823 When this variable is
6824 defined SCons will add options to the compiler and linker command line to
6825 cause them to generate external debugging information, and will also set up the
6826 dependencies for the PDB file. Example:
6829 env['PDB'] = 'hello.pdb'
6833 A deprecated synonym for $DVIPDFCOM.
6836 The prefix used for PDF file names.
6839 The suffix used for PDF file names.
6842 The name of the platform used to create the Environment. If no platform is
6843 specified when the Environment is created,
6845 autodetects the platform.
6848 env = Environment(tools = [])
6849 if env['PLATFORM'] == 'cygwin':
6855 .IP PRINT_CMD_LINE_FUNC
6856 A Python function used to print the command lines as they are executed
6857 (assuming command printing is not disabled by the
6861 options or their equivalents).
6862 The function should take four arguments:
6864 the command being executed (a string),
6866 the target being built (file node, list, or string name(s)),
6868 the source(s) used (file node, list, or string name(s)), and
6870 the environment being used.
6872 The function must do the printing itself. The default implementation,
6873 used if this variable is not set or is None, is:
6875 def print_cmd_line(s, target, source, env):
6876 sys.stdout.write(s + "\n")
6879 Here's an example of a more interesting function:
6881 def print_cmd_line(s, target, source, env):
6882 sys.stdout.write("Building %s -> %s...\n" %
6883 (' and '.join([str(x) for x in source]),
6884 ' and '.join([str(x) for x in target])))
6885 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6886 env.Program('foo', 'foo.c')
6889 This just prints "Building <targetname> from <sourcename>..." instead
6890 of the actual commands.
6891 Such a function could also log the actual commands to a log file,
6895 The prefix used for executable file names.
6898 The suffix used for executable file names.
6901 The command line used to convert TeX DVI files into a PostScript file.
6904 The string displayed when a TeX DVI file
6905 is converted into a PostScript file.
6906 If this is not set, then $PSCOM (the command line) is displayed.
6909 The prefix used for PostScript file names.
6912 The prefix used for PostScript file names.
6915 The qt tool tries to take this from os.environ.
6916 It also initializes all QT_*
6917 construction variables listed below.
6918 (Note that all paths are constructed
6919 with python's os.path.join() method,
6920 but are listed here with the '/' separator
6921 for easier reading.)
6922 In addition, the construction environment
6923 variables CPPPATH, LIBPATH and LIBS may be modified
6925 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6926 are modified. Because the build-performance is affected when using this tool,
6927 you have to explicitly specify it at Environment creation:
6930 Environment(tools=['default','qt'])
6933 The qt tool supports the following operations:
6935 .B Automatic moc file generation from header files.
6936 You do not have to specify moc files explicitly, the tool does it for you.
6937 However, there are a few preconditions to do so: Your header file must have
6938 the same filebase as your implementation file and must stay in the same
6939 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6940 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6941 See also the corresponding builder method
6944 .B Automatic moc file generation from cxx files.
6945 As stated in the qt documentation, include the moc file at the end of
6946 the cxx file. Note that you have to include the file, which is generated
6947 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6948 <basename>.moc. A warning is generated after building the moc file, if you
6949 do not include the correct file. If you are using BuildDir, you may
6950 need to specify duplicate=1. You can turn off automatic moc file generation
6951 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6954 .B Automatic handling of .ui files.
6955 The implementation files generated from .ui files are handled much the same
6956 as yacc or lex files. Each .ui file given as a source of Program, Library or
6957 SharedLibrary will generate three files, the declaration file, the
6958 implementation file and a moc file. Because there are also generated headers,
6959 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6963 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6964 specify files to run moc on.
6967 The path where the qt binaries are installed.
6968 The default value is '$QTDIR/bin'.
6971 The path where the qt header files are installed.
6972 The default value is '$QTDIR/include'.
6973 Note: If you set this variable to None, the tool won't change the CPPPATH
6974 construction variable.
6977 Prints lots of debugging information while scanning for moc files.
6980 The path where the qt libraries are installed.
6981 The default value is '$QTDIR/lib'.
6982 Note: If you set this variable to None, the tool won't change the LIBPATH
6983 construction variable.
6986 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
6987 this variable to None, the tool won't change the LIBS variable.
6990 Default value is '$QT_BINPATH/moc'.
6993 Default value is ''. Prefix for moc output files, when source is a cxx file.
6996 Default value is '.moc'. Suffix for moc output files, when source is a cxx
6999 .IP QT_MOCFROMCPPFLAGS
7000 Default value is '-i'. These flags are passed to moc, when moccing a
7003 .IP QT_MOCFROMCXXCOM
7004 Command to generate a moc file from a cpp file.
7006 .IP QT_MOCFROMCXXCOMSTR
7007 The string displayed when generating a moc file from a cpp file.
7008 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
7011 Command to generate a moc file from a header.
7013 .IP QT_MOCFROMHCOMSTR
7014 The string displayed when generating a moc file from a cpp file.
7015 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
7017 .IP QT_MOCFROMHFLAGS
7018 Default value is ''. These flags are passed to moc, when moccing a header
7022 Default value is 'moc_'. Prefix for moc output files, when source is a header.
7025 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
7029 Default value is '$QT_BINPATH/uic'.
7032 Command to generate header files from .ui files.
7035 The string displayed when generating header files from .ui files.
7036 If this is not set, then $QT_UICCOM (the command line) is displayed.
7039 Default value is ''. These flags are passed to uic, when creating a a h
7040 file from a .ui file.
7042 .IP QT_UICDECLPREFIX
7043 Default value is ''. Prefix for uic generated header files.
7045 .IP QT_UICDECLSUFFIX
7046 Default value is '.h'. Suffix for uic generated header files.
7049 Default value is ''. These flags are passed to uic, when creating a cxx
7050 file from a .ui file.
7052 .IP QT_UICIMPLPREFIX
7053 Default value is 'uic_'. Prefix for uic generated implementation files.
7055 .IP QT_UICIMPLSUFFIX
7056 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
7060 Default value is '.ui'. Suffix of designer input files.
7063 The archive indexer.
7066 General options passed to the archive indexer.
7069 The resource compiler used by the RES builder.
7072 The command line used by the RES builder.
7075 The string displayed when invoking the resource compiler.
7076 If this is not set, then $RCCOM (the command line) is displayed.
7079 The flags passed to the resource compiler by the RES builder.
7083 Note that this variable is not actually used
7084 for the command to fetch source files from RCS;
7087 construction variable, below.
7090 The RCS "checkout" executable,
7091 used to fetch source files from RCS.
7094 The command line used to
7095 fetch (checkout) source files from RCS.
7098 The string displayed when fetching
7099 a source file from RCS.
7100 If this is not set, then $RCS_COCOM
7101 (the command line) is displayed.
7104 Options that are passed to the $RCS_CO command.
7107 The program used to register DLLs on Windows systems.
7110 The command line used to register a newly-built DLL file
7112 Invoked when the "register=1"
7113 keyword argument is passed to the
7118 The string displayed when registering a newly-built DLL file.
7119 If this is not set, then $REGSVRCOM (the command line) is displayed.
7122 A function that converts a string into a list of Dir instances by
7123 searching the repositories.
7126 The Java RMI stub compiler.
7129 The command line used to compile stub
7130 and skeleton class files
7131 from Java classes that contain RMI implementations.
7132 Any options specified in the $RMICFLAGS construction variable
7133 are included on this command line.
7136 The string displayed when compiling
7137 stub and skeleton class files
7138 from Java classes that contain RMI implementations.
7139 If this is not set, then $RMICCOM (the command line) is displayed.
7142 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
7146 General options passed to the Java RMI stub compiler.
7149 The RPC protocol compiler.
7151 .IP RPCGENCLIENTFLAGS
7152 Options passed to the RPC protocol compiler
7153 when generating client side stubs.
7154 These are in addition to any flags specified in the
7156 construction variable.
7159 General options passed to the RPC protocol compiler.
7161 .IP RPCGENHEADERFLAGS
7162 Options passed to the RPC protocol compiler
7163 when generating a header file.
7164 These are in addition to any flags specified in the
7166 construction variable.
7168 .IP RPCGENSERVICEFLAGS
7169 Options passed to the RPC protocol compiler
7170 when generating server side stubs.
7171 These are in addition to any flags specified in the
7173 construction variable.
7176 Options passed to the RPC protocol compiler
7177 when generating XDR routines.
7178 These are in addition to any flags specified in the
7180 construction variable.
7183 A list of paths to search for shared libraries when running programs.
7184 Currently only used in the GNU (gnulink),
7185 IRIX (sgilink) and Sun (sunlink) linkers.
7186 Ignored on platforms and toolchains that don't support it.
7187 Note that the paths added to RPATH
7188 are not transformed by
7190 in any way: if you want an absolute
7191 path, you must make it absolute yourself.
7194 A list of the available implicit dependency scanners.
7195 New file scanners may be added by
7196 appending to this list,
7197 although the more flexible approach
7198 is to associate scanners
7199 with a specific Builder.
7200 See the sections "Builder Objects"
7201 and "Scanner Objects,"
7202 below, for more information.
7205 The SCCS executable.
7208 The command line used to
7209 fetch source files from SCCS.
7212 The string displayed when fetching
7213 a source file from a CVS repository.
7214 If this is not set, then $SCCSCOM
7215 (the command line) is displayed.
7218 General options that are passed to SCCS.
7221 Options that are passed specifically to the SCCS "get" subcommand.
7222 This can be set, for example, to
7224 to check out editable files from SCCS.
7227 The C compiler used for generating shared-library objects.
7230 The command line used to compile a C source file
7231 to a shared-library object file.
7232 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
7233 are included on this command line.
7236 The string displayed when a C source file
7237 is compiled to a shared object file.
7238 If this is not set, then $SHCCCOM (the command line) is displayed.
7241 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
7245 Options that are passed to the C compiler
7246 to generate shared-library objects.
7249 The C++ compiler used for generating shared-library objects.
7252 The command line used to compile a C++ source file
7253 to a shared-library object file.
7254 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
7255 are included on this command line.
7258 The string displayed when a C++ source file
7259 is compiled to a shared object file.
7260 If this is not set, then $SHCXXCOM (the command line) is displayed.
7263 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
7267 Options that are passed to the C++ compiler
7268 to generate shared-library objects.
7271 A string naming the shell program that will be passed to the
7276 construction variable for more information.
7279 The Fortran 77 compiler used for generating shared-library objects.
7280 You should normally set the $SHFORTRANC variable,
7281 which specifies the default Fortran compiler
7282 for all Fortran versions.
7283 You only need to set $SHF77 if you need to use a specific compiler
7284 or compiler version for Fortran 77 files.
7287 The command line used to compile a Fortran 77 source file
7288 to a shared-library object file.
7289 You only need to set $SHF77COM if you need to use a specific
7290 command line for Fortran 77 files.
7291 You should normally set the $SHFORTRANCOM variable,
7292 which specifies the default command line
7293 for all Fortran versions.
7296 The string displayed when a Fortran 77 source file
7297 is compiled to a shared-library object file.
7298 If this is not set, then $SHF77COM or $SHFORTRANCOM
7299 (the command line) is displayed.
7302 Options that are passed to the Fortran 77 compiler
7303 to generated shared-library objects.
7304 You only need to set $SHF77FLAGS if you need to define specific
7305 user options for Fortran 77 files.
7306 You should normally set the $SHFORTRANFLAGS variable,
7307 which specifies the user-specified options
7308 passed to the default Fortran compiler
7309 for all Fortran versions.
7312 The command line used to compile a Fortran 77 source file to a
7313 shared-library object file
7314 after first running the file through the C preprocessor.
7315 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
7316 are included on this command line.
7317 You only need to set $SHF77PPCOM if you need to use a specific
7318 C-preprocessor command line for Fortran 77 files.
7319 You should normally set the $SHFORTRANPPCOM variable,
7320 which specifies the default C-preprocessor command line
7321 for all Fortran versions.
7324 The Fortran 90 compiler used for generating shared-library objects.
7325 You should normally set the $SHFORTRANC variable,
7326 which specifies the default Fortran compiler
7327 for all Fortran versions.
7328 You only need to set $SHF90 if you need to use a specific compiler
7329 or compiler version for Fortran 90 files.
7332 The command line used to compile a Fortran 90 source file
7333 to a shared-library object file.
7334 You only need to set $SHF90COM if you need to use a specific
7335 command line for Fortran 90 files.
7336 You should normally set the $SHFORTRANCOM variable,
7337 which specifies the default command line
7338 for all Fortran versions.
7341 The string displayed when a Fortran 90 source file
7342 is compiled to a shared-library object file.
7343 If this is not set, then $SHF90COM or $SHFORTRANCOM
7344 (the command line) is displayed.
7347 Options that are passed to the Fortran 90 compiler
7348 to generated shared-library objects.
7349 You only need to set $SHF90FLAGS if you need to define specific
7350 user options for Fortran 90 files.
7351 You should normally set the $SHFORTRANFLAGS variable,
7352 which specifies the user-specified options
7353 passed to the default Fortran compiler
7354 for all Fortran versions.
7357 The command line used to compile a Fortran 90 source file to a
7358 shared-library object file
7359 after first running the file through the C preprocessor.
7360 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
7361 are included on this command line.
7362 You only need to set $SHF90PPCOM if you need to use a specific
7363 C-preprocessor command line for Fortran 90 files.
7364 You should normally set the $SHFORTRANPPCOM variable,
7365 which specifies the default C-preprocessor command line
7366 for all Fortran versions.
7369 The Fortran 95 compiler used for generating shared-library objects.
7370 You should normally set the $SHFORTRANC variable,
7371 which specifies the default Fortran compiler
7372 for all Fortran versions.
7373 You only need to set $SHF95 if you need to use a specific compiler
7374 or compiler version for Fortran 95 files.
7377 The command line used to compile a Fortran 95 source file
7378 to a shared-library object file.
7379 You only need to set $SHF95COM if you need to use a specific
7380 command line for Fortran 95 files.
7381 You should normally set the $SHFORTRANCOM variable,
7382 which specifies the default command line
7383 for all Fortran versions.
7386 The string displayed when a Fortran 95 source file
7387 is compiled to a shared-library object file.
7388 If this is not set, then $SHF95COM or $SHFORTRANCOM
7389 (the command line) is displayed.
7392 Options that are passed to the Fortran 95 compiler
7393 to generated shared-library objects.
7394 You only need to set $SHF95FLAGS if you need to define specific
7395 user options for Fortran 95 files.
7396 You should normally set the $SHFORTRANFLAGS variable,
7397 which specifies the user-specified options
7398 passed to the default Fortran compiler
7399 for all Fortran versions.
7402 The command line used to compile a Fortran 95 source file to a
7403 shared-library object file
7404 after first running the file through the C preprocessor.
7405 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
7406 are included on this command line.
7407 You only need to set $SHF95PPCOM if you need to use a specific
7408 C-preprocessor command line for Fortran 95 files.
7409 You should normally set the $SHFORTRANPPCOM variable,
7410 which specifies the default C-preprocessor command line
7411 for all Fortran versions.
7414 The default Fortran compiler used for generating shared-library objects.
7417 The command line used to compile a Fortran source file
7418 to a shared-library object file.
7421 The string displayed when a Fortran source file
7422 is compiled to a shared-library object file.
7423 If this is not set, then $SHFORTRANCOM
7424 (the command line) is displayed.
7427 Options that are passed to the Fortran compiler
7428 to generate shared-library objects.
7431 The command line used to compile a Fortran source file to a
7432 shared-library object file
7433 after first running the file through the C preprocessor.
7434 Any options specified
7435 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
7436 are included on this command line.
7439 The prefix used for shared library file names.
7442 The suffix used for shared library file names.
7445 The linker for programs that use shared libraries.
7448 The command line used to link programs using shared libaries.
7451 The string displayed when programs using shared libraries are linked.
7452 If this is not set, then $SHLINKCOM (the command line) is displayed.
7455 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
7459 General user options passed to the linker for programs using shared libraries.
7460 Note that this variable should
7464 (or similar) options for linking with the libraries listed in $LIBS,
7467 (or similar) include search path options
7468 that scons generates automatically from $LIBPATH.
7472 for the variable that expands to library-link options,
7476 for the variable that expands to library search path options.
7479 The prefix used for shared object file names.
7482 The suffix used for shared object file names.
7485 A reserved variable name
7486 that may not be set or used in a construction environment.
7487 (See "Variable Substitution," below.)
7490 A reserved variable name
7491 that may not be set or used in a construction environment.
7492 (See "Variable Substitution," below.)
7495 A command interpreter function that will be called to execute command line
7496 strings. The function must expect the following arguments:
7499 def spawn(shell, escape, cmd, args, env):
7503 is a string naming the shell program to use.
7505 is a function that can be called to escape shell special characters in
7508 is the path to the command to be executed.
7510 is the arguments to the command.
7512 is a dictionary of the environment variables
7513 in which the command should be executed.
7516 '\"The Subversion executable (usually named
7520 '\"The command line used to
7521 '\"fetch source files from a Subversion repository.
7524 '\"General options that are passed to Subversion.
7527 The scripting language wrapper and interface generator.
7530 The suffix that will be used for intermediate C
7531 source files generated by
7532 the scripting language wrapper and interface generator.
7533 The default value is
7534 .BR _wrap$CFILESUFFIX .
7535 By default, this value is used whenever the
7539 specified as part of the
7541 construction variable.
7544 The command line used to call
7545 the scripting language wrapper and interface generator.
7548 The string displayed when calling
7549 the scripting language wrapper and interface generator.
7550 If this is not set, then $SWIGCOM (the command line) is displayed.
7552 .IP SWIGCXXFILESUFFIX
7553 The suffix that will be used for intermediate C++
7554 source files generated by
7555 the scripting language wrapper and interface generator.
7556 The default value is
7557 .BR _wrap$CFILESUFFIX .
7558 By default, this value is used whenever the
7560 option is specified as part of the
7562 construction variable.
7565 General options passed to
7566 the scripting language wrapper and interface generator.
7567 This is where you should set
7571 or whatever other options you want to specify to SWIG.
7574 option in this variable,
7577 generate a C++ intermediate source file
7578 with the extension that is specified as the
7586 The command line used to call the tar archiver.
7589 The string displayed when archiving files
7590 using the tar archiver.
7591 If this is not set, then $TARCOM (the command line) is displayed.
7594 env = Environment(TARCOMSTR = "Archiving $TARGET")
7598 General options passed to the tar archiver.
7601 A reserved variable name
7602 that may not be set or used in a construction environment.
7603 (See "Variable Substitution," below.)
7606 A reserved variable name
7607 that may not be set or used in a construction environment.
7608 (See "Variable Substitution," below.)
7611 The suffix used for tar file names.
7614 The prefix for a temporary file used
7615 to execute lines longer than $MAXLINELENGTH.
7617 This may be set for toolchains that use other values,
7618 such as '-@' for the diab compiler
7619 or '-via' for ARM toolchain.
7622 The TeX formatter and typesetter.
7625 The command line used to call the TeX formatter and typesetter.
7628 The string displayed when calling
7629 the TeX formatter and typesetter.
7630 If this is not set, then $TEXCOM (the command line) is displayed.
7633 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7637 General options passed to the TeX formatter and typesetter.
7640 A list of the names of the Tool specifications
7641 that are part of this construction environment.
7643 .IP WIN32_INSERT_DEF
7644 When this is set to true,
7645 a library build of a WIN32 shared library (.dll file)
7646 will also build a corresponding .def file at the same time,
7647 if a .def file is not already listed as a build target.
7648 The default is 0 (do not build a .def file).
7651 The prefix used for WIN32 .def file names.
7654 The suffix used for WIN32 .def file names.
7657 The parser generator.
7660 The command line used to call the parser generator
7661 to generate a source file.
7664 The string displayed when generating a source file
7665 using the parser generator.
7666 If this is not set, then $YACCCOM (the command line) is displayed.
7669 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7673 General options passed to the parser generator.
7674 If $YACCFLAGS contains a \-d option,
7675 SCons assumes that the call will also create a .h file
7676 (if the yacc source file ends in a .y suffix)
7678 (if the yacc source file ends in a .yy suffix)
7682 header file generated by the parser generator
7686 Note that setting this variable does not cause
7687 the parser generator to generate a header
7688 file with the specified suffix,
7689 it exists to allow you to specify
7690 what suffix the parser generator will use of its own accord.
7691 The default value is
7694 .IP YACCHXXFILESUFFIX
7695 The suffix of the C++
7696 header file generated by the parser generator
7700 Note that setting this variable does not cause
7701 the parser generator to generate a header
7702 file with the specified suffix,
7703 it exists to allow you to specify
7704 what suffix the parser generator will use of its own accord.
7705 The default value is
7709 The zip compression and file packaging utility.
7712 The command line used to call the zip utility,
7713 or the internal Python function used to create a
7717 The string displayed when archiving files
7718 using the zip utility.
7719 If this is not set, then $ZIPCOM
7720 (the command line or internal Python function) is displayed.
7723 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7732 module used by the internal Python function
7733 to control whether the zip archive
7734 is compressed or not.
7735 The default value is
7736 .BR zipfile.ZIP_DEFLATED ,
7737 which creates a compressed zip archive.
7738 This value has no effect when using Python 1.5.2
7741 module is otherwise unavailable.
7744 General options passed to the zip utility.
7747 Construction variables can be retrieved and set using the
7749 method of the construction environment:
7752 dict = env.Dictionary()
7756 or using the [] operator:
7762 Construction variables can also be passed to the construction environment
7766 env = Environment(CC="cc")
7769 or when copying a construction environment using the
7774 env2 = env.Copy(CC="cl.exe")
7777 .SS Configure Contexts
7781 .I configure contexts,
7782 an integrated mechanism similar to the
7783 various AC_CHECK macros in GNU autoconf
7784 for testing for the existence of C header
7785 files, libraries, etc.
7786 In contrast to autoconf,
7788 does not maintain an explicit cache of the tested values,
7789 but uses its normal dependency tracking to keep the checked values
7790 up to date. However, users may override this behaviour with the
7792 command line option.
7794 The following methods can be used to perform checks:
7797 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7799 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7800 This creates a configure context, which can be used to perform checks.
7802 specifies the environment for building the tests.
7803 This environment may be modified when performing checks.
7805 is a dictionary containing custom tests.
7806 See also the section about custom tests below.
7807 By default, no custom tests are added to the configure context.
7809 specifies a directory where the test cases are built.
7810 Note that this directory is not used for building
7812 The default value is the directory
7815 specifies a file which collects the output from commands
7816 that are executed to check for the existence of header files, libraries, etc.
7817 The default is the file #/config.log.
7818 If you are using the
7821 you may want to specify a subdirectory under your build directory.
7823 specifies a C header file where the results of tests
7824 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7825 The default is to not write a
7828 You can specify the same
7830 file in multiple calls to Configure,
7833 will concatenate all results in the specified file.
7835 uses its normal dependency checking
7836 to decide if it's necessary to rebuild
7840 This means that the file is not necessarily re-built each
7842 but is only rebuilt if its contents will have changed
7843 and some target that depends on the
7845 file is being built.
7850 instance has the following associated methods:
7853 .RI Configure.Finish( self )
7854 This method should be called after configuration is done.
7855 It returns the environment as modified
7856 by the configuration checks performed.
7857 After this method is called, no further checks can be performed
7858 with this configuration context.
7859 However, you can create a new
7861 context to perform additional checks.
7862 Only one context should be active at a time.
7864 The following Checks are predefined.
7865 (This list will likely grow larger as time
7866 goes by and developers contribute new useful tests.)
7869 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7872 is usable in the specified language.
7875 in which case the last item in the list
7876 is the header file to be checked,
7877 and the previous list items are
7880 lines should precede the
7881 header line being checked for.
7882 The optional argument
7885 a two character string, where the first character denotes the opening
7886 quote and the second character denotes the closing quote.
7887 By default, both characters are " (double quote).
7888 The optional argument
7894 and selects the compiler to be used for the check.
7895 Returns 1 on success and 0 on failure.
7898 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7899 This is a wrapper around
7900 .B Configure.CheckHeader
7903 is usable in the C language.
7906 in which case the last item in the list
7907 is the header file to be checked,
7908 and the previous list items are
7911 lines should precede the
7912 header line being checked for.
7913 The optional argument
7916 a two character string, where the first character denotes the opening
7917 quote and the second character denotes the closing quote (both default
7919 Returns 1 on success and 0 on failure.
7922 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7923 This is a wrapper around
7924 .B Configure.CheckHeader
7927 is usable in the C++ language.
7930 in which case the last item in the list
7931 is the header file to be checked,
7932 and the previous list items are
7935 lines should precede the
7936 header line being checked for.
7937 The optional argument
7940 a two character string, where the first character denotes the opening
7941 quote and the second character denotes the closing quote (both default
7943 Returns 1 on success and 0 on failure.
7946 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7947 Checks if the specified
7948 C or C++ function is available.
7950 is the name of the function to check for.
7953 argument is a string
7957 that will be compiled
7958 to check if the function exists;
7964 char function_name();
7972 and selects the compiler to be used for the check;
7976 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
7983 is 1 and the library provides the specified
7985 appends the library to the LIBS construction environment variable.
7987 may also be None (the default),
7990 is checked with the current LIBS variable,
7991 or a list of library names,
7992 in which case each library in the list
7999 you can link against the specified
8007 and selects the compiler to be used for the check;
8009 The default value for
8012 It is assumed, that the C-language is used.
8013 This method returns 1 on success and 0 on error.
8016 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
8019 .RI Configure.CheckLib
8020 call, this call provides a more sophisticated way to check against libraries.
8023 specifies the library or a list of libraries to check.
8025 specifies a header to check for.
8028 in which case the last item in the list
8029 is the header file to be checked,
8030 and the previous list items are
8033 lines should precede the
8034 header line being checked for.
8036 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
8038 can be any valid expression (with a trailing ';'). The default is 'main();'.
8040 specifies whether to add the library to the environment (only if the check
8041 succeeds). This method returns 1 on success and 0 on error.
8044 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
8045 Checks for the existence of a type defined by
8048 specifies the typedef name to check for.
8050 is a string containing one or more
8052 lines that will be inserted into the program
8053 that will be run to test for the existence of the type.
8060 and selects the compiler to be used for the check;
8064 Example of a typical Configure usage:
8068 conf = Configure( env )
8069 if not conf.CheckCHeader( 'math.h' ):
8070 print 'We really need math.h!'
8072 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
8073 # do stuff for qt - usage, e.g.
8074 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
8079 You can define your own custom checks.
8080 in addition to the predefined checks.
8081 These are passed in a dictionary to the Configure function.
8082 This dictionary maps the names of the checks
8083 to user defined Python callables
8084 (either Python functions or class instances implementing the
8087 The first argument of the call is always a
8089 instance followed by the arguments,
8090 which must be supplied by the user of the check.
8091 These CheckContext instances define the following methods:
8094 .RI CheckContext.Message( self ", " text )
8096 Usually called before the check is started.
8098 will be displayed to the user, e.g. 'Checking for library X...'
8101 .RI CheckContext.Result( self, ", " res )
8103 Usually called after the check is done.
8105 can be either an integer or a string. In the former case, 'ok' (res != 0)
8106 or 'failed' (res == 0) is displayed to the user, in the latter case the
8107 given string is displayed.
8110 .RI CheckContext.TryCompile( self ", " text ", " extension )
8111 Checks if a file with the specified
8113 (e.g. '.c') containing
8115 can be compiled using the environment's
8117 builder. Returns 1 on success and 0 on failure.
8120 .RI CheckContext.TryLink( self ", " text ", " extension )
8121 Checks, if a file with the specified
8123 (e.g. '.c') containing
8125 can be compiled using the environment's
8127 builder. Returns 1 on success and 0 on failure.
8130 .RI CheckContext.TryRun( self ", " text ", " extension )
8131 Checks, if a file with the specified
8133 (e.g. '.c') containing
8135 can be compiled using the environment's
8137 builder. On success, the program is run. If the program
8138 executes successfully
8139 (that is, its return status is 0),
8144 is the standard output of the
8146 If the program fails execution
8147 (its return status is non-zero),
8148 then (0, '') is returned.
8151 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
8152 Checks if the specified
8154 with an optional source file (contents
8161 may be anything which can be converted to a
8168 is the content of the target file.
8174 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
8175 Low level implementation for testing specific builds;
8176 the methods above are based on this method.
8177 Given the Builder instance
8181 of a source file with optional
8183 this method returns 1 on success and 0 on failure. In addition,
8185 is set to the build target node, if the build was successful.
8188 Example for implementing and using custom tests:
8191 def CheckQt(context, qtdir):
8192 context.Message( 'Checking for qt ...' )
8193 lastLIBS = context.env['LIBS']
8194 lastLIBPATH = context.env['LIBPATH']
8195 lastCPPPATH= context.env['CPPPATH']
8196 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
8197 ret = context.TryLink("""
8199 int main(int argc, char **argv) {
8200 QApplication qapp(argc, argv);
8205 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
8206 context.Result( ret )
8210 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
8211 if not conf.CheckQt('/usr/lib/qt'):
8212 print 'We really need qt!'
8217 .SS Construction Variable Options
8219 Often when building software, various options need to be specified at build
8220 time that are not known when the SConstruct/SConscript files are
8221 written. For example, libraries needed for the build may be in non-standard
8222 locations, or site-specific compiler options may need to be passed to the
8225 provides a mechanism for overridding construction variables from the
8226 command line or a text-based SConscript file through an Options
8227 object. To create an Options object, call the Options() function:
8230 .RI Options([ files "], [" args ])
8231 This creates an Options object that will read construction variables from
8232 the file or list of filenames specified in
8234 If no files are specified,
8239 then no files will be read.
8240 The optional argument
8243 values that will override anything read from the specified files;
8244 it is primarily intended to be passed the
8246 dictionary that holds variables
8247 specified on the command line.
8251 opts = Options('custom.py')
8252 opts = Options('overrides.py', ARGUMENTS)
8253 opts = Options(None, {FOO:'expansion', BAR:7})
8256 Options objects have the following methods:
8259 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
8260 This adds a customizable construction variable to the Options object.
8262 is the name of the variable.
8264 is the help text for the variable.
8266 is the default value of the variable;
8267 if the default value is
8269 and there is no explicit value specified,
8270 the construction variable will
8272 be added to the construction environment.
8274 is called to validate the value of the variable, and should take three
8275 arguments: key, value, and environment
8277 is called to convert the value before putting it in the environment, and
8278 should take a single argument: value. Example:
8281 opts.Add('CC', 'The C compiler')
8285 .RI AddOptions( list )
8286 A wrapper script that adds
8287 multiple customizable construction variables
8288 to an Options object.
8290 is a list of tuple or list objects
8291 that contain the arguments
8292 for an individual call to the
8299 ('CC', 'The C compiler'),
8300 ('VALIDATE', 'An option for testing validation',
8301 'notset', validator, None),
8306 .RI Update( env ", [" args ])
8307 This updates a construction environment
8309 with the customized construction variables. Normally this method is not
8310 called directly, but is called indirectly by passing the Options object to
8311 the Environment() function:
8314 env = Environment(options=opts)
8318 The text file(s) that were specified
8319 when the Options object was created
8320 are executed as Python scripts,
8321 and the values of (global) Python variables set in the file
8322 are added to the construction environment.
8330 .RI Save( filename ", " env )
8331 This saves the currently set options into a script file named
8333 that can be used on the next invocation to automatically load the current
8334 settings. This method combined with the Options method can be used to
8335 support caching of options between runs.
8339 opts = Options(['options.cache', 'custom.py'])
8342 opts.Save('options.cache', env)
8346 .RI GenerateHelpText( env ", [" sort ])
8347 This generates help text documenting the customizable construction
8348 variables suitable to passing in to the Help() function.
8350 is the construction environment that will be used to get the actual values
8351 of customizable variables. Calling with
8355 will cause the output to be sorted
8356 by the specified argument.
8360 should take two arguments
8363 (like the standard Python
8368 Help(opts.GenerateHelpText(env))
8369 Help(opts.GenerateHelpText(env, sort=cmp))
8373 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
8374 This method returns a formatted string
8375 containing the printable help text
8377 It is normally not called directly,
8378 but is called by the
8379 .IR GenerateHelpText ()
8380 method to create the returned help text.
8381 It may be overridden with your own
8382 function that takes the arguments specified above
8383 and returns a string of help text formatted to your liking.
8385 .IR GenerateHelpText ()
8386 will not put any blank lines or extra
8387 characters in between the entries,
8388 so you must add those characters to the returned
8389 string if you want the entries separated.
8392 def my_format(env, opt, help, default, actual):
8393 fmt = "\n%s: default=%s actual=%s (%s)\n"
8394 return fmt % (opt, default. actual, help)
8395 opts.FormatOptionHelpText = my_format
8398 To make it more convenient to work with customizable Options,
8400 provides a number of functions
8401 that make it easy to set up
8402 various types of Options:
8405 .RI BoolOption( key ", " help ", " default )
8406 Return a tuple of arguments
8407 to set up a Boolean option.
8411 have a default value of
8413 and display the specified
8416 The option will interpret the values
8438 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
8439 Return a tuple of arguments
8441 whose value may be one
8442 of a specified list of legal enumerated values.
8446 have a default value of
8448 and display the specified
8451 The option will only support those
8457 argument is a dictionary
8458 that can be used to convert
8459 input values into specific legal values
8468 then the values are case-sensitive.
8473 then values will be matched
8479 then values will be matched
8481 and all input values will be
8482 converted to lower case.
8485 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
8486 Return a tuple of arguments
8488 whose value may be one or more
8489 of a specified list of legal enumerated values.
8493 have a default value of
8495 and display the specified
8498 The option will only support the values
8501 or the values in the
8504 More than one value may be specified,
8505 with all values separated by commas.
8506 The default may be a string of
8507 comma-separated default values,
8508 or a list of the default values.
8511 argument is a dictionary
8512 that can be used to convert
8513 input values into specific legal values
8519 .RI PackageOption( key ", " help ", " default )
8520 Return a tuple of arguments
8522 whose value is a path name
8523 of a package that may be
8524 enabled, disabled or
8525 given an explicit path name.
8529 have a default value of
8531 and display the specified
8534 The option will support the values
8541 in which case the specified
8544 or the option may be set to an
8546 (typically the path name to a package
8547 that is being enabled).
8548 The option will also support the values
8554 to disable use of the specified option.
8557 .RI PathOption( key ", " help ", " default ", [" validator ])
8558 Return a tuple of arguments
8560 whose value is expected to be a path name.
8564 have a default value of
8566 and display the specified
8572 that will be called to
8573 verify that the specified path
8576 following ready-made validators:
8577 .BR PathOption.PathExists
8579 which verifies that the specified path exists;
8580 .BR PathOption.PathIsFile ,
8581 which verifies that the specified path is an existing file;
8582 .BR PathOption.PathIsDir ,
8583 which verifies that the specified path is an existing directory;
8585 .BR PathOption.PathIsDirCreate ,
8586 which verifies that the specified path is a directory,
8587 and will create the specified directory if the path does not exist.
8588 You may supply your own
8591 which must take three arguments
8593 the name of the options variable to be set;
8595 the specified value being checked;
8598 the construction environment)
8599 and should raise an exception
8600 if the specified value is not acceptable.
8603 These functions make it
8604 convenient to create a number
8605 of options with consistent behavior
8606 in a single call to the
8612 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
8613 EnumOption('debug', 'debug output and symbols', 'no'
8614 allowed_values=('yes', 'no', 'full'),
8615 map={}, ignorecase=0), # case sensitive
8616 ListOption('shared',
8617 'libraries to build as shared libraries',
8619 names = list_of_libs),
8620 PackageOption('x11',
8621 'use X11 installed here (yes = search some places)',
8623 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
8624 PathOption('foopath', 'where the foo library is installed', foopath,
8625 PathOption.PathIsDir),
8630 .SS File and Directory Nodes
8640 Nodes, respectively.
8641 python objects, respectively.
8642 Those objects have several user-visible attributes
8643 and methods that are often useful:
8649 This path is relative to the top-level directory
8653 The build path is the same as the source path if
8658 The absolute build path of the given file or directory.
8668 object representing the
8677 # Get the current build dir's path, relative to top.
8679 # Current dir's absolute path
8681 # Next line is always '.', because it is the top dir's path relative to itself.
8683 File('foo.c').srcnode().path # source path of the given source file.
8685 # Builders also return File objects:
8686 foo = env.Program('foo.c')
8687 print "foo will be built in %s"%foo.path
8693 can be extended to build different types of targets
8694 by adding new Builder objects
8695 to a construction environment.
8697 you should only need to add a new Builder object
8698 when you want to build a new type of file or other external target.
8699 If you just want to invoke a different compiler or other tool
8700 to build a Program, Object, Library, or any other
8701 type of output file for which
8703 already has an existing Builder,
8704 it is generally much easier to
8705 use those existing Builders
8706 in a construction environment
8707 that sets the appropriate construction variables
8710 Builder objects are created
8716 function accepts the following arguments:
8719 The command line string used to build the target from the source.
8722 a list of strings representing the command
8723 to be executed and its arguments
8724 (suitable for enclosing white space in an argument),
8726 mapping source file name suffixes to
8727 any combination of command line strings
8728 (if the builder should accept multiple source file extensions),
8731 (see the next section);
8732 or a list of any of the above.
8735 takes three arguments:
8737 - a list of source nodes,
8739 - a list of target nodes,
8741 - the construction environment.
8744 The prefix that will be prepended to the target file name.
8745 This may be specified as a:
8755 - a function or other callable that takes
8756 two arguments (a construction environment and a list of sources)
8757 and returns a prefix,
8762 - specifies a mapping from a specific source suffix (of the first
8763 source specified) to a corresponding target prefix. Both the source
8764 suffix and target prefix specifications may use environment variable
8765 substitution, and the target prefix (the 'value' entries in the
8766 dictionary) may also be a callable object. The default target prefix
8767 may be indicated by a dictionary entry with a key value of None.
8772 b = Builder("build_it < $SOURCE > $TARGET"
8775 def gen_prefix(env, sources):
8776 return "file-" + env['PLATFORM'] + '-'
8777 b = Builder("build_it < $SOURCE > $TARGET",
8778 prefix = gen_prefix)
8780 b = Builder("build_it < $SOURCE > $TARGET",
8781 suffix = { None: "file-",
8782 "$SRC_SFX_A": gen_prefix })
8786 The suffix that will be appended to the target file name.
8787 This may be specified in the same manner as the prefix above.
8788 If the suffix is a string, then
8790 will append a '.' to the beginning of the suffix if it's not already
8791 there. The string returned by callable object (or obtained from the
8792 dictionary) is untouched and must append its own '.' to the beginning
8796 b = Builder("build_it < $SOURCE > $TARGET"
8799 def gen_suffix(env, sources):
8800 return "." + env['PLATFORM'] + "-file"
8801 b = Builder("build_it < $SOURCE > $TARGET",
8802 suffix = gen_suffix)
8804 b = Builder("build_it < $SOURCE > $TARGET",
8805 suffix = { None: ".sfx1",
8806 "$SRC_SFX_A": gen_suffix })
8810 The expected source file name suffix. This may be a string or a list
8814 A Scanner object that
8815 will be invoked to find
8816 implicit dependencies for this target file.
8817 This keyword argument should be used
8818 for Scanner objects that find
8819 implicit dependencies
8820 based only on the target file
8821 and the construction environment,
8824 (See the section "Scanner Objects," below,
8825 for information about creating Scanner objects.)
8828 A Scanner object that
8830 find implicit dependences in
8832 used to build this target file.
8833 This is where you would
8834 specify a scanner to
8837 lines in source files.
8840 Scanner object may be used to
8841 indicate that this Builder
8842 should scan directory trees
8843 for on-disk changes to files
8846 does not know about from other Builder or function calls.
8847 (See the section "Scanner Objects," below,
8848 for information about creating your own Scanner objects.)
8851 A factory function that the Builder will use
8852 to turn any targets specified as strings into SCons Nodes.
8854 SCons assumes that all targets are files.
8855 Other useful target_factory
8858 for when a Builder creates a directory target,
8861 for when a Builder can create either a file
8862 or directory target.
8867 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8869 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8870 env.MakeDirectory('new_directory', [])
8873 Note that the call to the MakeDirectory Builder
8874 needs to specify an empty source list
8875 to make the string represent the builder's target;
8876 without that, it would assume the argument is the source,
8877 and would try to deduce the target name from it,
8878 which in the absence of an automatically-added prefix or suffix
8879 would lead to a matching target and source name
8880 and a circular dependency.
8883 A factory function that the Builder will use
8884 to turn any sources specified as strings into SCons Nodes.
8886 SCons assumes that all source are files.
8887 Other useful source_factory
8890 for when a Builder uses a directory as a source,
8893 for when a Builder can use files
8894 or directories (or both) as sources.
8899 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8901 env.Append(BUILDERS = {'Collect':CollectBuilder})
8902 env.Collect('archive', ['directory_name', 'file_name'])
8906 A function or list of functions to manipulate the target and source
8907 lists before dependencies are established
8908 and the target(s) are actually built.
8910 can also be a string containing a construction variable to expand
8911 to an emitter function or list of functions,
8912 or a dictionary mapping source file suffixes
8913 to emitter functions.
8914 (Only the suffix of the first source file
8915 is used to select the actual emitter function
8916 from an emitter dictionary.)
8919 takes three arguments:
8921 - a list of source nodes,
8923 - a list of target nodes,
8925 - the construction environment.
8926 An emitter must return a tuple containing two lists,
8927 the list of targets to be built by this builder,
8928 and the list of sources for this builder.
8933 def e(target, source, env):
8934 return (target + ['foo.foo'], source + ['foo.src'])
8936 # Simple association of an emitter function with a Builder.
8937 b = Builder("my_build < $TARGET > $SOURCE",
8940 def e2(target, source, env):
8941 return (target + ['bar.foo'], source + ['bar.src'])
8943 # Simple association of a list of emitter functions with a Builder.
8944 b = Builder("my_build < $TARGET > $SOURCE",
8947 # Calling an emitter function through a construction variable.
8948 env = Environment(MY_EMITTER = e)
8949 b = Builder("my_build < $TARGET > $SOURCE",
8950 emitter = '$MY_EMITTER')
8952 # Calling a list of emitter functions through a construction variable.
8953 env = Environment(EMITTER_LIST = [e, e2])
8954 b = Builder("my_build < $TARGET > $SOURCE",
8955 emitter = '$EMITTER_LIST')
8957 # Associating multiple emitters with different file
8958 # suffixes using a dictionary.
8959 def e_suf1(target, source, env):
8960 return (target + ['another_target_file'], source)
8961 def e_suf2(target, source, env):
8962 return (target, source + ['another_source_file'])
8963 b = Builder("my_build < $TARGET > $SOURCE",
8964 emitter = {'.suf1' : e_suf1,
8969 Specifies whether this builder is allowed to be called multiple times for
8970 the same target file(s). The default is 0, which means the builder
8971 can not be called multiple times for the same target file(s). Calling a
8972 builder multiple times for the same target simply adds additional source
8973 files to the target; it is not allowed to change the environment associated
8974 with the target, specify addition environment overrides, or associate a different
8975 builder with the target.
8978 A construction environment that can be used
8979 to fetch source code using this Builder.
8980 (Note that this environment is
8982 used for normal builds of normal target files,
8983 which use the environment that was
8984 used to call the Builder for the target file.)
8987 A function that returns a list of actions that will be executed to build
8988 the target(s) from the source(s).
8989 The returned action(s) may be
8990 an Action object, or anything that
8991 can be converted into an Action object
8992 (see the next section).
8994 The generator function
8995 takes four arguments:
8997 - a list of source nodes,
8999 - a list of target nodes,
9001 - the construction environment,
9003 - a Boolean value that specifies
9004 whether the generator is being called
9005 for generating a build signature
9006 (as opposed to actually executing the command).
9010 def g(source, target, env, for_signature):
9011 return [["gcc", "-c", "-o"] + target + source]
9013 b = Builder(generator=g)
9021 arguments must not both be used for the same Builder.
9024 Specifies a builder to use when a source file name suffix does not match
9025 any of the suffixes of the builder. Using this argument produces a
9026 multi-stage builder.
9029 Specifies that this builder expects exactly one source file per call. Giving
9030 more than one source files without target files results in implicitely calling
9031 the builder multiple times (once for each source given). Giving multiple
9032 source files together with target files results in a UserError exception.
9040 arguments must not both be used for the same Builder.
9043 A construction environment that can be used
9044 to fetch source code using this Builder.
9045 (Note that this environment is
9047 used for normal builds of normal target files,
9048 which use the environment that was
9049 used to call the Builder for the target file.)
9052 b = Builder(action="build < $SOURCE > $TARGET")
9053 env = Environment(BUILDERS = {'MyBuild' : b})
9054 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
9058 A directory from which scons
9065 a string or a directory Node,
9066 scons will change to the specified directory.
9069 is not a string or Node
9071 then scons will change to the
9072 target file's directory.
9074 Note that scons will
9076 automatically modify
9078 construction variables like
9082 when using the chdir
9083 keyword argument--that is,
9084 the expanded file names
9085 will still be relative to
9086 the top-level SConstruct directory,
9087 and consequently incorrect
9088 relative to the chdir directory.
9089 Builders created using chdir keyword argument,
9090 will need to use construction variable
9095 to use just the filename portion of the
9099 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
9101 env = Environment(BUILDERS = {'MyBuild' : b})
9102 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
9106 Any additional keyword arguments supplied
9107 when a Builder object is created
9108 (that is, when the Builder() function is called)
9109 will be set in the executing construction
9110 environment when the Builder object is called.
9111 The canonical example here would be
9112 to set a construction variable to
9113 the repository of a source code system.
9115 Any additional keyword arguments supplied
9119 will only be associated with the target
9120 created by that particular Builder call
9121 (and any other files built as a
9122 result of the call).
9124 These extra keyword arguments are passed to the
9125 following functions:
9126 command generator functions,
9128 and emitter functions.
9134 function will turn its
9136 keyword argument into an appropriate
9137 internal Action object.
9138 You can also explicity create Action objects
9142 which can then be passed to the
9145 This can be used to configure
9146 an Action object more flexibly,
9147 or it may simply be more efficient
9148 than letting each separate Builder object
9149 create a separate Action
9151 Builder objects need to do the same thing.
9156 returns an appropriate object for the action
9157 represented by the type of the first argument:
9160 If the first argument is already an Action object,
9161 the object is simply returned.
9164 If the first argument is a string,
9165 a command-line Action is returned.
9166 Note that the command line string
9167 may be preceded by an
9170 to suppress printing of the
9171 specified command line,
9175 to ignore the exit status from
9176 the specified command.
9180 Action('$CC -c -o $TARGET $SOURCES')
9182 # Doesn't print the line being executed.
9183 Action('@build $TARGET $SOURCES')
9186 Action('-build $TARGET $SOURCES')
9189 .\" XXX From Gary Ruben, 23 April 2002:
9190 .\" What would be useful is a discussion of how you execute command
9191 .\" shell commands ie. what is the process used to spawn the shell, pass
9192 .\" environment variables to it etc., whether there is one shell per
9193 .\" environment or one per command etc. It might help to look at the Gnu
9194 .\" make documentation to see what they think is important to discuss about
9195 .\" a build system. I'm sure you can do a better job of organising the
9196 .\" documentation than they have :-)
9200 If the first argument is a list,
9201 then a list of Action objects is returned.
9202 An Action object is created as necessary
9203 for each element in the list.
9206 the list is itself a list,
9207 the internal list is the
9208 command and arguments to be executed via
9210 This allows white space to be enclosed
9211 in an argument by defining
9212 a command in a list within a list:
9215 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
9219 If the first argument is a Python function,
9220 a function Action is returned.
9221 The Python function takes three keyword arguments,
9223 (a Node object representing the target file),
9225 (a Node object representing the source file)
9228 (the construction environment
9229 used for building the target file).
9234 arguments may be lists of Node objects if there is
9235 more than one target file or source file.
9236 The actual target and source file name(s) may
9237 be retrieved from their Node objects
9238 via the built-in Python str() function:
9241 target_file_name = str(target)
9242 source_file_names = map(lambda x: str(x), source)
9245 The function should return
9249 to indicate a successful build of the target file(s).
9250 The function may raise an exception
9251 or return a non-zero exit status
9252 to indicate an unsuccessful build.
9255 def build_it(target = None, source = None, env = None):
9256 # build the target from the source
9259 a = Action(build_it)
9262 If the action argument is not one of the above,
9265 The second, optional argument
9266 is a Python function that returns
9267 a string to be printed to describe the action being executed.
9268 Like a function to build a file,
9269 this function takes three arguments:
9271 (a Node object representing the target file),
9273 (a Node object representing the source file)
9276 (a construction environment).
9281 arguments may be lists of Node objects if there is
9282 more than one target file or source file.
9286 def build_it(target, source, env):
9287 # build the target from the source
9290 def string_it(target, source, env):
9291 return "building '%s' from '%s'" % (target[0], source[0])
9293 # Use a positional argument.
9294 a = Action(build_it, string_it)
9296 # Alternatively, use a keyword argument.
9297 a = Action(build_it, strfunction=string_it)
9300 The third, also optional argument
9301 is a list of construction variables
9302 whose values will be included
9303 in the signature of the Action
9304 when deciding whether a target should
9305 be rebuilt because the action changed.
9306 This is necessary whenever you want a target to
9307 be rebuilt when a specific
9308 construction variable changes,
9309 because the underlying Python code for a function
9310 will not change when the value of the construction variable does.
9313 def build_it(target, source, env):
9314 # build the target from the 'XXX' construction variable
9315 open(target[0], 'w').write(env['XXX'])
9318 def string_it(target, source):
9319 return "building '%s' from '%s'" % (target[0], source[0])
9321 # Use positional arguments.
9322 a = Action(build_it, string_it, ['XXX'])
9324 # Alternatively, use a keyword argument.
9325 a = Action(build_it, varlist=['XXX'])
9335 which specifies that
9336 scons will execute the action
9337 after changing to the specified directory.
9338 If the chdir argument is
9339 a string or a directory Node,
9340 scons will change to the specified directory.
9341 If the chdir argument
9342 is not a string or Node
9344 then scons will change to the
9345 target file's directory.
9347 Note that scons will
9349 automatically modify
9351 construction variables like
9355 when using the chdir
9356 keyword argument--that is,
9357 the expanded file names
9358 will still be relative to
9359 the top-level SConstruct directory,
9360 and consequently incorrect
9361 relative to the chdir directory.
9362 Builders created using chdir keyword argument,
9363 will need to use construction variable
9368 to use just the filename portion of the
9372 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9382 which specifies a function
9383 that is passed the exit status
9385 from the specified action
9386 and can return an arbitrary
9388 This can be used, for example,
9389 to specify that an Action object's
9390 return value should be ignored
9391 and SCons should, therefore,
9392 consider that the action always suceeds:
9395 def always_succeed(s):
9396 # Always return 0, which indicates success.
9398 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9399 exitstatfunc=always_succeed)
9402 .SS Miscellaneous Action Functions
9405 supplies a number of functions
9406 that arrange for various common
9407 file and directory manipulations
9409 These are similar in concept to "tasks" in the
9411 although the implementation is slightly different.
9412 These functions do not actually
9413 perform the specified action
9414 at the time the function is called,
9415 but instead return an Action object
9416 that can be executed at the
9418 (In Object-Oriented terminology,
9423 that return Action objects.)
9426 there are two natural ways
9429 are intended to be used.
9433 to perform the action
9434 at the time the SConscript
9438 global function to do so:
9440 Execute(Touch('file'))
9444 you can use these functions
9445 to supply Actions in a list
9449 This can allow you to
9450 perform more complicated
9451 sequences of file manipulation
9453 on platform-specific
9457 env = Environment(TMPBUILD = '/tmp/builddir')
9458 env.Command('foo.out', 'foo.in',
9459 [Mkdir('$TMPBUILD'),
9460 Copy('$TMPBUILD', '${SOURCE.dir}')
9461 "cd $TMPBUILD && make",
9462 Delete('$TMPBUILD')])
9466 .RI Chmod( dest ", " mode )
9467 Returns an Action object that
9468 changes the permissions on the specified
9470 file or directory to the specified
9475 Execute(Chmod('file', 0755))
9477 env.Command('foo.out', 'foo.in',
9478 [Copy('$TARGET', '$SOURCE'),
9479 Chmod('$TARGET', 0755)])
9483 .RI Copy( dest ", " src )
9484 Returns an Action object
9487 source file or directory to the
9489 destination file or directory.
9493 Execute(Copy('foo.output', 'foo.input'))
9495 env.Command('bar.out', 'bar.in',
9496 Copy('$TARGET', '$SOURCE'))
9500 .RI Delete( entry ", [" must_exist ])
9501 Returns an Action that
9502 deletes the specified
9504 which may be a file or a directory tree.
9505 If a directory is specified,
9506 the entire directory tree
9511 then a Python error will be thrown
9512 if the specified entry does not exist;
9515 that is, the Action will silently do nothing
9516 if the entry does not exist.
9520 Execute(Delete('/tmp/buildroot'))
9522 env.Command('foo.out', 'foo.in',
9523 [Delete('${TARGET.dir}'),
9526 Execute(Delete('file_that_must_exist', must_exist=1))
9532 that creates the specified
9538 Execute(Mkdir('/tmp/outputdir'))
9540 env.Command('foo.out', 'foo.in',
9541 [Mkdir('/tmp/builddir',
9542 Copy('$SOURCE', '/tmp/builddir')
9543 "cd /tmp/builddir && ])
9548 .RI Move( dest ", " src )
9550 that moves the specified
9552 file or directory to
9559 Execute(Move('file.destination', 'file.source'))
9561 env.Command('output_file', 'input_file',
9563 Move('$TARGET', 'file_created_by_MyBuildAction')])
9569 that updates the modification time
9575 Execute(Touch('file_to_be_touched'))
9577 env.Command('marker', 'input_file',
9582 .SS Variable Substitution
9584 Before executing a command,
9586 performs construction variable interpolation on the strings that make up
9587 the command line of builders.
9588 Variables are introduced by a
9591 Besides construction variables, scons provides the following
9592 variables for each command execution:
9595 The file name of the target being built, or the file name of the first
9596 target if multiple targets are being built.
9599 The file names of all targets being built.
9602 The file name of the source of the build command, or the file name of the
9603 first source if multiple sources are being built.
9606 The file names of the sources of the build command.
9608 (Note that the above variables are reserved
9609 and may not be set in a construction environment.)
9612 For example, given the construction variable CC='cc', targets=['foo'], and
9613 sources=['foo.c', 'bar.c']:
9616 action='$CC -c -o $TARGET $SOURCES'
9619 would produce the command line:
9622 cc -c -o foo foo.c bar.c
9625 Variable names may be surrounded by curly braces ({})
9626 to separate the name from the trailing characters.
9627 Within the curly braces, a variable name may have
9628 a Python slice subscript appended to select one
9629 or more items from a list.
9630 In the previous example, the string:
9642 Additionally, a variable name may
9643 have the following special
9644 modifiers appended within the enclosing curly braces
9645 to modify the interpolated string:
9648 The base path of the file name,
9649 including the directory path
9650 but excluding any suffix.
9653 The name of the directory in which the file exists.
9657 minus any directory portion.
9660 Just the basename of the file,
9662 and minus the directory.
9665 Just the file suffix.
9668 The absolute path name of the file.
9671 The POSIX form of the path,
9672 with directories separated by
9676 This is sometimes necessary on Win32 systems
9677 when a path references a file on other (POSIX) systems.
9680 The directory and file name to the source file linked to this file
9681 through BuildDir. If this file isn't linked, it just returns the
9682 directory and filename unchanged.
9685 The directory containing the source file linked to this file
9686 through BuildDir. If this file isn't linked, it just returns the
9687 directory part of the filename.
9690 The directory and file name to the source file linked to this file
9691 through BuildDir. If the file does not exist locally but exists in
9692 a Repository, the path in the Repository is returned.
9693 If this file isn't linked, it just returns the
9694 directory and filename unchanged.
9697 The Repository directory containing the source file linked to this file
9698 through BuildDir. If this file isn't linked, it just returns the
9699 directory part of the filename.
9702 For example, the specified target will
9703 expand as follows for the corresponding modifiers:
9706 $TARGET => sub/dir/file.x
9707 ${TARGET.base} => sub/dir/file
9708 ${TARGET.dir} => sub/dir
9709 ${TARGET.file} => file.x
9710 ${TARGET.filebase} => file
9711 ${TARGET.suffix} => .x
9712 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9714 SConscript('src/SConscript', build_dir='sub/dir')
9715 $SOURCE => sub/dir/file.x
9716 ${SOURCE.srcpath} => src/file.x
9717 ${SOURCE.srcdir} => src
9719 Repository('/usr/repository')
9720 $SOURCE => sub/dir/file.x
9721 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9722 ${SOURCE.rsrcdir} => /usr/repository/src
9725 Lastly, a variable name
9726 may be a callable Python function
9728 construction variable in the environment.
9730 take four arguments:
9732 - a list of target nodes,
9734 - a list of source nodes,
9736 - the construction environment,
9738 - a Boolean value that specifies
9739 whether the function is being called
9740 for generating a build signature.
9741 SCons will insert whatever
9742 the called function returns
9743 into the expanded string:
9746 def foo(target, source, env, for_signature):
9749 # Will expand $BAR to "bar baz"
9750 env=Environment(FOO=foo, BAR="$FOO baz")
9753 You can use this feature to pass arguments to a
9754 Python function by creating a callable class
9755 that stores one or more arguments in an object,
9756 and then uses them when the
9759 Note that in this case,
9760 the entire variable expansion must
9761 be enclosed by curly braces
9762 so that the arguments will
9763 be associated with the
9764 instantiation of the class:
9768 def __init__(self, arg):
9771 def __call__(self, target, source, env, for_signature):
9774 # Will expand $BAR to "my argument bar baz"
9775 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9779 The special pseudo-variables
9783 may be used to surround parts of a command line
9786 causing a rebuild--that is,
9787 which are not included in the signature
9788 of target files built with this command.
9793 will be removed from the command line
9794 before it is added to file signatures,
9799 will be removed before the command is executed.
9800 For example, the command line:
9803 echo Last build occurred $( $TODAY $). > $TARGET
9807 would execute the command:
9810 echo Last build occurred $TODAY. > $TARGET
9814 but the command signature added to any target files would be:
9817 echo Last build occurred . > $TARGET
9820 SCons uses the following rules when converting construction variables into
9824 When the value is a string it is interpreted as a space delimited list of
9825 command line arguments.
9828 When the value is a list it is interpreted as a list of command line
9829 arguments. Each element of the list is converted to a string.
9832 Anything that is not a list or string is converted to a string and
9833 interpreted as a single command line argument.
9836 Newline characters (\\n) delimit lines. The newline parsing is done after
9837 all other parsing, so it is not possible for arguments (e.g. file names) to
9838 contain embedded newline characters. This limitation will likely go away in
9839 a future version of SCons.
9847 new file types for implicit dependencies.
9848 Scanner accepts the following arguments:
9851 A Python function that will process
9853 and return a list of strings (file names)
9854 representing the implicit
9855 dependencies found in the contents.
9856 The function takes three or four arguments:
9858 def scanner_function(node, env, path):
9860 def scanner_function(node, env, path, arg):
9864 argument is the internal
9865 SCons node representing the file.
9868 to fetch the name of the file, and
9869 .B node.get_contents()
9870 to fetch contents of the file.
9874 argument is the construction environment for the scan.
9875 Fetch values from it using the
9881 argument is a tuple (or list)
9882 of directories that can be searched
9884 This will usually be the tuple returned by the
9886 argument (see below).
9890 argument is the argument supplied
9891 when the scanner was created, if any.
9894 The name of the Scanner.
9896 to identify the Scanner internally.
9899 An optional argument that, if specified,
9900 will be passed to the scanner function
9902 and the path function
9906 An optional list that can be used to
9907 determine which scanner should be used for
9909 In the usual case of scanning for file names,
9910 this argument will be a list of suffixes
9911 for the different file types that this
9912 Scanner knows how to scan.
9913 If the argument is a string,
9914 then it will be expanded
9915 into a list by the current environment.
9918 A Python function that takes
9919 two or three arguments:
9920 a construction environment, directory Node,
9921 and optional argument supplied
9922 when the scanner was created.
9925 returns a tuple of directories
9926 that can be searched for files to be returned
9927 by this Scanner object.
9930 The class of Node that should be returned
9931 by this Scanner object.
9932 Any strings or other objects returned
9933 by the scanner function
9934 that are not of this class
9935 will be run through the
9940 A Python function that will take a string
9942 and turn it into the appropriate class of Node
9943 to be returned by this Scanner object.
9946 An optional Python function that takes two arguments,
9947 a Node (file) and a construction environment,
9948 and returns whether the
9949 Node should, in fact,
9950 be scanned for dependencies.
9951 This check can be used to eliminate unnecessary
9952 calls to the scanner function when,
9953 for example, the underlying file
9954 represented by a Node does not yet exist.
9957 An optional flag that
9958 specifies whether this scanner should be re-invoked
9959 on the dependency files returned by the scanner.
9960 When this flag is not set,
9961 the Node subsystem will
9962 only invoke the scanner on the file being scanned,
9963 and not (for example) also on the files
9964 specified by the #include lines
9965 in the file being scanned.
9967 may be a callable function,
9968 in which case it will be called with a list of
9970 should return a list of Nodes
9971 that should be scanned recursively;
9972 this can be used to select a specific subset of
9973 Nodes for additional scanning.
9978 .B SourceFileScanner
9979 object that is used by
9982 .BR SharedObject (),
9986 which scanner should be used
9987 for different file extensions.
9989 .BR SourceFileScanner.add_scanner ()
9990 method to add your own Scanner object
9994 that builds target programs or
9995 libraries from a list of
9996 source files of different types:
9999 def xyz_scan(node, env, path):
10000 contents = node.get_contents()
10001 # Scan the contents and return the included files.
10003 XYZScanner = Scanner(xyz_scan)
10005 SourceFileScanner.add_scanner('.xyx', XYZScanner)
10007 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
10010 .SH SYSTEM-SPECIFIC BEHAVIOR
10011 SCons and its configuration files are very portable,
10012 due largely to its implementation in Python.
10013 There are, however, a few portability
10014 issues waiting to trap the unwary.
10016 SCons handles the upper-case
10018 file suffix differently,
10019 depending on the capabilities of
10020 the underlying system.
10021 On a case-sensitive system
10022 such as Linux or UNIX,
10023 SCons treats a file with a
10025 suffix as a C++ source file.
10026 On a case-insensitive system
10028 SCons treats a file with a
10030 suffix as a C source file.
10032 SCons handles the upper-case
10034 file suffix differently,
10035 depending on the capabilities of
10036 the underlying system.
10037 On a case-sensitive system
10038 such as Linux or UNIX,
10039 SCons treats a file with a
10041 suffix as a Fortran source file
10042 that is to be first run through
10043 the standard C preprocessor.
10044 On a case-insensitive system
10046 SCons treats a file with a
10048 suffix as a Fortran source file that should
10050 be run through the C preprocessor.
10051 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
10052 Cygwin supplies a set of tools and utilities
10053 that let users work on a
10054 Windows system using a more POSIX-like environment.
10055 The Cygwin tools, including Cygwin Python,
10057 by sharing an ability to interpret UNIX-like path names.
10058 For example, the Cygwin tools
10059 will internally translate a Cygwin path name
10060 like /cygdrive/c/mydir
10061 to an equivalent Windows pathname
10062 of C:/mydir (equivalent to C:\\mydir).
10065 that are built for native Windows execution,
10066 such as the python.org and ActiveState versions,
10067 do not have the Cygwin path name semantics.
10068 This means that using a native Windows version of Python
10069 to build compiled programs using Cygwin tools
10070 (such as gcc, bison, and flex)
10071 may yield unpredictable results.
10072 "Mixing and matching" in this way
10073 can be made to work,
10074 but it requires careful attention to the use of path names
10075 in your SConscript files.
10077 In practice, users can sidestep
10078 the issue by adopting the following rules:
10080 use the Cygwin-supplied Python interpreter
10082 when using Microsoft Visual C/C++
10083 (or some other Windows compiler)
10084 use the python.org or ActiveState version of Python
10086 .SS WIN32: scons.bat file
10088 SCons is executed via a wrapper
10091 This has (at least) two ramifications:
10093 First, Windows command-line users
10094 that want to use variable assignment
10095 on the command line
10096 may have to put double quotes
10097 around the assignments:
10100 scons "FOO=BAR" "BAZ=BLEH"
10103 Second, the Cygwin shell does not
10104 recognize this file as being the same
10107 command issued at the command-line prompt.
10108 You can work around this either by
10111 from the Cygwin command line,
10112 or by creating a wrapper shell
10118 The MinGW bin directory must be in your PATH environment variable or the
10119 PATH variable under the ENV construction variable for SCons
10120 to detect and use the MinGW tools. When running under the native Windows
10121 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
10122 tools, if they are both installed, regardless of the order of the bin
10123 directories in the PATH variable. If you have both MSVC and MinGW
10124 installed and you want to use MinGW instead of MSVC,
10125 then you must explictly tell SCons to use MinGW by passing
10131 to the Environment() function, because SCons will prefer the MSVC tools
10132 over the MinGW tools.
10136 To help you get started using SCons,
10137 this section contains a brief overview of some common tasks.
10139 .SS Basic Compilation From a Single Source File
10142 env = Environment()
10143 env.Program(target = 'foo', source = 'foo.c')
10146 Note: Build the file by specifying
10147 the target as an argument
10148 ("scons foo" or "scons foo.exe").
10149 or by specifying a dot ("scons .").
10151 .SS Basic Compilation From Multiple Source Files
10154 env = Environment()
10155 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
10158 .SS Setting a Compilation Flag
10161 env = Environment(CCFLAGS = '-g')
10162 env.Program(target = 'foo', source = 'foo.c')
10165 .SS Search The Local Directory For .h Files
10169 need to set CCFLAGS to specify -I options by hand.
10170 SCons will construct the right -I options from CPPPATH.
10173 env = Environment(CPPPATH = ['.'])
10174 env.Program(target = 'foo', source = 'foo.c')
10177 .SS Search Multiple Directories For .h Files
10180 env = Environment(CPPPATH = ['include1', 'include2'])
10181 env.Program(target = 'foo', source = 'foo.c')
10184 .SS Building a Static Library
10187 env = Environment()
10188 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
10189 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
10192 .SS Building a Shared Library
10195 env = Environment()
10196 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
10197 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
10200 .SS Linking a Local Library Into a Program
10203 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
10204 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
10205 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
10208 .SS Defining Your Own Builder Object
10210 Notice that when you invoke the Builder,
10211 you can leave off the target file suffix,
10212 and SCons will add it automatically.
10215 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10217 src_suffix = '.tex')
10218 env = Environment(BUILDERS = {'PDFBuilder' : bld})
10219 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10221 # The following creates "bar.pdf" from "bar.tex"
10222 env.PDFBuilder(target = 'bar', source = 'bar')
10225 Note also that the above initialization
10226 overwrites the default Builder objects,
10227 so the Environment created above
10228 can not be used call Builders like env.Program(),
10229 env.Object(), env.StaticLibrary(), etc.
10231 .SS Adding Your Own Builder Object to an Environment
10234 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10236 src_suffix = '.tex')
10237 env = Environment()
10238 env.Append(BUILDERS = {'PDFBuilder' : bld})
10239 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10240 env.Program(target = 'bar', source = 'bar.c')
10243 You also can use other Pythonic techniques to add
10244 to the BUILDERS construction variable, such as:
10247 env = Environment()
10248 env['BUILDERS]['PDFBuilder'] = bld
10251 .SS Defining Your Own Scanner Object
10256 '\" Note: the \\ in the following are for the benefit of nroff/troff,
10257 '\" not inappropriate doubled escape characters within the r'' raw string.
10258 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
10260 def kfile_scan(node, env, path, arg):
10261 contents = node.get_contents()
10262 includes = include_re.findall(contents)
10265 kscan = Scanner(name = 'kfile',
10266 function = kfile_scan,
10269 scanners = Environment().Dictionary('SCANNERS')
10270 env = Environment(SCANNERS = scanners + [kscan])
10272 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
10274 bar_in = File('bar.in')
10275 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
10276 bar_in.target_scanner = kscan
10279 .SS Creating a Hierarchical Build
10281 Notice that the file names specified in a subdirectory's
10283 file are relative to that subdirectory.
10288 env = Environment()
10289 env.Program(target = 'foo', source = 'foo.c')
10291 SConscript('sub/SConscript')
10295 env = Environment()
10296 # Builds sub/foo from sub/foo.c
10297 env.Program(target = 'foo', source = 'foo.c')
10299 SConscript('dir/SConscript')
10301 sub/dir/SConscript:
10303 env = Environment()
10304 # Builds sub/dir/foo from sub/dir/foo.c
10305 env.Program(target = 'foo', source = 'foo.c')
10308 .SS Sharing Variables Between SConscript Files
10310 You must explicitly Export() and Import() variables that
10311 you want to share between SConscript files.
10316 env = Environment()
10317 env.Program(target = 'foo', source = 'foo.c')
10320 SConscript('subdirectory/SConscript')
10322 subdirectory/SConscript:
10325 env.Program(target = 'foo', source = 'foo.c')
10328 .SS Building Multiple Variants From the Same Source
10330 Use the build_dir keyword argument to
10331 the SConscript function to establish
10332 one or more separate build directories for
10333 a given source directory:
10338 cppdefines = ['FOO']
10339 Export("cppdefines")
10340 SConscript('src/SConscript', build_dir='foo')
10342 cppdefines = ['BAR']
10343 Export("cppdefines")
10344 SConscript('src/SConscript', build_dir='bar')
10348 Import("cppdefines")
10349 env = Environment(CPPDEFINES = cppdefines)
10350 env.Program(target = 'src', source = 'src.c')
10353 Note the use of the Export() method
10354 to set the "cppdefines" variable to a different
10355 value each time we call the SConscript function.
10357 .SS Hierarchical Build of Two Libraries Linked With a Program
10362 env = Environment(LIBPATH = ['#libA', '#libB'])
10364 SConscript('libA/SConscript')
10365 SConscript('libB/SConscript')
10366 SConscript('Main/SConscript')
10371 env.Library('a', Split('a1.c a2.c a3.c'))
10376 env.Library('b', Split('b1.c b2.c b3.c'))
10381 e = env.Copy(LIBS = ['a', 'b'])
10382 e.Program('foo', Split('m1.c m2.c m3.c'))
10385 The '#' in the LIBPATH directories specify that they're relative to the
10386 top-level directory, so they don't turn into "Main/libA" when they're
10387 used in Main/SConscript.
10389 Specifying only 'a' and 'b' for the library names
10390 allows SCons to append the appropriate library
10391 prefix and suffix for the current platform
10392 (for example, 'liba.a' on POSIX systems,
10393 'a.lib' on Windows).
10395 .SS Customizing contruction variables from the command line.
10397 The following would allow the C compiler to be specified on the command
10398 line or in the file custom.py.
10401 opts = Options('custom.py')
10402 opts.Add('CC', 'The C compiler.')
10403 env = Environment(options=opts)
10404 Help(opts.GenerateHelpText(env))
10407 The user could specify the C compiler on the command line:
10413 or in the custom.py file:
10419 or get documentation on the options:
10424 CC: The C compiler.
10430 .SS Using Microsoft Visual C++ precompiled headers
10432 Since windows.h includes everything and the kitchen sink, it can take quite
10433 some time to compile it over and over again for a bunch of object files, so
10434 Microsoft provides a mechanism to compile a set of headers once and then
10435 include the previously compiled headers in any object file. This
10436 technology is called precompiled headers. The general recipe is to create a
10437 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
10438 then include every header you want to precompile in "StdAfx.h", and finally
10439 include "StdAfx.h" as the first header in all the source files you are
10440 compiling to object files. For example:
10444 #include <windows.h>
10445 #include <my_big_header.h>
10450 #include <StdAfx.h>
10455 #include <StdAfx.h>
10457 /* do some stuff */
10462 #include <StdAfx.h>
10464 /* do some other stuff */
10470 env['PCHSTOP'] = 'StdAfx.h'
10471 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10472 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10475 For more information see the document for the PCH builder, and the PCH and
10476 PCHSTOP construction variables. To learn about the details of precompiled
10477 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10479 .SS Using Microsoft Visual C++ external debugging information
10481 Since including debugging information in programs and shared libraries can
10482 cause their size to increase significantly, Microsoft provides a mechanism
10483 for including the debugging information in an external file called a PDB
10484 file. SCons supports PDB files through the PDB construction
10490 env['PDB'] = 'MyApp.pdb'
10491 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10494 For more information see the document for the PDB construction variable.
10499 Specifies the directory that contains the SCons Python module directory
10500 (e.g. /home/aroach/scons-src-0.01/src/engine).
10503 A string of options that will be used by scons in addition to those passed
10504 on the command line.
10515 Steven Knight <knight@baldmt.com>
10517 Anthony Roach <aroach@electriceyeball.com>