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 file and invoke the $BIBTEX command line
1580 start $MAKEINDEX to generate an index if a
1583 and will examine the contents
1585 file and re-run the $LATEXCOM command
1586 if the log file says it is necessary.
1589 (hard-coded within TeX itself)
1590 is automatically added to the target
1591 if it is not already present. Examples:
1594 # builds from aaa.tex
1595 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1597 env.DVI(target = 'bbb', source = 'bbb.ltx')
1598 # builds from ccc.latex
1599 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1602 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1605 Builds a Java archive (.jar) file
1606 from a source tree of .class files.
1607 If the $JARCHDIR value is set, the
1609 command will change to the specified directory using the
1612 If the contents any of the source files begin with the string
1613 .BR Manifest-Version ,
1614 the file is assumed to be a manifest
1615 and is passed to the
1622 env.Jar(target = 'foo.jar', source = 'classes')
1625 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1628 Builds one or more Java class files
1629 from one or more source trees of .java files.
1630 The class files will be placed underneath
1631 the specified target directory.
1632 SCons will parse each source .java file
1634 (including inner classes)
1635 defined within that file,
1636 and from that figure out the
1637 target .class files that will be created.
1638 SCons will also search each Java file
1639 for the Java package name,
1640 which it assumes can be found on a line
1641 beginning with the string
1643 in the first column;
1644 the resulting .class files
1645 will be placed in a directory reflecting
1646 the specified package name.
1650 defining a single public
1653 containing a package name of
1655 will generate a corresponding
1656 .IR sub/dir/Foo.class
1662 env.Java(target = 'classes', source = 'src')
1663 env.Java(target = 'classes', source = ['src1', 'src2'])
1666 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1669 Builds C header and source files for
1670 implementing Java native methods.
1671 The target can be either a directory
1672 in which the header files will be written,
1673 or a header file name which
1674 will contain all of the definitions.
1675 The source can be either the names of .class files,
1676 or the objects returned from the
1680 If the construction variable
1682 is set, either in the environment
1683 or in the call to the
1685 builder method itself,
1686 then the value of the variable
1687 will be stripped from the
1688 beginning of any .class file names.
1693 # builds java_native.h
1694 classes = env.Java(target = 'classdir', source = 'src')
1695 env.JavaH(target = 'java_native.h', source = classes)
1697 # builds include/package_foo.h and include/package_bar.h
1698 env.JavaH(target = 'include',
1699 source = ['package/foo.class', 'package/bar.class'])
1701 # builds export/foo.h and export/bar.h
1702 env.JavaH(target = 'export',
1703 source = ['classes/foo.class', 'classes/bar.class'],
1704 JAVACLASSDIR = 'classes')
1707 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1714 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1715 .IP LoadableModule()
1716 .IP env.LoadableModule()
1719 .BR SharedLibrary ().
1720 On Mac OS X (Darwin) platforms,
1721 this creates a loadable module bundle.
1724 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1727 Builds an output file from an M4 input file.
1728 This uses a default $M4FLAGS value of
1730 which considers all warnings to be fatal
1731 and stops on the first warning
1732 when using the GNU version of m4.
1736 env.M4(target = 'foo.c', source = 'foo.c.m4')
1739 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1742 Builds an output file from a moc input file. Moc input files are either
1743 header files or cxx files. This builder is only available after using the
1744 tool 'qt'. See the QTDIR variable for more information.
1748 env.Moc('foo.h') # generates moc_foo.cc
1749 env.Moc('foo.cpp') # generates foo.moc
1752 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1754 .IP env.MSVSProject()
1755 Builds a Microsoft Visual Studio project file,
1756 and by default builds a solution file as well.
1758 This builds a Visual Studio project file, based on the version of
1759 Visual Studio that is configured (either the latest installed version,
1760 or the version specified by
1762 in the construction environment).
1763 For Visual Studio 6, it will generate a
1766 For Visual Studio 7 (.NET), it will
1772 this also generates a solution file
1773 for the specified project,
1776 file for Visual Studio 6
1779 file for Visual Studio 7 (.NET).
1780 This behavior may be disabled by specifying
1781 .B auto_build_solution=0
1784 in which case you presumably want to
1785 build the solution file(s)
1788 Builder (see below).
1790 It takes several lists of filenames to be placed into the project
1792 These are currently limited to
1799 These are pretty self-explanatory, but it should be noted that these
1800 lists are added to the $SOURCES construction variable as strings,
1801 NOT as SCons File Nodes. This is because they represent file
1802 names to be added to the project file, not the source files used to
1803 build the project file.
1805 In addition to the above lists of values (which are all optional,
1806 although not specifying any of them results in an empty project file),
1807 the following values may be specified:
1810 The name of the target
1816 suffix for the version of Visual Studio must be used, but the
1817 .B env['MSVSPROJECTSUFFIX']
1818 construction variable
1819 will be defined to the correct value (see example below).
1822 The name of this particular variant.
1823 For Visual Studio 7 projects,
1824 this can also be a list of variant names.
1825 These are typically things like "Debug" or "Release", but really
1826 can be anything you want.
1827 For Visual Studio 7 projects,
1828 they may also specify a target platform
1829 separated from the variant name by a
1834 The default target platform is Win32.
1837 with different variants are allowed;
1838 all variants will be added to the project file with their appropriate
1839 build targets and sources.
1842 An optional string, node, or list of strings or nodes
1843 (one per build variant), to tell the Visual Studio debugger
1844 what output target to use in what build variant.
1847 entries must match the number of
1854 barsrcs = ['bar.cpp'],
1855 barincs = ['bar.h'],
1856 barlocalincs = ['StdAfx.h']
1857 barresources = ['bar.rc','resource.h']
1858 barmisc = ['bar_readme.txt']
1860 dll = local.SharedLibrary(target = 'bar.dll',
1863 local.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1866 localincs = barlocalincs,
1867 resources = barresources,
1870 variant = 'Release')
1873 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1875 .IP env.MSVSSolution()
1876 Builds a Microsoft Visual Studio solution file.
1878 This builds a Visual Studio solution file,
1879 based on the version of Visual Studio that is configured
1880 (either the latest installed version,
1881 or the version specified by
1883 in the construction environment).
1884 For Visual Studio 6, it will generate a
1887 For Visual Studio 7 (.NET), it will
1892 The following values must be specified:
1895 The name of the target .dsw or .sln file. The correct
1896 suffix for the version of Visual Studio must be used, but the value
1897 .B env['MSVSSOLUTIONSUFFIX']
1898 will be defined to the correct value (see example below).
1901 The name of this particular variant, or a list of variant
1902 names (the latter is only supported for MSVS 7 solutions). These are
1903 typically things like "Debug" or "Release", but really can be anything
1904 you want. For MSVS 7 they may also specify target platform, like this
1905 "Debug|Xbox". Default platform is Win32.
1908 A list of project file names, or Project nodes returned by calls to the
1911 to be placed into the solution file.
1912 (NOTE: Currently only one project is supported per solution.)
1913 It should be noted that these file names are NOT added to the $SOURCES
1914 environment variable in form of files, but rather as strings. This
1915 is because they represent file names to be added to the solution file,
1916 not the source files used to build the solution file.
1921 local.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
1922 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
1923 variant = 'Release')
1926 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1933 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1936 Builds a Microsoft Visual C++ precompiled header.
1937 Calling this builder method
1938 returns a list of two targets: the PCH as the first element, and the object
1939 file as the second element. Normally the object file is ignored.
1940 This builder method is only
1941 provided when Microsoft Visual C++ is being used as the compiler.
1942 The PCH builder method is generally used in
1943 conjuction with the PCH construction variable to force object files to use
1944 the precompiled header:
1947 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1950 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1953 Builds a .pdf file from a .dvi input file
1954 (or, by extension, a .tex, .ltx, or .latex input file).
1955 The suffix specified by the $PDFSUFFIX construction variable
1957 is added automatically to the target
1958 if it is not already present. Example:
1961 # builds from aaa.tex
1962 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1963 # builds bbb.pdf from bbb.dvi
1964 env.PDF(target = 'bbb', source = 'bbb.dvi')
1967 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1969 .IP env.PostScript()
1970 Builds a .ps file from a .dvi input file
1971 (or, by extension, a .tex, .ltx, or .latex input file).
1972 The suffix specified by the $PSSUFFIX construction variable
1974 is added automatically to the target
1975 if it is not already present. Example:
1978 # builds from aaa.tex
1979 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1980 # builds bbb.ps from bbb.dvi
1981 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1984 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
1987 Builds an executable given one or more object files
1988 or C, C++, D, or Fortran source files.
1989 If any C, C++, D or Fortran source files are specified,
1990 then they will be automatically
1991 compiled to object files using the
1994 see that builder method's description for
1995 a list of legal source file suffixes
1996 and how they are interpreted.
1997 The target executable file prefix
1998 (specified by the $PROGPREFIX construction variable; nothing by default)
2000 (specified by the $PROGSUFFIX construction variable;
2001 by default, .exe on Windows systems, nothing on POSIX systems)
2002 are automatically added to the target if not already present.
2006 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
2009 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2012 Builds a Microsoft Visual C++ resource file.
2013 This builder method is only provided
2014 when Microsoft Visual C++ or MinGW is being used as the compiler. The
2018 for MinGW) suffix is added to the target name if no other suffix is given. The source
2019 file is scanned for implicit dependencies as though it were a C file. Example:
2022 env.RES('resource.rc')
2025 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2028 Builds stub and skeleton class files
2030 from Java .class files.
2031 The target is a directory
2032 relative to which the stub
2033 and skeleton class files will be written.
2034 The source can be the names of .class files,
2035 or the objects return from the
2039 If the construction variable
2041 is set, either in the environment
2042 or in the call to the
2044 builder method itself,
2045 then the value of the variable
2046 will be stripped from the
2047 beginning of any .class file names.
2050 classes = env.Java(target = 'classdir', source = 'src')
2051 env.RMIC(target = 'outdir1', source = classes)
2053 env.RMIC(target = 'outdir2',
2054 source = ['package/foo.class', 'package/bar.class'])
2056 env.RMIC(target = 'outdir3',
2057 source = ['classes/foo.class', 'classes/bar.class'],
2058 JAVACLASSDIR = 'classes')
2061 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2063 .IP env.RPCGenClient()
2064 Generates an RPC client stub (_clnt.c) file
2065 from a specified RPC (.x) source file.
2066 Because rpcgen only builds output files
2067 in the local directory,
2068 the command will be executed
2069 in the source file's directory by default.
2072 # Builds src/rpcif_clnt.c
2073 env.RPCGenClient('src/rpcif.x')
2076 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2078 .IP env.RPCGenHeader()
2079 Generates an RPC header (.h) file
2080 from a specified RPC (.x) source file.
2081 Because rpcgen only builds output files
2082 in the local directory,
2083 the command will be executed
2084 in the source file's directory by default.
2087 # Builds src/rpcif.h
2088 env.RPCGenHeader('src/rpcif.x')
2091 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2093 .IP env.RPCGenService()
2094 Generates an RPC server-skeleton (_svc.c) file
2095 from a specified RPC (.x) source file.
2096 Because rpcgen only builds output files
2097 in the local directory,
2098 the command will be executed
2099 in the source file's directory by default.
2102 # Builds src/rpcif_svc.c
2103 env.RPCGenClient('src/rpcif.x')
2106 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2109 Generates an RPC XDR routine (_xdr.c) file
2110 from a specified RPC (.x) source file.
2111 Because rpcgen only builds output files
2112 in the local directory,
2113 the command will be executed
2114 in the source file's directory by default.
2117 # Builds src/rpcif_xdr.c
2118 env.RPCGenClient('src/rpcif.x')
2121 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2123 .IP env.SharedLibrary()
2124 Builds a shared library
2125 (.so on a POSIX system, .dll on WIN32)
2126 given one or more object files
2127 or C, C++, D or Fortran source files.
2128 If any source files are given,
2129 then they will be automatically
2130 compiled to object files.
2131 The static library prefix and suffix (if any)
2132 are automatically added to the target.
2133 The target library file prefix
2134 (specified by the $SHLIBPREFIX construction variable;
2135 by default, lib on POSIX systems, nothing on Windows systems)
2137 (specified by the $SHLIBSUFFIX construction variable;
2138 by default, .dll on Windows systems, .so on POSIX systems)
2139 are automatically added to the target if not already present.
2143 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2146 On WIN32 systems, the
2148 builder method will always build an import (.lib) library
2149 in addition to the shared (.dll) library,
2150 adding a .lib library with the same basename
2151 if there is not already a .lib file explicitly
2152 listed in the targets.
2154 Any object files listed in the
2156 must have been built for a shared library
2161 will raise an error if there is any mismatch.
2163 On WIN32 systems, specifying "register=1" will cause the dll to be
2164 registered after it is built using REGSVR32. The command that is run
2165 ("regsvr32" by default) is determined by $REGSVR construction
2166 variable, and the flags passed are determined by $REGSVRFLAGS. By
2167 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
2168 up and requiring user attention when it is run. If you change
2169 $REGSVRFLAGS, be sure to include "/s". For example,
2172 env.SharedLibrary(target = 'bar',
2173 source = ['bar.cxx', 'foo.obj'],
2178 will register "bar.dll" as a COM object when it is done linking it.
2180 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2182 .IP env.SharedObject()
2183 Builds an object file for
2184 inclusion in a shared library.
2185 Source files must have one of the same set of extensions
2186 specified above for the
2189 On some platforms building a shared object requires additional
2190 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
2191 normal (static) object, but on some platforms there is no difference between a
2192 shared object and a normal (static) one. When there is a difference, SCons
2193 will only allow shared objects to be linked into a shared library, and will
2194 use a different suffix for shared objects. On platforms where there is no
2195 difference, SCons will allow both normal (static)
2196 and shared objects to be linked into a
2197 shared library, and will use the same suffix for shared and normal
2199 The target object file prefix
2200 (specified by the $SHOBJPREFIX construction variable;
2201 by default, the same as $OBJPREFIX)
2203 (specified by the $SHOBJSUFFIX construction variable)
2204 are automatically added to the target if not already present.
2208 env.SharedObject(target = 'ddd', source = 'ddd.c')
2209 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2210 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2213 Note that the source files will be scanned
2214 according to the suffix mappings in
2215 .B SourceFileScanner
2217 See the section "Scanner Objects,"
2218 below, for a more information.
2220 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2222 .IP env.StaticLibrary()
2223 Builds a static library given one or more object files
2224 or C, C++, D or Fortran source files.
2225 If any source files are given,
2226 then they will be automatically
2227 compiled to object files.
2228 The static library prefix and suffix (if any)
2229 are automatically added to the target.
2230 The target library file prefix
2231 (specified by the $LIBPREFIX construction variable;
2232 by default, lib on POSIX systems, nothing on Windows systems)
2234 (specified by the $LIBSUFFIX construction variable;
2235 by default, .lib on Windows systems, .a on POSIX systems)
2236 are automatically added to the target if not already present.
2240 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2244 Any object files listed in the
2246 must have been built for a static library
2251 will raise an error if there is any mismatch.
2253 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2255 .IP env.StaticObject()
2256 Builds a static object file
2257 from one or more C, C++, D, or Fortran source files.
2258 Source files must have one of the following extensions:
2261 .asm assembly language file
2262 .ASM assembly language file
2274 .F WIN32: Fortran file
2275 POSIX: Fortran file + C pre-processor
2278 .fpp Fortran file + C pre-processor
2279 .FPP Fortran file + C pre-processor
2281 .mm Objective C++ file
2282 .s assembly language file
2283 .S WIN32: assembly language file
2284 POSIX: assembly language file + C pre-processor
2285 .spp assembly language file + C pre-processor
2286 .SPP assembly language file + C pre-processor
2289 The target object file prefix
2290 (specified by the $OBJPREFIX construction variable; nothing by default)
2292 (specified by the $OBJSUFFIX construction variable;
2293 \.obj on Windows systems, .o on POSIX systems)
2294 are automatically added to the target if not already present.
2298 env.StaticObject(target = 'aaa', source = 'aaa.c')
2299 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2300 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2303 Note that the source files will be scanned
2304 according to the suffix mappings in
2305 .B SourceFileScanner
2307 See the section "Scanner Objects,"
2308 below, for a more information.
2310 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2313 Builds a tar archive of the specified files
2315 Unlike most builder methods,
2318 builder method may be called multiple times
2320 each additional call
2321 adds to the list of entries
2322 that will be built into the archive.
2323 Any source directories will
2324 be scanned for changes to
2326 regardless of whether or not
2328 knows about them from other Builder or function calls.
2331 env.Tar('src.tar', 'src')
2333 # Create the stuff.tar file.
2334 env.Tar('stuff', ['subdir1', 'subdir2'])
2335 # Also add "another" to the stuff.tar file.
2336 env.Tar('stuff', 'another')
2338 # Set TARFLAGS to create a gzip-filtered archive.
2339 env = Environment(TARFLAGS = '-c -z')
2340 env.Tar('foo.tar.gz', 'foo')
2342 # Also set the suffix to .tgz.
2343 env = Environment(TARFLAGS = '-c -z',
2348 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2350 .IP env.TypeLibrary()
2351 Builds a Windows type library (.tlb) file from and input IDL file
2352 (.idl). In addition, it will build the associated inteface stub and
2353 proxy source files. It names them according to the base name of the .idl file.
2358 env.TypeLibrary(source="foo.idl")
2361 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
2363 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2366 Builds a header file, an implementation file and a moc file from an ui file.
2367 and returns the corresponding nodes in the above order.
2368 This builder is only available after using the tool 'qt'. Note: you can
2369 specify .ui files directly as inputs for Program, Library and SharedLibrary
2370 without using this builder. Using the builder lets you override the standard
2371 naming conventions (be careful: prefixes are always prepended to names of
2372 built files; if you don't want prefixes, you may set them to ``).
2373 See the QTDIR variable for more information.
2377 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2378 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2379 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2382 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2385 Builds a zip archive of the specified files
2387 Unlike most builder methods,
2390 builder method may be called multiple times
2392 each additional call
2393 adds to the list of entries
2394 that will be built into the archive.
2395 Any source directories will
2396 be scanned for changes to
2398 regardless of whether or not
2400 knows about them from other Builder or function calls.
2403 env.Zip('src.zip', 'src')
2405 # Create the stuff.zip file.
2406 env.Zip('stuff', ['subdir1', 'subdir2'])
2407 # Also add "another" to the stuff.tar file.
2408 env.Zip('stuff', 'another')
2412 targets of builder methods automatically depend on their sources.
2413 An explicit dependency can
2414 be specified using the
2416 method of a construction environment (see below).
2421 source files for various programming languages,
2422 so the dependencies do not need to be specified explicitly.
2423 By default, SCons can
2426 Fortran source files with
2428 (POSIX systems only),
2433 and assembly language files with
2435 (POSIX systems only),
2440 for C preprocessor dependencies.
2441 SCons also has default support
2442 for scanning D source files,
2443 You can also write your own Scanners
2444 to add support for additional source file types.
2445 These can be added to the default
2446 Scanner object used by
2452 Builders by adding them
2454 .B SourceFileScanner
2457 See the section "Scanner Objects,"
2458 below, for a more information about
2459 defining your own Scanner objects.
2461 .SS Methods and Functions to Do Things
2462 In addition to Builder methods,
2464 provides a number of other construction environment methods
2465 and global functions to
2466 manipulate the build configuration.
2468 Usually, a construction environment method
2469 and global function with the same name both exist
2470 so that you don't have to remember whether
2471 to a specific bit of functionality
2472 must be called with or without a construction environment.
2473 In the following list,
2474 if you call something as a global function
2477 .RI Function( arguments )
2479 and if you call something through a construction
2480 environment it looks like:
2482 .RI env.Function( arguments )
2484 If you can call the functionality in both ways,
2485 then both forms are listed.
2487 Global functions may be called from custom Python modules that you
2488 import into an SConscript file by adding the following
2489 to the Python module:
2492 from SCons.Script import *
2495 Except where otherwise noted,
2497 construction environment method
2499 provide the exact same functionality.
2500 The only difference is that,
2502 calling the functionality through a construction environment will
2503 substitute construction variables into
2504 any supplied strings.
2507 env = Environment(FOO = 'foo')
2511 the first call to the global
2513 function will actually add a target named
2515 to the list of default targets,
2516 while the second call to the
2518 construction environment method
2519 will expand the value
2520 and add a target named
2522 to the list of default targets.
2523 For more on construction variable expansion,
2524 see the next section on
2525 construction variables.
2527 Construction environment methods
2528 and global functions supported by
2532 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2534 .RI Action( action ", [" strfunction ", " varlist ])
2536 .RI env.Action( action ", [" strfunction ", " varlist ])
2537 Creates an Action object for
2540 See the section "Action Objects,"
2541 below, for a complete explanation of the arguments and behavior.
2543 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2545 .RI AddPostAction( target ", " action )
2547 .RI env.AddPostAction( target ", " action )
2548 Arranges for the specified
2554 The specified action(s) may be
2555 an Action object, or anything that
2556 can be converted into an Action object
2559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2561 .RI AddPreAction( target ", " action )
2563 .RI env.AddPreAction( target ", " action )
2564 Arranges for the specified
2567 before the specified
2570 The specified action(s) may be
2571 an Action object, or anything that
2572 can be converted into an Action object
2575 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2577 .RI Alias( alias ", [" targets ", [" action ]])
2579 .RI env.Alias( alias ", [" targets ", [" action ]])
2580 Creates one or more phony targets that
2581 expand to one or more other targets.
2586 can be specified that will be executed
2587 whenever the any of the alias targets are out-of-date.
2588 Returns the Node object representing the alias,
2589 which exists outside of any file system.
2590 This Node object, or the alias name,
2591 may be used as a dependency of any other target,
2592 including another alias.
2594 can be called multiple times for the same
2595 alias to add additional targets to the alias,
2596 or additional actions to the list for this alias.
2600 Alias('install', '/usr/bin')
2601 Alias(['install', 'install-lib'], '/usr/local/lib')
2603 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2604 env.Alias('install', ['/usr/local/man'])
2606 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2609 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2611 .RI AlwaysBuild( target ", ...)"
2613 .RI env.AlwaysBuild( target ", ...)"
2616 so that it is always assumed to be out of date,
2617 and will always be rebuilt if needed.
2620 does not add its target(s) to the default target list,
2621 so the targets will only be built
2622 if they are specified on the command line,
2623 or are a dependent of a target specified on the command line--but
2626 be built if so specified.
2627 Multiple targets can be passed in to a single call to
2630 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2632 .RI env.Append( key = val ", [...])"
2633 Appends the specified keyword arguments
2634 to the end of construction variables in the environment.
2635 If the Environment does not have
2636 the specified construction variable,
2637 it is simply added to the environment.
2638 If the values of the construction variable
2639 and the keyword argument are the same type,
2640 then the two values will be simply added together.
2641 Otherwise, the construction variable
2642 and the value of the keyword argument
2643 are both coerced to lists,
2644 and the lists are added together.
2645 (See also the Prepend method, below.)
2648 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2651 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2653 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ])
2654 This appends new path elements to the given path in the
2655 specified external environment
2659 any particular path once (leaving the last one it encounters and
2660 ignoring the rest, to preserve path order),
2661 and to help assure this,
2662 will normalize all paths (using
2665 .BR os.path.normcase ).
2666 This can also handle the
2667 case where the given old path variable is a list instead of a
2668 string, in which case a list will be returned instead of a string.
2672 print 'before:',env['ENV']['INCLUDE']
2673 include_path = '/foo/bar:/foo'
2674 env.AppendENVPath('INCLUDE', include_path)
2675 print 'after:',env['ENV']['INCLUDE']
2679 after: /biz:/foo/bar:/foo
2682 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2684 .RI env.AppendUnique( key = val ", [...])"
2685 Appends the specified keyword arguments
2686 to the end of construction variables in the environment.
2687 If the Environment does not have
2688 the specified construction variable,
2689 it is simply added to the environment.
2690 If the construction variable being appended to is a list,
2691 then any value(s) that already exist in the
2692 construction variable will
2694 be added again to the list.
2697 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2700 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2703 A factory function that
2704 returns a Builder object
2705 to be used to fetch source files
2707 The returned Builder
2708 is intended to be passed to the
2713 env.SourceCode('.', env.BitKeeper())
2716 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2718 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
2720 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
2721 This specifies a build directory
2723 in which to build all derived files
2724 that would normally be built under
2726 Multiple build directories can be set up for multiple build variants, for
2729 must be underneath the SConstruct file's directory,
2732 may not be underneath the
2735 The default behavior is for
2737 to duplicate all of the files in the tree underneath
2741 and then build the derived files within the copied tree.
2742 (The duplication is performed by
2744 depending on the platform; see also the
2747 This guarantees correct builds
2748 regardless of whether intermediate source files
2749 are generated during the build,
2750 where preprocessors or other scanners search
2752 or whether individual compilers or other invoked tools
2753 are hard-coded to put derived files in the same directory as source files.
2755 This behavior of making a complete copy of the source tree
2756 may be disabled by setting
2761 to invoke Builders using the
2762 path names of source files in
2764 and the path names of derived files within
2766 This is always more efficient than
2768 and is usually safe for most builds.
2772 may cause build problems
2773 if source files are generated during the build,
2774 if any invoked tools are hard-coded to
2775 put derived files in the same directory as the source files.
2777 Note that specifying a
2779 works most naturally
2780 with a subsidiary SConscript file
2781 in the source directory.
2783 you would then call the subsidiary SConscript file
2784 not in the source directory,
2789 had made a virtual copy of the source tree
2790 regardless of the value of
2792 This is how you tell
2794 which variant of a source tree to build.
2798 BuildDir('build-variant1', 'src')
2799 SConscript('build-variant1/SConscript')
2800 BuildDir('build-variant2', 'src')
2801 SConscript('build-variant2/SConscript')
2807 function, described below,
2809 specify a build directory
2810 in conjunction with calling a subsidiary
2813 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2815 .RI Builder( action ", [" arguments ])
2817 .RI env.Builder( action ", [" arguments ])
2818 Creates a Builder object for
2821 See the section "Builder Objects,"
2822 below, for a complete explanation of the arguments and behavior.
2824 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2826 .RI CacheDir( cache_dir )
2828 .RI env.CacheDir( cache_dir )
2831 will maintain a cache of derived files in
2833 The derived files in the cache will be shared
2834 among all the builds using the same
2842 finds a derived file that needs to be rebuilt,
2843 it will first look in the cache to see if a
2844 derived file has already been built
2845 from identical input files and an identical build action
2846 (as incorporated into the MD5 build signature).
2849 will retrieve the file from the cache.
2850 If the derived file is not present in the cache,
2853 then place a copy of the built file in the cache
2854 (identified by its MD5 build signature),
2855 so that it may be retrieved by other
2856 builds that need to build the same derived file
2857 from identical inputs.
2861 may be disabled for any invocation
2870 will place a copy of
2872 derived files in the cache,
2873 even if they already existed
2874 and were not built by this invocation.
2875 This is useful to populate a cache
2878 is added to a build,
2887 "Retrieved `file' from cache,"
2890 option is being used.
2895 will print the action that
2897 have been used to build the file,
2898 without any indication that
2899 the file was actually retrieved from the cache.
2900 This is useful to generate build logs
2901 that are equivalent regardless of whether
2902 a given derived file has been built in-place
2903 or retrieved from the cache.
2905 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2907 .RI Clean( targets ", " files_or_dirs )
2909 .RI env.Clean( targets ", " files_or_dirs )
2910 This specifies a list of files or directories which should be removed
2911 whenever the targets are specified with the
2913 command line option.
2914 The specified targets may be a list
2915 or an individual target.
2919 and create new targets or add files and directories to the
2920 clean list for the specified targets.
2922 Multiple files or directories should be specified
2923 either as separate arguments to the
2925 method, or as a list.
2927 will also accept the return value of any of the construction environment
2932 Clean('foo', ['bar', 'baz'])
2933 Clean('dist', env.Program('hello', 'hello.c'))
2934 Clean(['foo', 'bar'], 'something_else_to_clean')
2937 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2939 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
2941 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
2942 Executes a specific action
2943 (or list of actions)
2944 to build a target file or files.
2945 This is more convenient
2946 than defining a separate Builder object
2947 for a single special-case build.
2949 As a special case, the
2951 keyword argument can
2954 that will be used to scan the sources.
2958 if any of the sources will be directories
2959 that must be scanned on-disk for
2960 changes to files that aren't
2961 already specified in other Builder of function calls.)
2963 Any other keyword arguments specified override any
2964 same-named existing construction variables.
2966 An action can be an external command,
2967 specified as a string,
2968 or a callable Python object;
2969 see "Action Objects," below,
2970 for more complete information.
2971 Also note that a string specifying an external command
2972 may be preceded by an
2975 to suppress printing the command in question,
2979 to ignore the exit status of the external command.
2983 env.Command('foo.out', 'foo.in',
2984 "$FOO_BUILD < $SOURCES > $TARGET")
2986 env.Command('bar.out', 'bar.in',
2988 "$BAR_BUILD < $SOURCES > $TARGET"],
2989 ENV = {'PATH' : '/usr/local/bin/'})
2991 def rename(env, target, source):
2993 os.rename('.tmp', str(target[0]))
2995 env.Command('baz.out', 'baz.in',
2996 ["$BAZ_BUILD < $SOURCES > .tmp",
3000 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3002 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
3004 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
3005 Creates a Configure object for integrated
3006 functionality similar to GNU autoconf.
3007 See the section "Configure Contexts,"
3008 below, for a complete explanation of the arguments and behavior.
3010 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3012 .RI env.Copy([ key = val ", ...])"
3013 Return a separate copy of a construction environment.
3014 If there are any keyword arguments specified,
3015 they are added to the returned copy,
3016 overwriting any existing values
3021 env3 = env.Copy(CCFLAGS = '-g')
3024 Additionally, a list of tools and a toolpath may be specified, as in
3025 the Environment constructor:
3028 def MyTool(env): env['FOO'] = 'bar'
3029 env4 = env.Copy(tools = ['msvc', MyTool])
3032 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3034 .RI env.CVS( repository ", " module )
3035 A factory function that
3036 returns a Builder object
3037 to be used to fetch source files
3041 The returned Builder
3042 is intended to be passed to the
3046 The optional specified
3048 will be added to the beginning
3049 of all repository path names;
3050 this can be used, in essence,
3051 to strip initial directory names
3052 from the repository path names,
3053 so that you only have to
3054 replicate part of the repository
3055 directory hierarchy in your
3056 local build directory:
3059 # Will fetch foo/bar/src.c
3060 # from /usr/local/CVSROOT/foo/bar/src.c.
3061 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
3063 # Will fetch bar/src.c
3064 # from /usr/local/CVSROOT/foo/bar/src.c.
3065 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
3068 # from /usr/local/CVSROOT/foo/bar/src.c.
3069 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
3072 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3074 .RI Default( targets )
3076 .RI env.Default( targets )
3077 This specifies a list of default targets,
3078 which will be built by
3080 if no explicit targets are given on the command line.
3084 and add to the list of default targets.
3086 Multiple targets should be specified as
3087 separate arguments to the
3089 method, or as a list.
3091 will also accept the Node returned by any
3092 of a construction environment's
3097 Default('foo', 'bar', 'baz')
3098 env.Default(['a', 'b', 'c'])
3099 hello = env.Program('hello', 'hello.c')
3107 will clear all default targets.
3110 will add to the (now empty) default-target list
3113 The current list of targets added using the
3115 function or method is available in the
3120 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3122 .RI DefaultEnvironment([ args ])
3123 Creates and returns a default construction environment object.
3124 This construction environment is used internally by SCons
3125 in order to execute many of the global functions in this list,
3126 and to fetch source files transparently
3127 from source code management systems.
3129 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3131 .RI Depends( target ", " dependency )
3133 .RI env.Depends( target ", " dependency )
3134 Specifies an explicit dependency;
3135 the target file(s) will be rebuilt
3136 whenever the dependency file(s) has changed.
3137 This should only be necessary
3138 for cases where the dependency
3139 is not caught by a Scanner
3143 env.Depends('foo', 'other-input-file-for-foo')
3146 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3148 .RI env.Dictionary([ vars ])
3149 Returns a dictionary object
3150 containing copies of all of the
3151 construction variables in the environment.
3152 If there are any variable names specified,
3153 only the specified construction
3154 variables are returned in the dictionary.
3157 dict = env.Dictionary()
3158 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3161 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3163 .RI Dir( name ", [" directory ])
3165 .RI env.Dir( name ", [" directory ])
3166 This returns a Directory Node,
3167 an object that represents the specified directory
3170 can be a relative or absolute path.
3172 is an optional directory that will be used as the parent directory.
3175 is specified, the current script's directory is used as the parent.
3177 Directory Nodes can be used anywhere you
3178 would supply a string as a directory name
3179 to a Builder method or function.
3180 Directory Nodes have attributes and methods
3181 that are useful in many situations;
3182 see "File and Directory Nodes," below.
3184 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3186 .RI env.Dump([ key ])
3187 Returns a pretty printable representation of the environment.
3191 should be a string containing the name of the variable of interest.
3196 print env.Dump('CCCOM')
3200 '$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
3210 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3213 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3218 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3220 .RI EnsurePythonVersion( major ", " minor )
3222 .RI env.EnsurePythonVersion( major ", " minor )
3223 Ensure that the Python version is at least
3226 print out an error message and exit SCons with a non-zero exit code if the
3227 actual Python version is not late enough.
3230 EnsurePythonVersion(2,2)
3233 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3235 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
3237 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
3238 Ensure that the SCons version is at least
3241 .IR major.minor.revision .
3246 print out an error message and exit SCons with a non-zero exit code if the
3247 actual SCons version is not late enough.
3250 EnsureSConsVersion(0,14)
3252 EnsureSConsVersion(0,96,90)
3255 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3257 .RI Environment([ key = value ", ...])"
3259 .RI env.Environment([ key = value ", ...])"
3260 Return a new construction environment
3261 initialized with the specified
3265 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3267 .RI Execute( action ", [" strfunction ", " varlist ])
3269 .RI env.Execute( action ", [" strfunction ", " varlist ])
3270 Executes an Action object.
3273 may be an Action object
3274 (see the section "Action Objects,"
3275 below, for a complete explanation of the arguments and behavior),
3276 or it may be a command-line string,
3278 or executable Python function,
3279 each of which will be converted
3280 into an Action object
3282 The exit value of the command
3283 or return value of the Python function
3286 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3290 .RI env.Exit([ value ])
3296 A default exit value of
3299 is used if no value is specified.
3301 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3305 .RI env.Export( vars )
3308 to export a list of variables from the current
3309 SConscript file to all other SConscript files.
3310 The exported variables are kept in a global collection,
3311 so subsequent calls to
3313 will over-write previous exports that have the same name.
3314 Multiple variable names can be passed to
3316 as separate arguments or as a list. A dictionary can be used to map
3317 variables to a different name when exported. Both local variables and
3318 global variables can be exported.
3323 # Make env available for all SConscript files to Import().
3327 # Make env and package available for all SConscript files:.
3328 Export("env", "package")
3330 # Make env and package available for all SConscript files:
3331 Export(["env", "package"])
3333 # Make env available using the name debug:.
3334 Export({"debug":env})
3340 function supports an
3342 argument that makes it easier to to export a variable or
3343 set of variables to a single SConscript file.
3344 See the description of the
3348 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3350 .RI File( name ", [" directory ])
3352 .RI env.File( name ", [" directory ])
3355 an object that represents the specified file
3358 can be a relative or absolute path.
3360 is an optional directory that will be used as the parent directory.
3362 File Nodes can be used anywhere you
3363 would supply a string as a file name
3364 to a Builder method or function.
3365 File Nodes have attributes and methods
3366 that are useful in many situations;
3367 see "File and Directory Nodes," below.
3369 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3371 .RI FindFile( file ", " dirs )
3373 .RI env.FindFile( file ", " dirs )
3376 in the path specified by
3379 may be a list of file names or a single file name. In addition to searching
3380 for files that exist in the filesytem, this function also searches for
3381 derived files that have not yet been built.
3384 foo = env.FindFile('foo', ['dir1', 'dir2'])
3387 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3389 .RI Flatten( sequence )
3391 .RI env.Flatten( sequence )
3392 Takes a sequence (that is, a Python list or tuple)
3393 that may contain nested sequences
3394 and returns a flattened list containing
3395 all of the individual elements in any sequence.
3396 This can be helpful for collecting
3397 the lists returned by calls to Builders;
3398 other Builders will automatically
3399 flatten lists specified as input,
3400 but direct Python manipulation of
3401 these lists does not:
3404 foo = Object('foo.c')
3405 bar = Object('bar.c')
3407 # Because `foo' and `bar' are lists returned by the Object() Builder,
3408 # `objects' will be a list containing nested lists:
3409 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3411 # Passing such a list to another Builder is all right because
3412 # the Builder will flatten the list automatically:
3413 Program(source = objects)
3415 # If you need to manipulate the list directly using Python, you need to
3416 # call Flatten() yourself, or otherwise handle nested lists:
3417 for object in Flatten(objects):
3421 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3423 .RI GetBuildPath( file ", [" ... ])
3425 .RI env.GetBuildPath( file ", [" ... ])
3428 path name (or names) for the specified
3436 Nodes or strings representing path names.
3438 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3442 .RI env.GetLaunchDir()
3443 Returns the absolute path name of the directory from which
3446 was initially invoked.
3447 This can be useful when using the
3452 options, which internally
3453 change to the directory in which the
3457 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3459 .RI GetOption( name )
3461 .RI env.GetOption( name )
3462 This function provides a way to query a select subset of the scons command line
3463 options from a SConscript file. See
3465 for a description of the options available.
3467 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3469 '\".RI GlobalBuilders( flag )
3473 '\"adds the names of the default builders
3474 '\"(Program, Library, etc.)
3475 '\"to the global name space
3476 '\"so they can be called without an explicit construction environment.
3477 '\"(This is the default.)
3481 '\"the names of the default builders are removed
3482 '\"from the global name space
3483 '\"so that an explicit construction environment is required
3484 '\"to call all builders.
3486 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3490 .RI env.Help( text )
3491 This specifies help text to be printed if the
3493 argument is given to
3497 is called multiple times, the text is appended together in the order
3502 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3504 .RI Ignore( target ", " dependency )
3506 .RI env.Ignore( target ", " dependency )
3507 The specified dependency file(s)
3508 will be ignored when deciding if
3509 the target file(s) need to be rebuilt.
3512 env.Ignore('foo', 'foo.c')
3513 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3516 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3520 .RI env.Import( vars )
3523 to import a list of variables into the current SConscript file. This
3524 will import variables that were exported with
3530 Variables exported by
3533 Multiple variable names can be passed to
3535 as separate arguments or as a list. The variable "*" can be used
3536 to import all variables.
3541 Import("env", "variable")
3542 Import(["env", "variable"])
3546 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3548 .RI Install( dir ", " source )
3550 .RI env.Install( dir ", " source )
3551 Installs one or more files in a destination directory.
3552 The file names remain the same.
3555 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
3558 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3560 .RI InstallAs( target ", " source )
3562 .RI env.InstallAs( target ", " source )
3563 Installs one or more files as specific file names,
3564 allowing changing a file name as part of the
3566 It is an error if the target and source
3567 list different numbers of files.
3570 env.InstallAs(target = '/usr/local/bin/foo',
3571 source = 'foo_debug')
3572 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
3573 source = ['libFOO.a', 'libBAR.a'])
3576 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3578 .RI Literal( string )
3580 .RI env.Literal( string )
3583 will be preserved as-is
3584 and not have construction variables expanded.
3586 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3588 .RI Local( targets )
3590 .RI env.Local( targets )
3593 will have copies made in the local tree,
3594 even if an already up-to-date copy
3595 exists in a repository.
3596 Returns a list of the target Node or Nodes.
3598 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3600 .RI env.ParseConfig( command ", [" function ", " unique ])
3603 to modify the environment as specified by the output of
3607 expects the output of a typical
3611 and adds the options
3612 to the appropriate construction variables.
3614 duplicate values are not
3615 added to any construction variables;
3638 construction variables,
3642 option gets added to both the
3649 option gets added to the
3652 Any other strings not associated with options
3653 are assumed to be the names of libraries
3656 construction variable.
3658 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3660 .RI ParseDepends( filename ", [" must_exist ])
3662 .RI env.ParseDepends( filename ", [" must_exist " " only_one ])
3663 Parses the contents of the specified
3665 as a list of dependencies in the style of
3669 and explicitly establishes all of the listed dependencies.
3678 argument may be set to a non-zero
3681 throw an exception and
3682 generate an error if the file does not exist,
3683 or is otherwise inaccessible.
3687 argument may be set to a non-zero
3690 thrown an exception and
3692 if the file contains dependency
3693 information for more than one target.
3694 This can provide a small sanity check
3695 for files intended to be generated
3696 by, for example, the
3699 which should typically only
3700 write dependency information for
3701 one output file into a corresponding
3707 and all of the files listed therein
3708 will be interpreted relative to
3709 the directory of the
3711 file which calls the
3715 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3718 A factory function that
3719 returns a Builder object
3720 to be used to fetch source files
3721 from the Perforce source code management system.
3722 The returned Builder
3723 is intended to be passed to the
3728 env.SourceCode('.', env.Perforce())
3731 Perforce uses a number of external
3732 environment variables for its operation.
3733 Consequently, this function adds the
3734 following variables from the user's external environment
3735 to the construction environment's
3748 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3750 .RI Platform( string )
3751 Returns a callable object
3752 that can be used to initialize
3753 a construction environment using the
3754 platform keyword of the Environment() method:
3757 env = Environment(platform = Platform('win32'))
3760 .RI env.Platform( string )
3761 Applies the callable object for the specified platform
3763 to the environment through which the method was called.
3766 env.Platform('posix')
3775 variables from the user's external environment
3776 to the construction environment's
3779 This is so that any executed commands
3780 that use sockets to connect with other systems
3781 (such as fetching source files from
3782 external CVS repository specifications like
3783 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
3784 will work on Win32 systems.
3786 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3788 .RI Precious( target ", ...)"
3790 .RI env.Precious( target ", ...)"
3793 as precious so it is not deleted before it is rebuilt. Normally
3795 deletes a target before building it.
3796 Multiple targets can be passed in to a single call to
3799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3801 .RI env.Prepend( key = val ", [...])"
3802 Appends the specified keyword arguments
3803 to the beginning of construction variables in the environment.
3804 If the Environment does not have
3805 the specified construction variable,
3806 it is simply added to the environment.
3807 If the values of the construction variable
3808 and the keyword argument are the same type,
3809 then the two values will be simply added together.
3810 Otherwise, the construction variable
3811 and the value of the keyword argument
3812 are both coerced to lists,
3813 and the lists are added together.
3814 (See also the Append method, above.)
3817 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3820 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3822 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ])
3823 This appends new path elements to the given path in the
3824 specified external environment
3828 any particular path once (leaving the first one it encounters and
3829 ignoring the rest, to preserve path order),
3830 and to help assure this,
3831 will normalize all paths (using
3834 .BR os.path.normcase ).
3835 This can also handle the
3836 case where the given old path variable is a list instead of a
3837 string, in which case a list will be returned instead of a string.
3841 print 'before:',env['ENV']['INCLUDE']
3842 include_path = '/foo/bar:/foo'
3843 env.PrependENVPath('INCLUDE', include_path)
3844 print 'after:',env['ENV']['INCLUDE']
3848 after: /foo/bar:/foo:/biz
3851 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3853 .RI env.PrependUnique( key = val ", [...])"
3854 Appends the specified keyword arguments
3855 to the beginning of construction variables in the environment.
3856 If the Environment does not have
3857 the specified construction variable,
3858 it is simply added to the environment.
3859 If the construction variable being appended to is a list,
3860 then any value(s) that already exist in the
3861 construction variable will
3863 be added again to the list.
3866 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3869 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3872 A factory function that
3873 returns a Builder object
3874 to be used to fetch source files
3876 The returned Builder
3877 is intended to be passed to the
3882 env.SourceCode('.', env.RCS())
3887 will fetch source files
3888 from RCS subdirectories automatically,
3890 as demonstrated in the above example
3891 should only be necessary if
3892 you are fetching from
3895 directory as the source files,
3896 or if you need to explicitly specify RCS
3897 for a specific subdirectory.
3899 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3901 .RI env.Replace( key = val ", [...])"
3902 Replaces construction variables in the Environment
3903 with the specified keyword arguments.
3906 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
3909 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3911 .RI Repository( directory )
3913 .RI env.Repository( directory )
3916 is a repository to be searched for files.
3920 and each one adds to the list of
3921 repositories that will be searched.
3925 a repository is a copy of the source tree,
3926 from the top-level directory on down,
3928 both source files and derived files
3929 that can be used to build targets in
3930 the local source tree.
3931 The canonical example would be an
3932 official source tree maintained by an integrator.
3933 If the repository contains derived files,
3934 then the derived files should have been built using
3936 so that the repository contains the necessary
3937 signature information to allow
3939 to figure out when it is appropriate to
3940 use the repository copy of a derived file,
3941 instead of building one locally.
3943 Note that if an up-to-date derived file
3944 already exists in a repository,
3948 make a copy in the local directory tree.
3949 In order to guarantee that a local copy
3955 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3960 what variable(s) to use as the return value(s) of the current SConscript
3961 file. These variables will be returned to the "calling" SConscript file
3962 as the return value(s) of
3964 Multiple variable names should be passed to
3970 Return(["foo", "bar"])
3973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3975 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3977 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
3978 Creates a Scanner object for
3981 See the section "Scanner Objects,"
3982 below, for a complete explanation of the arguments and behavior.
3984 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3987 A factory function that
3988 returns a Builder object
3989 to be used to fetch source files
3991 The returned Builder
3992 is intended to be passed to the
3997 env.SourceCode('.', env.SCCS())
4002 will fetch source files
4003 from SCCS subdirectories automatically,
4005 as demonstrated in the above example
4006 should only be necessary if
4007 you are fetching from
4010 directory as the source files,
4011 or if you need to explicitly specify SCCS
4012 for a specific subdirectory.
4014 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4016 .RI SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
4018 .RI env.SConscript( scripts ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
4020 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
4022 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " build_dir ", " src_dir ", " duplicate ])
4026 one or more subsidiary SConscript (configuration) files.
4027 There are two ways to call the
4031 The first way you can call
4033 is to explicitly specify one or more
4035 as the first argument.
4036 A single script may be specified as a string;
4037 multiple scripts must be specified as a list
4038 (either explicitly or as created by
4042 The second way you can call
4044 is to specify a list of (sub)directory names
4051 execute a subsidiary configuration file named
4053 in each of the specified directories.
4054 You may specify a name other than
4056 by supplying an optional
4062 argument provides a list of variable names or a dictionary of
4063 named values to export to the
4065 These variables are locally exported only to the specified
4067 and do not affect the
4068 global pool of variables used by
4072 '\"If multiple dirs are provided,
4073 '\"each script gets a fresh export.
4078 function to import the variables.
4082 argument specifies that all of the target files
4083 (for example, object files and executables)
4084 that would normally be built in the subdirectory in which
4086 resides should actually
4090 is interpreted relative to the directory
4091 of the calling SConscript file.
4095 argument specifies that the
4096 source files from which
4097 the target files should be built
4101 is interpreted relative to the directory
4102 of the calling SConscript file.
4106 will link or copy (depending on the platform)
4107 all the source files into the build directory.
4108 This behavior may be disabled by
4109 setting the optional
4112 (it is set to 1 by default),
4115 will refer directly to
4116 the source files in their source directory
4117 when building target files.
4120 is usually safe, and always more efficient
4123 but it may cause build problems in certain end-cases,
4124 such as compiling from source files that
4125 are generated by the build.)
4127 Any variables returned by
4131 will be returned by the call to
4137 SConscript('subdir/SConscript')
4138 foo = SConscript('sub/SConscript', exports='env')
4139 SConscript('dir/SConscript', exports=['env', 'variable'])
4140 SConscript('src/SConscript', build_dir='build', duplicate=0)
4141 SConscript('bld/SConscript', src_dir='src', exports='env variable')
4142 SConscript(dirs=['sub1', 'sub2'])
4143 SConscript(dirs=['sub3', 'sub4'], name='MySConscript')
4146 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4148 .RI SConscriptChdir( value )
4150 .RI env.SConscriptChdir( value )
4153 changes its working directory
4154 to the directory in which each
4155 subsidiary SConscript file lives.
4156 This behavior may be disabled
4157 by specifying either:
4161 env.SConscriptChdir(0)
4166 will stay in the top-level directory
4167 while reading all SConscript files.
4168 (This may be necessary when building from repositories,
4169 when all the directories in which SConscript files may be found
4170 don't necessarily exist locally.)
4172 You may enable and disable
4173 this ability by calling
4180 SConscript('foo/SConscript') # will not chdir to foo
4181 env.SConscriptChdir(1)
4182 SConscript('bar/SConscript') # will chdir to bar
4185 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4187 .RI SConsignFile([ file , dbm_module ])
4189 .RI env.SConsignFile([ file , dbm_module ])
4192 to store all file signatures
4193 in the specified database
4200 (The actual file name(s) stored on disk
4201 may have an appropriated suffix appended
4206 is not an absolute path name,
4207 the file is placed in the same directory as the top-level
4217 will store file signatures
4220 file in each directory,
4221 not in one global database file.
4222 (This was the default behavior
4223 prior to SCons 0.96.91 and 0.97.)
4227 argument can be used to specify
4228 which Python database module
4229 The default is to use a custom
4231 module that uses pickled
4232 Python data structures,
4233 and which works on all Python versions from 1.5.2 on.
4238 # Explicitly stores signatures in ".sconsign.dblite"
4239 # in the top-level SConstruct directory (the
4240 # default behavior).
4243 # Stores signatures in the file "etc/scons-signatures"
4244 # relative to the top-level SConstruct directory.
4245 SConsignFile("etc/scons-signatures")
4247 # Stores signatures in the specified absolute file name.
4248 SConsignFile("/home/me/SCons/signatures")
4250 # Stores signatures in a separate .sconsign file
4251 # in each directory.
4255 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4257 .RI env.SetDefault(key = val ", [...])"
4258 Sets construction variables to default values specified with the keyword
4259 arguments if (and only if) the variables are not already set.
4260 The following statements are equivalent:
4263 env.SetDefault(FOO = 'foo')
4265 if not env.has_key('FOO'): env['FOO'] = 'foo'
4268 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4270 .RI SetOption( name ", " value )
4272 .RI env.SetOption( name ", " value )
4273 This function provides a way to set a select subset of the scons command
4274 line options from a SConscript file. The options supported are:
4276 which corresponds to -c, --clean, and --remove;
4279 corresponds to --duplicate;
4281 which corresponds to --implicit-cache;
4283 which corresponds to --max-drift;
4285 which corresponds to -j and --jobs.
4286 See the documentation for the
4287 corresponding command line object for information about each specific
4291 SetOption('max_drift', 1)
4294 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4296 .RI SideEffect( side_effect ", " target )
4298 .RI env.SideEffect( side_effect ", " target )
4301 as a side effect of building
4307 can be a list, a file name, or a node.
4308 A side effect is a target that is created
4309 as a side effect of building other targets.
4310 For example, a Windows PDB
4311 file is created as a side effect of building the .obj
4312 files for a static library.
4313 If a target is a side effect of multiple build commands,
4315 will ensure that only one set of commands
4316 is executed at a time.
4317 Consequently, you only need to use this method
4318 for side-effect targets that are built as a result of
4319 multiple build commands.
4321 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4323 .RI SourceCode( entries ", " builder )
4325 .RI env.SourceCode( entries ", " builder )
4326 Arrange for non-existent source files to
4327 be fetched from a source code management system
4332 may be a Node, string or list of both,
4333 and may represent either individual
4334 source files or directories in which
4335 source files can be found.
4337 For any non-existent source files,
4339 will search up the directory tree
4349 will not use a builder to fetch
4350 source files for the specified
4354 builder has been specified
4355 for a directory higher up the tree.
4359 fetch files from SCCS or RCS subdirectories
4360 without explicit configuration.
4361 This takes some extra processing time
4362 to search for the necessary
4363 source code management files on disk.
4364 You can avoid these extra searches
4365 and speed up your build a little
4366 by disabling these searches as follows:
4369 env.SourceCode('.', None)
4373 Note that if the specified
4375 is one you create by hand,
4376 it must have an associated
4377 construction environment to use
4378 when fetching a source file.
4381 provides a set of canned factory
4382 functions that return appropriate
4383 Builders for various popular
4384 source code management systems.
4385 Canonical examples of invocation include:
4388 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4389 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4390 env.SourceCode('/', env.RCS())
4391 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4392 env.SourceCode('no_source.c', None)
4394 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4396 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4398 .RI env.subst( string ", [" raw ", " target ", " source ", " conv ])
4399 Performs construction variable interpolation
4400 on the specified string argument.
4403 leading or trailing white space will
4404 be removed from the result.
4405 and all sequences of white space
4406 will be compressed to a single space character.
4411 character sequences will be stripped from the returned string,
4414 argument may be set to
4416 if you want to preserve white space and
4421 argument may be set to
4423 if you want to strip
4424 all characters between
4430 (as is done for signature calculation).
4437 must be set to lists of
4438 target and source nodes, respectively,
4445 to be available for expansion.
4446 This is usually necessary if you are
4449 from within a Python function used
4453 all returned values are converted
4454 to their string representation.
4458 may specify a conversion function
4459 that will be used in place of
4461 For example, if you want Python objects
4462 (including SCons Nodes)
4463 to be returned as Python objects,
4464 you can use the Python
4466 idiom to pass in an unnamed function
4467 that simply returns its unconverted argument.
4470 print env.subst("The C compiler is: $CC")
4472 def compile(target, source, env):
4473 sourceDir = env.subst("${SOURCE.srcdir}",
4477 source_nodes = env.subst('$EXPAND_TO_NODELIST',
4481 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4483 '\".RI Subversion( repository ", " module )
4484 '\"A factory function that
4485 '\"returns a Builder object
4486 '\"to be used to fetch source files
4487 '\"from the specified Subversion
4489 '\"The returned Builder
4490 '\"is intended to be passed to the
4494 '\"The optional specified
4496 '\"will be added to the beginning
4497 '\"of all repository path names;
4498 '\"this can be used, in essence,
4499 '\"to strip initial directory names
4500 '\"from the repository path names,
4501 '\"so that you only have to
4502 '\"replicate part of the repository
4503 '\"directory hierarchy in your
4504 '\"local build directory:
4507 '\"# Will fetch foo/bar/src.c
4508 '\"# from /usr/local/Subversion/foo/bar/src.c.
4509 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
4511 '\"# Will fetch bar/src.c
4512 '\"# from /usr/local/Subversion/foo/bar/src.c.
4513 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
4515 '\"# Will fetch src.c
4516 '\"# from /usr/local/Subversion/foo/bar/src.c.
4517 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
4520 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4522 .RI SourceSignatures( type )
4524 .RI env.SourceSignatures( type )
4525 This function tells SCons what type of signature to use for source files:
4529 If the environment method is used,
4530 the specified type of source signature
4531 is only used when deciding whether targets
4532 built with that environment are up-to-date or must be rebuilt.
4533 If the global function is used,
4534 the specified type of source signature becomes the default
4535 used for all decisions
4536 about whether targets are up-to-date.
4538 "MD5" means the signature of a source file
4539 is the MD5 checksum of its contents.
4540 "timestamp" means the signature of a source file
4541 is its timestamp (modification time).
4542 There is no different between the two behaviors
4546 "MD5" signatures take longer to compute,
4547 but are more accurate than "timestamp" signatures.
4548 The default is "MD5".
4550 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4554 .RI env.Split( arg )
4555 Returns a list of file names or other objects.
4557 it will be split on strings of white-space characters
4559 making it easier to write long lists of file names.
4560 If arg is already a list,
4561 the list will be returned untouched.
4562 If arg is any other type of object,
4563 it will be returned as a list
4564 containing just the object.
4567 files = Split("f1.c f2.c f3.c")
4568 files = env.Split("f4.c f5.c f6.c")
4576 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4578 .RI TargetSignatures( type )
4580 .RI env.TargetSignatures( type )
4581 This function tells SCons what type of signatures to use
4586 If the environment method is used,
4587 the specified type of signature is only used
4588 for targets built with that environment.
4589 If the global function is used,
4590 the specified type of signature becomes the default
4591 used for all target files that
4592 don't have an explicit target signature type
4593 specified for their environments.
4595 "build" means the signature of a target file
4596 is made by concatenating all of the
4597 signatures of all its source files.
4598 "content" means the signature of a target
4599 file is an MD5 checksum of its contents.
4600 "build" signatures are usually faster to compute,
4601 but "content" signatures can prevent unnecessary rebuilds
4602 when a target file is rebuilt to the exact same contents
4603 as the previous build.
4604 The default is "build".
4606 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4608 .RI Tool( string [, toolpath ", " **kw ])
4609 Returns a callable object
4610 that can be used to initialize
4611 a construction environment using the
4612 tools keyword of the Environment() method.
4613 The object may be called with a construction
4614 environment as an argument,
4615 in which case the object will
4616 add the necessary variables
4617 to the construction environment
4618 and the name of the tool will be added to the
4620 construction variable.
4622 Additional keyword arguments are passed to the tool's
4627 env = Environment(tools = [ Tool('msvc') ])
4631 t(env) # adds 'msvc' to the TOOLS variable
4632 u = Tool('opengl', toolpath = ['tools'])
4633 u(env) # adds 'opengl' to the TOOLS variable
4636 .RI env.Tool( string [, toolpath ", " **kw ])
4637 Applies the callable object for the specified tool
4639 to the environment through which the method was called.
4641 Additional keyword arguments are passed to the tool's
4647 env.Tool('opengl', toolpath = ['build/tools'])
4650 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4654 .RI env.Value( value )
4655 Returns a Node object representing the specified Python value. Value
4656 nodes can be used as dependencies of targets. If the result of
4659 changes between SCons runs, any targets depending on
4661 will be rebuilt. When using timestamp source signatures, Value nodes'
4662 timestamps are equal to the system time when the node is created.
4665 def create(target, source, env):
4666 f = open(str(target[0]), 'wb')
4667 f.write('prefix=' + source[0].get_contents())
4669 prefix = ARGUMENTS.get('prefix', '/usr/local')
4671 env['BUILDERS']['Config'] = Builder(action = create)
4672 env.Config(target = 'package-config', source = Value(prefix))
4675 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4677 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
4679 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
4681 Searches for the specified executable
4683 returning the full path name to the program
4685 and returning None if not.
4686 Searches the specified
4688 the value of the calling environment's PATH
4689 (env['ENV']['PATH']),
4690 or the user's current external PATH
4691 (os.environ['PATH'])
4693 On Win32 systems, searches for executable
4694 programs with any of the file extensions
4695 listed in the specified
4697 the calling environment's PATHEXT
4698 (env['ENV']['PATHEXT'])
4699 or the user's current PATHEXT
4700 (os.environ['PATHEXT'])
4708 .SS SConscript Variables
4709 In addition to the global functions and methods,
4711 supports a number of Python variables
4712 that can be used in SConscript files
4713 to affect how you want the build to be performed.
4714 These variables may be accessed from custom Python modules that you
4715 import into an SConscript file by adding the following
4716 to the Python module:
4719 from SCons.Script import *
4722 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4727 arguments specified on the command line.
4728 Each element in the list is a tuple
4730 .RI ( keyword , value )
4736 elements of the tuple
4738 subscripting for element
4742 of the tuple, respectively.
4745 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4746 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4747 third_tuple = ARGLIST[2]
4748 print "third keyword, value =", third_tuple[0], third_tuple[1]
4749 for key, value in ARGLIST:
4750 # process key and value
4753 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4756 A dictionary of all the
4758 arguments specified on the command line.
4759 The dictionary is not in order,
4760 and if a given keyword has
4761 more than one value assigned to it
4762 on the command line,
4763 the last (right-most) value is
4769 if ARGUMENTS.get('debug', 0):
4770 env = Environment(CCFLAGS = '-g')
4775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4778 A list of the targets which
4780 will actually try to build,
4781 regardless of whether they were specified on
4782 the command line or via the
4785 The elements of this list may be strings
4787 nodes, so you should run the list through the Python
4789 function to make sure any Node path names
4790 are converted to strings.
4792 Because this list may be taken from the
4793 list of targets specified using the
4796 the contents of the list may change
4797 on each successive call to
4802 for additional information.
4805 if 'foo' in BUILD_TARGETS:
4806 print "Don't forget to test the `foo' program!"
4807 if 'special/program' in BUILD_TARGETS:
4808 SConscript('special')
4813 list only contains targets expected listed
4814 on the command line or via calls to the
4819 contain all dependent targets that will be built as
4820 a result of making the sure the explicitly-specified
4821 targets are up to date.
4823 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4825 COMMAND_LINE_TARGETS
4826 A list of the targets explicitly specified on
4828 If there are no targets specified on the command line,
4830 This can be used, for example,
4831 to take specific actions only
4832 when a certain target or targets
4833 is explicitly being built:
4836 if 'foo' in COMMAND_LINE_TARGETS:
4837 print "Don't forget to test the `foo' program!"
4838 if 'special/program' in COMMAND_LINE_TARGETS:
4839 SConscript('special')
4842 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4845 A list of the target
4847 that have been specified using the
4850 The elements of the list are nodes,
4851 so you need to run them through the Python
4853 function to get at the path name for each Node.
4856 print str(DEFAULT_TARGETS[0])
4857 if 'foo' in map(str, DEFAULT_TARGETS):
4858 print "Don't forget to test the `foo' program!"
4863 list change on on each successive call to the
4868 print map(str, DEFAULT_TARGETS) # originally []
4870 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4872 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4874 print map(str, DEFAULT_TARGETS) # back to []
4877 Consequently, be sure to use
4879 only after you've made all of your
4882 or else simply be careful of the order
4883 of these statements in your SConscript files
4884 so that you don't look for a specific
4885 default target before it's actually been added to the list.
4887 .SS Construction Variables
4888 .\" XXX From Gary Ruben, 23 April 2002:
4889 .\" I think it would be good to have an example with each construction
4890 .\" variable description in the documentation.
4892 .\" CC The C compiler
4893 .\" Example: env["CC"] = "c68x"
4894 .\" Default: env["CC"] = "cc"
4896 .\" CCCOM The command line ...
4898 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
4899 .\" env["CC"] = "c68x"
4900 .\" env["CFLAGS"] = "-ps -qq -mr"
4901 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
4903 .\" (I dunno what this is ;-)
4904 A construction environment has an associated dictionary of
4905 .I construction variables
4906 that are used by built-in or user-supplied build rules.
4907 Construction variables must follow the same rules for
4909 the initial character must be an underscore or letter,
4910 followed by any number of underscores, letters, or digits.
4912 A number of useful construction variables are automatically defined by
4913 scons for each supported platform, and additional construction variables
4914 can be defined by the user. The following is a list of the automatically
4915 defined construction variables:
4918 The static library archiver.
4921 The command line used to generate a static library from object files.
4924 The string displayed when an object file
4925 is generated from an assembly-language source file.
4926 If this is not set, then $ARCOM (the command line) is displayed.
4929 env = Environment(ARCOMSTR = "Archiving $TARGET")
4933 General options passed to the static library archiver.
4939 The command line used to generate an object file
4940 from an assembly-language source file.
4943 The string displayed when an object file
4944 is generated from an assembly-language source file.
4945 If this is not set, then $ASCOM (the command line) is displayed.
4948 env = Environment(ASCOMSTR = "Assembling $TARGET")
4952 General options passed to the assembler.
4955 The command line used to assemble an assembly-language
4956 source file into an object file
4957 after first running the file through the C preprocessor.
4958 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
4959 are included on this command line.
4962 The string displayed when an object file
4963 is generated from an assembly-language source file
4964 after first running the file through the C preprocessor.
4965 If this is not set, then $ASPPCOM (the command line) is displayed.
4968 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4972 General options when an assembling an assembly-language
4973 source file into an object file
4974 after first running the file through the C preprocessor.
4975 The default is to use the value of $ASFLAGS.
4978 The bibliography generator for the TeX formatter and typesetter and the
4979 LaTeX structured formatter and typesetter.
4982 The command line used to call the bibliography generator for the
4983 TeX formatter and typesetter and the LaTeX structured formatter and
4987 The string displayed when generating a bibliography
4989 If this is not set, then $BIBTEXCOM (the command line) is displayed.
4992 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4997 General options passed to the bibliography generator for the TeX formatter
4998 and typesetter and the LaTeX structured formatter and typesetter.
5001 The BitKeeper executable.
5004 The command line for
5005 fetching source files using BitKeeper.
5008 The string displayed when fetching
5009 a source file using BitKeeper.
5010 If this is not set, then $BITKEEPERCOM
5011 (the command line) is displayed.
5014 The command ($BITKEEPER) and subcommand
5015 for fetching source files using BitKeeper.
5017 .IP BITKEEPERGETFLAGS
5018 Options that are passed to the BitKeeper
5023 A dictionary mapping the names of the builders
5024 available through this environment
5025 to underlying Builder objects.
5027 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
5028 are available by default.
5029 If you initialize this variable when an
5030 Environment is created:
5033 env = Environment(BUILDERS = {'NewBuilder' : foo})
5036 the default Builders will no longer be available.
5037 To use a new Builder object in addition to the default Builders,
5038 add your new Builder object like this:
5042 env.Append(BUILDERS = {'NewBuilder' : foo})
5049 env['BUILDERS]['NewBuilder'] = foo
5056 The command line used to compile a C source file to a (static) object file.
5057 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
5058 are included on this command line.
5061 The string displayed when a C source file
5062 is compiled to a (static) object file.
5063 If this is not set, then $CCCOM (the command line) is displayed.
5066 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
5070 General options that are passed to the C compiler.
5073 The suffix for C source files.
5074 This is used by the internal CFile builder
5075 when generating C files from Lex (.l) or YACC (.y) input files.
5076 The default suffix, of course, is
5079 On case-insensitive systems (like Win32),
5086 The version number of the C compiler.
5087 This may or may not be set,
5088 depending on the specific C compiler being used.
5091 A function used to produce variables like $_CPPINCFLAGS. It takes
5093 arguments: a prefix to concatenate onto each element, a list of
5094 elements, a suffix to concatenate onto each element, an environment
5095 for variable interpolation, and an optional function that will be
5096 called to transform the list before concatenation.
5099 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
5103 The name of the directory in which
5104 Configure context test files are written.
5107 in the top-level directory
5113 The name of the Configure context log file.
5116 in the top-level directory
5122 A platform independent specification of C preprocessor definitions.
5123 The definitions will be added to command lines
5124 through the automatically-generated
5125 $_CPPDEFFLAGS construction variable (see below),
5126 which is constructed according to
5127 the type of value of $CPPDEFINES:
5130 If $CPPDEFINES is a string,
5132 $CPPDEFPREFIX and $CPPDEFSUFFIX
5133 construction variables
5134 will be added to the beginning and end.
5137 # Will add -Dxyz to POSIX compiler command lines,
5138 # and /Dxyz to Microsoft Visual C++ command lines.
5139 env = Environment(CPPDEFINES='xyz')
5143 If $CPPDEFINES is a list,
5145 $CPPDEFPREFIX and $CPPDEFSUFFIX
5146 construction variables
5147 will be appended to the beginning and end
5148 of each element in the list.
5149 If any element is a list or tuple,
5150 then the first item is the name being
5151 defined and the second item is its value:
5154 # Will add -DB=2 -DA to POSIX compiler command lines,
5155 # and /DB=2 /DA to Microsoft Visual C++ command lines.
5156 env = Environment(CPPDEFINES=[('B', 2), 'A'])
5160 If $CPPDEFINES is a dictionary,
5162 $CPPDEFPREFIX and $CPPDEFSUFFIX
5163 construction variables
5164 will be appended to the beginning and end
5165 of each item from the dictionary.
5166 The key of each dictionary item
5167 is a name being defined
5168 to the dictionary item's corresponding value;
5171 then the name is defined without an explicit value.
5172 Note that the resulting flags are sorted by keyword
5173 to ensure that the order of the options on the
5174 command line is consistent each time
5179 # Will add -DA -DB=2 to POSIX compiler command lines,
5180 # and /DA /DB=2 to Microsoft Visual C++ command lines.
5181 env = Environment(CPPDEFINES={'B':2, 'A':None})
5185 An automatically-generated construction variable
5186 containing the C preprocessor command-line options
5188 The value of $_CPPDEFFLAGS is created
5189 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
5190 to the beginning and end
5191 of each directory in $CPPDEFINES.
5194 The prefix used to specify preprocessor definitions
5195 on the C compiler command line.
5196 This will be appended to the beginning of each definition
5197 in the $CPPDEFINES construction variable
5198 when the $_CPPDEFFLAGS variable is automatically generated.
5201 The suffix used to specify preprocessor definitions
5202 on the C compiler command line.
5203 This will be appended to the end of each definition
5204 in the $CPPDEFINES construction variable
5205 when the $_CPPDEFFLAGS variable is automatically generated.
5208 User-specified C preprocessor options.
5209 These will be included in any command that uses the C preprocessor,
5210 including not just compilation of C and C++ source files
5211 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
5212 but also the $FORTRANPPCOM, $SHFORTRANPPCOM,
5213 $F77PPCOM and $SHF77PPCOM command lines
5214 used to compile a Fortran source file,
5215 and the $ASPPCOM command line
5216 used to assemble an assembly language source file,
5217 after first running each file through the C preprocessor.
5218 Note that this variable does
5222 (or similar) include search path options
5223 that scons generates automatically from $CPPPATH.
5227 for the variable that expands to those options.
5230 An automatically-generated construction variable
5231 containing the C preprocessor command-line options
5232 for specifying directories to be searched for include files.
5233 The value of $_CPPINCFLAGS is created
5234 by appending $INCPREFIX and $INCSUFFIX
5235 to the beginning and end
5236 of each directory in $CPPPATH.
5239 The list of directories that the C preprocessor will search for include
5240 directories. The C/C++ implicit dependency scanner will search these
5241 directories for include files. Don't explicitly put include directory
5242 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
5243 and the directories will not be searched by the dependency scanner. Note:
5244 directory names in CPPPATH will be looked-up relative to the SConscript
5245 directory when they are used in a command. To force
5247 to look-up a directory relative to the root of the source tree use #:
5250 env = Environment(CPPPATH='#/include')
5254 The directory look-up can also be forced using the
5259 include = Dir('include')
5260 env = Environment(CPPPATH=include)
5264 The directory list will be added to command lines
5265 through the automatically-generated
5267 construction variable,
5268 which is constructed by
5269 appending the values of the
5270 $INCPREFIX and $INCSUFFIX
5271 construction variables
5272 to the beginning and end
5273 of each directory in $CPPPATH.
5274 Any command lines you define that need
5275 the CPPPATH directory list should
5276 include $_CPPINCFLAGS:
5279 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5283 The list of suffixes of files that will be scanned
5284 for C preprocessor implicit dependencies
5286 The default list is:
5289 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5290 ".h", ".H", ".hxx", ".hpp", ".hh",
5291 ".F", ".fpp", ".FPP",
5293 ".S", ".spp", ".SPP"]
5300 Options that are passed to the CVS checkout subcommand.
5303 The command line used to
5304 fetch source files from a CVS repository.
5307 The string displayed when fetching
5308 a source file from a CVS repository.
5309 If this is not set, then $CVSCOM
5310 (the command line) is displayed.
5313 General options that are passed to CVS.
5314 By default, this is set to
5316 to specify from where the files must be fetched.
5319 The path to the CVS repository.
5320 This is referenced in the default
5327 The suffix for C++ source files.
5328 This is used by the internal CXXFile builder
5329 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
5330 The default suffix is
5332 SCons also treats files with the suffixes
5341 suffixes as Objective C++ files.
5342 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5349 The command line used to compile a C++ source file to an object file.
5350 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
5351 are included on this command line.
5354 The string displayed when a C++ source file
5355 is compiled to a (static) object file.
5356 If this is not set, then $CXXCOM (the command line) is displayed.
5359 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5363 General options that are passed to the C++ compiler.
5364 By default, this includes the value of $CCFLAGS,
5365 so that setting $CCFLAGS affects both C and C++ compilation.
5366 If you want to add C++-specific flags,
5367 you must set or override the value of $CXXFLAGS.
5370 The version number of the C++ compiler.
5371 This may or may not be set,
5372 depending on the specific C++ compiler being used.
5375 A function that converts a string
5376 into a Dir instance relative to the target being built.
5379 A function that converts a list of strings
5380 into a list of Dir instances relative to the target being built.
5383 The list of suffixes of files that will be scanned
5384 for imported D package files.
5385 The default list is:
5392 The TeX DVI file to PDF file converter.
5395 General options passed to the TeX DVI file to PDF file converter.
5398 The command line used to convert TeX DVI files into a PDF file.
5401 The string displayed when a TeX DVI file
5402 is converted into a PDF file.
5403 If this is not set, then $DVIPDFCOM (the command line) is displayed.
5406 The TeX DVI file to PostScript converter.
5409 General options passed to the TeX DVI file to PostScript converter.
5412 A dictionary of environment variables
5413 to use when invoking commands. When ENV is used in a command all list
5414 values will be joined using the path separator and any other non-string
5415 values will simply be coerced to a string.
5416 Note that, by default,
5420 propagate the environment in force when you
5423 to the commands used to build target files.
5424 This is so that builds will be guaranteed
5425 repeatable regardless of the environment
5426 variables set at the time
5430 If you want to propagate your
5431 environment variables
5432 to the commands executed
5433 to build target files,
5434 you must do so explicitly:
5438 env = Environment(ENV = os.environ)
5442 Note that you can choose only to propagate
5443 certain environment variables.
5447 environment variable,
5450 uses the same utilities
5451 as the invoking shell (or other process):
5456 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5460 A function that will be called to escape shell special characters in
5461 command lines. The function should take one argument: the command line
5462 string to escape; and should return the escaped command line.
5465 The Fortran 77 compiler.
5466 You should normally set the $FORTRAN variable,
5467 which specifies the default Fortran compiler
5468 for all Fortran versions.
5469 You only need to set $F77 if you need to use a specific compiler
5470 or compiler version for Fortran 77 files.
5473 The command line used to compile a Fortran 77 source file to an object file.
5474 You only need to set $F77COM if you need to use a specific
5475 command line for Fortran 77 files.
5476 You should normally set the $FORTRANCOM variable,
5477 which specifies the default command line
5478 for all Fortran versions.
5481 The string displayed when a Fortran 77 source file
5482 is compiled to an object file.
5483 If this is not set, then $F77COM or $FORTRANCOM (the command line) is displayed.
5486 General user-specified options that are passed to the Fortran 77 compiler.
5487 Note that this variable does
5491 (or similar) include search path options
5492 that scons generates automatically from $F77PATH.
5496 for the variable that expands to those options.
5497 You only need to set $F77FLAGS if you need to define specific
5498 user options for Fortran 77 files.
5499 You should normally set the $FORTRANFLAGS variable,
5500 which specifies the user-specified options
5501 passed to the default Fortran compiler
5502 for all Fortran versions.
5505 An automatically-generated construction variable
5506 containing the Fortran 77 compiler command-line options
5507 for specifying directories to be searched for include files.
5508 The value of $_F77INCFLAGS is created
5509 by appending $INCPREFIX and $INCSUFFIX
5510 to the beginning and end
5511 of each directory in $F77PATH.
5514 The list of directories that the Fortran 77 compiler will search for include
5515 directories. The implicit dependency scanner will search these
5516 directories for include files. Don't explicitly put include directory
5517 arguments in $F77FLAGS because the result will be non-portable
5518 and the directories will not be searched by the dependency scanner. Note:
5519 directory names in $F77PATH will be looked-up relative to the SConscript
5520 directory when they are used in a command. To force
5522 to look-up a directory relative to the root of the source tree use #:
5523 You only need to set $F77PATH if you need to define a specific
5524 include path for Fortran 77 files.
5525 You should normally set the $FORTRANPATH variable,
5526 which specifies the include path
5527 for the default Fortran compiler
5528 for all Fortran versions.
5531 env = Environment(F77PATH='#/include')
5535 The directory look-up can also be forced using the
5540 include = Dir('include')
5541 env = Environment(F77PATH=include)
5545 The directory list will be added to command lines
5546 through the automatically-generated
5548 construction variable,
5549 which is constructed by
5550 appending the values of the
5551 $INCPREFIX and $INCSUFFIX
5552 construction variables
5553 to the beginning and end
5554 of each directory in $F77PATH.
5555 Any command lines you define that need
5556 the F77PATH directory list should
5557 include $_F77INCFLAGS:
5560 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5564 The command line used to compile a Fortran 77 source file to an object file
5565 after first running the file through the C preprocessor.
5566 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
5567 are included on this command line.
5568 You only need to set $F77PPCOM if you need to use a specific
5569 C-preprocessor command line for Fortran 77 files.
5570 You should normally set the $FORTRANPPCOM variable,
5571 which specifies the default C-preprocessor command line
5572 for all Fortran versions.
5575 The Fortran 90 compiler.
5576 You should normally set the $FORTRAN variable,
5577 which specifies the default Fortran compiler
5578 for all Fortran versions.
5579 You only need to set $F90 if you need to use a specific compiler
5580 or compiler version for Fortran 90 files.
5583 The command line used to compile a Fortran 90 source file to an object file.
5584 You only need to set $F90COM if you need to use a specific
5585 command line for Fortran 90 files.
5586 You should normally set the $FORTRANCOM variable,
5587 which specifies the default command line
5588 for all Fortran versions.
5591 The string displayed when a Fortran 90 source file
5592 is compiled to an object file.
5593 If this is not set, then $F90COM or $FORTRANCOM
5594 (the command line) is displayed.
5597 General user-specified options that are passed to the Fortran 90 compiler.
5598 Note that this variable does
5602 (or similar) include search path options
5603 that scons generates automatically from $F90PATH.
5607 for the variable that expands to those options.
5608 You only need to set $F90FLAGS if you need to define specific
5609 user options for Fortran 90 files.
5610 You should normally set the $FORTRANFLAGS variable,
5611 which specifies the user-specified options
5612 passed to the default Fortran compiler
5613 for all Fortran versions.
5616 An automatically-generated construction variable
5617 containing the Fortran 90 compiler command-line options
5618 for specifying directories to be searched for include files.
5619 The value of $_F90INCFLAGS is created
5620 by appending $INCPREFIX and $INCSUFFIX
5621 to the beginning and end
5622 of each directory in $F90PATH.
5625 The list of directories that the Fortran 90 compiler will search for include
5626 directories. The implicit dependency scanner will search these
5627 directories for include files. Don't explicitly put include directory
5628 arguments in $F90FLAGS because the result will be non-portable
5629 and the directories will not be searched by the dependency scanner. Note:
5630 directory names in $F90PATH will be looked-up relative to the SConscript
5631 directory when they are used in a command. To force
5633 to look-up a directory relative to the root of the source tree use #:
5634 You only need to set $F90PATH if you need to define a specific
5635 include path for Fortran 90 files.
5636 You should normally set the $FORTRANPATH variable,
5637 which specifies the include path
5638 for the default Fortran compiler
5639 for all Fortran versions.
5642 env = Environment(F90PATH='#/include')
5646 The directory look-up can also be forced using the
5651 include = Dir('include')
5652 env = Environment(F90PATH=include)
5656 The directory list will be added to command lines
5657 through the automatically-generated
5659 construction variable,
5660 which is constructed by
5661 appending the values of the
5662 $INCPREFIX and $INCSUFFIX
5663 construction variables
5664 to the beginning and end
5665 of each directory in $F90PATH.
5666 Any command lines you define that need
5667 the F90PATH directory list should
5668 include $_F90INCFLAGS:
5671 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5675 The command line used to compile a Fortran 90 source file to an object file
5676 after first running the file through the C preprocessor.
5677 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
5678 are included on this command line.
5679 You only need to set $F90PPCOM if you need to use a specific
5680 C-preprocessor command line for Fortran 90 files.
5681 You should normally set the $FORTRANPPCOM variable,
5682 which specifies the default C-preprocessor command line
5683 for all Fortran versions.
5686 The Fortran 95 compiler.
5687 You should normally set the $FORTRAN variable,
5688 which specifies the default Fortran compiler
5689 for all Fortran versions.
5690 You only need to set $F95 if you need to use a specific compiler
5691 or compiler version for Fortran 95 files.
5694 The command line used to compile a Fortran 95 source file to an object file.
5695 You only need to set $F95COM if you need to use a specific
5696 command line for Fortran 95 files.
5697 You should normally set the $FORTRANCOM variable,
5698 which specifies the default command line
5699 for all Fortran versions.
5702 The string displayed when a Fortran 95 source file
5703 is compiled to an object file.
5704 If this is not set, then $F95COM or $FORTRANCOM
5705 (the command line) is displayed.
5708 General user-specified options that are passed to the Fortran 95 compiler.
5709 Note that this variable does
5713 (or similar) include search path options
5714 that scons generates automatically from $F95PATH.
5718 for the variable that expands to those options.
5719 You only need to set $F95FLAGS if you need to define specific
5720 user options for Fortran 95 files.
5721 You should normally set the $FORTRANFLAGS variable,
5722 which specifies the user-specified options
5723 passed to the default Fortran compiler
5724 for all Fortran versions.
5727 An automatically-generated construction variable
5728 containing the Fortran 95 compiler command-line options
5729 for specifying directories to be searched for include files.
5730 The value of $_F95INCFLAGS is created
5731 by appending $INCPREFIX and $INCSUFFIX
5732 to the beginning and end
5733 of each directory in $F95PATH.
5736 The list of directories that the Fortran 95 compiler will search for include
5737 directories. The implicit dependency scanner will search these
5738 directories for include files. Don't explicitly put include directory
5739 arguments in $F95FLAGS because the result will be non-portable
5740 and the directories will not be searched by the dependency scanner. Note:
5741 directory names in $F95PATH will be looked-up relative to the SConscript
5742 directory when they are used in a command. To force
5744 to look-up a directory relative to the root of the source tree use #:
5745 You only need to set $F95PATH if you need to define a specific
5746 include path for Fortran 95 files.
5747 You should normally set the $FORTRANPATH variable,
5748 which specifies the include path
5749 for the default Fortran compiler
5750 for all Fortran versions.
5753 env = Environment(F95PATH='#/include')
5757 The directory look-up can also be forced using the
5762 include = Dir('include')
5763 env = Environment(F95PATH=include)
5767 The directory list will be added to command lines
5768 through the automatically-generated
5770 construction variable,
5771 which is constructed by
5772 appending the values of the
5773 $INCPREFIX and $INCSUFFIX
5774 construction variables
5775 to the beginning and end
5776 of each directory in $F95PATH.
5777 Any command lines you define that need
5778 the F95PATH directory list should
5779 include $_F95INCFLAGS:
5782 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5786 The command line used to compile a Fortran 95 source file to an object file
5787 after first running the file through the C preprocessor.
5788 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
5789 are included on this command line.
5790 You only need to set $F95PPCOM if you need to use a specific
5791 C-preprocessor command line for Fortran 95 files.
5792 You should normally set the $FORTRANPPCOM variable,
5793 which specifies the default C-preprocessor command line
5794 for all Fortran versions.
5797 The default Fortran compiler
5798 for all versions of Fortran.
5801 The command line used to compile a Fortran source file to an object file.
5802 By default, any options specified
5803 in the $FORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS,
5804 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables
5805 are included on this command line.
5808 The string displayed when a Fortran source file
5809 is compiled to an object file.
5810 If this is not set, then $FORTRANCOM
5811 (the command line) is displayed.
5814 General user-specified options that are passed to the Fortran compiler.
5815 Note that this variable does
5819 (or similar) include or module search path options
5820 that scons generates automatically from $FORTRANPATH.
5822 .BR _FORTRANINCFLAGS and _FORTRANMODFLAGS,
5824 for the variables that expand those options.
5826 .IP _FORTRANINCFLAGS
5827 An automatically-generated construction variable
5828 containing the Fortran compiler command-line options
5829 for specifying directories to be searched for include
5830 files and module files.
5831 The value of $_FORTRANINCFLAGS is created
5832 by prepending/appending $INCPREFIX and $INCSUFFIX
5833 to the beginning and end
5834 of each directory in $FORTRANPATH.
5837 Directory location where the Fortran compiler should place
5838 any module files it generates. This variable is empty, by default. Some
5839 Fortran compilers will internally append this directory in the search path
5840 for module files, as well.
5842 .IP FORTRANMODDIRPREFIX
5843 The prefix used to specify a module directory on the Fortran compiler command
5845 This will be appended to the beginning of the directory
5846 in the $FORTRANMODDIR construction variables
5847 when the $_FORTRANMODFLAG variables is automatically generated.
5849 .IP FORTRANMODDIRSUFFIX
5850 The suffix used to specify a module directory on the Fortran compiler command
5852 This will be appended to the beginning of the directory
5853 in the $FORTRANMODDIR construction variables
5854 when the $_FORTRANMODFLAG variables is automatically generated.
5857 An automatically-generated construction variable
5858 containing the Fortran compiler command-line option
5859 for specifying the directory location where the Fortran
5860 compiler should place any module files that happen to get
5861 generated during compilation.
5862 The value of $_FORTRANMODFLAG is created
5863 by prepending/appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX
5864 to the beginning and end of the directory in $FORTRANMODDIR.
5866 .IP FORTRANMODPREFIX
5867 The module file prefix used by the Fortran compiler. SCons assumes that
5868 the Fortran compiler follows the quasi-standard naming convention for
5870 .I <module_name>.mod.
5871 As a result, this variable is left empty, by default. For situations in
5872 which the compiler does not necessarily follow the normal convention,
5873 the user may use this variable. Its value will be appended to every
5874 module file name as scons attempts to resolve dependencies.
5876 .IP FORTRANMODSUFFIX
5877 The module file suffix used by the Fortran compiler. SCons assumes that
5878 the Fortran compiler follows the quasi-standard naming convention for
5880 .I <module_name>.mod.
5881 As a result, this variable is set to ".mod", by default. For situations
5882 in which the compiler does not necessarily follow the normal convention,
5883 the user may use this variable. Its value will be appended to every
5884 module file name as scons attempts to resolve dependencies.
5887 The list of directories that the Fortran compiler will search for
5888 include files and (for some compilers) module files. The Fortran implicit
5889 dependency scanner will search these directories for include files (but
5890 not module files since they are autogenerated and, as such, may not
5891 actually exist at the time the scan takes place). Don't explicitly put
5892 include directory arguments in FORTRANFLAGS because the result will be
5893 non-portable and the directories will not be searched by the dependency
5894 scanner. Note: directory names in FORTRANPATH will be looked-up relative
5895 to the SConscript directory when they are used in a command. To force
5897 to look-up a directory relative to the root of the source tree use #:
5900 env = Environment(FORTRANPATH='#/include')
5904 The directory look-up can also be forced using the
5909 include = Dir('include')
5910 env = Environment(FORTRANPATH=include)
5914 The directory list will be added to command lines
5915 through the automatically-generated
5917 construction variable,
5918 which is constructed by
5919 appending the values of the
5920 $INCPREFIX and $INCSUFFIX
5921 construction variables
5922 to the beginning and end
5923 of each directory in $FORTRANPATH.
5924 Any command lines you define that need
5925 the FORTRANPATH directory list should
5926 include $_FORTRANINCFLAGS:
5929 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5933 The command line used to compile a Fortran source file to an object file
5934 after first running the file through the C preprocessor.
5935 By default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
5936 _CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
5937 construction variables are included on this command line.
5940 The list of suffixes of files that will be scanned
5941 for Fortran implicit dependencies
5942 (INCLUDE lines & USE statements).
5943 The default list is:
5946 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5947 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5951 A function that converts a string into a File instance relative to the
5955 On Mac OS X with gcc,
5956 a list containing the paths to search for frameworks.
5957 Used by the compiler to find framework-style includes like
5958 #include <Fmwk/Header.h>.
5959 Used by the linker to find user-specified frameworks when linking (see
5963 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
5968 ... -Fmyframeworkdir
5971 to the compiler and linker command lines.
5974 On Mac OS X with gcc, an automatically-generated construction variable
5975 containing the linker command-line options corresponding to FRAMEWORKPATH.
5977 .IP FRAMEWORKPATHPREFIX
5978 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
5979 (see $FRAMEWORKPATH).
5980 The default value is
5984 On Mac OS X with gcc,
5985 the prefix to be used for linking in frameworks
5987 The default value is
5991 On Mac OS X with gcc, a list of the framework names to be linked into a
5992 program or shared library or bundle.
5993 The default value is the empty list.
5996 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
6000 On Mac OS X with gcc,
6001 an automatically-generated construction variable
6002 containing the linker command-line options
6003 for linking with FRAMEWORKS.
6006 On Mac OS X with gcc,
6007 general user-supplied frameworks options to be added at
6008 the end of a command
6009 line building a loadable module.
6010 (This has been largely superceded by
6011 the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX,
6012 $FRAMWORKPREFIX and $FRAMEWORKS variables
6016 The Ghostscript program used to convert PostScript to PDF files.
6019 General options passed to the Ghostscript program
6020 when converting PostScript to PDF files.
6023 The Ghostscript command line used to convert PostScript to PDF files.
6026 The string displayed when
6027 Ghostscript is used to convert
6028 a PostScript file to a PDF file.
6029 If this is not set, then $GSCOM (the command line) is displayed.
6032 The list of suffixes of files that will be scanned
6033 for IDL implicit dependencies
6034 (#include or import lines).
6035 The default list is:
6042 The prefix used to specify an include directory on the C compiler command
6044 This will be appended to the beginning of each directory
6045 in the $CPPPATH and $FORTRANPATH construction variables
6046 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
6047 variables are automatically generated.
6050 The suffix used to specify an include directory on the C compiler command
6052 This will be appended to the end of each directory
6053 in the $CPPPATH and $FORTRANPATH construction variables
6054 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
6055 variables are automatically generated.
6058 A function to be called to install a file into a
6059 destination file name.
6060 The default function copies the file into the destination
6061 (and sets the destination file's mode and permission bits
6062 to match the source file's).
6063 The function takes the following arguments:
6066 def install(dest, source, env):
6070 is the path name of the destination file.
6072 is the path name of the source file.
6074 is the construction environment
6075 (a dictionary of construction values)
6076 in force for this file installation.
6079 The string displayed when a file is
6080 installed into a destination file name.
6083 Install file: "$SOURCE" as "$TARGET"
6086 .IP INTEL_C_COMPILER_VERSION
6087 Set by the "intelc" Tool
6088 to the major version number of the Intel C compiler
6092 The Java archive tool.
6095 The directory to which the Java archive tool should change
6101 The command line used to call the Java archive tool.
6104 The string displayed when the Java archive tool
6106 If this is not set, then $JARCOM (the command line) is displayed.
6109 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
6113 General options passed to the Java archive tool.
6114 By default this is set to
6116 to create the necessary
6121 The suffix for Java archives:
6129 The command line used to compile a directory tree containing
6130 Java source files to
6131 corresponding Java class files.
6132 Any options specified in the $JAVACFLAGS construction variable
6133 are included on this command line.
6136 The string displayed when compiling
6137 a directory tree of Java source files to
6138 corresponding Java class files.
6139 If this is not set, then $JAVACCOM (the command line) is displayed.
6142 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
6146 General options that are passed to the Java compiler.
6149 The directory in which Java class files may be found.
6150 This is stripped from the beginning of any Java .class
6151 file names supplied to the
6156 The suffix for Java class files;
6161 The Java generator for C header and stub files.
6164 The command line used to generate C header and stub files
6166 Any options specified in the $JAVAHFLAGS construction variable
6167 are included on this command line.
6170 The string displayed when C header and stub files
6171 are generated from Java classes.
6172 If this is not set, then $JAVAHCOM (the command line) is displayed.
6175 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
6179 General options passed to the C header and stub file generator
6183 The suffix for Java files;
6188 The LaTeX structured formatter and typesetter.
6191 The command line used to call the LaTeX structured formatter and typesetter.
6194 The string displayed when calling
6195 the LaTeX structured formatter and typesetter.
6196 If this is not set, then $LATEXCOM (the command line) is displayed.
6199 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
6203 General options passed to the LaTeX structured formatter and typesetter.
6206 The list of suffixes of files that will be scanned
6207 for LaTeX implicit dependencies
6208 (\\include or \\import files).
6209 The default list is:
6212 [".tex", ".ltx", ".latex"]
6216 The linker for building loadable modules.
6217 By default, this is the same as $SHLINK.
6220 The command line for building loadable modules.
6221 On Mac OS X, this uses the $LDMODULE,
6222 $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
6223 On other systems, this is the same as $SHLINK.
6226 The string displayed when building loadable modules.
6227 If this is not set, then $LDMODULECOM (the command line) is displayed.
6230 General user options passed to the linker for building loadable modules.
6233 The prefix used for loadable module file names.
6234 On Mac OS X, this is null;
6235 on other systems, this is
6236 the same as $SHLIBPREFIX.
6239 The suffix used for loadable module file names.
6240 On Mac OS X, this is null;
6241 on other systems, this is
6242 the same as $SHLIBSUFFIX.
6245 The lexical analyzer generator.
6248 General options passed to the lexical analyzer generator.
6251 The command line used to call the lexical analyzer generator
6252 to generate a source file.
6255 The string displayed when generating a source file
6256 using the lexical analyzer generator.
6257 If this is not set, then $LEXCOM (the command line) is displayed.
6260 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
6264 An automatically-generated construction variable
6265 containing the linker command-line options
6266 for specifying directories to be searched for library.
6267 The value of $_LIBDIRFLAGS is created
6268 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
6269 to the beginning and end
6270 of each directory in $LIBPATH.
6273 The prefix used to specify a library directory on the linker command line.
6274 This will be appended to the beginning of each directory
6275 in the $LIBPATH construction variable
6276 when the $_LIBDIRFLAGS variable is automatically generated.
6279 The suffix used to specify a library directory on the linker command line.
6280 This will be appended to the end of each directory
6281 in the $LIBPATH construction variable
6282 when the $_LIBDIRFLAGS variable is automatically generated.
6285 An automatically-generated construction variable
6286 containing the linker command-line options
6287 for specifying libraries to be linked with the resulting target.
6288 The value of $_LIBFLAGS is created
6289 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
6290 to the beginning and end
6291 of each filename in $LIBS.
6294 The prefix used to specify a library to link on the linker command line.
6295 This will be appended to the beginning of each library
6296 in the $LIBS construction variable
6297 when the $_LIBFLAGS variable is automatically generated.
6300 The suffix used to specify a library to link on the linker command line.
6301 This will be appended to the end of each library
6302 in the $LIBS construction variable
6303 when the $_LIBFLAGS variable is automatically generated.
6306 The list of directories that will be searched for libraries.
6307 The implicit dependency scanner will search these
6308 directories for include files. Don't explicitly put include directory
6309 arguments in $LINKFLAGS or $SHLINKFLAGS
6310 because the result will be non-portable
6311 and the directories will not be searched by the dependency scanner. Note:
6312 directory names in LIBPATH will be looked-up relative to the SConscript
6313 directory when they are used in a command. To force
6315 to look-up a directory relative to the root of the source tree use #:
6318 env = Environment(LIBPATH='#/libs')
6322 The directory look-up can also be forced using the
6328 env = Environment(LIBPATH=libs)
6332 The directory list will be added to command lines
6333 through the automatically-generated
6335 construction variable,
6336 which is constructed by
6337 appending the values of the
6338 $LIBDIRPREFIX and $LIBDIRSUFFIX
6339 construction variables
6340 to the beginning and end
6341 of each directory in $LIBPATH.
6342 Any command lines you define that need
6343 the LIBPATH directory list should
6344 include $_LIBDIRFLAGS:
6347 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6351 The prefix used for (static) library file names.
6352 A default value is set for each platform
6353 (posix, win32, os2, etc.),
6354 but the value is overridden by individual tools
6355 (ar, mslib, sgiar, sunar, tlib, etc.)
6356 to reflect the names of the libraries they create.
6359 An array of legal prefixes for library file names.
6362 A list of one or more libraries
6363 that will be linked with
6364 any executable programs
6365 created by this environment.
6368 The library list will be added to command lines
6369 through the automatically-generated
6371 construction variable,
6372 which is constructed by
6373 appending the values of the
6374 $LIBLINKPREFIX and $LIBLINKSUFFIX
6375 construction variables
6376 to the beginning and end
6377 of each filename in $LIBS.
6378 Any command lines you define that need
6379 the LIBS library list should
6383 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6391 list, the name of that file will be added to
6393 and thus the link line, as is, without
6399 env.Append(LIBS=File('/tmp/mylib.so'))
6403 In all cases, scons will add dependencies from the executable program to
6404 all the libraries in this list.
6407 The suffix used for (static) library file names.
6408 A default value is set for each platform
6409 (posix, win32, os2, etc.),
6410 but the value is overridden by individual tools
6411 (ar, mslib, sgiar, sunar, tlib, etc.)
6412 to reflect the names of the libraries they create.
6415 An array of legal suffixes for library file names.
6421 General user options passed to the linker.
6422 Note that this variable should
6426 (or similar) options for linking with the libraries listed in $LIBS,
6429 (or similar) library search path options
6430 that scons generates automatically from $LIBPATH.
6434 for the variable that expands to library-link options,
6438 for the variable that expands to library search path options.
6441 The command line used to link object files into an executable.
6444 The string displayed when object files
6445 are linked into an executable.
6446 If this is not set, then $LINKCOM (the command line) is displayed.
6449 env = Environment(LINKCOMSTR = "Linking $TARGET")
6453 The M4 macro preprocessor.
6456 General options passed to the M4 macro preprocessor.
6459 The command line used to pass files through the M4 macro preprocessor.
6462 The string displayed when
6463 a file is passed through the M4 macro preprocessor.
6464 If this is not set, then $M4COM (the command line) is displayed.
6467 The makeindex generator for the TeX formatter and typesetter and the
6468 LaTeX structured formatter and typesetter.
6471 The command line used to call the makeindex generator for the
6472 TeX formatter and typesetter and the LaTeX structured formatter and
6476 The string displayed when calling the makeindex generator for the
6477 TeX formatter and typesetter
6478 and the LaTeX structured formatter and typesetter.
6479 If this is not set, then $MAKEINDEXCOM (the command line) is displayed.
6482 General options passed to the makeindex generator for the TeX formatter
6483 and typesetter and the LaTeX structured formatter and typesetter.
6486 The maximum number of characters allowed on an external command line.
6488 link lines longer than this many characters
6489 are linke via a temporary file name.
6492 When the Microsoft Visual Studio tools are initialized, they set up
6493 this dictionary with the following keys:
6496 the version of MSVS being used (can be set via
6500 the available versions of MSVS installed
6503 installed directory of Visual C++
6506 installed directory of Visual Studio
6509 installed directory of the .NET framework
6511 .B FRAMEWORKVERSIONS:
6512 list of installed versions of the .NET framework, sorted latest to oldest.
6514 .B FRAMEWORKVERSION:
6515 latest installed version of the .NET framework
6518 installed location of the .NET SDK.
6521 installed location of the Platform SDK.
6523 .B PLATFORMSDK_MODULES:
6524 dictionary of installed Platform SDK modules,
6525 where the dictionary keys are keywords for the various modules, and
6526 the values are 2-tuples where the first is the release date, and the
6527 second is the version number.
6529 If a value isn't set, it wasn't available in the registry.
6531 .IP MSVS_IGNORE_IDE_PATHS
6532 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
6533 instead of the settings from the IDE.
6535 For Visual Studio, SCons will (by default) automatically determine
6536 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
6537 set by the IDE. You can override this behavior by setting these
6538 variables after Environment initialization, or by setting
6539 .B MSVS_IGNORE_IDE_PATHS = 1
6540 in the Environment initialization.
6541 Specifying this will not leave these unset, but will set them to a
6542 minimal set of paths needed to run the tools successfully.
6545 For VS6, the mininimal set is:
6546 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
6547 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
6548 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
6550 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
6551 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
6552 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
6556 Where '<VSDir>' is the installed location of Visual Studio.
6558 .IP MSVS_PROJECT_BASE_PATH
6560 placed in a generated Microsoft Visual Studio solution file
6562 .B SccProjectFilePathRelativizedFromConnection0
6564 .B SccProjectFilePathRelativizedFromConnection1
6566 .B GlobalSection(SourceCodeControl)
6568 There is no default value.
6570 .IP MSVS_PROJECT_GUID
6572 placed in a generated Microsoft Visual Studio project file
6576 The string is also placed in the
6579 .B GlobalSection(SourceCodeControl)
6580 section of the Microsoft Visual Studio solution file.
6581 There is no default value.
6583 .IP MSVS_SCC_AUX_PATH
6585 placed in a generated Microsoft Visual Studio project file
6590 .I MSVS_SCC_PROVIDER
6591 construction variable is also set.
6592 There is no default value.
6594 .IP MSVS_SCC_LOCAL_PATH
6596 placed in a generated Microsoft Visual Studio project file
6601 .I MSVS_SCC_PROVIDER
6602 construction variable is also set.
6603 The path name is also placed in the
6608 .B GlobalSection(SourceCodeControl)
6609 section of the Microsoft Visual Studio solution file.
6610 There is no default value.
6612 .IP MSVS_SCC_PROJECT_NAME
6614 placed in a generated Microsoft Visual Studio project file
6618 There is no default value.
6620 .IP MSVS_SCC_PROVIDER
6622 placed in a generated Microsoft Visual Studio project file
6626 The string is also placed in the
6629 .B GlobalSection(SourceCodeControl)
6630 section of the Microsoft Visual Studio solution file.
6631 There is no default value.
6633 .IP MSVS_USE_MFC_DIRS
6634 Tells the MS Visual Studio tool(s) to use
6635 the MFC directories in its default paths
6636 for compiling and linking.
6637 Under MSVS version 6,
6639 .B MSVS_USE_MFC_DIRS
6648 external environment variable,
6654 external environment variable.
6655 Under MSVS version 7,
6657 .B MSVS_USE_MFC_DIRS
6660 .B "atlmfc\\\\include"
6661 directory to the default
6663 external environment variable,
6666 directory to the default
6668 external environment variable.
6669 The current default value is
6671 which means these directories
6672 are added to the paths by default.
6673 This default value is likely to change
6674 in a future release,
6675 so users who want the ATL and MFC
6676 values included in their paths
6677 are encouraged to enable the
6678 .B MSVS_USE_MFC_DIRS
6680 to avoid future incompatibility.
6681 This variable has no effect if the
6685 environment variables are set explictly.
6688 Sets the preferred version of MSVS to use.
6690 SCons will (by default) select the latest version of MSVS
6691 installed on your machine.
6692 So, if you have version 6 and version 7 (MSVS .NET) installed,
6693 it will prefer version 7.
6694 You can override this by
6697 variable in the Environment initialization, setting it to the
6698 appropriate version ('6.0' or '7.0', for example).
6699 If the given version isn't installed, tool initialization will fail.
6702 The build command line placed in
6703 a generated Microsoft Visual Studio project file.
6704 The default is to have Visual Studio invoke SCons with any specified
6708 The clean command line placed in
6709 a generated Microsoft Visual Studio project file.
6710 The default is to have Visual Studio invoke SCons with the -c option
6711 to remove any specified targets.
6714 The encoding string placed in
6715 a generated Microsoft Visual Studio project file.
6716 The default is encoding
6720 The action used to generate Microsoft Visual Studio project files.
6722 .IP MSVSPROJECTSUFFIX
6723 The suffix used for Microsoft Visual Studio project (DSP) files.
6724 The default value is
6726 when using Visual Studio version 7.x (.NET),
6729 when using earlier versions of Visual Studio.
6732 The rebuild command line placed in
6733 a generated Microsoft Visual Studio project file.
6734 The default is to have Visual Studio invoke SCons with any specified
6738 The SCons used in generated Microsoft Visual Studio project files.
6739 The default is the version of SCons being
6740 used to generate the project file.
6743 The SCons flags used in generated Microsoft Visual Studio
6747 The default SCons command used in generated Microsoft Visual Studio
6757 that will be invoked by Visual Studio
6762 The default is the same sconscript file
6763 that contains the call to
6765 to build the project file.
6768 The action used to generate Microsoft Visual Studio solution files.
6770 .IP MSVSSOLUTIONSUFFIX
6771 The suffix used for Microsoft Visual Studio solution (DSW) files.
6772 The default value is
6774 when using Visual Studio version 7.x (.NET),
6777 when using earlier versions of Visual Studio.
6780 The version number of the MetroWerks CodeWarrior C compiler
6784 A list of installed versions of the MetroWerks CodeWarrior C compiler
6788 When set to non-zero,
6789 suppresses creation of a corresponding Win32 static import lib by the
6791 builder when used with
6792 MinGW or Microsoft Visual Studio.
6793 This also suppresses creation
6794 of an export (.exp) file
6795 when using Microsoft Visual Studio.
6798 The prefix used for (static) object file names.
6801 The suffix used for (static) object file names.
6804 The Perforce executable.
6807 The command line used to
6808 fetch source files from Perforce.
6811 The string displayed when
6812 fetching a source file from Perforce.
6813 If this is not set, then $P4COM (the command line) is displayed.
6816 General options that are passed to Perforce.
6819 The Microsoft Visual C++ precompiled header that will be used when compiling
6820 object files. This variable is ignored by tools other than Microsoft Visual C++.
6821 When this variable is
6822 defined SCons will add options to the compiler command line to
6823 cause it to use the precompiled header, and will also set up the
6824 dependencies for the PCH file. Example:
6827 env['PCH'] = 'StdAfx.pch'
6831 The command line used by the
6833 builder to generated a precompiled header.
6836 The string displayed when generating a precompiled header.
6837 If this is not set, then $PCHCOM (the command line) is displayed.
6840 This variable specifies how much of a source file is precompiled. This
6841 variable is ignored by tools other than Microsoft Visual C++, or when
6842 the PCH variable is not being used. When this variable is define it
6843 must be a string that is the name of the header that
6844 is included at the end of the precompiled portion of the source files, or
6845 the empty string if the "#pragma hrdstop" construct is being used:
6848 env['PCHSTOP'] = 'StdAfx.h'
6852 The Microsoft Visual C++ PDB file that will store debugging information for
6853 object files, shared libraries, and programs. This variable is ignored by
6854 tools other than Microsoft Visual C++.
6855 When this variable is
6856 defined SCons will add options to the compiler and linker command line to
6857 cause them to generate external debugging information, and will also set up the
6858 dependencies for the PDB file. Example:
6861 env['PDB'] = 'hello.pdb'
6865 A deprecated synonym for $DVIPDFCOM.
6868 The prefix used for PDF file names.
6871 The suffix used for PDF file names.
6874 The name of the platform used to create the Environment. If no platform is
6875 specified when the Environment is created,
6877 autodetects the platform.
6880 env = Environment(tools = [])
6881 if env['PLATFORM'] == 'cygwin':
6887 .IP PRINT_CMD_LINE_FUNC
6888 A Python function used to print the command lines as they are executed
6889 (assuming command printing is not disabled by the
6893 options or their equivalents).
6894 The function should take four arguments:
6896 the command being executed (a string),
6898 the target being built (file node, list, or string name(s)),
6900 the source(s) used (file node, list, or string name(s)), and
6902 the environment being used.
6904 The function must do the printing itself. The default implementation,
6905 used if this variable is not set or is None, is:
6907 def print_cmd_line(s, target, source, env):
6908 sys.stdout.write(s + "\n")
6911 Here's an example of a more interesting function:
6913 def print_cmd_line(s, target, source, env):
6914 sys.stdout.write("Building %s -> %s...\n" %
6915 (' and '.join([str(x) for x in source]),
6916 ' and '.join([str(x) for x in target])))
6917 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6918 env.Program('foo', 'foo.c')
6921 This just prints "Building <targetname> from <sourcename>..." instead
6922 of the actual commands.
6923 Such a function could also log the actual commands to a log file,
6927 The prefix used for executable file names.
6930 The suffix used for executable file names.
6933 The command line used to convert TeX DVI files into a PostScript file.
6936 The string displayed when a TeX DVI file
6937 is converted into a PostScript file.
6938 If this is not set, then $PSCOM (the command line) is displayed.
6941 The prefix used for PostScript file names.
6944 The prefix used for PostScript file names.
6947 The qt tool tries to take this from os.environ.
6948 It also initializes all QT_*
6949 construction variables listed below.
6950 (Note that all paths are constructed
6951 with python's os.path.join() method,
6952 but are listed here with the '/' separator
6953 for easier reading.)
6954 In addition, the construction environment
6955 variables CPPPATH, LIBPATH and LIBS may be modified
6957 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
6958 are modified. Because the build-performance is affected when using this tool,
6959 you have to explicitly specify it at Environment creation:
6962 Environment(tools=['default','qt'])
6965 The qt tool supports the following operations:
6967 .B Automatic moc file generation from header files.
6968 You do not have to specify moc files explicitly, the tool does it for you.
6969 However, there are a few preconditions to do so: Your header file must have
6970 the same filebase as your implementation file and must stay in the same
6971 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
6972 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
6973 See also the corresponding builder method
6976 .B Automatic moc file generation from cxx files.
6977 As stated in the qt documentation, include the moc file at the end of
6978 the cxx file. Note that you have to include the file, which is generated
6979 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
6980 <basename>.moc. A warning is generated after building the moc file, if you
6981 do not include the correct file. If you are using BuildDir, you may
6982 need to specify duplicate=1. You can turn off automatic moc file generation
6983 by setting QT_AUTOSCAN to 0. See also the corresponding builder method
6986 .B Automatic handling of .ui files.
6987 The implementation files generated from .ui files are handled much the same
6988 as yacc or lex files. Each .ui file given as a source of Program, Library or
6989 SharedLibrary will generate three files, the declaration file, the
6990 implementation file and a moc file. Because there are also generated headers,
6991 you may need to specify duplicate=1 in calls to BuildDir. See also the corresponding builder method
6995 Turn off scanning for mocable files. Use the Moc Builder to explicitely
6996 specify files to run moc on.
6999 The path where the qt binaries are installed.
7000 The default value is '$QTDIR/bin'.
7003 The path where the qt header files are installed.
7004 The default value is '$QTDIR/include'.
7005 Note: If you set this variable to None, the tool won't change the CPPPATH
7006 construction variable.
7009 Prints lots of debugging information while scanning for moc files.
7012 The path where the qt libraries are installed.
7013 The default value is '$QTDIR/lib'.
7014 Note: If you set this variable to None, the tool won't change the LIBPATH
7015 construction variable.
7018 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
7019 this variable to None, the tool won't change the LIBS variable.
7022 Default value is '$QT_BINPATH/moc'.
7025 Default value is ''. Prefix for moc output files, when source is a cxx file.
7028 Default value is '.moc'. Suffix for moc output files, when source is a cxx
7031 .IP QT_MOCFROMCPPFLAGS
7032 Default value is '-i'. These flags are passed to moc, when moccing a
7035 .IP QT_MOCFROMCXXCOM
7036 Command to generate a moc file from a cpp file.
7038 .IP QT_MOCFROMCXXCOMSTR
7039 The string displayed when generating a moc file from a cpp file.
7040 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
7043 Command to generate a moc file from a header.
7045 .IP QT_MOCFROMHCOMSTR
7046 The string displayed when generating a moc file from a cpp file.
7047 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
7049 .IP QT_MOCFROMHFLAGS
7050 Default value is ''. These flags are passed to moc, when moccing a header
7054 Default value is 'moc_'. Prefix for moc output files, when source is a header.
7057 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
7061 Default value is '$QT_BINPATH/uic'.
7064 Command to generate header files from .ui files.
7067 The string displayed when generating header files from .ui files.
7068 If this is not set, then $QT_UICCOM (the command line) is displayed.
7071 Default value is ''. These flags are passed to uic, when creating a a h
7072 file from a .ui file.
7074 .IP QT_UICDECLPREFIX
7075 Default value is ''. Prefix for uic generated header files.
7077 .IP QT_UICDECLSUFFIX
7078 Default value is '.h'. Suffix for uic generated header files.
7081 Default value is ''. These flags are passed to uic, when creating a cxx
7082 file from a .ui file.
7084 .IP QT_UICIMPLPREFIX
7085 Default value is 'uic_'. Prefix for uic generated implementation files.
7087 .IP QT_UICIMPLSUFFIX
7088 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
7092 Default value is '.ui'. Suffix of designer input files.
7095 The archive indexer.
7098 General options passed to the archive indexer.
7101 The resource compiler used to build
7102 a Microsoft Visual C++ resource file.
7105 The command line used to build
7106 a Microsoft Visual C++ resource file.
7109 The string displayed when invoking the resource compiler
7110 to build a Microsoft Visual C++ resource file.
7111 If this is not set, then $RCCOM (the command line) is displayed.
7114 The flags passed to the resource compiler by the RES builder.
7118 Note that this variable is not actually used
7119 for the command to fetch source files from RCS;
7122 construction variable, below.
7125 The RCS "checkout" executable,
7126 used to fetch source files from RCS.
7129 The command line used to
7130 fetch (checkout) source files from RCS.
7133 The string displayed when fetching
7134 a source file from RCS.
7135 If this is not set, then $RCS_COCOM
7136 (the command line) is displayed.
7139 Options that are passed to the $RCS_CO command.
7142 The program used to register DLLs on Windows systems.
7145 The command line used to register a newly-built DLL file
7147 Invoked when the "register=1"
7148 keyword argument is passed to the
7153 The string displayed when registering a newly-built DLL file.
7154 If this is not set, then $REGSVRCOM (the command line) is displayed.
7157 A function that converts a string into a list of Dir instances by
7158 searching the repositories.
7161 The Java RMI stub compiler.
7164 The command line used to compile stub
7165 and skeleton class files
7166 from Java classes that contain RMI implementations.
7167 Any options specified in the $RMICFLAGS construction variable
7168 are included on this command line.
7171 The string displayed when compiling
7172 stub and skeleton class files
7173 from Java classes that contain RMI implementations.
7174 If this is not set, then $RMICCOM (the command line) is displayed.
7177 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
7181 General options passed to the Java RMI stub compiler.
7184 The RPC protocol compiler.
7186 .IP RPCGENCLIENTFLAGS
7187 Options passed to the RPC protocol compiler
7188 when generating client side stubs.
7189 These are in addition to any flags specified in the
7191 construction variable.
7194 General options passed to the RPC protocol compiler.
7196 .IP RPCGENHEADERFLAGS
7197 Options passed to the RPC protocol compiler
7198 when generating a header file.
7199 These are in addition to any flags specified in the
7201 construction variable.
7203 .IP RPCGENSERVICEFLAGS
7204 Options passed to the RPC protocol compiler
7205 when generating server side stubs.
7206 These are in addition to any flags specified in the
7208 construction variable.
7211 Options passed to the RPC protocol compiler
7212 when generating XDR routines.
7213 These are in addition to any flags specified in the
7215 construction variable.
7218 A list of paths to search for shared libraries when running programs.
7219 Currently only used in the GNU (gnulink),
7220 IRIX (sgilink) and Sun (sunlink) linkers.
7221 Ignored on platforms and toolchains that don't support it.
7222 Note that the paths added to RPATH
7223 are not transformed by
7225 in any way: if you want an absolute
7226 path, you must make it absolute yourself.
7229 A list of the available implicit dependency scanners.
7230 New file scanners may be added by
7231 appending to this list,
7232 although the more flexible approach
7233 is to associate scanners
7234 with a specific Builder.
7235 See the sections "Builder Objects"
7236 and "Scanner Objects,"
7237 below, for more information.
7240 The SCCS executable.
7243 The command line used to
7244 fetch source files from SCCS.
7247 The string displayed when fetching
7248 a source file from a CVS repository.
7249 If this is not set, then $SCCSCOM
7250 (the command line) is displayed.
7253 General options that are passed to SCCS.
7256 Options that are passed specifically to the SCCS "get" subcommand.
7257 This can be set, for example, to
7259 to check out editable files from SCCS.
7262 The (optional) path to the SCons library directory,
7263 initialized from the external environment.
7264 If set, this is used to construct a shorter and more
7265 efficient search path in the
7267 command line executed
7268 from Microsoft Visual Studio project files.
7271 The C compiler used for generating shared-library objects.
7274 The command line used to compile a C source file
7275 to a shared-library object file.
7276 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
7277 are included on this command line.
7280 The string displayed when a C source file
7281 is compiled to a shared object file.
7282 If this is not set, then $SHCCCOM (the command line) is displayed.
7285 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
7289 Options that are passed to the C compiler
7290 to generate shared-library objects.
7293 The C++ compiler used for generating shared-library objects.
7296 The command line used to compile a C++ source file
7297 to a shared-library object file.
7298 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
7299 are included on this command line.
7302 The string displayed when a C++ source file
7303 is compiled to a shared object file.
7304 If this is not set, then $SHCXXCOM (the command line) is displayed.
7307 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
7311 Options that are passed to the C++ compiler
7312 to generate shared-library objects.
7315 A string naming the shell program that will be passed to the
7320 construction variable for more information.
7323 The Fortran 77 compiler used for generating shared-library objects.
7324 You should normally set the $SHFORTRANC variable,
7325 which specifies the default Fortran compiler
7326 for all Fortran versions.
7327 You only need to set $SHF77 if you need to use a specific compiler
7328 or compiler version for Fortran 77 files.
7331 The command line used to compile a Fortran 77 source file
7332 to a shared-library object file.
7333 You only need to set $SHF77COM if you need to use a specific
7334 command line for Fortran 77 files.
7335 You should normally set the $SHFORTRANCOM variable,
7336 which specifies the default command line
7337 for all Fortran versions.
7340 The string displayed when a Fortran 77 source file
7341 is compiled to a shared-library object file.
7342 If this is not set, then $SHF77COM or $SHFORTRANCOM
7343 (the command line) is displayed.
7346 Options that are passed to the Fortran 77 compiler
7347 to generated shared-library objects.
7348 You only need to set $SHF77FLAGS if you need to define specific
7349 user options for Fortran 77 files.
7350 You should normally set the $SHFORTRANFLAGS variable,
7351 which specifies the user-specified options
7352 passed to the default Fortran compiler
7353 for all Fortran versions.
7356 The command line used to compile a Fortran 77 source file to a
7357 shared-library object file
7358 after first running the file through the C preprocessor.
7359 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
7360 are included on this command line.
7361 You only need to set $SHF77PPCOM if you need to use a specific
7362 C-preprocessor command line for Fortran 77 files.
7363 You should normally set the $SHFORTRANPPCOM variable,
7364 which specifies the default C-preprocessor command line
7365 for all Fortran versions.
7368 The Fortran 90 compiler used for generating shared-library objects.
7369 You should normally set the $SHFORTRANC variable,
7370 which specifies the default Fortran compiler
7371 for all Fortran versions.
7372 You only need to set $SHF90 if you need to use a specific compiler
7373 or compiler version for Fortran 90 files.
7376 The command line used to compile a Fortran 90 source file
7377 to a shared-library object file.
7378 You only need to set $SHF90COM if you need to use a specific
7379 command line for Fortran 90 files.
7380 You should normally set the $SHFORTRANCOM variable,
7381 which specifies the default command line
7382 for all Fortran versions.
7385 The string displayed when a Fortran 90 source file
7386 is compiled to a shared-library object file.
7387 If this is not set, then $SHF90COM or $SHFORTRANCOM
7388 (the command line) is displayed.
7391 Options that are passed to the Fortran 90 compiler
7392 to generated shared-library objects.
7393 You only need to set $SHF90FLAGS if you need to define specific
7394 user options for Fortran 90 files.
7395 You should normally set the $SHFORTRANFLAGS variable,
7396 which specifies the user-specified options
7397 passed to the default Fortran compiler
7398 for all Fortran versions.
7401 The command line used to compile a Fortran 90 source file to a
7402 shared-library object file
7403 after first running the file through the C preprocessor.
7404 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
7405 are included on this command line.
7406 You only need to set $SHF90PPCOM if you need to use a specific
7407 C-preprocessor command line for Fortran 90 files.
7408 You should normally set the $SHFORTRANPPCOM variable,
7409 which specifies the default C-preprocessor command line
7410 for all Fortran versions.
7413 The Fortran 95 compiler used for generating shared-library objects.
7414 You should normally set the $SHFORTRANC variable,
7415 which specifies the default Fortran compiler
7416 for all Fortran versions.
7417 You only need to set $SHF95 if you need to use a specific compiler
7418 or compiler version for Fortran 95 files.
7421 The command line used to compile a Fortran 95 source file
7422 to a shared-library object file.
7423 You only need to set $SHF95COM if you need to use a specific
7424 command line for Fortran 95 files.
7425 You should normally set the $SHFORTRANCOM variable,
7426 which specifies the default command line
7427 for all Fortran versions.
7430 The string displayed when a Fortran 95 source file
7431 is compiled to a shared-library object file.
7432 If this is not set, then $SHF95COM or $SHFORTRANCOM
7433 (the command line) is displayed.
7436 Options that are passed to the Fortran 95 compiler
7437 to generated shared-library objects.
7438 You only need to set $SHF95FLAGS if you need to define specific
7439 user options for Fortran 95 files.
7440 You should normally set the $SHFORTRANFLAGS variable,
7441 which specifies the user-specified options
7442 passed to the default Fortran compiler
7443 for all Fortran versions.
7446 The command line used to compile a Fortran 95 source file to a
7447 shared-library object file
7448 after first running the file through the C preprocessor.
7449 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
7450 are included on this command line.
7451 You only need to set $SHF95PPCOM if you need to use a specific
7452 C-preprocessor command line for Fortran 95 files.
7453 You should normally set the $SHFORTRANPPCOM variable,
7454 which specifies the default C-preprocessor command line
7455 for all Fortran versions.
7458 The default Fortran compiler used for generating shared-library objects.
7461 The command line used to compile a Fortran source file
7462 to a shared-library object file.
7465 The string displayed when a Fortran source file
7466 is compiled to a shared-library object file.
7467 If this is not set, then $SHFORTRANCOM
7468 (the command line) is displayed.
7471 Options that are passed to the Fortran compiler
7472 to generate shared-library objects.
7475 The command line used to compile a Fortran source file to a
7476 shared-library object file
7477 after first running the file through the C preprocessor.
7478 Any options specified
7479 in the $SHFORTRANFLAGS and $CPPFLAGS construction variables
7480 are included on this command line.
7483 The prefix used for shared library file names.
7486 The suffix used for shared library file names.
7489 The linker for programs that use shared libraries.
7492 The command line used to link programs using shared libaries.
7495 The string displayed when programs using shared libraries are linked.
7496 If this is not set, then $SHLINKCOM (the command line) is displayed.
7499 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
7503 General user options passed to the linker for programs using shared libraries.
7504 Note that this variable should
7508 (or similar) options for linking with the libraries listed in $LIBS,
7511 (or similar) include search path options
7512 that scons generates automatically from $LIBPATH.
7516 for the variable that expands to library-link options,
7520 for the variable that expands to library search path options.
7523 The prefix used for shared object file names.
7526 The suffix used for shared object file names.
7529 A reserved variable name
7530 that may not be set or used in a construction environment.
7531 (See "Variable Substitution," below.)
7534 A reserved variable name
7535 that may not be set or used in a construction environment.
7536 (See "Variable Substitution," below.)
7539 A command interpreter function that will be called to execute command line
7540 strings. The function must expect the following arguments:
7543 def spawn(shell, escape, cmd, args, env):
7547 is a string naming the shell program to use.
7549 is a function that can be called to escape shell special characters in
7552 is the path to the command to be executed.
7554 is the arguments to the command.
7556 is a dictionary of the environment variables
7557 in which the command should be executed.
7560 '\"The Subversion executable (usually named
7564 '\"The command line used to
7565 '\"fetch source files from a Subversion repository.
7568 '\"General options that are passed to Subversion.
7571 The scripting language wrapper and interface generator.
7574 The suffix that will be used for intermediate C
7575 source files generated by
7576 the scripting language wrapper and interface generator.
7577 The default value is
7578 .BR _wrap$CFILESUFFIX .
7579 By default, this value is used whenever the
7583 specified as part of the
7585 construction variable.
7588 The command line used to call
7589 the scripting language wrapper and interface generator.
7592 The string displayed when calling
7593 the scripting language wrapper and interface generator.
7594 If this is not set, then $SWIGCOM (the command line) is displayed.
7596 .IP SWIGCXXFILESUFFIX
7597 The suffix that will be used for intermediate C++
7598 source files generated by
7599 the scripting language wrapper and interface generator.
7600 The default value is
7601 .BR _wrap$CFILESUFFIX .
7602 By default, this value is used whenever the
7604 option is specified as part of the
7606 construction variable.
7609 General options passed to
7610 the scripting language wrapper and interface generator.
7611 This is where you should set
7615 or whatever other options you want to specify to SWIG.
7618 option in this variable,
7621 generate a C++ intermediate source file
7622 with the extension that is specified as the
7630 The command line used to call the tar archiver.
7633 The string displayed when archiving files
7634 using the tar archiver.
7635 If this is not set, then $TARCOM (the command line) is displayed.
7638 env = Environment(TARCOMSTR = "Archiving $TARGET")
7642 General options passed to the tar archiver.
7645 A reserved variable name
7646 that may not be set or used in a construction environment.
7647 (See "Variable Substitution," below.)
7650 A reserved variable name
7651 that may not be set or used in a construction environment.
7652 (See "Variable Substitution," below.)
7655 The suffix used for tar file names.
7658 The prefix for a temporary file used
7659 to execute lines longer than $MAXLINELENGTH.
7661 This may be set for toolchains that use other values,
7662 such as '-@' for the diab compiler
7663 or '-via' for ARM toolchain.
7666 The TeX formatter and typesetter.
7669 The command line used to call the TeX formatter and typesetter.
7672 The string displayed when calling
7673 the TeX formatter and typesetter.
7674 If this is not set, then $TEXCOM (the command line) is displayed.
7677 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7681 General options passed to the TeX formatter and typesetter.
7684 List of directories that the LaTeX programm will search
7685 for include directories.
7686 The LaTeX implicit dependency scanner will search these
7687 directories for \include and \import files.
7690 A list of the names of the Tool specifications
7691 that are part of this construction environment.
7693 .IP WIN32_INSERT_DEF
7694 When this is set to true,
7695 a library build of a WIN32 shared library (.dll file)
7696 will also build a corresponding .def file at the same time,
7697 if a .def file is not already listed as a build target.
7698 The default is 0 (do not build a .def file).
7701 The prefix used for WIN32 .def file names.
7704 The suffix used for WIN32 .def file names.
7707 The parser generator.
7710 The command line used to call the parser generator
7711 to generate a source file.
7714 The string displayed when generating a source file
7715 using the parser generator.
7716 If this is not set, then $YACCCOM (the command line) is displayed.
7719 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
7723 General options passed to the parser generator.
7724 If $YACCFLAGS contains a \-d option,
7725 SCons assumes that the call will also create a .h file
7726 (if the yacc source file ends in a .y suffix)
7728 (if the yacc source file ends in a .yy suffix)
7732 header file generated by the parser generator
7736 Note that setting this variable does not cause
7737 the parser generator to generate a header
7738 file with the specified suffix,
7739 it exists to allow you to specify
7740 what suffix the parser generator will use of its own accord.
7741 The default value is
7744 .IP YACCHXXFILESUFFIX
7745 The suffix of the C++
7746 header file generated by the parser generator
7750 Note that setting this variable does not cause
7751 the parser generator to generate a header
7752 file with the specified suffix,
7753 it exists to allow you to specify
7754 what suffix the parser generator will use of its own accord.
7755 The default value is
7759 The zip compression and file packaging utility.
7762 The command line used to call the zip utility,
7763 or the internal Python function used to create a
7767 The string displayed when archiving files
7768 using the zip utility.
7769 If this is not set, then $ZIPCOM
7770 (the command line or internal Python function) is displayed.
7773 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
7782 module used by the internal Python function
7783 to control whether the zip archive
7784 is compressed or not.
7785 The default value is
7786 .BR zipfile.ZIP_DEFLATED ,
7787 which creates a compressed zip archive.
7788 This value has no effect when using Python 1.5.2
7791 module is otherwise unavailable.
7794 General options passed to the zip utility.
7797 Construction variables can be retrieved and set using the
7799 method of the construction environment:
7802 dict = env.Dictionary()
7806 or using the [] operator:
7812 Construction variables can also be passed to the construction environment
7816 env = Environment(CC="cc")
7819 or when copying a construction environment using the
7824 env2 = env.Copy(CC="cl.exe")
7827 .SS Configure Contexts
7831 .I configure contexts,
7832 an integrated mechanism similar to the
7833 various AC_CHECK macros in GNU autoconf
7834 for testing for the existence of C header
7835 files, libraries, etc.
7836 In contrast to autoconf,
7838 does not maintain an explicit cache of the tested values,
7839 but uses its normal dependency tracking to keep the checked values
7840 up to date. However, users may override this behaviour with the
7842 command line option.
7844 The following methods can be used to perform checks:
7847 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
7849 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
7850 This creates a configure context, which can be used to perform checks.
7852 specifies the environment for building the tests.
7853 This environment may be modified when performing checks.
7855 is a dictionary containing custom tests.
7856 See also the section about custom tests below.
7857 By default, no custom tests are added to the configure context.
7859 specifies a directory where the test cases are built.
7860 Note that this directory is not used for building
7862 The default value is the directory
7865 specifies a file which collects the output from commands
7866 that are executed to check for the existence of header files, libraries, etc.
7867 The default is the file #/config.log.
7868 If you are using the
7871 you may want to specify a subdirectory under your build directory.
7873 specifies a C header file where the results of tests
7874 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
7875 The default is to not write a
7878 You can specify the same
7880 file in multiple calls to Configure,
7883 will concatenate all results in the specified file.
7885 uses its normal dependency checking
7886 to decide if it's necessary to rebuild
7890 This means that the file is not necessarily re-built each
7892 but is only rebuilt if its contents will have changed
7893 and some target that depends on the
7895 file is being built.
7900 instance has the following associated methods:
7903 .RI Configure.Finish( self )
7904 This method should be called after configuration is done.
7905 It returns the environment as modified
7906 by the configuration checks performed.
7907 After this method is called, no further checks can be performed
7908 with this configuration context.
7909 However, you can create a new
7911 context to perform additional checks.
7912 Only one context should be active at a time.
7914 The following Checks are predefined.
7915 (This list will likely grow larger as time
7916 goes by and developers contribute new useful tests.)
7919 .RI Configure.CheckHeader( self ", " header ", [" include_quotes ", " language ])
7922 is usable in the specified language.
7925 in which case the last item in the list
7926 is the header file to be checked,
7927 and the previous list items are
7930 lines should precede the
7931 header line being checked for.
7932 The optional argument
7935 a two character string, where the first character denotes the opening
7936 quote and the second character denotes the closing quote.
7937 By default, both characters are " (double quote).
7938 The optional argument
7944 and selects the compiler to be used for the check.
7945 Returns 1 on success and 0 on failure.
7948 .RI Configure.CheckCHeader( self ", " header ", [" include_quotes ])
7949 This is a wrapper around
7950 .B Configure.CheckHeader
7953 is usable in the C language.
7956 in which case the last item in the list
7957 is the header file to be checked,
7958 and the previous list items are
7961 lines should precede the
7962 header line being checked for.
7963 The optional argument
7966 a two character string, where the first character denotes the opening
7967 quote and the second character denotes the closing quote (both default
7969 Returns 1 on success and 0 on failure.
7972 .RI Configure.CheckCXXHeader( self ", " header ", [" include_quotes ])
7973 This is a wrapper around
7974 .B Configure.CheckHeader
7977 is usable in the C++ language.
7980 in which case the last item in the list
7981 is the header file to be checked,
7982 and the previous list items are
7985 lines should precede the
7986 header line being checked for.
7987 The optional argument
7990 a two character string, where the first character denotes the opening
7991 quote and the second character denotes the closing quote (both default
7993 Returns 1 on success and 0 on failure.
7996 .RI Configure.CheckFunc( self ", " function_name ", [" header ", " language ])
7997 Checks if the specified
7998 C or C++ function is available.
8000 is the name of the function to check for.
8003 argument is a string
8007 that will be compiled
8008 to check if the function exists;
8014 char function_name();
8022 and selects the compiler to be used for the check;
8026 .RI Configure.CheckLib( self ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
8033 is 1 and the library provides the specified
8035 appends the library to the LIBS construction environment variable.
8037 may also be None (the default),
8040 is checked with the current LIBS variable,
8041 or a list of library names,
8042 in which case each library in the list
8049 you can link against the specified
8057 and selects the compiler to be used for the check;
8059 The default value for
8062 It is assumed, that the C-language is used.
8063 This method returns 1 on success and 0 on error.
8066 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
8069 .RI Configure.CheckLib
8070 call, this call provides a more sophisticated way to check against libraries.
8073 specifies the library or a list of libraries to check.
8075 specifies a header to check for.
8078 in which case the last item in the list
8079 is the header file to be checked,
8080 and the previous list items are
8083 lines should precede the
8084 header line being checked for.
8086 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
8088 can be any valid expression (with a trailing ';'). The default is 'main();'.
8090 specifies whether to add the library to the environment (only if the check
8091 succeeds). This method returns 1 on success and 0 on error.
8094 .RI Configure.CheckType( self ", " type_name ", [" includes ", " language ])
8095 Checks for the existence of a type defined by
8098 specifies the typedef name to check for.
8100 is a string containing one or more
8102 lines that will be inserted into the program
8103 that will be run to test for the existence of the type.
8110 and selects the compiler to be used for the check;
8114 Example of a typical Configure usage:
8118 conf = Configure( env )
8119 if not conf.CheckCHeader( 'math.h' ):
8120 print 'We really need math.h!'
8122 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
8123 # do stuff for qt - usage, e.g.
8124 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
8129 You can define your own custom checks.
8130 in addition to the predefined checks.
8131 These are passed in a dictionary to the Configure function.
8132 This dictionary maps the names of the checks
8133 to user defined Python callables
8134 (either Python functions or class instances implementing the
8137 The first argument of the call is always a
8139 instance followed by the arguments,
8140 which must be supplied by the user of the check.
8141 These CheckContext instances define the following methods:
8144 .RI CheckContext.Message( self ", " text )
8146 Usually called before the check is started.
8148 will be displayed to the user, e.g. 'Checking for library X...'
8151 .RI CheckContext.Result( self, ", " res )
8153 Usually called after the check is done.
8155 can be either an integer or a string. In the former case, 'ok' (res != 0)
8156 or 'failed' (res == 0) is displayed to the user, in the latter case the
8157 given string is displayed.
8160 .RI CheckContext.TryCompile( self ", " text ", " extension )
8161 Checks if a file with the specified
8163 (e.g. '.c') containing
8165 can be compiled using the environment's
8167 builder. Returns 1 on success and 0 on failure.
8170 .RI CheckContext.TryLink( self ", " text ", " extension )
8171 Checks, if a file with the specified
8173 (e.g. '.c') containing
8175 can be compiled using the environment's
8177 builder. Returns 1 on success and 0 on failure.
8180 .RI CheckContext.TryRun( self ", " text ", " extension )
8181 Checks, if a file with the specified
8183 (e.g. '.c') containing
8185 can be compiled using the environment's
8187 builder. On success, the program is run. If the program
8188 executes successfully
8189 (that is, its return status is 0),
8194 is the standard output of the
8196 If the program fails execution
8197 (its return status is non-zero),
8198 then (0, '') is returned.
8201 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
8202 Checks if the specified
8204 with an optional source file (contents
8211 may be anything which can be converted to a
8218 is the content of the target file.
8224 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
8225 Low level implementation for testing specific builds;
8226 the methods above are based on this method.
8227 Given the Builder instance
8231 of a source file with optional
8233 this method returns 1 on success and 0 on failure. In addition,
8235 is set to the build target node, if the build was successful.
8238 Example for implementing and using custom tests:
8241 def CheckQt(context, qtdir):
8242 context.Message( 'Checking for qt ...' )
8243 lastLIBS = context.env['LIBS']
8244 lastLIBPATH = context.env['LIBPATH']
8245 lastCPPPATH= context.env['CPPPATH']
8246 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
8247 ret = context.TryLink("""
8249 int main(int argc, char **argv) {
8250 QApplication qapp(argc, argv);
8255 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
8256 context.Result( ret )
8260 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
8261 if not conf.CheckQt('/usr/lib/qt'):
8262 print 'We really need qt!'
8267 .SS Construction Variable Options
8269 Often when building software, various options need to be specified at build
8270 time that are not known when the SConstruct/SConscript files are
8271 written. For example, libraries needed for the build may be in non-standard
8272 locations, or site-specific compiler options may need to be passed to the
8275 provides a mechanism for overridding construction variables from the
8276 command line or a text-based SConscript file through an Options
8277 object. To create an Options object, call the Options() function:
8280 .RI Options([ files "], [" args ])
8281 This creates an Options object that will read construction variables from
8282 the file or list of filenames specified in
8284 If no files are specified,
8289 then no files will be read.
8290 The optional argument
8293 values that will override anything read from the specified files;
8294 it is primarily intended to be passed the
8296 dictionary that holds variables
8297 specified on the command line.
8301 opts = Options('custom.py')
8302 opts = Options('overrides.py', ARGUMENTS)
8303 opts = Options(None, {FOO:'expansion', BAR:7})
8306 Options objects have the following methods:
8309 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
8310 This adds a customizable construction variable to the Options object.
8312 is the name of the variable.
8314 is the help text for the variable.
8316 is the default value of the variable;
8317 if the default value is
8319 and there is no explicit value specified,
8320 the construction variable will
8322 be added to the construction environment.
8324 is called to validate the value of the variable, and should take three
8325 arguments: key, value, and environment
8327 is called to convert the value before putting it in the environment, and
8328 should take a single argument: value. Example:
8331 opts.Add('CC', 'The C compiler')
8335 .RI AddOptions( list )
8336 A wrapper script that adds
8337 multiple customizable construction variables
8338 to an Options object.
8340 is a list of tuple or list objects
8341 that contain the arguments
8342 for an individual call to the
8349 ('CC', 'The C compiler'),
8350 ('VALIDATE', 'An option for testing validation',
8351 'notset', validator, None),
8356 .RI Update( env ", [" args ])
8357 This updates a construction environment
8359 with the customized construction variables. Normally this method is not
8360 called directly, but is called indirectly by passing the Options object to
8361 the Environment() function:
8364 env = Environment(options=opts)
8368 The text file(s) that were specified
8369 when the Options object was created
8370 are executed as Python scripts,
8371 and the values of (global) Python variables set in the file
8372 are added to the construction environment.
8380 .RI Save( filename ", " env )
8381 This saves the currently set options into a script file named
8383 that can be used on the next invocation to automatically load the current
8384 settings. This method combined with the Options method can be used to
8385 support caching of options between runs.
8389 opts = Options(['options.cache', 'custom.py'])
8392 opts.Save('options.cache', env)
8396 .RI GenerateHelpText( env ", [" sort ])
8397 This generates help text documenting the customizable construction
8398 variables suitable to passing in to the Help() function.
8400 is the construction environment that will be used to get the actual values
8401 of customizable variables. Calling with
8405 will cause the output to be sorted
8406 by the specified argument.
8410 should take two arguments
8413 (like the standard Python
8418 Help(opts.GenerateHelpText(env))
8419 Help(opts.GenerateHelpText(env, sort=cmp))
8423 .RI FormatOptionHelpText( env ", " opt ", " help ", " default ", " actual )
8424 This method returns a formatted string
8425 containing the printable help text
8427 It is normally not called directly,
8428 but is called by the
8429 .IR GenerateHelpText ()
8430 method to create the returned help text.
8431 It may be overridden with your own
8432 function that takes the arguments specified above
8433 and returns a string of help text formatted to your liking.
8435 .IR GenerateHelpText ()
8436 will not put any blank lines or extra
8437 characters in between the entries,
8438 so you must add those characters to the returned
8439 string if you want the entries separated.
8442 def my_format(env, opt, help, default, actual):
8443 fmt = "\n%s: default=%s actual=%s (%s)\n"
8444 return fmt % (opt, default. actual, help)
8445 opts.FormatOptionHelpText = my_format
8448 To make it more convenient to work with customizable Options,
8450 provides a number of functions
8451 that make it easy to set up
8452 various types of Options:
8455 .RI BoolOption( key ", " help ", " default )
8456 Return a tuple of arguments
8457 to set up a Boolean option.
8461 have a default value of
8463 and display the specified
8466 The option will interpret the values
8488 .RI EnumOption( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
8489 Return a tuple of arguments
8491 whose value may be one
8492 of a specified list of legal enumerated values.
8496 have a default value of
8498 and display the specified
8501 The option will only support those
8507 argument is a dictionary
8508 that can be used to convert
8509 input values into specific legal values
8518 then the values are case-sensitive.
8523 then values will be matched
8529 then values will be matched
8531 and all input values will be
8532 converted to lower case.
8535 .RI ListOption( key ", " help ", " default ", " names ", [", map ])
8536 Return a tuple of arguments
8538 whose value may be one or more
8539 of a specified list of legal enumerated values.
8543 have a default value of
8545 and display the specified
8548 The option will only support the values
8551 or the values in the
8554 More than one value may be specified,
8555 with all values separated by commas.
8556 The default may be a string of
8557 comma-separated default values,
8558 or a list of the default values.
8561 argument is a dictionary
8562 that can be used to convert
8563 input values into specific legal values
8569 .RI PackageOption( key ", " help ", " default )
8570 Return a tuple of arguments
8572 whose value is a path name
8573 of a package that may be
8574 enabled, disabled or
8575 given an explicit path name.
8579 have a default value of
8581 and display the specified
8584 The option will support the values
8591 in which case the specified
8594 or the option may be set to an
8596 (typically the path name to a package
8597 that is being enabled).
8598 The option will also support the values
8604 to disable use of the specified option.
8607 .RI PathOption( key ", " help ", " default ", [" validator ])
8608 Return a tuple of arguments
8610 whose value is expected to be a path name.
8614 have a default value of
8616 and display the specified
8622 that will be called to
8623 verify that the specified path
8626 following ready-made validators:
8627 .BR PathOption.PathExists
8629 which verifies that the specified path exists;
8630 .BR PathOption.PathIsFile ,
8631 which verifies that the specified path is an existing file;
8632 .BR PathOption.PathIsDir ,
8633 which verifies that the specified path is an existing directory;
8635 .BR PathOption.PathIsDirCreate ,
8636 which verifies that the specified path is a directory,
8637 and will create the specified directory if the path does not exist.
8638 You may supply your own
8641 which must take three arguments
8643 the name of the options variable to be set;
8645 the specified value being checked;
8648 the construction environment)
8649 and should raise an exception
8650 if the specified value is not acceptable.
8653 These functions make it
8654 convenient to create a number
8655 of options with consistent behavior
8656 in a single call to the
8662 BoolOption('warnings', 'compilation with -Wall and similiar', 1),
8663 EnumOption('debug', 'debug output and symbols', 'no'
8664 allowed_values=('yes', 'no', 'full'),
8665 map={}, ignorecase=0), # case sensitive
8666 ListOption('shared',
8667 'libraries to build as shared libraries',
8669 names = list_of_libs),
8670 PackageOption('x11',
8671 'use X11 installed here (yes = search some places)',
8673 PathOption('qtdir', 'where the root of Qt is installed', qtdir),
8674 PathOption('foopath', 'where the foo library is installed', foopath,
8675 PathOption.PathIsDir),
8680 .SS File and Directory Nodes
8690 Nodes, respectively.
8691 python objects, respectively.
8692 Those objects have several user-visible attributes
8693 and methods that are often useful:
8699 This path is relative to the top-level directory
8703 The build path is the same as the source path if
8708 The absolute build path of the given file or directory.
8718 object representing the
8727 # Get the current build dir's path, relative to top.
8729 # Current dir's absolute path
8731 # Next line is always '.', because it is the top dir's path relative to itself.
8733 File('foo.c').srcnode().path # source path of the given source file.
8735 # Builders also return File objects:
8736 foo = env.Program('foo.c')
8737 print "foo will be built in %s"%foo.path
8743 can be extended to build different types of targets
8744 by adding new Builder objects
8745 to a construction environment.
8747 you should only need to add a new Builder object
8748 when you want to build a new type of file or other external target.
8749 If you just want to invoke a different compiler or other tool
8750 to build a Program, Object, Library, or any other
8751 type of output file for which
8753 already has an existing Builder,
8754 it is generally much easier to
8755 use those existing Builders
8756 in a construction environment
8757 that sets the appropriate construction variables
8760 Builder objects are created
8766 function accepts the following arguments:
8769 The command line string used to build the target from the source.
8772 a list of strings representing the command
8773 to be executed and its arguments
8774 (suitable for enclosing white space in an argument),
8776 mapping source file name suffixes to
8777 any combination of command line strings
8778 (if the builder should accept multiple source file extensions),
8781 (see the next section);
8782 or a list of any of the above.
8785 takes three arguments:
8787 - a list of source nodes,
8789 - a list of target nodes,
8791 - the construction environment.
8794 The prefix that will be prepended to the target file name.
8795 This may be specified as a:
8805 - a function or other callable that takes
8806 two arguments (a construction environment and a list of sources)
8807 and returns a prefix,
8812 - specifies a mapping from a specific source suffix (of the first
8813 source specified) to a corresponding target prefix. Both the source
8814 suffix and target prefix specifications may use environment variable
8815 substitution, and the target prefix (the 'value' entries in the
8816 dictionary) may also be a callable object. The default target prefix
8817 may be indicated by a dictionary entry with a key value of None.
8822 b = Builder("build_it < $SOURCE > $TARGET"
8825 def gen_prefix(env, sources):
8826 return "file-" + env['PLATFORM'] + '-'
8827 b = Builder("build_it < $SOURCE > $TARGET",
8828 prefix = gen_prefix)
8830 b = Builder("build_it < $SOURCE > $TARGET",
8831 suffix = { None: "file-",
8832 "$SRC_SFX_A": gen_prefix })
8836 The suffix that will be appended to the target file name.
8837 This may be specified in the same manner as the prefix above.
8838 If the suffix is a string, then
8840 will append a '.' to the beginning of the suffix if it's not already
8841 there. The string returned by callable object (or obtained from the
8842 dictionary) is untouched and must append its own '.' to the beginning
8846 b = Builder("build_it < $SOURCE > $TARGET"
8849 def gen_suffix(env, sources):
8850 return "." + env['PLATFORM'] + "-file"
8851 b = Builder("build_it < $SOURCE > $TARGET",
8852 suffix = gen_suffix)
8854 b = Builder("build_it < $SOURCE > $TARGET",
8855 suffix = { None: ".sfx1",
8856 "$SRC_SFX_A": gen_suffix })
8860 The expected source file name suffix. This may be a string or a list
8864 A Scanner object that
8865 will be invoked to find
8866 implicit dependencies for this target file.
8867 This keyword argument should be used
8868 for Scanner objects that find
8869 implicit dependencies
8870 based only on the target file
8871 and the construction environment,
8874 (See the section "Scanner Objects," below,
8875 for information about creating Scanner objects.)
8878 A Scanner object that
8880 find implicit dependences in
8882 used to build this target file.
8883 This is where you would
8884 specify a scanner to
8887 lines in source files.
8890 Scanner object may be used to
8891 indicate that this Builder
8892 should scan directory trees
8893 for on-disk changes to files
8896 does not know about from other Builder or function calls.
8897 (See the section "Scanner Objects," below,
8898 for information about creating your own Scanner objects.)
8901 A factory function that the Builder will use
8902 to turn any targets specified as strings into SCons Nodes.
8904 SCons assumes that all targets are files.
8905 Other useful target_factory
8908 for when a Builder creates a directory target,
8911 for when a Builder can create either a file
8912 or directory target.
8917 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
8919 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
8920 env.MakeDirectory('new_directory', [])
8923 Note that the call to the MakeDirectory Builder
8924 needs to specify an empty source list
8925 to make the string represent the builder's target;
8926 without that, it would assume the argument is the source,
8927 and would try to deduce the target name from it,
8928 which in the absence of an automatically-added prefix or suffix
8929 would lead to a matching target and source name
8930 and a circular dependency.
8933 A factory function that the Builder will use
8934 to turn any sources specified as strings into SCons Nodes.
8936 SCons assumes that all source are files.
8937 Other useful source_factory
8940 for when a Builder uses a directory as a source,
8943 for when a Builder can use files
8944 or directories (or both) as sources.
8949 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
8951 env.Append(BUILDERS = {'Collect':CollectBuilder})
8952 env.Collect('archive', ['directory_name', 'file_name'])
8956 A function or list of functions to manipulate the target and source
8957 lists before dependencies are established
8958 and the target(s) are actually built.
8960 can also be a string containing a construction variable to expand
8961 to an emitter function or list of functions,
8962 or a dictionary mapping source file suffixes
8963 to emitter functions.
8964 (Only the suffix of the first source file
8965 is used to select the actual emitter function
8966 from an emitter dictionary.)
8969 takes three arguments:
8971 - a list of source nodes,
8973 - a list of target nodes,
8975 - the construction environment.
8976 An emitter must return a tuple containing two lists,
8977 the list of targets to be built by this builder,
8978 and the list of sources for this builder.
8983 def e(target, source, env):
8984 return (target + ['foo.foo'], source + ['foo.src'])
8986 # Simple association of an emitter function with a Builder.
8987 b = Builder("my_build < $TARGET > $SOURCE",
8990 def e2(target, source, env):
8991 return (target + ['bar.foo'], source + ['bar.src'])
8993 # Simple association of a list of emitter functions with a Builder.
8994 b = Builder("my_build < $TARGET > $SOURCE",
8997 # Calling an emitter function through a construction variable.
8998 env = Environment(MY_EMITTER = e)
8999 b = Builder("my_build < $TARGET > $SOURCE",
9000 emitter = '$MY_EMITTER')
9002 # Calling a list of emitter functions through a construction variable.
9003 env = Environment(EMITTER_LIST = [e, e2])
9004 b = Builder("my_build < $TARGET > $SOURCE",
9005 emitter = '$EMITTER_LIST')
9007 # Associating multiple emitters with different file
9008 # suffixes using a dictionary.
9009 def e_suf1(target, source, env):
9010 return (target + ['another_target_file'], source)
9011 def e_suf2(target, source, env):
9012 return (target, source + ['another_source_file'])
9013 b = Builder("my_build < $TARGET > $SOURCE",
9014 emitter = {'.suf1' : e_suf1,
9019 Specifies whether this builder is allowed to be called multiple times for
9020 the same target file(s). The default is 0, which means the builder
9021 can not be called multiple times for the same target file(s). Calling a
9022 builder multiple times for the same target simply adds additional source
9023 files to the target; it is not allowed to change the environment associated
9024 with the target, specify addition environment overrides, or associate a different
9025 builder with the target.
9028 A construction environment that can be used
9029 to fetch source code using this Builder.
9030 (Note that this environment is
9032 used for normal builds of normal target files,
9033 which use the environment that was
9034 used to call the Builder for the target file.)
9037 A function that returns a list of actions that will be executed to build
9038 the target(s) from the source(s).
9039 The returned action(s) may be
9040 an Action object, or anything that
9041 can be converted into an Action object
9042 (see the next section).
9044 The generator function
9045 takes four arguments:
9047 - a list of source nodes,
9049 - a list of target nodes,
9051 - the construction environment,
9053 - a Boolean value that specifies
9054 whether the generator is being called
9055 for generating a build signature
9056 (as opposed to actually executing the command).
9060 def g(source, target, env, for_signature):
9061 return [["gcc", "-c", "-o"] + target + source]
9063 b = Builder(generator=g)
9071 arguments must not both be used for the same Builder.
9074 Specifies a builder to use when a source file name suffix does not match
9075 any of the suffixes of the builder. Using this argument produces a
9076 multi-stage builder.
9079 Specifies that this builder expects exactly one source file per call. Giving
9080 more than one source files without target files results in implicitely calling
9081 the builder multiple times (once for each source given). Giving multiple
9082 source files together with target files results in a UserError exception.
9090 arguments must not both be used for the same Builder.
9093 A construction environment that can be used
9094 to fetch source code using this Builder.
9095 (Note that this environment is
9097 used for normal builds of normal target files,
9098 which use the environment that was
9099 used to call the Builder for the target file.)
9102 b = Builder(action="build < $SOURCE > $TARGET")
9103 env = Environment(BUILDERS = {'MyBuild' : b})
9104 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
9108 A directory from which scons
9115 a string or a directory Node,
9116 scons will change to the specified directory.
9119 is not a string or Node
9121 then scons will change to the
9122 target file's directory.
9124 Note that scons will
9126 automatically modify
9128 construction variables like
9132 when using the chdir
9133 keyword argument--that is,
9134 the expanded file names
9135 will still be relative to
9136 the top-level SConstruct directory,
9137 and consequently incorrect
9138 relative to the chdir directory.
9139 Builders created using chdir keyword argument,
9140 will need to use construction variable
9145 to use just the filename portion of the
9149 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
9151 env = Environment(BUILDERS = {'MyBuild' : b})
9152 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
9156 Any additional keyword arguments supplied
9157 when a Builder object is created
9158 (that is, when the Builder() function is called)
9159 will be set in the executing construction
9160 environment when the Builder object is called.
9161 The canonical example here would be
9162 to set a construction variable to
9163 the repository of a source code system.
9165 Any additional keyword arguments supplied
9169 will only be associated with the target
9170 created by that particular Builder call
9171 (and any other files built as a
9172 result of the call).
9174 These extra keyword arguments are passed to the
9175 following functions:
9176 command generator functions,
9178 and emitter functions.
9184 function will turn its
9186 keyword argument into an appropriate
9187 internal Action object.
9188 You can also explicity create Action objects
9192 which can then be passed to the
9195 This can be used to configure
9196 an Action object more flexibly,
9197 or it may simply be more efficient
9198 than letting each separate Builder object
9199 create a separate Action
9201 Builder objects need to do the same thing.
9206 returns an appropriate object for the action
9207 represented by the type of the first argument:
9210 If the first argument is already an Action object,
9211 the object is simply returned.
9214 If the first argument is a string,
9215 a command-line Action is returned.
9216 Note that the command line string
9217 may be preceded by an
9220 to suppress printing of the
9221 specified command line,
9225 to ignore the exit status from
9226 the specified command.
9230 Action('$CC -c -o $TARGET $SOURCES')
9232 # Doesn't print the line being executed.
9233 Action('@build $TARGET $SOURCES')
9236 Action('-build $TARGET $SOURCES')
9239 .\" XXX From Gary Ruben, 23 April 2002:
9240 .\" What would be useful is a discussion of how you execute command
9241 .\" shell commands ie. what is the process used to spawn the shell, pass
9242 .\" environment variables to it etc., whether there is one shell per
9243 .\" environment or one per command etc. It might help to look at the Gnu
9244 .\" make documentation to see what they think is important to discuss about
9245 .\" a build system. I'm sure you can do a better job of organising the
9246 .\" documentation than they have :-)
9250 If the first argument is a list,
9251 then a list of Action objects is returned.
9252 An Action object is created as necessary
9253 for each element in the list.
9256 the list is itself a list,
9257 the internal list is the
9258 command and arguments to be executed via
9260 This allows white space to be enclosed
9261 in an argument by defining
9262 a command in a list within a list:
9265 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
9269 If the first argument is a Python function,
9270 a function Action is returned.
9271 The Python function takes three keyword arguments,
9273 (a Node object representing the target file),
9275 (a Node object representing the source file)
9278 (the construction environment
9279 used for building the target file).
9284 arguments may be lists of Node objects if there is
9285 more than one target file or source file.
9286 The actual target and source file name(s) may
9287 be retrieved from their Node objects
9288 via the built-in Python str() function:
9291 target_file_name = str(target)
9292 source_file_names = map(lambda x: str(x), source)
9295 The function should return
9299 to indicate a successful build of the target file(s).
9300 The function may raise an exception
9301 or return a non-zero exit status
9302 to indicate an unsuccessful build.
9305 def build_it(target = None, source = None, env = None):
9306 # build the target from the source
9309 a = Action(build_it)
9312 If the action argument is not one of the above,
9315 The second, optional argument
9316 is a Python function that returns
9317 a string to be printed to describe the action being executed.
9318 Like a function to build a file,
9319 this function takes three arguments:
9321 (a Node object representing the target file),
9323 (a Node object representing the source file)
9326 (a construction environment).
9331 arguments may be lists of Node objects if there is
9332 more than one target file or source file.
9336 def build_it(target, source, env):
9337 # build the target from the source
9340 def string_it(target, source, env):
9341 return "building '%s' from '%s'" % (target[0], source[0])
9343 # Use a positional argument.
9344 a = Action(build_it, string_it)
9346 # Alternatively, use a keyword argument.
9347 a = Action(build_it, strfunction=string_it)
9350 The third, also optional argument
9351 is a list of construction variables
9352 whose values will be included
9353 in the signature of the Action
9354 when deciding whether a target should
9355 be rebuilt because the action changed.
9356 This is necessary whenever you want a target to
9357 be rebuilt when a specific
9358 construction variable changes,
9359 because the underlying Python code for a function
9360 will not change when the value of the construction variable does.
9363 def build_it(target, source, env):
9364 # build the target from the 'XXX' construction variable
9365 open(target[0], 'w').write(env['XXX'])
9368 def string_it(target, source):
9369 return "building '%s' from '%s'" % (target[0], source[0])
9371 # Use positional arguments.
9372 a = Action(build_it, string_it, ['XXX'])
9374 # Alternatively, use a keyword argument.
9375 a = Action(build_it, varlist=['XXX'])
9385 which specifies that
9386 scons will execute the action
9387 after changing to the specified directory.
9388 If the chdir argument is
9389 a string or a directory Node,
9390 scons will change to the specified directory.
9391 If the chdir argument
9392 is not a string or Node
9394 then scons will change to the
9395 target file's directory.
9397 Note that scons will
9399 automatically modify
9401 construction variables like
9405 when using the chdir
9406 keyword argument--that is,
9407 the expanded file names
9408 will still be relative to
9409 the top-level SConstruct directory,
9410 and consequently incorrect
9411 relative to the chdir directory.
9412 Builders created using chdir keyword argument,
9413 will need to use construction variable
9418 to use just the filename portion of the
9422 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9432 which specifies a function
9433 that is passed the exit status
9435 from the specified action
9436 and can return an arbitrary
9438 This can be used, for example,
9439 to specify that an Action object's
9440 return value should be ignored
9441 and SCons should, therefore,
9442 consider that the action always suceeds:
9445 def always_succeed(s):
9446 # Always return 0, which indicates success.
9448 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9449 exitstatfunc=always_succeed)
9452 .SS Miscellaneous Action Functions
9455 supplies a number of functions
9456 that arrange for various common
9457 file and directory manipulations
9459 These are similar in concept to "tasks" in the
9461 although the implementation is slightly different.
9462 These functions do not actually
9463 perform the specified action
9464 at the time the function is called,
9465 but instead return an Action object
9466 that can be executed at the
9468 (In Object-Oriented terminology,
9473 that return Action objects.)
9476 there are two natural ways
9479 are intended to be used.
9483 to perform the action
9484 at the time the SConscript
9488 global function to do so:
9490 Execute(Touch('file'))
9494 you can use these functions
9495 to supply Actions in a list
9499 This can allow you to
9500 perform more complicated
9501 sequences of file manipulation
9503 on platform-specific
9507 env = Environment(TMPBUILD = '/tmp/builddir')
9508 env.Command('foo.out', 'foo.in',
9509 [Mkdir('$TMPBUILD'),
9510 Copy('$TMPBUILD', '${SOURCE.dir}')
9511 "cd $TMPBUILD && make",
9512 Delete('$TMPBUILD')])
9516 .RI Chmod( dest ", " mode )
9517 Returns an Action object that
9518 changes the permissions on the specified
9520 file or directory to the specified
9525 Execute(Chmod('file', 0755))
9527 env.Command('foo.out', 'foo.in',
9528 [Copy('$TARGET', '$SOURCE'),
9529 Chmod('$TARGET', 0755)])
9533 .RI Copy( dest ", " src )
9534 Returns an Action object
9537 source file or directory to the
9539 destination file or directory.
9543 Execute(Copy('foo.output', 'foo.input'))
9545 env.Command('bar.out', 'bar.in',
9546 Copy('$TARGET', '$SOURCE'))
9550 .RI Delete( entry ", [" must_exist ])
9551 Returns an Action that
9552 deletes the specified
9554 which may be a file or a directory tree.
9555 If a directory is specified,
9556 the entire directory tree
9561 then a Python error will be thrown
9562 if the specified entry does not exist;
9565 that is, the Action will silently do nothing
9566 if the entry does not exist.
9570 Execute(Delete('/tmp/buildroot'))
9572 env.Command('foo.out', 'foo.in',
9573 [Delete('${TARGET.dir}'),
9576 Execute(Delete('file_that_must_exist', must_exist=1))
9582 that creates the specified
9588 Execute(Mkdir('/tmp/outputdir'))
9590 env.Command('foo.out', 'foo.in',
9591 [Mkdir('/tmp/builddir',
9592 Copy('$SOURCE', '/tmp/builddir')
9593 "cd /tmp/builddir && ])
9598 .RI Move( dest ", " src )
9600 that moves the specified
9602 file or directory to
9609 Execute(Move('file.destination', 'file.source'))
9611 env.Command('output_file', 'input_file',
9613 Move('$TARGET', 'file_created_by_MyBuildAction')])
9619 that updates the modification time
9625 Execute(Touch('file_to_be_touched'))
9627 env.Command('marker', 'input_file',
9632 .SS Variable Substitution
9634 Before executing a command,
9636 performs construction variable interpolation on the strings that make up
9637 the command line of builders.
9638 Variables are introduced by a
9641 Besides construction variables, scons provides the following
9642 variables for each command execution:
9645 The file name of the target being built, or the file name of the first
9646 target if multiple targets are being built.
9649 The file names of all targets being built.
9652 The file name of the source of the build command, or the file name of the
9653 first source if multiple sources are being built.
9656 The file names of the sources of the build command.
9658 (Note that the above variables are reserved
9659 and may not be set in a construction environment.)
9662 For example, given the construction variable CC='cc', targets=['foo'], and
9663 sources=['foo.c', 'bar.c']:
9666 action='$CC -c -o $TARGET $SOURCES'
9669 would produce the command line:
9672 cc -c -o foo foo.c bar.c
9675 Variable names may be surrounded by curly braces ({})
9676 to separate the name from the trailing characters.
9677 Within the curly braces, a variable name may have
9678 a Python slice subscript appended to select one
9679 or more items from a list.
9680 In the previous example, the string:
9692 Additionally, a variable name may
9693 have the following special
9694 modifiers appended within the enclosing curly braces
9695 to modify the interpolated string:
9698 The base path of the file name,
9699 including the directory path
9700 but excluding any suffix.
9703 The name of the directory in which the file exists.
9707 minus any directory portion.
9710 Just the basename of the file,
9712 and minus the directory.
9715 Just the file suffix.
9718 The absolute path name of the file.
9721 The POSIX form of the path,
9722 with directories separated by
9726 This is sometimes necessary on Win32 systems
9727 when a path references a file on other (POSIX) systems.
9730 The directory and file name to the source file linked to this file
9731 through BuildDir. If this file isn't linked, it just returns the
9732 directory and filename unchanged.
9735 The directory containing the source file linked to this file
9736 through BuildDir. If this file isn't linked, it just returns the
9737 directory part of the filename.
9740 The directory and file name to the source file linked to this file
9741 through BuildDir. If the file does not exist locally but exists in
9742 a Repository, the path in the Repository is returned.
9743 If this file isn't linked, it just returns the
9744 directory and filename unchanged.
9747 The Repository directory containing the source file linked to this file
9748 through BuildDir. If this file isn't linked, it just returns the
9749 directory part of the filename.
9752 For example, the specified target will
9753 expand as follows for the corresponding modifiers:
9756 $TARGET => sub/dir/file.x
9757 ${TARGET.base} => sub/dir/file
9758 ${TARGET.dir} => sub/dir
9759 ${TARGET.file} => file.x
9760 ${TARGET.filebase} => file
9761 ${TARGET.suffix} => .x
9762 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9764 SConscript('src/SConscript', build_dir='sub/dir')
9765 $SOURCE => sub/dir/file.x
9766 ${SOURCE.srcpath} => src/file.x
9767 ${SOURCE.srcdir} => src
9769 Repository('/usr/repository')
9770 $SOURCE => sub/dir/file.x
9771 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9772 ${SOURCE.rsrcdir} => /usr/repository/src
9775 Lastly, a variable name
9776 may be a callable Python function
9778 construction variable in the environment.
9780 take four arguments:
9782 - a list of target nodes,
9784 - a list of source nodes,
9786 - the construction environment,
9788 - a Boolean value that specifies
9789 whether the function is being called
9790 for generating a build signature.
9791 SCons will insert whatever
9792 the called function returns
9793 into the expanded string:
9796 def foo(target, source, env, for_signature):
9799 # Will expand $BAR to "bar baz"
9800 env=Environment(FOO=foo, BAR="$FOO baz")
9803 You can use this feature to pass arguments to a
9804 Python function by creating a callable class
9805 that stores one or more arguments in an object,
9806 and then uses them when the
9809 Note that in this case,
9810 the entire variable expansion must
9811 be enclosed by curly braces
9812 so that the arguments will
9813 be associated with the
9814 instantiation of the class:
9818 def __init__(self, arg):
9821 def __call__(self, target, source, env, for_signature):
9824 # Will expand $BAR to "my argument bar baz"
9825 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9829 The special pseudo-variables
9833 may be used to surround parts of a command line
9836 causing a rebuild--that is,
9837 which are not included in the signature
9838 of target files built with this command.
9843 will be removed from the command line
9844 before it is added to file signatures,
9849 will be removed before the command is executed.
9850 For example, the command line:
9853 echo Last build occurred $( $TODAY $). > $TARGET
9857 would execute the command:
9860 echo Last build occurred $TODAY. > $TARGET
9864 but the command signature added to any target files would be:
9867 echo Last build occurred . > $TARGET
9870 SCons uses the following rules when converting construction variables into
9874 When the value is a string it is interpreted as a space delimited list of
9875 command line arguments.
9878 When the value is a list it is interpreted as a list of command line
9879 arguments. Each element of the list is converted to a string.
9882 Anything that is not a list or string is converted to a string and
9883 interpreted as a single command line argument.
9886 Newline characters (\\n) delimit lines. The newline parsing is done after
9887 all other parsing, so it is not possible for arguments (e.g. file names) to
9888 contain embedded newline characters. This limitation will likely go away in
9889 a future version of SCons.
9897 new file types for implicit dependencies.
9898 Scanner accepts the following arguments:
9901 A Python function that will process
9903 and return a list of strings (file names)
9904 representing the implicit
9905 dependencies found in the contents.
9906 The function takes three or four arguments:
9908 def scanner_function(node, env, path):
9910 def scanner_function(node, env, path, arg):
9914 argument is the internal
9915 SCons node representing the file.
9918 to fetch the name of the file, and
9919 .B node.get_contents()
9920 to fetch contents of the file.
9924 argument is the construction environment for the scan.
9925 Fetch values from it using the
9931 argument is a tuple (or list)
9932 of directories that can be searched
9934 This will usually be the tuple returned by the
9936 argument (see below).
9940 argument is the argument supplied
9941 when the scanner was created, if any.
9944 The name of the Scanner.
9946 to identify the Scanner internally.
9949 An optional argument that, if specified,
9950 will be passed to the scanner function
9952 and the path function
9956 An optional list that can be used to
9957 determine which scanner should be used for
9959 In the usual case of scanning for file names,
9960 this argument will be a list of suffixes
9961 for the different file types that this
9962 Scanner knows how to scan.
9963 If the argument is a string,
9964 then it will be expanded
9965 into a list by the current environment.
9968 A Python function that takes
9969 two or three arguments:
9970 a construction environment, directory Node,
9971 and optional argument supplied
9972 when the scanner was created.
9975 returns a tuple of directories
9976 that can be searched for files to be returned
9977 by this Scanner object.
9980 The class of Node that should be returned
9981 by this Scanner object.
9982 Any strings or other objects returned
9983 by the scanner function
9984 that are not of this class
9985 will be run through the
9990 A Python function that will take a string
9992 and turn it into the appropriate class of Node
9993 to be returned by this Scanner object.
9996 An optional Python function that takes two arguments,
9997 a Node (file) and a construction environment,
9998 and returns whether the
9999 Node should, in fact,
10000 be scanned for dependencies.
10001 This check can be used to eliminate unnecessary
10002 calls to the scanner function when,
10003 for example, the underlying file
10004 represented by a Node does not yet exist.
10007 An optional flag that
10008 specifies whether this scanner should be re-invoked
10009 on the dependency files returned by the scanner.
10010 When this flag is not set,
10011 the Node subsystem will
10012 only invoke the scanner on the file being scanned,
10013 and not (for example) also on the files
10014 specified by the #include lines
10015 in the file being scanned.
10017 may be a callable function,
10018 in which case it will be called with a list of
10020 should return a list of Nodes
10021 that should be scanned recursively;
10022 this can be used to select a specific subset of
10023 Nodes for additional scanning.
10028 .B SourceFileScanner
10029 object that is used by
10032 .BR SharedObject (),
10034 .BR StaticObject ()
10036 which scanner should be used
10037 for different file extensions.
10039 .BR SourceFileScanner.add_scanner ()
10040 method to add your own Scanner object
10044 that builds target programs or
10045 libraries from a list of
10046 source files of different types:
10049 def xyz_scan(node, env, path):
10050 contents = node.get_contents()
10051 # Scan the contents and return the included files.
10053 XYZScanner = Scanner(xyz_scan)
10055 SourceFileScanner.add_scanner('.xyx', XYZScanner)
10057 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
10060 .SH SYSTEM-SPECIFIC BEHAVIOR
10061 SCons and its configuration files are very portable,
10062 due largely to its implementation in Python.
10063 There are, however, a few portability
10064 issues waiting to trap the unwary.
10066 SCons handles the upper-case
10068 file suffix differently,
10069 depending on the capabilities of
10070 the underlying system.
10071 On a case-sensitive system
10072 such as Linux or UNIX,
10073 SCons treats a file with a
10075 suffix as a C++ source file.
10076 On a case-insensitive system
10078 SCons treats a file with a
10080 suffix as a C source file.
10082 SCons handles the upper-case
10084 file suffix differently,
10085 depending on the capabilities of
10086 the underlying system.
10087 On a case-sensitive system
10088 such as Linux or UNIX,
10089 SCons treats a file with a
10091 suffix as a Fortran source file
10092 that is to be first run through
10093 the standard C preprocessor.
10094 On a case-insensitive system
10096 SCons treats a file with a
10098 suffix as a Fortran source file that should
10100 be run through the C preprocessor.
10101 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
10102 Cygwin supplies a set of tools and utilities
10103 that let users work on a
10104 Windows system using a more POSIX-like environment.
10105 The Cygwin tools, including Cygwin Python,
10107 by sharing an ability to interpret UNIX-like path names.
10108 For example, the Cygwin tools
10109 will internally translate a Cygwin path name
10110 like /cygdrive/c/mydir
10111 to an equivalent Windows pathname
10112 of C:/mydir (equivalent to C:\\mydir).
10115 that are built for native Windows execution,
10116 such as the python.org and ActiveState versions,
10117 do not have the Cygwin path name semantics.
10118 This means that using a native Windows version of Python
10119 to build compiled programs using Cygwin tools
10120 (such as gcc, bison, and flex)
10121 may yield unpredictable results.
10122 "Mixing and matching" in this way
10123 can be made to work,
10124 but it requires careful attention to the use of path names
10125 in your SConscript files.
10127 In practice, users can sidestep
10128 the issue by adopting the following rules:
10130 use the Cygwin-supplied Python interpreter
10132 when using Microsoft Visual C/C++
10133 (or some other Windows compiler)
10134 use the python.org or ActiveState version of Python
10136 .SS WIN32: scons.bat file
10138 SCons is executed via a wrapper
10141 This has (at least) two ramifications:
10143 First, Windows command-line users
10144 that want to use variable assignment
10145 on the command line
10146 may have to put double quotes
10147 around the assignments:
10150 scons "FOO=BAR" "BAZ=BLEH"
10153 Second, the Cygwin shell does not
10154 recognize this file as being the same
10157 command issued at the command-line prompt.
10158 You can work around this either by
10161 from the Cygwin command line,
10162 or by creating a wrapper shell
10168 The MinGW bin directory must be in your PATH environment variable or the
10169 PATH variable under the ENV construction variable for SCons
10170 to detect and use the MinGW tools. When running under the native Windows
10171 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
10172 tools, if they are both installed, regardless of the order of the bin
10173 directories in the PATH variable. If you have both MSVC and MinGW
10174 installed and you want to use MinGW instead of MSVC,
10175 then you must explictly tell SCons to use MinGW by passing
10181 to the Environment() function, because SCons will prefer the MSVC tools
10182 over the MinGW tools.
10186 To help you get started using SCons,
10187 this section contains a brief overview of some common tasks.
10189 .SS Basic Compilation From a Single Source File
10192 env = Environment()
10193 env.Program(target = 'foo', source = 'foo.c')
10196 Note: Build the file by specifying
10197 the target as an argument
10198 ("scons foo" or "scons foo.exe").
10199 or by specifying a dot ("scons .").
10201 .SS Basic Compilation From Multiple Source Files
10204 env = Environment()
10205 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
10208 .SS Setting a Compilation Flag
10211 env = Environment(CCFLAGS = '-g')
10212 env.Program(target = 'foo', source = 'foo.c')
10215 .SS Search The Local Directory For .h Files
10219 need to set CCFLAGS to specify -I options by hand.
10220 SCons will construct the right -I options from CPPPATH.
10223 env = Environment(CPPPATH = ['.'])
10224 env.Program(target = 'foo', source = 'foo.c')
10227 .SS Search Multiple Directories For .h Files
10230 env = Environment(CPPPATH = ['include1', 'include2'])
10231 env.Program(target = 'foo', source = 'foo.c')
10234 .SS Building a Static Library
10237 env = Environment()
10238 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
10239 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
10242 .SS Building a Shared Library
10245 env = Environment()
10246 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
10247 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
10250 .SS Linking a Local Library Into a Program
10253 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
10254 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
10255 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
10258 .SS Defining Your Own Builder Object
10260 Notice that when you invoke the Builder,
10261 you can leave off the target file suffix,
10262 and SCons will add it automatically.
10265 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10267 src_suffix = '.tex')
10268 env = Environment(BUILDERS = {'PDFBuilder' : bld})
10269 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10271 # The following creates "bar.pdf" from "bar.tex"
10272 env.PDFBuilder(target = 'bar', source = 'bar')
10275 Note also that the above initialization
10276 overwrites the default Builder objects,
10277 so the Environment created above
10278 can not be used call Builders like env.Program(),
10279 env.Object(), env.StaticLibrary(), etc.
10281 .SS Adding Your Own Builder Object to an Environment
10284 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10286 src_suffix = '.tex')
10287 env = Environment()
10288 env.Append(BUILDERS = {'PDFBuilder' : bld})
10289 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10290 env.Program(target = 'bar', source = 'bar.c')
10293 You also can use other Pythonic techniques to add
10294 to the BUILDERS construction variable, such as:
10297 env = Environment()
10298 env['BUILDERS]['PDFBuilder'] = bld
10301 .SS Defining Your Own Scanner Object
10306 '\" Note: the \\ in the following are for the benefit of nroff/troff,
10307 '\" not inappropriate doubled escape characters within the r'' raw string.
10308 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
10310 def kfile_scan(node, env, path, arg):
10311 contents = node.get_contents()
10312 includes = include_re.findall(contents)
10315 kscan = Scanner(name = 'kfile',
10316 function = kfile_scan,
10319 scanners = Environment().Dictionary('SCANNERS')
10320 env = Environment(SCANNERS = scanners + [kscan])
10322 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
10324 bar_in = File('bar.in')
10325 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
10326 bar_in.target_scanner = kscan
10329 .SS Creating a Hierarchical Build
10331 Notice that the file names specified in a subdirectory's
10333 file are relative to that subdirectory.
10338 env = Environment()
10339 env.Program(target = 'foo', source = 'foo.c')
10341 SConscript('sub/SConscript')
10345 env = Environment()
10346 # Builds sub/foo from sub/foo.c
10347 env.Program(target = 'foo', source = 'foo.c')
10349 SConscript('dir/SConscript')
10351 sub/dir/SConscript:
10353 env = Environment()
10354 # Builds sub/dir/foo from sub/dir/foo.c
10355 env.Program(target = 'foo', source = 'foo.c')
10358 .SS Sharing Variables Between SConscript Files
10360 You must explicitly Export() and Import() variables that
10361 you want to share between SConscript files.
10366 env = Environment()
10367 env.Program(target = 'foo', source = 'foo.c')
10370 SConscript('subdirectory/SConscript')
10372 subdirectory/SConscript:
10375 env.Program(target = 'foo', source = 'foo.c')
10378 .SS Building Multiple Variants From the Same Source
10380 Use the build_dir keyword argument to
10381 the SConscript function to establish
10382 one or more separate build directories for
10383 a given source directory:
10388 cppdefines = ['FOO']
10389 Export("cppdefines")
10390 SConscript('src/SConscript', build_dir='foo')
10392 cppdefines = ['BAR']
10393 Export("cppdefines")
10394 SConscript('src/SConscript', build_dir='bar')
10398 Import("cppdefines")
10399 env = Environment(CPPDEFINES = cppdefines)
10400 env.Program(target = 'src', source = 'src.c')
10403 Note the use of the Export() method
10404 to set the "cppdefines" variable to a different
10405 value each time we call the SConscript function.
10407 .SS Hierarchical Build of Two Libraries Linked With a Program
10412 env = Environment(LIBPATH = ['#libA', '#libB'])
10414 SConscript('libA/SConscript')
10415 SConscript('libB/SConscript')
10416 SConscript('Main/SConscript')
10421 env.Library('a', Split('a1.c a2.c a3.c'))
10426 env.Library('b', Split('b1.c b2.c b3.c'))
10431 e = env.Copy(LIBS = ['a', 'b'])
10432 e.Program('foo', Split('m1.c m2.c m3.c'))
10435 The '#' in the LIBPATH directories specify that they're relative to the
10436 top-level directory, so they don't turn into "Main/libA" when they're
10437 used in Main/SConscript.
10439 Specifying only 'a' and 'b' for the library names
10440 allows SCons to append the appropriate library
10441 prefix and suffix for the current platform
10442 (for example, 'liba.a' on POSIX systems,
10443 'a.lib' on Windows).
10445 .SS Customizing contruction variables from the command line.
10447 The following would allow the C compiler to be specified on the command
10448 line or in the file custom.py.
10451 opts = Options('custom.py')
10452 opts.Add('CC', 'The C compiler.')
10453 env = Environment(options=opts)
10454 Help(opts.GenerateHelpText(env))
10457 The user could specify the C compiler on the command line:
10463 or in the custom.py file:
10469 or get documentation on the options:
10474 CC: The C compiler.
10480 .SS Using Microsoft Visual C++ precompiled headers
10482 Since windows.h includes everything and the kitchen sink, it can take quite
10483 some time to compile it over and over again for a bunch of object files, so
10484 Microsoft provides a mechanism to compile a set of headers once and then
10485 include the previously compiled headers in any object file. This
10486 technology is called precompiled headers. The general recipe is to create a
10487 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
10488 then include every header you want to precompile in "StdAfx.h", and finally
10489 include "StdAfx.h" as the first header in all the source files you are
10490 compiling to object files. For example:
10494 #include <windows.h>
10495 #include <my_big_header.h>
10500 #include <StdAfx.h>
10505 #include <StdAfx.h>
10507 /* do some stuff */
10512 #include <StdAfx.h>
10514 /* do some other stuff */
10520 env['PCHSTOP'] = 'StdAfx.h'
10521 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10522 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10525 For more information see the document for the PCH builder, and the PCH and
10526 PCHSTOP construction variables. To learn about the details of precompiled
10527 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10529 .SS Using Microsoft Visual C++ external debugging information
10531 Since including debugging information in programs and shared libraries can
10532 cause their size to increase significantly, Microsoft provides a mechanism
10533 for including the debugging information in an external file called a PDB
10534 file. SCons supports PDB files through the PDB construction
10540 env['PDB'] = 'MyApp.pdb'
10541 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10544 For more information see the document for the PDB construction variable.
10549 Specifies the directory that contains the SCons Python module directory
10550 (e.g. /home/aroach/scons-src-0.01/src/engine).
10553 A string of options that will be used by scons in addition to those passed
10554 on the command line.
10565 Steven Knight <knight@baldmt.com>
10567 Anthony Roach <aroach@electriceyeball.com>