1 .\" Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 The SCons Foundation
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 .\" doc/man/scons.1 3842 2008/12/20 22:59:52 scons
24 .TH SCONS 1 "December 2008"
25 .\" ES - Example Start - indents and turns off line fill
31 .\" EE - Example End - ends indent and turns line fill back on
38 scons \- a software construction tool
54 utility builds software (or other files) by determining which
55 component pieces must be rebuilt and executing the necessary commands to
60 searches for a file named
65 (in that order) in the current directory and reads its
66 configuration from the first file found.
67 An alternate file name may be
74 file can specify subsidiary
75 configuration files using the
79 these subsidiary files are named
81 although any name may be used.
82 (Because of this naming convention,
83 the term "SConscript files"
84 is sometimes used to refer
88 regardless of actual file name.)
90 The configuration files
91 specify the target files to be built, and
92 (optionally) the rules to build those targets. Reasonable default
93 rules exist for building common software components (executable
94 programs, object files, libraries), so that for most software
95 projects, only the target and input files need be specified.
101 looks for a directory named
103 in the directory containing the
107 is added to sys.path,
109 .IR site_scons/site_init.py ,
110 is evaluated if it exists,
112 .I site_scons/site_tools
113 is added to the default toolpath if it exist.
118 options for more details.
121 reads and executes the SConscript files as Python scripts,
122 so you may use normal Python scripting capabilities
123 (such as flow control, data manipulation, and imported Python libraries)
124 to handle complicated build situations.
126 however, reads and executes all of the SConscript files
128 it begins building any targets.
129 To make this obvious,
131 prints the following messages about what it is doing:
135 scons: Reading SConscript files ...
136 scons: done reading SConscript files.
137 scons: Building targets ...
139 scons: done building targets.
144 (everything except the line that reads "cp foo.in foo.out")
145 may be suppressed using the
150 does not automatically propagate
151 the external environment used to execute
153 to the commands used to build target files.
154 This is so that builds will be guaranteed
155 repeatable regardless of the environment
156 variables set at the time
159 This also means that if the compiler or other commands
160 that you want to use to build your target files
161 are not in standard system locations,
163 will not find them unless
164 you explicitly set the PATH
165 to include those locations.
166 Whenever you create an
168 construction environment,
169 you can propagate the value of PATH
170 from your external environment as follows:
174 env = Environment(ENV = {'PATH' : os.environ['PATH']})
177 Similarly, if the commands use external environment variables
178 like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc.,
179 these variables can also be explicitly propagated:
183 env = Environment(ENV = {'PATH' : os.environ['PATH'],
184 'HOME' : os.environ['HOME']})
187 Or you may explicitly propagate the invoking user's
188 complete external environment:
192 env = Environment(ENV = os.environ)
195 This comes at the expense of making your build
196 dependent on the user's environment being set correctly,
197 but it may be more convenient for many configurations.
200 can scan known input files automatically for dependency
201 information (for example, #include statements
202 in C or C++ files) and will rebuild dependent files appropriately
203 whenever any "included" input file changes.
206 ability to define new scanners for unknown input file types.
209 knows how to fetch files automatically from
210 SCCS or RCS subdirectories
211 using SCCS, RCS or BitKeeper.
214 is normally executed in a top-level directory containing a
216 file, optionally specifying
217 as command-line arguments
218 the target file or files to be built.
220 By default, the command
226 will build all target files in or below the current directory.
227 Explicit default targets
228 (to be built when no targets are specified on the command line)
229 may be defined the SConscript file(s)
232 function, described below.
236 targets are specified in the SConscript file(s),
237 all target files in or below the current directory
238 may be built by explicitly specifying
239 the current directory (.)
240 as a command-line target:
246 Building all target files,
247 including any files outside of the current directory,
248 may be specified by supplying a command-line target
249 of the root directory (on POSIX systems):
255 or the path name(s) of the volume(s) in which all the targets
256 should be built (on Windows systems):
262 To build only specific targets,
263 supply them as command-line arguments:
269 in which case only the specified targets will be built
270 (along with any derived files on which they depend).
272 Specifying "cleanup" targets in SConscript files is not usually necessary.
275 flag removes all files
276 necessary to build the specified target:
282 to remove all target files, or:
285 scons -c build export
288 to remove target files under build and export.
289 Additional files or directories to remove can be specified using the
292 Conversely, targets that would normally be removed by the
295 can be prevented from being removed by using the
299 A subset of a hierarchical tree may be built by
300 remaining at the top-level directory (where the
302 file lives) and specifying the subdirectory as the target to be
309 or by changing directory and invoking scons with the
311 option, which traverses up the directory
312 hierarchy until it finds the
314 file, and then builds
315 targets relatively to the current subdirectory:
323 supports building multiple targets in parallel via a
325 option that takes, as its argument, the number
326 of simultaneous tasks that may be spawned:
332 builds four targets in parallel, for example.
335 can maintain a cache of target (derived) files that can
336 be shared between multiple builds. When caching is enabled in a
337 SConscript file, any target files built by
340 to the cache. If an up-to-date target file is found in the cache, it
341 will be retrieved from the cache instead of being rebuilt locally.
342 Caching behavior may be disabled and controlled in other ways by the
344 .BR --cache-disable ,
347 command-line options. The
349 option is useful to prevent multiple builds
350 from trying to update the cache simultaneously.
352 Values of variables to be passed to the SConscript file(s)
353 may be specified on the command line:
359 These variables are available in SConscript files
360 through the ARGUMENTS dictionary,
361 and can be used in the SConscript file(s) to modify
362 the build in any way:
365 if ARGUMENTS.get('debug', 0):
366 env = Environment(CCFLAGS = '-g')
371 The command-line variable arguments are also available
373 indexed by their order on the command line.
374 This allows you to process them in order rather than by name,
376 ARGLIST[0] returns a tuple
377 containing (argname, argvalue).
378 A Python exception is thrown if you
379 try to access a list member that
383 requires Python version 1.5.2 or later.
384 There should be no other dependencies or requirements to run
387 .\" The following paragraph reflects the default tool search orders
388 .\" currently in SCons/Tool/__init__.py. If any of those search orders
389 .\" change, this documentation should change, too.
392 knows how to search for available programming tools
396 searches in order for the
397 Microsoft Visual C++ tools,
398 the MinGW tool chain,
399 the Intel compiler tools,
400 and the PharLap ETS compiler.
403 searches in order for the
406 and the Microsoft Visual C++ tools,
407 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
409 searches for the native compiler tools
410 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
411 and the GCC tool chain.
412 On all other platforms,
413 including POSIX (Linux and UNIX) platforms,
416 for the GCC tool chain,
417 the Microsoft Visual C++ tools,
418 and the Intel compiler tools.
419 You may, of course, override these default values
420 by appropriate configuration of
421 Environment construction variables.
426 supports the same command-line options as GNU
428 and many of those supported by
433 Ignored for compatibility with non-GNU versions of
437 -c, --clean, --remove
438 Clean up by removing all target files for which a construction
439 command is specified.
440 Also remove any files or directories associated to the construction command
444 Will not remove any targets specified by the
449 .RI --cache-debug= file
450 Print debug information about the
460 the debug information are printed to the standard output.
461 The printed messages describe what signature file names are
462 being looked for in, retrieved from, or written to the
467 --cache-disable, --no-cache
468 Disable the derived-file caching specified by
471 will neither retrieve files from the cache
472 nor copy files to the cache.
475 --cache-force, --cache-populate
478 populate a cache by copying any already-existing, up-to-date
479 derived files to the cache,
480 in addition to files built by this invocation.
481 This is useful to populate a new cache with
482 all the current derived files,
483 or to add to the cache any derived files
484 recently built with caching disabled via the
492 and retrieving a derived file from the cache,
494 that would have been executed to build the file,
495 instead of the usual report,
496 "Retrieved `file' from cache."
497 This will produce consistent output for build logs,
498 regardless of whether a target
499 file was rebuilt or retrieved from the cache.
503 This specifies how the
505 call should use or generate the
506 results of configuration tests.
507 The option should be specified from
508 among the following choices:
512 scons will use its normal dependency mechanisms
513 to decide if a test must be rebuilt or not.
514 This saves time by not running the same configuration tests
515 every time you invoke scons,
516 but will overlook changes in system header files
517 or external commands (such as compilers)
518 if you don't specify those dependecies explicitly.
519 This is the default behavior.
523 If this option is specified,
524 all configuration tests will be re-run
525 regardless of whether the
526 cached results are out of date.
527 This can be used to explicitly
528 force the configuration tests to be updated
529 in response to an otherwise unconfigured change
530 in a system header file or compiler.
534 If this option is specified,
535 no configuration tests will be rerun
536 and all results will be taken from cache.
537 Note that scons will still consider it an error
538 if --config=cache is specified
539 and a necessary test does not
540 yet have any results in the cache.
543 .RI "-C" " directory" ", --directory=" directory
544 Change to the specified
546 before searching for the
551 file, or doing anything
554 options are interpreted
555 relative to the previous one, and the right-most
557 option wins. (This option is nearly
559 .BR "-f directory/SConstruct" ,
560 except that it will search for
565 in the specified directory.)
569 .\" Display dependencies while building target files. Useful for
570 .\" figuring out why a specific file is being rebuilt, as well as
571 .\" general debugging of the build process.
575 Works exactly the same way as the
577 option except for the way default targets are handled.
578 When this option is used and no targets are specified on the command line,
579 all default targets are built, whether or not they are below the current
584 Debug the build process.
586 specifies what type of debugging:
590 Print how many objects are created
591 of the various classes used internally by SCons
592 before and after reading the SConscript files
593 and before and after building targets.
594 This is not supported when run under Python versions earlier than 2.1,
595 when SCons is executed with the Python
598 or when the SCons modules
599 have been compiled with optimization
600 (that is, when executing from
606 A synonym for the newer
609 This will be deprecated in some future release
610 and ultimately removed.
614 Print an explanation of precisely why
616 is deciding to (re-)build any targets.
617 (Note: this does not print anything
624 Instruct the scanner that searches for libraries
625 to print a message about each potential library
626 name it is searching for,
627 and about the actual libraries it finds.
631 Print the include tree after each top-level target is built.
632 This is generally used to find out what files are included by the sources
633 of a given derived file:
636 $ scons --debug=includes foo.o
641 Prints a summary of hits and misses using the Memoizer,
642 an internal subsystem that counts
643 how often SCons uses cached values in memory
644 instead of recomputing them each time they're needed.
645 Only available when using Python 2.2 or later.
649 Prints how much memory SCons uses
650 before and after reading the SConscript files
651 and before and after building targets.
655 A deprecated option preserved for backwards compatibility.
659 Prints a list of the various objects
660 of the various classes used internally by SCons.
661 This only works when run under Python 2.1 or later.
665 Re-run SCons under the control of the
671 Print the raw command line used to build each target
672 before the construction environment variables are substituted.
673 Also shows which targets are being built by this command.
674 Output looks something like this:
676 $ scons --debug=presub
677 Building myprog.o with action(s):
678 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
684 Prints an internal Python stack trace
685 when encountering an otherwise unexplained error.
689 A synonym for the newer
692 This will be deprecated in some future release
693 and ultimately removed.
697 Prints various time profiling information:
698 the time spent executing each individual build command;
699 the total build time (time SCons ran from beginning to end);
700 the total time spent reading and executing SConscript files;
701 the total time spent SCons itself spend running
702 (that is, not counting reading and executing SConscript files);
703 and both the total time spent executing all build commands
704 and the elapsed wall-clock time spent executing those build commands.
707 is executed without the
710 the elapsed wall-clock time will typically
711 be slightly longer than the total time spent
712 executing all the build commands,
713 due to the SCons processing that takes place
714 in between executing each command.
722 and your build configuration allows good parallelization,
723 the elapsed wall-clock time should
724 be significantly smaller than the
725 total time spent executing all the build commands,
726 since multiple build commands and
727 intervening SCons processing
728 should take place in parallel.)
732 A synonym for the newer
735 This will be deprecated in some future release
736 and ultimately removed.
739 .RI --diskcheck= types
740 Enable specific checks for
741 whether or not there is a file on disk
742 where the SCons configuration expects a directory
744 and whether or not RCS or SCCS sources exist
745 when searching for source and include files.
748 argument can be set to:
750 to enable all checks explicitly
751 (the default behavior);
753 to disable all such checks;
755 to check that files and directories on disk
756 match SCons' expected configuration;
758 to check for the existence of an RCS source
759 for any missing source or include files;
761 to check for the existence of an SCCS source
762 for any missing source or include files.
763 Multiple checks can be specified separated by commas;
765 .B --diskcheck=sccs,rcs
766 would still check for SCCS and RCS sources,
767 but disable the check for on-disk matches of files and directories.
768 Disabling some or all of these checks
769 can provide a performance boost for large configurations,
770 or when the configuration will check for files and/or directories
771 across networked or shared file systems,
772 at the slight increased risk of an incorrect build
773 or of not handling errors gracefully
774 (if include files really should be
775 found in SCCS or RCS, for example,
776 or if a file really does exist
777 where the SCons configuration expects a directory).
780 .RI --duplicate= ORDER
781 There are three ways to duplicate files in a build tree: hard links,
782 soft (symbolic) links and copies. The default behaviour of SCons is to
783 prefer hard links to soft links to copies. You can specify different
784 behaviours with this option.
794 SCons will attempt to duplicate files using
795 the mechanisms in the specified order.
798 .\" -e, --environment-overrides
799 .\" Variables from the execution environment override construction
800 .\" variables from the SConscript files.
803 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
806 as the initial SConscript file.
809 options may be specified,
812 will read all of the specified files.
816 Print a local help message for this build, if one is defined in
817 the SConscript file(s), plus a line that describes the
819 option for command-line option help. If no local help message
820 is defined, prints the standard help message about command-line
821 options. Exits after displaying the appropriate message.
825 Print the standard help message about command-line options and
830 Ignore all errors from commands executed to rebuild files.
833 .RI -I " directory" ", --include-dir=" directory
837 imported Python modules. If several
840 are used, the directories are searched in the order specified.
844 Cache implicit dependencies.
847 to use the implicit (scanned) dependencies
848 from the last time it was run
849 instead of scanning the files for implicit dependencies.
850 This can significantly speed up SCons,
851 but with the following limitations:
854 will not detect changes to implicit dependency search paths
856 .BR CPPPATH ", " LIBPATH )
857 that would ordinarily
858 cause different versions of same-named files to be used.
861 will miss changes in the implicit dependencies
862 in cases where a new implicit
863 dependency is added earlier in the implicit dependency search path
865 .BR CPPPATH ", " LIBPATH )
866 than a current implicit dependency with the same name.
869 --implicit-deps-changed
870 Forces SCons to ignore the cached implicit dependencies. This causes the
871 implicit dependencies to be rescanned and recached. This implies
872 .BR --implicit-cache .
875 --implicit-deps-unchanged
876 Force SCons to ignore changes in the implicit dependencies.
877 This causes cached implicit dependencies to always be used.
879 .BR --implicit-cache .
883 Starts SCons in interactive mode.
884 The SConscript files are read once and a
887 Targets may now be rebuilt by typing commands at interactive prompt
888 without having to re-read the SConscript files
889 and re-initialize the dependency graph from scratch.
891 SCons interactive mode supports the following commands:
895 .BI build "[OPTIONS] [TARGETS] ..."
898 (and their dependencies)
907 The following SCons command-line options affect the
913 --cache-disable, --no-cache
914 --cache-force, --cache-populate
920 -n, --no-exec, --just-print, --dry-run, --recon
922 -s, --silent, --quiet
923 --taskmastertrace=FILE
928 Any other SCons command-line options that are specified
930 but have no effect on the
933 (mainly because they affect how the SConscript files are read,
934 which only happens once at the beginning of interactive mode).
937 .BI clean "[OPTIONS] [TARGETS] ..."
940 (and their dependencies)
941 with the specified options.
944 This command is itself a synonym for
949 Exits SCons interactive mode.
950 You can also exit by terminating input
951 (CTRL+D on UNIX or Linux systems,
952 CTRL+Z on Windows systems).
956 Provides a help message about
957 the commands available in SCons interactive mode.
967 .BI shell "[COMMANDLINE]"
968 Executes the specified
974 executes the interactive command interpreter
978 (on UNIX and Linux systems)
982 (on Windows systems).
990 Prints SCons version information.
994 An empty line repeats the last typed command.
995 Command-line editing can be used if the
1000 $ scons --interactive
1001 scons: Reading SConscript files ...
1002 scons: done reading SConscript files.
1003 scons>>> build -n prog
1008 .RI -j " N" ", --jobs=" N
1009 Specifies the number of jobs (commands) to run simultaneously.
1010 If there is more than one
1012 option, the last one is effective.
1016 .\" is specified without an argument,
1018 .\" will not limit the number of
1019 .\" simultaneous jobs.
1023 Continue as much as possible after an error. The target that
1024 failed and those that depend on it will not be remade, but other
1025 targets specified on the command line will still be processed.
1028 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
1029 .\" No new jobs (commands) will be started if
1030 .\" there are other jobs running and the system load
1031 .\" average is at least
1033 .\" (a floating-point number).
1038 .\" List derived files (targets, dependencies) that would be built,
1039 .\" but do not build them.
1040 .\" [XXX This can probably go away with the right
1041 .\" combination of other options. Revisit this issue.]
1045 .\" List derived files that would be built, with the actions
1046 .\" (commands) that build them. Does not build the files.
1047 .\" [XXX This can probably go away with the right
1048 .\" combination of other options. Revisit this issue.]
1052 .\" List derived files that would be built, plus where the file is
1053 .\" defined (file name and line number). Does not build the files.
1054 .\" [XXX This can probably go away with the right
1055 .\" combination of other options. Revisit this issue.]
1059 Ignored for compatibility with non-GNU versions of
1063 .RI --max-drift= SECONDS
1064 Set the maximum expected drift in the modification time of files to
1066 This value determines how long a file must be unmodified
1067 before its cached content signature
1068 will be used instead of
1069 calculating a new content signature (MD5 checksum)
1070 of the file's contents.
1071 The default value is 2 days, which means a file must have a
1072 modification time of at least two days ago in order to have its
1073 cached content signature used.
1074 A negative value means to never cache the content
1075 signature and to ignore the cached value if there already is one. A value
1076 of 0 means to always use the cached signature,
1077 no matter how old the file is.
1080 .RI --md5-chunksize= KILOBYTES
1081 Set the block size used to compute MD5 signatures to
1083 This value determines the size of the chunks which are read in at once when
1084 computing MD5 signatures. Files below that size are fully stored in memory
1085 before performing the signature computation while bigger files are read in
1086 block-by-block. A huge block-size leads to high memory consumption while a very
1087 small block-size slows down the build considerably.
1089 The default value is to use a chunk size of 64 kilobytes, which should
1090 be appropriate for most uses.
1093 -n, --just-print, --dry-run, --recon
1094 No execute. Print the commands that would be executed to build
1095 any out-of-date target files, but do not execute the commands.
1099 Prevents the automatic addition of the standard
1103 Also prevents loading the
1104 .I site_scons/site_init.py
1105 module if it exists, and prevents adding
1106 .I site_scons/site_tools
1110 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
1114 .\" not rebuild anything due to changes in the contents of
1117 .\" .RI --override " file"
1118 .\" Read values to override specific build environment variables
1119 .\" from the specified
1123 .\" Print the data base (construction environments,
1124 .\" Builder and Scanner objects) that are defined
1125 .\" after reading the SConscript files.
1126 .\" After printing, a normal build is performed
1127 .\" as usual, as specified by other command-line options.
1128 .\" This also prints version information
1133 .\" To print the database without performing a build do:
1141 Run SCons under the Python profiler
1142 and save the results in the specified
1144 The results may be analyzed using the Python
1149 Do not run any commands, or print anything. Just return an exit
1150 status that is zero if the specified targets are already up to
1151 date, non-zero otherwise.
1154 Quiets SCons status messages about
1155 reading SConscript files,
1157 and entering directories.
1158 Commands that are executed
1159 to rebuild target files are still printed.
1162 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
1163 .\" Clear the default construction variables. Construction
1164 .\" environments that are created will be completely empty.
1168 Build dependencies in a random order. This is useful when
1169 building multiple trees simultaneously with caching enabled,
1170 to prevent multiple builds from simultaneously trying to build
1171 or retrieve the same target files.
1174 -s, --silent, --quiet
1175 Silent. Do not print commands that are executed to rebuild
1177 Also suppresses SCons status messages.
1180 -S, --no-keep-going, --stop
1181 Ignored for compatibility with GNU
1186 Uses the named dir as the site dir rather than the default
1188 dir. This dir will get prepended to
1191 .IR dir /site_init.py
1192 will get loaded if it exists, and
1194 will get added to the default toolpath.
1197 .RI --stack-size= KILOBYTES
1198 Set the size stack used to run threads to
1200 This value determines the stack size of the threads used to run jobs.
1201 These are the threads that execute the actions of the builders for the
1202 nodes that are out-of-date.
1203 Note that this option has no effect unless the
1205 option, which corresponds to -j and --jobs, is larger than one. Using
1206 a stack size that is too small may cause stack overflow errors. This
1207 usually shows up as segmentation faults that cause scons to abort
1208 before building anything. Using a stack size that is too large will
1209 cause scons to use more memory than required and may slow down the entire
1212 The default value is to use a stack size of 256 kilobytes, which should
1213 be appropriate for most uses. You should not need to increase this value
1214 unless you encounter stack overflow errors.
1218 Ignored for compatibility with GNU
1220 (Touching a file to make it
1221 appear up-to-date is unnecessary when using
1225 .RI --taskmastertrace= file
1226 Prints trace information to the specified
1228 about how the internal Taskmaster object
1229 evaluates and controls the order in which Nodes are built.
1232 may be used to specify the standard output.
1236 Prints a tree of the dependencies
1237 after each top-level target is built.
1238 This prints out some or all of the tree,
1246 Print the entire dependency tree
1247 after each top-level target is built.
1248 This prints out the complete dependency tree,
1249 including implicit dependencies and ignored dependencies.
1253 Restricts the tree output to only derived (target) files,
1258 Prints status information for each displayed node.
1262 Prunes the tree to avoid repeating dependency information
1263 for nodes that have already been displayed.
1264 Any node that has already been displayed
1265 will have its name printed in
1266 .BR "[square brackets]" ,
1267 as an indication that the dependencies
1268 for that node can be found by searching
1269 for the relevant output higher up in the tree.
1272 Multiple options may be specified,
1273 separated by commas:
1276 # Prints only derived files, with status information:
1277 scons --tree=derived,status
1279 # Prints all dependencies of target, with status information
1280 # and pruning dependencies of already-visited Nodes:
1281 scons --tree=all,prune,status target
1285 -u, --up, --search-up
1286 Walks up the directory structure until an
1291 file is found, and uses that
1292 as the top of the directory tree.
1293 If no targets are specified on the command line,
1294 only targets at or below the
1295 current directory will be built.
1299 Works exactly the same way as the
1301 option except for the way default targets are handled.
1302 When this option is used and no targets are specified on the command line,
1303 all default targets that are defined in the SConscript(s) in the current
1304 directory are built, regardless of what directory the resultant targets end
1311 version, copyright information,
1312 list of authors, and any other relevant information.
1316 -w, --print-directory
1317 Print a message containing the working directory before and
1318 after other processing.
1321 --no-print-directory
1322 Turn off -w, even if it was turned on implicitly.
1325 .RI --warn= type ", --warn=no-" type
1326 Enable or disable warnings.
1328 specifies the type of warnings to be enabled or disabled:
1331 --warn=all, --warn=no-all
1332 Enables or disables all warnings.
1335 --warn=cache-write-error, --warn=no-cache-write-error
1336 Enables or disables warnings about errors trying to
1337 write a copy of a built file to a specified
1339 These warnings are disabled by default.
1342 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
1343 Enables or disables warnings about unfamiliar signature data in
1346 These warnings are enabled by default.
1349 --warn=dependency, --warn=no-dependency
1350 Enables or disables warnings about dependencies.
1351 These warnings are disabled by default.
1354 --warn=deprecated, --warn=no-deprecated
1355 Enables or disables all warnings about use of deprecated features.
1356 These warnings are enabled by default.
1357 Warnings for some specific deprecated features
1358 may be enabled or disabled individually;
1363 --warn=deprecated-copy, --warn=no-deprecated-copy
1364 Enables or disables warnings about use of the deprecated
1369 --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures
1370 Enables or disables warnings about use of the deprecated
1371 .B SourceSignatures()
1373 .B env.SourceSignatures()
1377 --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures
1378 Enables or disables warnings about use of the deprecated
1379 .B TargetSignatures()
1381 .B env.TargetSignatures()
1386 --warn=duplicate-environment, --warn=no-duplicate-environment
1387 Enables or disables warnings about attempts to specify a build
1388 of a target with two different construction environments
1389 that use the same action.
1390 These warnings are enabled by default.
1393 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
1394 Enables or disables the specific warning about linking
1395 Fortran and C++ object files in a single executable,
1396 which can yield unpredictable behavior with some compilers.
1399 --warn=link, --warn=no-link
1400 Enables or disables warnings about link steps.
1403 --warn=misleading-keywords, --warn=no-misleading-keywords
1404 Enables or disables warnings about use of the misspelled keywords
1408 when calling Builders.
1411 characters, the correct spellings are
1415 These warnings are enabled by default.
1418 --warn=missing-sconscript, --warn=no-missing-sconscript
1419 Enables or disables warnings about missing SConscript files.
1420 These warnings are enabled by default.
1423 --warn=no-md5-module, --warn=no-no-md5-module
1424 Enables or disables warnings about the version of Python
1425 not having an MD5 checksum module available.
1426 These warnings are enabled by default.
1429 --warn=no-metaclass-support, --warn=no-no-metaclass-support
1430 Enables or disables warnings about the version of Python
1431 not supporting metaclasses when the
1434 These warnings are enabled by default.
1437 --warn=no-object-count, --warn=no-no-object-count
1438 Enables or disables warnings about the
1440 feature not working when
1442 is run with the python
1444 option or from optimized Python (.pyo) modules.
1447 --warn=no-parallel-support, --warn=no-no-parallel-support
1448 Enables or disables warnings about the version of Python
1449 not being able to support parallel builds when the
1452 These warnings are enabled by default.
1455 --warn=python-version, --warn=no-python-version
1456 Enables or disables the warning about running
1457 SCons with a deprecated version of Python.
1458 These warnings are enabled by default.
1461 --warn=reserved-variable, --warn=no-reserved-variable
1462 Enables or disables warnings about attempts to set the
1463 reserved construction variable names
1469 These warnings are disabled by default.
1472 --warn=stack-size, --warn=no-stack-size
1473 Enables or disables warnings about requests to set the stack size
1474 that could not be honored.
1475 These warnings are enabled by default.
1478 .\" .RI --write-filenames= file
1479 .\" Write all filenames considered into
1483 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
1484 .\" Pretend that the target
1487 .\" modified. When used with the
1490 .\" show you what would be rebuilt if you were to modify that file.
1496 .\" --warn-undefined-variables
1497 .\" Warn when an undefined variable is referenced.
1500 .RI -Y " repository" ", --repository=" repository ", --srcdir=" repository
1501 Search the specified repository for any input and target
1502 files not found in the local directory hierarchy. Multiple
1504 options may be specified, in which case the
1505 repositories are searched in the order specified.
1507 .SH CONFIGURATION FILE REFERENCE
1508 .\" .SS Python Basics
1509 .\" XXX Adding this in the future would be a help.
1510 .SS Construction Environments
1511 A construction environment is the basic means by which the SConscript
1512 files communicate build information to
1514 A new construction environment is created using the
1525 may be set in a construction environment
1526 either by specifying them as keywords when the object is created
1527 or by assigning them a value after the object is created:
1530 env = Environment(FOO = 'foo')
1535 construction variables may also be set or modified by the
1537 keyword argument, which applies the
1539 method (described below) to the argument value
1540 after all other processing is completed.
1541 This is useful either if the exact content of the flags is unknown
1542 (for example, read from a control file)
1543 or if the flags are distributed to a number of construction variables.
1546 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1549 This example adds 'include' to
1556 By default, a new construction environment is
1557 initialized with a set of builder methods
1558 and construction variables that are appropriate
1559 for the current platform.
1560 An optional platform keyword argument may be
1561 used to specify that an environment should
1562 be initialized for a different platform:
1565 env = Environment(platform = 'cygwin')
1566 env = Environment(platform = 'os2')
1567 env = Environment(platform = 'posix')
1568 env = Environment(platform = 'win32')
1571 Specifying a platform initializes the appropriate
1572 construction variables in the environment
1573 to use and generate file names with prefixes
1574 and suffixes appropriate for the platform.
1582 variables from the user's external environment
1583 to the construction environment's
1586 This is so that any executed commands
1587 that use sockets to connect with other systems
1588 (such as fetching source files from
1589 external CVS repository specifications like
1590 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
1591 will work on Windows systems.
1593 The platform argument may be function or callable object,
1594 in which case the Environment() method
1595 will call the specified argument to update
1596 the new construction environment:
1599 def my_platform(env):
1600 env['VAR'] = 'xyzzy'
1602 env = Environment(platform = my_platform)
1605 Additionally, a specific set of tools
1606 with which to initialize the environment
1607 may be specified as an optional keyword argument:
1610 env = Environment(tools = ['msvc', 'lex'])
1613 Non-built-in tools may be specified using the toolpath argument:
1616 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1619 This looks for a tool specification in tools/foo.py (as well as
1620 using the ordinary default tools for the platform). foo.py should
1621 have two functions: generate(env, **kw) and exists(env).
1625 modifies the passed-in environment
1626 to set up variables so that the tool
1628 it may use any keyword arguments
1629 that the user supplies (see below)
1630 to vary its initialization.
1633 function should return a true
1634 value if the tool is available.
1635 Tools in the toolpath are used before
1636 any of the built-in ones. For example, adding gcc.py to the toolpath
1637 would override the built-in gcc tool.
1638 Also note that the toolpath is
1639 stored in the environment for use
1647 base = Environment(toolpath=['custom_path'])
1648 derived = base.Clone(tools=['custom_tool'])
1649 derived.CustomBuilder()
1652 The elements of the tools list may also
1653 be functions or callable objects,
1654 in which case the Environment() method
1655 will call the specified elements
1656 to update the new construction environment:
1660 env['XYZZY'] = 'xyzzy'
1662 env = Environment(tools = [my_tool])
1665 The individual elements of the tools list
1666 may also themselves be two-element lists of the form
1667 .RI ( toolname ", " kw_dict ).
1668 SCons searches for the
1670 specification file as described above, and
1673 which must be a dictionary, as keyword arguments to the tool's
1678 function can use the arguments to modify the tool's behavior
1679 by setting up the environment in different ways
1680 or otherwise changing its initialization.
1683 # in tools/my_tool.py:
1684 def generate(env, **kw):
1685 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1686 env['MY_TOOL'] = kw.get('arg1', '1')
1691 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1695 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1696 the environment it receives to customize the tool for different platforms.
1698 If no tool list is specified, then SCons will auto-detect the installed
1699 tools using the PATH variable in the ENV construction variable and the
1700 platform name when the Environment is constructed. Changing the PATH
1701 variable after the Environment is constructed will not cause the tools to
1704 SCons supports the following tool specifications out of the box:
1784 Additionally, there is a "tool" named
1786 which configures the
1787 environment with a default set of tools for the current platform.
1789 On posix and cygwin platforms
1790 the GNU tools (e.g. gcc) are preferred by SCons,
1791 on Windows the Microsoft tools (e.g. msvc)
1792 followed by MinGW are preferred by SCons,
1793 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
1797 Build rules are specified by calling a construction
1798 environment's builder methods.
1799 The arguments to the builder methods are
1801 (a list of targets to be built,
1805 (a list of sources to be built,
1806 usually file names).
1808 Because long lists of file names
1809 can lead to a lot of quoting,
1814 and a same-named environment method
1815 that split a single string
1816 into a list, separated on
1817 strings of white-space characters.
1818 (These are similar to the
1819 string.split() method
1820 from the standard Python library,
1821 but work even if the input isn't a string.)
1823 Like all Python arguments,
1824 the target and source arguments to a builder method
1825 can be specified either with or without
1826 the "target" and "source" keywords.
1827 When the keywords are omitted,
1828 the target is first,
1829 followed by the source.
1830 The following are equivalent examples of calling the Program builder method:
1833 env.Program('bar', ['bar.c', 'foo.c'])
1834 env.Program('bar', Split('bar.c foo.c'))
1835 env.Program('bar', env.Split('bar.c foo.c'))
1836 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1837 env.Program(target = 'bar', Split('bar.c foo.c'))
1838 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1839 env.Program('bar', source = string.split('bar.c foo.c'))
1842 Target and source file names
1843 that are not absolute path names
1844 (that is, do not begin with
1851 an optional drive letter)
1852 are interpreted relative to the directory containing the
1858 on a path name means that the rest of the file name
1859 is interpreted relative to
1860 the directory containing
1866 is followed by a directory separator character
1867 (slash or backslash).
1872 # The comments describing the targets that will be built
1873 # assume these calls are in a SConscript file in the
1874 # a subdirectory named "subdir".
1876 # Builds the program "subdir/foo" from "subdir/foo.c":
1877 env.Program('foo', 'foo.c')
1879 # Builds the program "/tmp/bar" from "subdir/bar.c":
1880 env.Program('/tmp/bar', 'bar.c')
1882 # An initial '#' or '#/' are equivalent; the following
1883 # calls build the programs "foo" and "bar" (in the
1884 # top-level SConstruct directory) from "subdir/foo.c" and
1885 # "subdir/bar.c", respectively:
1886 env.Program('#foo', 'foo.c')
1887 env.Program('#/bar', 'bar.c')
1889 # Builds the program "other/foo" (relative to the top-level
1890 # SConstruct directory) from "subdir/foo.c":
1891 env.Program('#other/foo', 'foo.c')
1894 When the target shares the same base name
1895 as the source and only the suffix varies,
1896 and if the builder method has a suffix defined for the target file type,
1897 then the target argument may be omitted completely,
1900 will deduce the target file name from
1901 the source file name.
1902 The following examples all build the
1908 (on Windows systems)
1909 from the bar.c source file:
1912 env.Program(target = 'bar', source = 'bar.c')
1913 env.Program('bar', source = 'bar.c')
1914 env.Program(source = 'bar.c')
1915 env.Program('bar.c')
1920 keyword argument may be specified
1921 when calling a Builder.
1923 all source file strings that are not absolute paths
1924 will be interpreted relative to the specified
1926 The following example will build the
1931 program from the files
1937 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1940 It is possible to override or add construction variables when calling a
1941 builder method by passing additional keyword arguments.
1942 These overridden or added
1943 variables will only be in effect when building the target, so they will not
1944 affect other parts of the build. For example, if you want to add additional
1945 libraries for just one program:
1948 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1951 or generate a shared library with a non-standard suffix:
1954 env.SharedLibrary('word', 'word.cpp',
1956 LIBSUFFIXES=['.ocx'])
1959 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1960 if you want SCons to search automatically
1961 for dependencies on the non-standard library names;
1962 see the descriptions of these variables, below, for more information.)
1964 It is also possible to use the
1966 keyword argument in an override:
1969 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1972 This example adds 'include' to
1979 Although the builder methods defined by
1982 methods of a construction environment object,
1983 they may also be called without an explicit environment:
1986 Program('hello', 'hello.c')
1987 SharedLibrary('word', 'word.cpp')
1991 the methods are called internally using a default construction
1992 environment that consists of the tools and values that
1994 has determined are appropriate for the local system.
1996 Builder methods that can be called without an explicit
1997 environment may be called from custom Python modules that you
1998 import into an SConscript file by adding the following
1999 to the Python module:
2002 from SCons.Script import *
2005 All builder methods return a list-like object
2006 containing Nodes that
2007 represent the target or targets that will be built.
2010 is an internal SCons object
2012 build targets or sources.
2014 The returned Node-list object
2015 can be passed to other builder methods as source(s)
2016 or passed to any SCons function or method
2017 where a filename would normally be accepted.
2018 For example, if it were necessary
2021 flag when compiling one specific object file:
2024 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2025 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2028 Using a Node in this way
2029 makes for a more portable build
2030 by avoiding having to specify
2031 a platform-specific object suffix
2032 when calling the Program() builder method.
2034 Note that Builder calls will automatically "flatten"
2035 the source and target file lists,
2036 so it's all right to have the bar_obj list
2037 return by the StaticObject() call
2038 in the middle of the source file list.
2039 If you need to manipulate a list of lists returned by Builders
2040 directly using Python,
2041 you can either build the list by hand:
2044 foo = Object('foo.c')
2045 bar = Object('bar.c')
2046 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2047 for object in objects:
2053 function supplied by scons
2054 to create a list containing just the Nodes,
2055 which may be more convenient:
2058 foo = Object('foo.c')
2059 bar = Object('bar.c')
2060 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2061 for object in objects:
2065 Note also that because Builder calls return
2066 a list-like object, not an actual Python list,
2071 operator to append Builder results to a Python list.
2072 Because the list and the object are different types,
2073 Python will not update the original list in place,
2074 but will instead create a new Node-list object
2075 containing the concatenation of the list
2076 elements and the Builder results.
2077 This will cause problems for any other Python variables
2078 in your SCons configuration
2079 that still hold on to a reference to the original list.
2080 Instead, use the Python
2082 method to make sure the list is updated in-place.
2088 # Do NOT use += as follows:
2090 # object_files += Object('bar.c')
2092 # It will not update the object_files list in place.
2094 # Instead, use the .extend() method:
2095 object_files.extend(Object('bar.c'))
2099 The path name for a Node's file may be used
2100 by passing the Node to the Python-builtin
2105 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2106 print "The path to bar_obj is:", str(bar_obj_list[0])
2109 Note again that because the Builder call returns a list,
2110 we have to access the first element in the list
2111 .B (bar_obj_list[0])
2112 to get at the Node that actually represents
2115 Builder calls support a
2117 keyword argument that
2118 specifies that the Builder's action(s)
2120 after changing directory.
2124 a string or a directory Node,
2125 scons will change to the specified directory.
2128 is not a string or Node
2130 then scons will change to the
2131 target file's directory.
2134 # scons will change to the "sub" subdirectory
2135 # before executing the "cp" command.
2136 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2137 "cp dir/foo.in dir/foo.out",
2140 # Because chdir is not a string, scons will change to the
2141 # target's directory ("sub/dir") before executing the
2143 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2144 "cp foo.in foo.out",
2148 Note that scons will
2150 automatically modify
2152 construction variables like
2156 when using the chdir
2157 keyword argument--that is,
2158 the expanded file names
2159 will still be relative to
2160 the top-level SConstruct directory,
2161 and consequently incorrect
2162 relative to the chdir directory.
2163 If you use the chdir keyword argument,
2164 you will typically need to supply a different
2170 to use just the filename portion of the
2174 provides the following builder methods:
2176 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2177 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2179 '\" The descriptions below of the various SCons Builders are generated
2180 '\" from the .xml files that live next to the various Python modules in
2181 '\" the build enginer library. If you're reading this [gnt]roff file
2182 '\" with an eye towards patching this man page, you can still submit
2183 '\" a diff against this text, but it will have to be translated to a
2184 '\" diff against the underlying .xml file before the patch is actually
2185 '\" accepted. If you do that yourself, it will make it easier to
2186 '\" integrate the patch.
2188 '\" BEGIN GENERATED BUILDER DESCRIPTIONS
2189 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2191 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2194 Builds a C source file given a lex (\fB.l\fP)
2195 or yacc (\fB.y\fP) input file.
2196 The suffix specified by the $CFILESUFFIX construction variable
2197 (\fB.c\fP by default)
2198 is automatically added to the target
2199 if it is not already present.
2204 env.CFile(target = 'foo.c', source = 'foo.l')
2206 env.CFile(target = 'bar', source = 'bar.y')
2209 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2212 Builds a C++ source file given a lex (\fB.ll\fP)
2215 The suffix specified by the $CXXFILESUFFIX construction variable
2216 (\fB.cc\fP by default)
2217 is automatically added to the target
2218 if it is not already present.
2223 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
2225 env.CXXFile(target = 'bar', source = 'bar.yy')
2228 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2231 Builds a \fB.dvi\fP file
2233 \fB.ltx\fP or \fB.latex\fP input file.
2234 If the source file suffix is \fB.tex\fP,
2236 will examine the contents of the file;
2241 is found, the file is assumed to be a LaTeX file and
2242 the target is built by invoking the $LATEXCOM command line;
2243 otherwise, the $TEXCOM command line is used.
2244 If the file is a LaTeX file,
2247 builder method will also examine the contents
2250 file and invoke the $BIBTEX command line
2254 start $MAKEINDEX to generate an index if a
2257 and will examine the contents
2259 file and re-run the $LATEXCOM command
2260 if the log file says it is necessary.
2262 The suffix \fB.dvi\fP
2263 (hard-coded within TeX itself)
2264 is automatically added to the target
2265 if it is not already present.
2269 # builds from aaa.tex
2270 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
2272 env.DVI(target = 'bbb', source = 'bbb.ltx')
2273 # builds from ccc.latex
2274 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
2277 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2280 Installs one or more source files or directories
2281 in the specified target,
2282 which must be a directory.
2283 The names of the specified source files or directories
2284 remain the same within the destination directory.
2287 env.Install('/usr/local/bin', source = ['foo', 'bar'])
2290 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2293 Installs one or more source files or directories
2295 allowing changing a file or directory name
2296 as part of the installation.
2297 It is an error if the
2301 arguments list different numbers of files or directories.
2304 env.InstallAs(target = '/usr/local/bin/foo',
2305 source = 'foo_debug')
2306 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2307 source = ['libFOO.a', 'libBAR.a'])
2310 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2313 Builds a Java archive (\fB.jar\fP) file
2314 from the specified list of sources.
2315 Any directories in the source list
2316 will be searched for \fB.class\fP files).
2317 Any \fB.java\fP files in the source list
2318 will be compiled to \fB.class\fP files
2319 by calling the \fBJava\fP() Builder.
2321 If the $JARCHDIR value is set, the
2323 command will change to the specified directory using the
2326 If $JARCHDIR is not set explicitly,
2327 &SCons; will use the top of any subdirectory tree
2328 in which Java \fB.class\fP
2329 were built by the \fBJava\fP() Builder.
2331 If the contents any of the source files begin with the string
2332 .BR Manifest-Version ,
2333 the file is assumed to be a manifest
2334 and is passed to the
2341 env.Jar(target = 'foo.jar', source = 'classes')
2343 env.Jar(target = 'bar.jar',
2344 source = ['bar1.java', 'bar2.java'])
2347 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2350 Builds one or more Java class files.
2351 The sources may be any combination of explicit
2353 or directory trees which will be scanned
2354 for \fB.java\fP files.
2356 SCons will parse each source \fB.java\fP file
2358 (including inner classes)
2359 defined within that file,
2360 and from that figure out the
2361 target \fB.class\fP files that will be created.
2362 The class files will be placed underneath
2363 the specified target directory.
2365 SCons will also search each Java file
2366 for the Java package name,
2367 which it assumes can be found on a line
2368 beginning with the string
2370 in the first column;
2371 the resulting \fB.class\fP files
2372 will be placed in a directory reflecting
2373 the specified package name.
2377 defining a single public
2380 containing a package name of
2382 will generate a corresponding
2383 .B sub/dir/Foo.class
2389 env.Java(target = 'classes', source = 'src')
2390 env.Java(target = 'classes', source = ['src1', 'src2'])
2391 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
2394 Java source files can use the native encoding for the underlying OS.
2395 Since SCons compiles in simple ASCII mode by default,
2396 the compiler will generate warnings about unmappable characters,
2397 which may lead to errors as the file is processed further.
2398 In this case, the user must specify the \fBLANG\fP
2399 environment variable to tell the compiler what encoding is uesd.
2400 For portibility, it's best if the encoding is hard-coded
2401 so that the compile will work if it is done on a system
2402 with a different encoding.
2406 env['ENV']['LANG'] = 'en_GB.UTF-8'
2409 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2412 Builds C header and source files for
2413 implementing Java native methods.
2414 The target can be either a directory
2415 in which the header files will be written,
2416 or a header file name which
2417 will contain all of the definitions.
2418 The source can be the names of \fB.class\fP files,
2419 the names of \fB.java\fP files
2420 to be compiled into \fB.class\fP files
2421 by calling the \fBJava\fP() builder method,
2422 or the objects returned from the
2426 If the construction variable
2428 is set, either in the environment
2429 or in the call to the
2431 builder method itself,
2432 then the value of the variable
2433 will be stripped from the
2434 beginning of any \fB.class\fP file names.
2439 # builds java_native.h
2440 classes = env.Java(target = 'classdir', source = 'src')
2441 env.JavaH(target = 'java_native.h', source = classes)
2443 # builds include/package_foo.h and include/package_bar.h
2444 env.JavaH(target = 'include',
2445 source = ['package/foo.class', 'package/bar.class'])
2447 # builds export/foo.h and export/bar.h
2448 env.JavaH(target = 'export',
2449 source = ['classes/foo.class', 'classes/bar.class'],
2450 JAVACLASSDIR = 'classes')
2453 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2457 .BR StaticLibrary ()
2460 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2461 .IP LoadableModule()
2462 .IP env.LoadableModule()
2465 .BR SharedLibrary ().
2466 On Mac OS X (Darwin) platforms,
2467 this creates a loadable module bundle.
2469 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2472 Builds an output file from an M4 input file.
2473 This uses a default $M4FLAGS value of
2475 which considers all warnings to be fatal
2476 and stops on the first warning
2477 when using the GNU version of m4.
2481 env.M4(target = 'foo.c', source = 'foo.c.m4')
2484 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2487 Builds an output file from a moc input file. Moc input files are either
2488 header files or cxx files. This builder is only available after using the
2489 tool 'qt'. See the $QTDIR variable for more information.
2493 env.Moc('foo.h') # generates moc_foo.cc
2494 env.Moc('foo.cpp') # generates foo.moc
2497 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2499 .IP env.MSVSProject()
2500 Builds a Microsoft Visual Studio project file,
2501 and by default builds a solution file as well.
2503 This builds a Visual Studio project file, based on the version of
2504 Visual Studio that is configured (either the latest installed version,
2505 or the version specified by
2507 in the Environment constructor).
2508 For Visual Studio 6, it will generate a
2511 For Visual Studio 7 (.NET) and later versions, it will generate a
2516 this also generates a solution file
2517 for the specified project,
2520 file for Visual Studio 6
2523 file for Visual Studio 7 (.NET).
2524 This behavior may be disabled by specifying
2525 .B auto_build_solution=0
2528 in which case you presumably want to
2529 build the solution file(s)
2532 Builder (see below).
2534 The \fBMSVSProject\fP() builder
2535 takes several lists of filenames
2536 to be placed into the project file.
2537 These are currently limited to
2544 These are pretty self-explanatory, but it should be noted that these
2545 lists are added to the $SOURCES construction variable as strings,
2546 NOT as SCons File Nodes. This is because they represent file
2547 names to be added to the project file, not the source files used to
2548 build the project file.
2550 The above filename lists are all optional,
2551 although at least one must be specified
2552 for the resulting project file to be non-empty.
2554 In addition to the above lists of values,
2555 the following values may be specified:
2558 The name of the target
2564 suffix for the version of Visual Studio must be used,
2567 construction variable
2568 will be defined to the correct value (see example below).
2571 The name of this particular variant.
2572 For Visual Studio 7 projects,
2573 this can also be a list of variant names.
2574 These are typically things like "Debug" or "Release", but really
2575 can be anything you want.
2576 For Visual Studio 7 projects,
2577 they may also specify a target platform
2578 separated from the variant name by a
2583 The default target platform is Win32.
2586 with different variants are allowed;
2587 all variants will be added to the project file with their appropriate
2588 build targets and sources.
2591 An optional string, node, or list of strings or nodes
2592 (one per build variant), to tell the Visual Studio debugger
2593 what output target to use in what build variant.
2596 entries must match the number of
2601 The name of the file that Visual Studio 7 and later
2603 This appears as the value of the
2605 field in the resutling Visual Studio project file.
2606 If this is not specified,
2607 the default is the same as the specified
2611 Note that because &SCons; always executes its build commands
2612 from the directory in which the \fBSConstruct\fP file is located,
2613 if you generate a project file in a different directory
2614 than the \fBSConstruct\fP directory,
2615 users will not be able to double-click
2616 on the file name in compilation error messages
2617 displayed in the Visual Studio console output window.
2618 This can be remedied by adding the
2621 compiler option to the $CCFLAGS variable
2622 so that the compiler will print
2623 the full path name of any
2624 files that cause compilation errors.
2629 barsrcs = ['bar.cpp'],
2630 barincs = ['bar.h'],
2631 barlocalincs = ['StdAfx.h']
2632 barresources = ['bar.rc','resource.h']
2633 barmisc = ['bar_readme.txt']
2635 dll = env.SharedLibrary(target = 'bar.dll',
2638 env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
2641 localincs = barlocalincs,
2642 resources = barresources,
2645 variant = 'Release')
2648 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2650 .IP env.MSVSSolution()
2651 Builds a Microsoft Visual Studio solution file.
2653 This builds a Visual Studio solution file,
2654 based on the version of Visual Studio that is configured
2655 (either the latest installed version,
2656 or the version specified by
2658 in the construction environment).
2659 For Visual Studio 6, it will generate a
2662 For Visual Studio 7 (.NET), it will
2667 The following values must be specified:
2670 The name of the target .dsw or .sln file. The correct
2671 suffix for the version of Visual Studio must be used, but the value
2673 will be defined to the correct value (see example below).
2676 The name of this particular variant, or a list of variant
2677 names (the latter is only supported for MSVS 7 solutions). These are
2678 typically things like "Debug" or "Release", but really can be anything
2679 you want. For MSVS 7 they may also specify target platform, like this
2680 "Debug|Xbox". Default platform is Win32.
2683 A list of project file names, or Project nodes returned by calls to the
2686 to be placed into the solution file.
2687 It should be noted that these file names are NOT added to the $SOURCES
2688 environment variable in form of files, but rather as strings. This
2689 is because they represent file names to be added to the solution file,
2690 not the source files used to build the solution file.
2692 (NOTE: Currently only one project is supported per solution.)
2697 env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
2698 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
2699 variant = 'Release')
2702 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2709 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2712 Builds software distribution packages.
2713 Packages consist of files to install and packaging information.
2714 The former may be specified with the \fIsource\fP parameter and may be left out,
2715 in which case the &FindInstalledFiles; function will collect
2716 all files that have an \fBInstall\fP() or \fBInstallAs\fP() Builder attached.
2717 If the \fItarget\fP is not specified
2718 it will be deduced from additional information given to this Builder.
2720 The packaging information is specified
2721 with the help of construction variables documented below.
2722 This information is called a tag to stress that
2723 some of them can also be attached to files with the &Tag; function.
2724 The mandatory ones will complain if they were not specified.
2725 They vary depending on chosen target packager.
2727 The target packager may be selected with the "PACKAGETYPE" command line
2728 option or with the $PACKAGETYPE construction variable. Currently
2729 the following packagers available:
2731 * msi - Microsoft Installer
2732 * rpm - Redhat Package Manger
2733 * ipkg - Itsy Package Management System
2734 * tarbz2 - compressed tar
2735 * targz - compressed tar
2737 * src_tarbz2 - compressed tar source
2738 * src_targz - compressed tar source
2739 * src_zip - zip file source
2741 An updated list is always available under the "package_type" option when
2742 running "scons --help" on a project that has packaging activated.
2744 env = Environment(tools=['default', 'packaging'])
2745 env.Install('/bin/', 'my_program')
2746 env.Package( NAME = 'foo',
2749 PACKAGETYPE = 'rpm',
2751 SUMMARY = 'balalalalal',
2752 DESCRIPTION = 'this should be really really long',
2753 X_RPM_GROUP = 'Application/fu',
2754 SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
2758 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2761 Builds a Microsoft Visual C++ precompiled header.
2762 Calling this builder method
2763 returns a list of two targets: the PCH as the first element, and the object
2764 file as the second element. Normally the object file is ignored.
2765 This builder method is only
2766 provided when Microsoft Visual C++ is being used as the compiler.
2767 The PCH builder method is generally used in
2768 conjuction with the PCH construction variable to force object files to use
2769 the precompiled header:
2772 env['PCH'] = env.PCH('StdAfx.cpp')[0]
2775 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2778 Builds a \fB.pdf\fP file
2779 from a \fB.dvi\fP input file
2780 (or, by extension, a \fB.tex\fP,
2783 \fB.latex\fP input file).
2784 The suffix specified by the $PDFSUFFIX construction variable
2785 (\fB.pdf\fP by default)
2786 is added automatically to the target
2787 if it is not already present. Example:
2790 # builds from aaa.tex
2791 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
2792 # builds bbb.pdf from bbb.dvi
2793 env.PDF(target = 'bbb', source = 'bbb.dvi')
2796 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2798 .IP env.PostScript()
2799 Builds a \fB.ps\fP file
2800 from a \fB.dvi\fP input file
2801 (or, by extension, a \fB.tex\fP,
2804 \fB.latex\fP input file).
2805 The suffix specified by the $PSSUFFIX construction variable
2806 (\fB.ps\fP by default)
2807 is added automatically to the target
2808 if it is not already present. Example:
2811 # builds from aaa.tex
2812 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
2813 # builds bbb.ps from bbb.dvi
2814 env.PostScript(target = 'bbb', source = 'bbb.dvi')
2817 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2820 Builds an executable given one or more object files
2821 or C, C++, D, or Fortran source files.
2822 If any C, C++, D or Fortran source files are specified,
2823 then they will be automatically
2824 compiled to object files using the
2827 see that builder method's description for
2828 a list of legal source file suffixes
2829 and how they are interpreted.
2830 The target executable file prefix
2831 (specified by the $PROGPREFIX construction variable; nothing by default)
2833 (specified by the $PROGSUFFIX construction variable;
2834 by default, \fB.exe\fP on Windows systems,
2835 nothing on POSIX systems)
2836 are automatically added to the target if not already present.
2840 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
2843 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2846 Builds a Microsoft Visual C++ resource file.
2847 This builder method is only provided
2848 when Microsoft Visual C++ or MinGW is being used as the compiler. The
2852 for MinGW) suffix is added to the target name if no other suffix is given.
2854 file is scanned for implicit dependencies as though it were a C file.
2858 env.RES('resource.rc')
2861 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2864 Builds stub and skeleton class files
2866 from Java \fB.class\fP files.
2867 The target is a directory
2868 relative to which the stub
2869 and skeleton class files will be written.
2870 The source can be the names of \fB.class\fP files,
2871 or the objects return from the
2875 If the construction variable
2877 is set, either in the environment
2878 or in the call to the
2880 builder method itself,
2881 then the value of the variable
2882 will be stripped from the
2883 beginning of any \fB.class \fP
2887 classes = env.Java(target = 'classdir', source = 'src')
2888 env.RMIC(target = 'outdir1', source = classes)
2890 env.RMIC(target = 'outdir2',
2891 source = ['package/foo.class', 'package/bar.class'])
2893 env.RMIC(target = 'outdir3',
2894 source = ['classes/foo.class', 'classes/bar.class'],
2895 JAVACLASSDIR = 'classes')
2898 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2900 .IP env.RPCGenClient()
2901 Generates an RPC client stub (\fB_clnt.c\fP) file
2902 from a specified RPC (\fB.x\fP) source file.
2903 Because rpcgen only builds output files
2904 in the local directory,
2905 the command will be executed
2906 in the source file's directory by default.
2909 # Builds src/rpcif_clnt.c
2910 env.RPCGenClient('src/rpcif.x')
2913 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2915 .IP env.RPCGenHeader()
2916 Generates an RPC header (\fB.h\fP) file
2917 from a specified RPC (\fB.x\fP) source file.
2918 Because rpcgen only builds output files
2919 in the local directory,
2920 the command will be executed
2921 in the source file's directory by default.
2924 # Builds src/rpcif.h
2925 env.RPCGenHeader('src/rpcif.x')
2928 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2930 .IP env.RPCGenService()
2931 Generates an RPC server-skeleton (\fB_svc.c\fP) file
2932 from a specified RPC (\fB.x\fP) source file.
2933 Because rpcgen only builds output files
2934 in the local directory,
2935 the command will be executed
2936 in the source file's directory by default.
2939 # Builds src/rpcif_svc.c
2940 env.RPCGenClient('src/rpcif.x')
2943 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2946 Generates an RPC XDR routine (\fB_xdr.c\fP) file
2947 from a specified RPC (\fB.x\fP) source file.
2948 Because rpcgen only builds output files
2949 in the local directory,
2950 the command will be executed
2951 in the source file's directory by default.
2954 # Builds src/rpcif_xdr.c
2955 env.RPCGenClient('src/rpcif.x')
2958 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
2960 .IP env.SharedLibrary()
2961 Builds a shared library
2962 (\fB.so\fP on a POSIX system,
2963 \fB.dll\fP on Windows)
2964 given one or more object files
2965 or C, C++, D or Fortran source files.
2966 If any source files are given,
2967 then they will be automatically
2968 compiled to object files.
2969 The static library prefix and suffix (if any)
2970 are automatically added to the target.
2971 The target library file prefix
2972 (specified by the $SHLIBPREFIX construction variable;
2973 by default, \fBlib\fP on POSIX systems,
2974 nothing on Windows systems)
2976 (specified by the $SHLIBSUFFIX construction variable;
2977 by default, \fB.dll\fP on Windows systems,
2978 \fB.so\fP on POSIX systems)
2979 are automatically added to the target if not already present.
2983 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2986 On Windows systems, the
2987 .BR SharedLibrary ()
2988 builder method will always build an import
2989 (\fB.lib\fP) library
2990 in addition to the shared (\fB.dll\fP) library,
2991 adding a \fB.lib\fP library with the same basename
2992 if there is not already a \fB.lib\fP file explicitly
2993 listed in the targets.
2995 Any object files listed in the
2997 must have been built for a shared library
3002 will raise an error if there is any mismatch.
3004 On some platforms, there is a distinction between a shared library
3005 (loaded automatically by the system to resolve external references)
3006 and a loadable module (explicitly loaded by user action).
3007 For maximum portability, use the \fBLoadableModule\fP() builder for the latter.
3009 On Windows systems, specifying
3011 will cause the \fB.dll\fP to be
3012 registered after it is built using REGSVR32.
3013 The command that is run
3014 ("regsvr32" by default) is determined by $REGSVR construction
3015 variable, and the flags passed are determined by $REGSVRFLAGS. By
3016 default, $REGSVRFLAGS includes the \fB/s\fP option,
3017 to prevent dialogs from popping
3018 up and requiring user attention when it is run. If you change
3019 $REGSVRFLAGS, be sure to include the \fB/s\fP option.
3023 env.SharedLibrary(target = 'bar',
3024 source = ['bar.cxx', 'foo.obj'],
3028 will register \fBbar.dll\fP as a COM object
3029 when it is done linking it.
3031 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3033 .IP env.SharedObject()
3034 Builds an object file for
3035 inclusion in a shared library.
3036 Source files must have one of the same set of extensions
3037 specified above for the
3040 On some platforms building a shared object requires additional
3042 (e.g. \fB\-fPIC\fP for gcc)
3043 in addition to those needed to build a
3044 normal (static) object, but on some platforms there is no difference between a
3045 shared object and a normal (static) one. When there is a difference, SCons
3046 will only allow shared objects to be linked into a shared library, and will
3047 use a different suffix for shared objects. On platforms where there is no
3048 difference, SCons will allow both normal (static)
3049 and shared objects to be linked into a
3050 shared library, and will use the same suffix for shared and normal
3052 The target object file prefix
3053 (specified by the $SHOBJPREFIX construction variable;
3054 by default, the same as $OBJPREFIX)
3056 (specified by the $SHOBJSUFFIX construction variable)
3057 are automatically added to the target if not already present.
3061 env.SharedObject(target = 'ddd', source = 'ddd.c')
3062 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
3063 env.SharedObject(target = 'fff.obj', source = 'fff.for')
3066 Note that the source files will be scanned
3067 according to the suffix mappings in the
3068 .B SourceFileScanner
3070 See the section "Scanner Objects,"
3071 below, for a more information.
3073 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3075 .IP env.StaticLibrary()
3076 Builds a static library given one or more object files
3077 or C, C++, D or Fortran source files.
3078 If any source files are given,
3079 then they will be automatically
3080 compiled to object files.
3081 The static library prefix and suffix (if any)
3082 are automatically added to the target.
3083 The target library file prefix
3084 (specified by the $LIBPREFIX construction variable;
3085 by default, \fBlib\fP on POSIX systems,
3086 nothing on Windows systems)
3088 (specified by the $LIBSUFFIX construction variable;
3089 by default, \fB.lib\fP on Windows systems,
3090 \fB.a\fP on POSIX systems)
3091 are automatically added to the target if not already present.
3095 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
3098 Any object files listed in the
3100 must have been built for a static library
3105 will raise an error if there is any mismatch.
3107 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3109 .IP env.StaticObject()
3110 Builds a static object file
3111 from one or more C, C++, D, or Fortran source files.
3112 Source files must have one of the following extensions:
3115 .asm assembly language file
3116 .ASM assembly language file
3128 .F Windows: Fortran file
3129 POSIX: Fortran file + C pre-processor
3132 .fpp Fortran file + C pre-processor
3133 .FPP Fortran file + C pre-processor
3136 .s assembly language file
3137 .S Windows: assembly language file
3138 ARM: CodeSourcery Sourcery Lite
3139 .sx assembly language file + C pre-processor
3140 POSIX: assembly language file + C pre-processor
3141 .spp assembly language file + C pre-processor
3142 .SPP assembly language file + C pre-processor
3145 The target object file prefix
3146 (specified by the $OBJPREFIX construction variable; nothing by default)
3148 (specified by the $OBJSUFFIX construction variable;
3149 \fB.obj\fP on Windows systems,
3150 \fB.o\fP on POSIX systems)
3151 are automatically added to the target if not already present.
3155 env.StaticObject(target = 'aaa', source = 'aaa.c')
3156 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
3157 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
3160 Note that the source files will be scanned
3161 according to the suffix mappings in
3162 .B SourceFileScanner
3164 See the section "Scanner Objects,"
3165 below, for a more information.
3167 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3170 Builds a tar archive of the specified files
3172 Unlike most builder methods,
3175 builder method may be called multiple times
3177 each additional call
3178 adds to the list of entries
3179 that will be built into the archive.
3180 Any source directories will
3181 be scanned for changes to
3183 regardless of whether or not
3185 knows about them from other Builder or function calls.
3188 env.Tar('src.tar', 'src')
3190 # Create the stuff.tar file.
3191 env.Tar('stuff', ['subdir1', 'subdir2'])
3192 # Also add "another" to the stuff.tar file.
3193 env.Tar('stuff', 'another')
3195 # Set TARFLAGS to create a gzip-filtered archive.
3196 env = Environment(TARFLAGS = '-c -z')
3197 env.Tar('foo.tar.gz', 'foo')
3199 # Also set the suffix to .tgz.
3200 env = Environment(TARFLAGS = '-c -z',
3205 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3207 .IP env.TypeLibrary()
3208 Builds a Windows type library (\fB.tlb\fP)
3209 file from an input IDL file (\fB.idl\fP).
3210 In addition, it will build the associated inteface stub and
3212 naming them according to the base name of the \fB.idl\fP file.
3216 env.TypeLibrary(source="foo.idl")
3219 Will create \fBfoo.tlb\fP,
3227 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3230 Builds a header file, an implementation file and a moc file from an ui file.
3231 and returns the corresponding nodes in the above order.
3232 This builder is only available after using the tool 'qt'. Note: you can
3233 specify \fB.ui\fP files directly as source
3234 files to the \fBProgram\fP(),
3235 .BR Library\fP() and \fBSharedLibrary () builders
3236 without using this builder. Using this builder lets you override the standard
3237 naming conventions (be careful: prefixes are always prepended to names of
3238 built files; if you don't want prefixes, you may set them to ``).
3239 See the $QTDIR variable for more information.
3243 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
3244 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
3245 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
3248 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3251 Builds a zip archive of the specified files
3253 Unlike most builder methods,
3256 builder method may be called multiple times
3258 each additional call
3259 adds to the list of entries
3260 that will be built into the archive.
3261 Any source directories will
3262 be scanned for changes to
3264 regardless of whether or not
3266 knows about them from other Builder or function calls.
3269 env.Zip('src.zip', 'src')
3271 # Create the stuff.zip file.
3272 env.Zip('stuff', ['subdir1', 'subdir2'])
3273 # Also add "another" to the stuff.tar file.
3274 env.Zip('stuff', 'another')
3276 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3277 '\" END GENERATED BUILDER DESCRIPTIONS
3279 '\" The descriptions above of the various SCons Builders are generated
3280 '\" from the .xml files that live next to the various Python modules in
3281 '\" the build enginer library. If you're reading this [gnt]roff file
3282 '\" with an eye towards patching this man page, you can still submit
3283 '\" a diff against this text, but it will have to be translated to a
3284 '\" diff against the underlying .xml file before the patch is actually
3285 '\" accepted. If you do that yourself, it will make it easier to
3286 '\" integrate the patch.
3288 '\" END GENERATED BUILDER DESCRIPTIONS
3289 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3293 targets of builder methods automatically depend on their sources.
3294 An explicit dependency can
3295 be specified using the
3297 method of a construction environment (see below).
3302 source files for various programming languages,
3303 so the dependencies do not need to be specified explicitly.
3304 By default, SCons can
3307 Fortran source files with
3309 (POSIX systems only),
3314 and assembly language files with
3316 (POSIX systems only),
3321 for C preprocessor dependencies.
3322 SCons also has default support
3323 for scanning D source files,
3324 You can also write your own Scanners
3325 to add support for additional source file types.
3326 These can be added to the default
3327 Scanner object used by the
3329 .BR StaticObject (),
3332 Builders by adding them
3334 .B SourceFileScanner
3337 See the section "Scanner Objects,"
3338 below, for a more information about
3339 defining your own Scanner objects.
3341 .SS Methods and Functions to Do Things
3342 In addition to Builder methods,
3344 provides a number of other construction environment methods
3345 and global functions to
3346 manipulate the build configuration.
3348 Usually, a construction environment method
3349 and global function with the same name both exist
3350 so that you don't have to remember whether
3351 to a specific bit of functionality
3352 must be called with or without a construction environment.
3353 In the following list,
3354 if you call something as a global function
3357 .RI Function( arguments )
3359 and if you call something through a construction
3360 environment it looks like:
3362 .RI env.Function( arguments )
3364 If you can call the functionality in both ways,
3365 then both forms are listed.
3367 Global functions may be called from custom Python modules that you
3368 import into an SConscript file by adding the following
3369 to the Python module:
3372 from SCons.Script import *
3375 Except where otherwise noted,
3377 construction environment method
3379 provide the exact same functionality.
3380 The only difference is that,
3382 calling the functionality through a construction environment will
3383 substitute construction variables into
3384 any supplied strings.
3388 env = Environment(FOO = 'foo')
3393 In the above example,
3394 the first call to the global
3396 function will actually add a target named
3398 to the list of default targets,
3399 while the second call to the
3401 construction environment method
3402 will expand the value
3403 and add a target named
3405 to the list of default targets.
3406 For more on construction variable expansion,
3407 see the next section on
3408 construction variables.
3410 Construction environment methods
3411 and global functions supported by
3415 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3417 .RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
3419 .IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])"
3420 Creates an Action object for
3423 See the section "Action Objects,"
3424 below, for a complete explanation of the arguments and behavior.
3428 form of the invocation will expand
3429 construction variables in any argument strings,
3432 argument, at the time it is called
3433 using the construction variables in the
3435 construction environment through which
3440 form delays all variable expansion
3441 until the Action object is actually used.
3443 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3445 .RI AddMethod( object, function ", [" name ])
3447 .RI env.AddMethod( function ", [" name ])
3448 When called with the
3455 as the specified method
3457 When called with the
3458 .BR env.AddMethod ()
3462 to the construction environment
3464 as the specified method
3473 itself is used for the method name.
3478 # Note that the first argument to the function to
3479 # be attached as a method must be the object through
3480 # which the method will be called; the Python
3481 # convention is to call it 'self'.
3482 def my_method(self, arg):
3483 print "my_method() got", arg
3485 # Use the global AddMethod() function to add a method
3486 # to the Environment class. This
3487 AddMethod(Environment, my_method)
3489 env.my_method('arg')
3491 # Add the function as a method, using the function
3492 # name for the method call.
3494 env.AddMethod(my_method, 'other_method_name')
3495 env.other_method_name('another arg')
3498 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3500 .RI AddOption( arguments )
3501 This function adds a new command-line option to be recognized.
3504 are the same as supported by the standard Python
3505 .BR optparse.add_option ()
3506 method (with a few additional capabilities noted below);
3507 see the documentation for
3509 for a thorough discussion of its option-processing capabities.
3510 (Note that although the
3512 module was not a standard module until Python 2.3,
3514 contains a compatible version of the module
3515 that is used to provide identical functionality
3516 when run by earlier Python versions.)
3518 In addition to the arguments and values supported by the
3519 .B optparse.add_option ()
3523 function allows you to set the
3527 (a string with just the question mark)
3528 to indicate that the specified long option(s) take(s) an
3538 may be used to supply the "default"
3539 value that should be used when the
3540 option is specified on the command line
3541 without an explicit argument.
3545 keyword argument is supplied when calling
3547 the option will have a default value of
3550 Once a new command-line option has been added with
3552 the option value may be accessed using
3555 .BR env.GetOption ().
3556 \" NOTE: in SCons 1.x or 2.0, user options will be settable, but not yet.
3557 \" Uncomment this when that works. See tigris issue 2105.
3558 \" The value may also be set, using
3561 \" .BR env.SetOption (),
3562 \" if conditions in a
3564 \" require overriding any default value.
3565 \" Note, however, that a
3566 \" value specified on the command line will
3568 \" override a value set by any SConscript file.
3572 strings for the new option(s)
3573 will be displayed by the
3578 (the latter only if no other help text is
3579 specified in the SConscript files).
3580 The help text for the local options specified by
3582 will appear below the SCons options themselves,
3586 The options will appear in the help text
3587 in the order in which the
3594 AddOption('--prefix',
3596 nargs=1, type='string',
3599 help='installation prefix')
3600 env = Environment(PREFIX = GetOption('prefix'))
3603 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3605 .RI AddPostAction( target ", " action )
3607 .RI env.AddPostAction( target ", " action )
3608 Arranges for the specified
3614 The specified action(s) may be
3615 an Action object, or anything that
3616 can be converted into an Action object
3619 When multiple targets are supplied,
3620 the action may be called multiple times,
3621 once after each action that generates
3622 one or more targets in the list.
3624 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3626 .RI AddPreAction( target ", " action )
3628 .RI env.AddPreAction( target ", " action )
3629 Arranges for the specified
3632 before the specified
3635 The specified action(s) may be
3636 an Action object, or anything that
3637 can be converted into an Action object
3640 When multiple targets are specified,
3641 the action(s) may be called multiple times,
3642 once before each action that generates
3643 one or more targets in the list.
3645 Note that if any of the targets are built in multiple steps,
3646 the action will be invoked just
3647 before the "final" action that specifically
3648 generates the specified target(s).
3649 For example, when building an executable program
3650 from a specified source
3652 file via an intermediate object file:
3655 foo = Program('foo.c')
3656 AddPreAction(foo, 'pre_action')
3661 would be executed before
3663 calls the link command that actually
3664 generates the executable program binary
3666 not before compiling the
3668 file into an object file.
3670 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3672 .RI Alias( alias ", [" targets ", [" action ]])
3674 .RI env.Alias( alias ", [" targets ", [" action ]])
3675 Creates one or more phony targets that
3676 expand to one or more other targets.
3681 can be specified that will be executed
3682 whenever the any of the alias targets are out-of-date.
3683 Returns the Node object representing the alias,
3684 which exists outside of any file system.
3685 This Node object, or the alias name,
3686 may be used as a dependency of any other target,
3687 including another alias.
3689 can be called multiple times for the same
3690 alias to add additional targets to the alias,
3691 or additional actions to the list for this alias.
3697 Alias('install', '/usr/bin')
3698 Alias(['install', 'install-lib'], '/usr/local/lib')
3700 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
3701 env.Alias('install', ['/usr/local/man'])
3703 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
3706 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3708 .RI AllowSubstExceptions([ exception ", ...])"
3709 Specifies the exceptions that will be allowed
3710 when expanding construction variables.
3712 any construction variable expansions that generate a
3716 exception will expand to a
3718 (a null string) and not cause scons to fail.
3719 All exceptions not in the specified list
3720 will generate an error message
3721 and terminate processing.
3724 .B AllowSubstExceptions
3725 is called multiple times,
3726 each call completely overwrites the previous list
3727 of allowed exceptions.
3732 # Requires that all construction variable names exist.
3733 # (You may wish to do this if you want to enforce strictly
3734 # that all construction variables must be defined before use.)
3735 AllowSubstExceptions()
3737 # Also allow a string containing a zero-division expansion
3738 # like '${1 / 0}' to evalute to ''.
3739 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
3742 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3744 .RI AlwaysBuild( target ", ...)"
3746 .RI env.AlwaysBuild( target ", ...)"
3749 so that it is always assumed to be out of date,
3750 and will always be rebuilt if needed.
3753 does not add its target(s) to the default target list,
3754 so the targets will only be built
3755 if they are specified on the command line,
3756 or are a dependent of a target specified on the command line--but
3759 be built if so specified.
3760 Multiple targets can be passed in to a single call to
3763 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3765 .RI env.Append( key = val ", [...])"
3766 Appends the specified keyword arguments
3767 to the end of construction variables in the environment.
3768 If the Environment does not have
3769 the specified construction variable,
3770 it is simply added to the environment.
3771 If the values of the construction variable
3772 and the keyword argument are the same type,
3773 then the two values will be simply added together.
3774 Otherwise, the construction variable
3775 and the value of the keyword argument
3776 are both coerced to lists,
3777 and the lists are added together.
3778 (See also the Prepend method, below.)
3783 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
3786 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3788 .RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
3789 This appends new path elements to the given path in the
3790 specified external environment
3794 any particular path once (leaving the last one it encounters and
3795 ignoring the rest, to preserve path order),
3796 and to help assure this,
3797 will normalize all paths (using
3800 .BR os.path.normcase ).
3801 This can also handle the
3802 case where the given old path variable is a list instead of a
3803 string, in which case a list will be returned instead of a string.
3807 is 0, then adding a path that already exists
3808 will not move it to the end; it will stay where it is in the list.
3813 print 'before:',env['ENV']['INCLUDE']
3814 include_path = '/foo/bar:/foo'
3815 env.AppendENVPath('INCLUDE', include_path)
3816 print 'after:',env['ENV']['INCLUDE']
3820 after: /biz:/foo/bar:/foo
3823 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3825 .RI env.AppendUnique( key = val ", [...], delete_existing=0)"
3826 Appends the specified keyword arguments
3827 to the end of construction variables in the environment.
3828 If the Environment does not have
3829 the specified construction variable,
3830 it is simply added to the environment.
3831 If the construction variable being appended to is a list,
3832 then any value(s) that already exist in the
3833 construction variable will
3835 be added again to the list.
3836 However, if delete_existing is 1,
3837 existing matching values are removed first, so
3838 existing values in the arg list move to the end of the list.
3843 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3846 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3849 A factory function that
3850 returns a Builder object
3851 to be used to fetch source files
3853 The returned Builder
3854 is intended to be passed to the
3861 env.SourceCode('.', env.BitKeeper())
3864 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3866 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
3868 .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ])
3869 Deprecated synonyms for
3872 .BR env.VariantDir ().
3875 argument becomes the
3880 .BR env.VariantDir ().
3882 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3884 .RI Builder( action ", [" arguments ])
3886 .RI env.Builder( action ", [" arguments ])
3887 Creates a Builder object for
3890 See the section "Builder Objects,"
3891 below, for a complete explanation of the arguments and behavior.
3895 form of the invocation will expand
3896 construction variables in any arguments strings,
3900 at the time it is called
3901 using the construction variables in the
3903 construction environment through which
3908 form delays all variable expansion
3909 until after the Builder object is actually called.
3911 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
3913 .RI CacheDir( cache_dir )
3915 .RI env.CacheDir( cache_dir )
3918 will maintain a cache of derived files in
3920 The derived files in the cache will be shared
3921 among all the builds using the same
3928 disables derived file caching.
3932 will only affect targets built
3933 through the specified construction environment.
3936 sets a global default
3937 that will be used by all targets built
3938 through construction environments
3949 finds a derived file that needs to be rebuilt,
3950 it will first look in the cache to see if a
3951 derived file has already been built
3952 from identical input files and an identical build action
3953 (as incorporated into the MD5 build signature).
3956 will retrieve the file from the cache.
3957 If the derived file is not present in the cache,
3960 then place a copy of the built file in the cache
3961 (identified by its MD5 build signature),
3962 so that it may be retrieved by other
3963 builds that need to build the same derived file
3964 from identical inputs.
3968 may be disabled for any invocation
3977 will place a copy of
3979 derived files in the cache,
3980 even if they already existed
3981 and were not built by this invocation.
3982 This is useful to populate a cache
3985 is added to a build,
3994 "Retrieved `file' from cache,"
3997 option is being used.
4002 will print the action that
4004 have been used to build the file,
4005 without any indication that
4006 the file was actually retrieved from the cache.
4007 This is useful to generate build logs
4008 that are equivalent regardless of whether
4009 a given derived file has been built in-place
4010 or retrieved from the cache.
4014 method can be used to disable caching of specific files. This can be
4015 useful if inputs and/or outputs of some tool are impossible to
4016 predict or prohibitively large.
4018 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4020 .RI Clean( targets ", " files_or_dirs )
4022 .RI env.Clean( targets ", " files_or_dirs )
4023 This specifies a list of files or directories which should be removed
4024 whenever the targets are specified with the
4026 command line option.
4027 The specified targets may be a list
4028 or an individual target.
4032 and create new targets or add files and directories to the
4033 clean list for the specified targets.
4035 Multiple files or directories should be specified
4036 either as separate arguments to the
4038 method, or as a list.
4040 will also accept the return value of any of the construction environment
4046 function overrides calling
4048 for the same target,
4049 and any targets passed to both functions will
4058 Clean('foo', ['bar', 'baz'])
4059 Clean('dist', env.Program('hello', 'hello.c'))
4060 Clean(['foo', 'bar'], 'something_else_to_clean')
4063 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4065 .RI Command( target ", " source ", " action ", [" key = val ", ...])"
4067 .RI env.Command( target ", " source ", " action ", [" key = val ", ...])"
4068 Executes a specific action
4069 (or list of actions)
4070 to build a target file or files.
4071 This is more convenient
4072 than defining a separate Builder object
4073 for a single special-case build.
4075 As a special case, the
4077 keyword argument can
4080 that will be used to scan the sources.
4084 if any of the sources will be directories
4085 that must be scanned on-disk for
4086 changes to files that aren't
4087 already specified in other Builder of function calls.)
4089 Any other keyword arguments specified override any
4090 same-named existing construction variables.
4092 An action can be an external command,
4093 specified as a string,
4094 or a callable Python object;
4095 see "Action Objects," below,
4096 for more complete information.
4097 Also note that a string specifying an external command
4098 may be preceded by an
4101 to suppress printing the command in question,
4105 to ignore the exit status of the external command.
4110 env.Command('foo.out', 'foo.in',
4111 "$FOO_BUILD < $SOURCES > $TARGET")
4113 env.Command('bar.out', 'bar.in',
4115 "$BAR_BUILD < $SOURCES > $TARGET"],
4116 ENV = {'PATH' : '/usr/local/bin/'})
4118 def rename(env, target, source):
4120 os.rename('.tmp', str(target[0]))
4122 env.Command('baz.out', 'baz.in',
4123 ["$BAZ_BUILD < $SOURCES > .tmp",
4130 function will usually assume, by default,
4131 that the specified targets and/or sources are Files,
4132 if no other part of the configuration
4133 identifies what type of entry it is.
4134 If necessary, you can explicitly specify
4135 that targets or source nodes should
4136 be treated as directoriese
4146 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
4148 env['DISTDIR'] = 'destination/directory'
4149 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
4153 (Also note that SCons will usually
4154 automatically create any directory necessary to hold a target file,
4155 so you normally don't need to create directories by hand.)
4157 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4159 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
4161 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ])
4162 Creates a Configure object for integrated
4163 functionality similar to GNU autoconf.
4164 See the section "Configure Contexts,"
4165 below, for a complete explanation of the arguments and behavior.
4167 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4169 .RI env.Clone([ key = val ", ...])"
4170 Return a separate copy of a construction environment.
4171 If there are any keyword arguments specified,
4172 they are added to the returned copy,
4173 overwriting any existing values
4180 env3 = env.Clone(CCFLAGS = '-g')
4183 Additionally, a list of tools and a toolpath may be specified, as in
4184 the Environment constructor:
4187 def MyTool(env): env['FOO'] = 'bar'
4188 env4 = env.Clone(tools = ['msvc', MyTool])
4193 keyword argument is also recognized:
4196 # create an environment for compiling programs that use wxWidgets
4197 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
4200 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4202 .RI env.Copy([ key = val ", ...])"
4203 A now-deprecated synonym for
4206 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4208 .RI env.CVS( repository ", " module )
4209 A factory function that
4210 returns a Builder object
4211 to be used to fetch source files
4215 The returned Builder
4216 is intended to be passed to the
4220 The optional specified
4222 will be added to the beginning
4223 of all repository path names;
4224 this can be used, in essence,
4225 to strip initial directory names
4226 from the repository path names,
4227 so that you only have to
4228 replicate part of the repository
4229 directory hierarchy in your
4230 local build directory.
4235 # Will fetch foo/bar/src.c
4236 # from /usr/local/CVSROOT/foo/bar/src.c.
4237 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
4239 # Will fetch bar/src.c
4240 # from /usr/local/CVSROOT/foo/bar/src.c.
4241 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
4244 # from /usr/local/CVSROOT/foo/bar/src.c.
4245 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
4248 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4250 .RI Decider( function )
4252 .RI env.Decider( function )
4253 Specifies that all up-to-date decisions for
4254 targets built through this construction environment
4255 will be handled by the specified
4259 can be one of the following strings
4260 that specify the type of decision function
4266 Specifies that a target shall be considered out of date and rebuilt
4267 if the dependency's timestamp is newer than the target file's timestamp.
4268 This is the behavior of the classic Make utility,
4271 can be used a synonym for
4272 .BR timestamp-newer .
4276 Specifies that a target shall be considered out of date and rebuilt
4277 if the dependency's timestamp is different than the
4278 timestamp recorded the last time the target was built.
4279 This provides behavior very similar to the classic Make utility
4280 (in particular, files are not opened up so that their
4281 contents can be checksummed)
4282 except that the target will also be rebuilt if a
4283 dependency file has been restored to a version with an
4285 timestamp, such as can happen when restoring files from backup archives.
4289 Specifies that a target shall be considered out of date and rebuilt
4290 if the dependency's content has changed sine the last time
4291 the target was built,
4292 as determined be performing an MD5 checksum
4293 on the dependency's contents
4294 and comparing it to the checksum recorded the
4295 last time the target was built.
4297 can be used as a synonym for
4302 Specifies that a target shall be considered out of date and rebuilt
4303 if the dependency's content has changed sine the last time
4304 the target was built,
4305 except that dependencies with a timestamp that matches
4306 the last time the target was rebuilt will be
4307 assumed to be up-to-date and
4310 This provides behavior very similar
4313 behavior of always checksumming file contents,
4314 with an optimization of not checking
4315 the contents of files whose timestamps haven't changed.
4316 The drawback is that SCons will
4318 detect if a file's content has changed
4319 but its timestamp is the same,
4320 as might happen in an automated script
4323 and runs the build again,
4324 all within a single second.
4331 # Use exact timestamp matches by default.
4332 Decider('timestamp-match')
4334 # Use MD5 content signatures for any targets built
4335 # with the attached construction environment.
4336 env.Decider('content')
4340 In addition to the above already-available functions,
4343 argument may be an actual Python function
4344 that takes the following three arguments:
4348 The Node (file) which
4352 if it has "changed" since the last tme
4353 .I target was built.
4356 The Node (file) being built.
4358 this is what should get rebuilt
4364 Stored information about the state of the
4369 This can be consulted to match various
4370 file characteristics
4371 such as the timestamp,
4372 size, or content signature.
4383 has "changed" since the last time
4387 (indicating that the target
4394 (indicating that the target should
4397 Note that the decision can be made
4398 using whatever criteria are appopriate.
4399 Ignoring some or all of the function arguments
4400 is perfectly normal.
4405 def my_decider(dependency, target, prev_ni):
4406 return not os.path.exists(str(target))
4408 env.Decider(my_decider)
4411 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4413 .RI Default( targets )
4415 .RI env.Default( targets )
4416 This specifies a list of default targets,
4417 which will be built by
4419 if no explicit targets are given on the command line.
4423 and add to the list of default targets.
4425 Multiple targets should be specified as
4426 separate arguments to the
4428 method, or as a list.
4430 will also accept the Node returned by any
4431 of a construction environment's
4437 Default('foo', 'bar', 'baz')
4438 env.Default(['a', 'b', 'c'])
4439 hello = env.Program('hello', 'hello.c')
4447 will clear all default targets.
4450 will add to the (now empty) default-target list
4453 The current list of targets added using the
4455 function or method is available in the
4460 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4462 .RI DefaultEnvironment([ args ])
4463 Creates and returns a default construction environment object.
4464 This construction environment is used internally by SCons
4465 in order to execute many of the global functions in this list,
4466 and to fetch source files transparently
4467 from source code management systems.
4469 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4471 .RI Depends( target ", " dependency )
4473 .RI env.Depends( target ", " dependency )
4474 Specifies an explicit dependency;
4486 (usually the path name of a file or directory)
4488 or a list of strings or Node objects
4489 (such as returned by a Builder call).
4490 This should only be necessary
4491 for cases where the dependency
4492 is not caught by a Scanner
4498 env.Depends('foo', 'other-input-file-for-foo')
4500 mylib = env.Library('mylib.c')
4501 installed_lib = env.Install('lib', mylib)
4502 bar = env.Program('bar.c')
4504 # Arrange for the library to be copied into the installation
4505 # directory before trying to build the "bar" program.
4506 # (Note that this is for example only. A "real" library
4507 # dependency would normally be configured through the $LIBS
4508 # and $LIBPATH variables, not using an env.Depends() call.)
4510 env.Depends(bar, installed_lib)
4513 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4515 .RI env.Dictionary([ vars ])
4516 Returns a dictionary object
4517 containing copies of all of the
4518 construction variables in the environment.
4519 If there are any variable names specified,
4520 only the specified construction
4521 variables are returned in the dictionary.
4526 dict = env.Dictionary()
4527 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
4530 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4532 .RI Dir( name ", [" directory ])
4534 .RI env.Dir( name ", [" directory ])
4535 This returns a Directory Node,
4536 an object that represents the specified directory
4539 can be a relative or absolute path.
4541 is an optional directory that will be used as the parent directory.
4544 is specified, the current script's directory is used as the parent.
4548 is a list, SCons returns a list of Dir nodes.
4549 Construction variables are expanded in
4552 Directory Nodes can be used anywhere you
4553 would supply a string as a directory name
4554 to a Builder method or function.
4555 Directory Nodes have attributes and methods
4556 that are useful in many situations;
4557 see "File and Directory Nodes," below.
4559 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4561 .RI env.Dump([ key ])
4562 Returns a pretty printable representation of the environment.
4566 should be a string containing the name of the variable of interest.
4571 print env.Dump('CCCOM')
4576 \&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES'
4587 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
4590 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
4595 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4597 .RI EnsurePythonVersion( major ", " minor )
4599 .RI env.EnsurePythonVersion( major ", " minor )
4600 Ensure that the Python version is at least
4603 print out an error message and exit SCons with a non-zero exit code if the
4604 actual Python version is not late enough.
4609 EnsurePythonVersion(2,2)
4612 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4614 .RI EnsureSConsVersion( major ", " minor ", [" revision ])
4616 .RI env.EnsureSConsVersion( major ", " minor ", [" revision ])
4617 Ensure that the SCons version is at least
4620 .IR major.minor.revision .
4625 print out an error message and exit SCons with a non-zero exit code if the
4626 actual SCons version is not late enough.
4631 EnsureSConsVersion(0,14)
4633 EnsureSConsVersion(0,96,90)
4636 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4638 .RI Environment([ key = value ", ...])"
4640 .RI env.Environment([ key = value ", ...])"
4641 Return a new construction environment
4642 initialized with the specified
4646 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4648 .RI Execute( action ", [" strfunction ", " varlist ])
4650 .RI env.Execute( action ", [" strfunction ", " varlist ])
4651 Executes an Action object.
4654 may be an Action object
4655 (see the section "Action Objects,"
4656 below, for a complete explanation of the arguments and behavior),
4657 or it may be a command-line string,
4659 or executable Python function,
4660 each of which will be converted
4661 into an Action object
4663 The exit value of the command
4664 or return value of the Python function
4669 will print an error message if the executed
4672 exits with or returns a non-zero value.
4677 automatically terminate the build
4681 If you want the build to stop in response to a failed
4684 you must explicitly check for a non-zero return value:
4687 Execute(Copy('file.out', 'file.in'))
4689 if Execute("mkdir sub/dir/ectory"):
4690 # The mkdir failed, don't try to build.
4694 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4698 .RI env.Exit([ value ])
4704 A default exit value of
4707 is used if no value is specified.
4709 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4713 .RI env.Export( vars )
4716 to export a list of variables from the current
4717 SConscript file to all other SConscript files.
4718 The exported variables are kept in a global collection,
4719 so subsequent calls to
4721 will over-write previous exports that have the same name.
4722 Multiple variable names can be passed to
4724 as separate arguments or as a list. A dictionary can be used to map
4725 variables to a different name when exported. Both local variables and
4726 global variables can be exported.
4732 # Make env available for all SConscript files to Import().
4736 # Make env and package available for all SConscript files:.
4737 Export("env", "package")
4739 # Make env and package available for all SConscript files:
4740 Export(["env", "package"])
4742 # Make env available using the name debug:.
4743 Export({"debug":env})
4749 function supports an
4751 argument that makes it easier to to export a variable or
4752 set of variables to a single SConscript file.
4753 See the description of the
4757 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4759 .RI File( name ", [" directory ])
4761 .RI env.File( name ", [" directory ])
4764 an object that represents the specified file
4767 can be a relative or absolute path.
4769 is an optional directory that will be used as the parent directory.
4773 is a list, SCons returns a list of File nodes.
4774 Construction variables are expanded in
4777 File Nodes can be used anywhere you
4778 would supply a string as a file name
4779 to a Builder method or function.
4780 File Nodes have attributes and methods
4781 that are useful in many situations;
4782 see "File and Directory Nodes," below.
4784 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4786 .RI FindFile( file ", " dirs )
4788 .RI env.FindFile( file ", " dirs )
4791 in the path specified by
4794 may be a list of directory names or a single directory name.
4795 In addition to searching for files that exist in the filesytem,
4796 this function also searches for derived files
4797 that have not yet been built.
4802 foo = env.FindFile('foo', ['dir1', 'dir2'])
4805 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4807 .RI FindInstalledFiles( )
4809 .RI env.FindInstalledFiles( )
4810 Returns the list of targets set up by the
4816 This function serves as a convenient method to select the contents of
4822 Install( '/bin', [ 'executable_a', 'executable_b' ] )
4824 # will return the file node list
4825 # [ '/bin/executable_a', '/bin/executable_b' ]
4826 FindInstalledFiles()
4828 Install( '/lib', [ 'some_library' ] )
4830 # will return the file node list
4831 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
4832 FindInstalledFiles()
4835 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4837 .RI FindSourceFiles( node = '"."' )
4839 .RI env.FindSourceFiles( node = '"."' )
4841 Returns the list of nodes which serve as the source of the built files.
4842 It does so by inspecting the dependency tree starting at the optional
4845 which defaults to the '"."'-node. It will then return all leaves of
4847 These are all children which have no further children.
4849 This function is a convenient method to select the contents of a Source
4855 Program( 'src/main_a.c' )
4856 Program( 'src/main_b.c' )
4857 Program( 'main_c.c' )
4859 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
4862 # returns ['src/main_b.c', 'src/main_a.c' ]
4863 FindSourceFiles( 'src' )
4867 As you can see build support files (SConstruct in the above example)
4868 will also be returned by this function.
4870 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4872 .RI FindPathDirs( variable )
4874 (actually a callable Python object)
4875 intended to be used as the
4877 of a Scanner object.
4878 The returned object will look up the specified
4880 in a construction environment
4881 and treat the construction variable's value as a list of
4882 directory paths that should be searched
4890 is generally preferable to
4893 for the following reasons:
4894 1) The returned list will contain all appropriate directories
4895 found in source trees
4899 or in code repositories
4905 2) scons will identify expansions of
4907 that evaluate to the same list of directories as,
4908 in fact, the same list,
4909 and avoid re-scanning the directories for files,
4915 def my_scan(node, env, path, arg):
4916 # Code to scan file contents goes here...
4917 return include_files
4919 scanner = Scanner(name = 'myscanner',
4921 path_function = FindPathDirs('MYPATH'))
4924 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4926 .RI Flatten( sequence )
4928 .RI env.Flatten( sequence )
4929 Takes a sequence (that is, a Python list or tuple)
4930 that may contain nested sequences
4931 and returns a flattened list containing
4932 all of the individual elements in any sequence.
4933 This can be helpful for collecting
4934 the lists returned by calls to Builders;
4935 other Builders will automatically
4936 flatten lists specified as input,
4937 but direct Python manipulation of
4938 these lists does not.
4943 foo = Object('foo.c')
4944 bar = Object('bar.c')
4946 # Because `foo' and `bar' are lists returned by the Object() Builder,
4947 # `objects' will be a list containing nested lists:
4948 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
4950 # Passing such a list to another Builder is all right because
4951 # the Builder will flatten the list automatically:
4952 Program(source = objects)
4954 # If you need to manipulate the list directly using Python, you need to
4955 # call Flatten() yourself, or otherwise handle nested lists:
4956 for object in Flatten(objects):
4960 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
4962 .RI GetBuildFailures()
4963 Returns a list of exceptions for the
4964 actions that failed while
4965 attempting to build targets.
4966 Each element in the returned list is a
4969 with the following attributes
4970 that record various aspects
4971 of the build failure:
4974 The node that was being built
4975 when the build failure occurred.
4978 The numeric exit status
4979 returned by the command or Python function
4980 that failed when trying to build the
4984 The SCons error string
4985 describing the build failure.
4986 (This is often a generic
4987 message like "Error 2"
4988 to indicate that an executed
4989 command exited with a status of 2.)
4992 The name of the file or
4993 directory that actually caused the failure.
4994 This may be different from the
4998 if an attempt to build a target named
5002 directory could not be created,
5013 The SCons Executor object
5016 This can be used to retrieve
5017 the construction environment used
5018 for the failed action.
5021 The actual SCons Action object that failed.
5022 This will be one specific action
5023 out of the possible list of
5024 actions that would have been
5025 executed to build the target.
5028 The actual expanded command that was executed and failed,
5032 and other construction variables.
5035 .BR GetBuildFailures ()
5037 will always return an empty list
5038 until any build failure has occurred,
5040 .BR GetBuildFailures ()
5041 will always return an empty list
5044 files are being read.
5045 Its primary intended use is
5046 for functions that will be
5047 executed before SCons exits
5048 by passing them to the
5050 .BR atexit.register ()
5057 def print_build_failures():
5058 from SCons.Script import GetBuildFailures
5059 for bf in GetBuildFailures():
5060 print "%s failed: %s" % (bf.node, bf.errstr)
5062 atexit.register(print_build_failures)
5065 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5067 .RI GetBuildPath( file ", [" ... ])
5069 .RI env.GetBuildPath( file ", [" ... ])
5072 path name (or names) for the specified
5080 Nodes or strings representing path names.
5082 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5086 .RI env.GetLaunchDir()
5087 Returns the absolute path name of the directory from which
5089 was initially invoked.
5090 This can be useful when using the
5095 options, which internally
5096 change to the directory in which the
5100 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5102 .RI GetOption( name )
5104 .RI env.GetOption( name )
5105 This function provides a way to query the value of
5106 SCons options set on scons command line
5110 The options supported are:
5115 which corresponds to --cache-debug;
5118 which corresponds to --cache-disable;
5121 which corresponds to --cache-force;
5124 which corresponds to --cache-show;
5127 which corresponds to -c, --clean and --remove;
5130 which corresponds to --config;
5133 which corresponds to -C and --directory;
5136 which corresponds to --diskcheck
5139 which corresponds to --duplicate;
5142 which corresponds to -f, --file, --makefile and --sconstruct;
5145 which corresponds to -h and --help;
5148 which corresponds to --ignore-errors;
5151 which corresponds to --implicit-cache;
5153 .B implicit_deps_changed
5154 which corresponds to --implicit-deps-changed;
5156 .B implicit_deps_unchanged
5157 which corresponds to --implicit-deps-unchanged;
5160 which corresponds to --interact and --interactive;
5163 which corresponds to -k and --keep-going;
5166 which corresponds to --max-drift;
5169 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
5172 which corresponds to --no-site-dir;
5175 which corresponds to -j and --jobs;
5178 which corresponds to --profile;
5181 which corresponds to -q and --question;
5184 which corresponds to --random;
5187 which corresponds to -Y, --repository and --srcdir;
5190 which corresponds to -s, --silent and --quiet;
5193 which corresponds to --site-dir;
5196 which corresponds to --stack-size;
5198 .B taskmastertrace_file
5199 which corresponds to --taskmastertrace; and
5202 which corresponds to --warn and --warning.
5206 See the documentation for the
5207 corresponding command line object for information about each specific
5210 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5212 .RI Glob( pattern ", [" ondisk ", " source ", " strings ])
5214 .RI env.Glob( pattern ", [" ondisk ", " source ", " strings ])
5215 Returns Nodes (or strings) that match the specified
5217 relative to the directory of the current
5222 form performs string substition on
5224 and returns whatever matches
5225 the resulting expanded pattern.
5229 uses Unix shell style metacharacters for matching:
5232 * matches everything
5233 ? matches any single character
5234 [seq] matches any character in seq
5235 [!seq] matches any char not in seq
5239 Character matches do
5241 span directory separators.
5250 and source directories
5255 returns a Node (or string, if so configured)
5256 in the local (SConscript) directory
5257 if matching Node is found
5258 anywhere in a corresponding
5259 repository or source directory.
5263 argument may be set to
5265 (or any other non-true value)
5266 to disable the search for matches on disk,
5267 thereby only returning matches among
5268 already-configured File or Dir Nodes.
5269 The default behavior is to
5270 return corresponding Nodes
5271 for any on-disk matches found.
5275 argument may be set to
5277 (or any equivalent value)
5279 when the local directory is a
5281 the returned Nodes should be from the
5282 corresponding source directory,
5283 not the local directory.
5287 argument may be set to
5289 (or any equivalent value)
5292 function return strings, not Nodes,
5293 that represent the matched files or directories.
5294 The returned strings will be relative to
5295 the local (SConscript) directory.
5296 (Note that This may make it easier to perform
5297 arbitrary manipulation of file names,
5298 but if the returned strings are
5299 passed to a different
5302 any Node translation will be relative
5313 Program('foo', Glob('*.c'))
5316 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5318 '\".RI GlobalBuilders( flag )
5322 '\"adds the names of the default builders
5323 '\"(Program, Library, etc.)
5324 '\"to the global name space
5325 '\"so they can be called without an explicit construction environment.
5326 '\"(This is the default.)
5330 '\"the names of the default builders are removed
5331 '\"from the global name space
5332 '\"so that an explicit construction environment is required
5333 '\"to call all builders.
5335 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5339 .RI env.Help( text )
5340 This specifies help text to be printed if the
5342 argument is given to
5346 is called multiple times, the text is appended together in the order
5351 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5353 .RI Ignore( target ", " dependency )
5355 .RI env.Ignore( target ", " dependency )
5356 The specified dependency file(s)
5357 will be ignored when deciding if
5358 the target file(s) need to be rebuilt.
5362 to remove a target from the default build.
5363 In order to do this you must specify the directory the target will
5364 be built in as the target, and the file you want to skip building
5367 Note that this will only remove the dependencies listed from
5368 the files built by default. It will still be built if that
5369 dependency is needed by another object being built.
5370 See the third and forth examples below.
5375 env.Ignore('foo', 'foo.c')
5376 env.Ignore('bar', ['bar1.h', 'bar2.h'])
5377 env.Ignore('.','foobar.obj')
5378 env.Ignore('bar','bar/foobar.obj')
5381 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5385 .RI env.Import( vars )
5388 to import a list of variables into the current SConscript file. This
5389 will import variables that were exported with
5395 Variables exported by
5398 Multiple variable names can be passed to
5400 as separate arguments or as a list. The variable "*" can be used
5401 to import all variables.
5407 Import("env", "variable")
5408 Import(["env", "variable"])
5412 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5414 .RI Literal( string )
5416 .RI env.Literal( string )
5419 will be preserved as-is
5420 and not have construction variables expanded.
5422 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5424 .RI Local( targets )
5426 .RI env.Local( targets )
5429 will have copies made in the local tree,
5430 even if an already up-to-date copy
5431 exists in a repository.
5432 Returns a list of the target Node or Nodes.
5434 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5436 \" .RI env.MergeShellPaths( arg ", [" prepend ])
5437 \" Merges the elements of the specified
5439 \" which must be a dictionary, to the construction
5440 \" environment's copy of the shell environment
5442 \" (This is the environment which is passed
5443 \" to subshells spawned by SCons.)
5446 \" must be a single value,
5447 \" so multiple strings must
5448 \" be passed in as a list,
5449 \" not as separate arguments to
5450 \" .BR env.MergeShellPaths ().
5452 \" New values are prepended to the environment variable by default,
5453 \" unless prepend=0 is specified.
5454 \" Duplicate values are always eliminated,
5455 \" since this function calls
5458 \" .B PrependENVPath
5461 \" argument. See those functions for more details.
5466 \" # Prepend a path to the shell PATH.
5467 \" env.MergeShellPaths({'PATH':'/usr/local/bin'} )
5468 \" # Append two dirs to the shell INCLUDE.
5469 \" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 )
5473 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5475 .RI env.MergeFlags( arg ", [" unique ])
5476 Merges the specified
5478 values to the construction environment's construction variables.
5481 argument is not a dictionary,
5482 it is converted to one by calling
5485 before the values are merged.
5488 must be a single value,
5489 so multiple strings must
5490 be passed in as a list,
5491 not as separate arguments to
5492 .BR env.MergeFlags ().
5495 duplicate values are eliminated;
5496 you can, however, specify
5500 When eliminating duplicate values,
5501 any construction variables that end with
5504 keep the left-most unique value.
5505 All other construction variables keep
5506 the right-most unique value.
5511 # Add an optimization flag to $CCFLAGS.
5512 env.MergeFlags('-O3')
5514 # Combine the flags returned from running pkg-config with an optimization
5515 # flag and merge the result into the construction variables.
5516 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
5518 # Combine an optimization flag with the flags returned from running pkg-config
5519 # twice and merge the result into the construction variables.
5520 env.MergeFlags(['-O3',
5521 '!pkg-config gtk+-2.0 --cflags --libs',
5522 '!pkg-config libpng12 --cflags --libs'])
5525 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5527 .RI NoCache( target ", ...)"
5529 .RI env.NoCache( target ", ...)"
5530 Specifies a list of files which should
5532 be cached whenever the
5534 method has been activated.
5535 The specified targets may be a list
5536 or an individual target.
5538 Multiple files should be specified
5539 either as separate arguments to the
5541 method, or as a list.
5543 will also accept the return value of any of the construction environment
5548 on directories and other non-File Node types has no effect because
5549 only File Nodes are cached.
5555 NoCache(env.Program('hello', 'hello.c'))
5558 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5560 .RI NoClean( target ", ...)"
5562 .RI env.NoClean( target ", ...)"
5563 Specifies a list of files or directories which should
5565 be removed whenever the targets (or their dependencies)
5566 are specified with the
5568 command line option.
5569 The specified targets may be a list
5570 or an individual target.
5574 and prevent each specified target
5575 from being removed by calls to the
5579 Multiple files or directories should be specified
5580 either as separate arguments to the
5582 method, or as a list.
5584 will also accept the return value of any of the construction environment
5589 for a target overrides calling
5591 for the same target,
5592 and any targets passed to both functions will
5602 NoClean(env.Program('hello', 'hello.c'))
5605 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5607 .RI env.ParseConfig( command ", [" function ", " unique ])
5610 to modify the environment as specified by the output of
5615 .BR env.MergeFlags (),
5616 which expects the output of a typical
5620 and adds the options
5621 to the appropriate construction variables.
5623 duplicate values are not
5624 added to any construction variables;
5631 and the construction variables they affect
5632 are as specified for the
5633 .BR env.ParseFlags ()
5634 method (which this method calls).
5635 See that method's description, below,
5636 for a table of options and construction variables.
5638 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5640 .RI ParseDepends( filename ", [" must_exist ", " only_one ])
5642 .RI env.ParseDepends( filename ", [" must_exist ", " only_one ])
5643 Parses the contents of the specified
5645 as a list of dependencies in the style of
5649 and explicitly establishes all of the listed dependencies.
5658 argument may be set to a non-zero
5661 throw an exception and
5662 generate an error if the file does not exist,
5663 or is otherwise inaccessible.
5667 argument may be set to a non-zero
5670 thrown an exception and
5672 if the file contains dependency
5673 information for more than one target.
5674 This can provide a small sanity check
5675 for files intended to be generated
5676 by, for example, the
5679 which should typically only
5680 write dependency information for
5681 one output file into a corresponding
5687 and all of the files listed therein
5688 will be interpreted relative to
5689 the directory of the
5691 file which calls the
5695 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5697 .RI env.ParseFlags( flags ", ...)"
5698 Parses one or more strings containing
5699 typical command-line flags for GCC tool chains
5700 and returns a dictionary with the flag values
5701 separated into the appropriate SCons construction variables.
5702 This is intended as a companion to the
5703 .BR env.MergeFlags ()
5704 method, but allows for the values in the returned dictionary
5705 to be modified, if necessary,
5706 before merging them into the construction environment.
5708 .BR env.MergeFlags ()
5709 will call this method if its argument is not a dictionary,
5710 so it is usually not necessary to call
5711 .BR env.ParseFlags ()
5712 directly unless you want to manipulate the values.)
5714 If the first character in any string is
5715 an exclamation mark (!),
5716 the rest of the string is executed as a command,
5717 and the output from the command is
5718 parsed as GCC tool chain command-line flags
5719 and added to the resulting dictionary.
5721 Flag values are translated accordig to the prefix found,
5722 and added to the following construction variables:
5725 -arch CCFLAGS, LINKFLAGS
5727 -framework FRAMEWORKS
5728 -frameworkdir= FRAMEWORKPATH
5730 -isysroot CCFLAGS, LINKFLAGS
5734 -mno-cygwin CCFLAGS, LINKFLAGS
5736 -pthread CCFLAGS, LINKFLAGS
5738 -Wa, ASFLAGS, CCFLAGS
5745 + CCFLAGS, LINKFLAGS
5749 Any other strings not associated with options
5750 are assumed to be the names of libraries
5753 construction variable.
5755 Examples (all of which produce the same result):
5758 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
5759 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
5760 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
5761 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
5764 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5767 A factory function that
5768 returns a Builder object
5769 to be used to fetch source files
5770 from the Perforce source code management system.
5771 The returned Builder
5772 is intended to be passed to the
5779 env.SourceCode('.', env.Perforce())
5782 Perforce uses a number of external
5783 environment variables for its operation.
5784 Consequently, this function adds the
5785 following variables from the user's external environment
5786 to the construction environment's
5799 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5801 .RI Platform( string )
5802 Returns a callable object
5803 that can be used to initialize
5804 a construction environment using the
5805 platform keyword of the Environment() method.
5810 env = Environment(platform = Platform('win32'))
5813 .RI env.Platform( string )
5814 Applies the callable object for the specified platform
5816 to the environment through which the method was called.
5819 env.Platform('posix')
5828 variables from the user's external environment
5829 to the construction environment's
5832 This is so that any executed commands
5833 that use sockets to connect with other systems
5834 (such as fetching source files from
5835 external CVS repository specifications like
5836 .BR :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons )
5837 will work on Windows systems.
5839 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5841 .RI Progress( callable ", [" interval ])
5843 .RI Progress( string ", [" interval ", " file ", " overwrite ])
5845 .RI Progress( list_of_strings ", [" interval ", " file ", " overwrite ])
5846 Allows SCons to show progress made during the build
5847 by displaying a string or calling a function while
5848 evaluating Nodes (e.g. files).
5850 If the first specified argument is a Python callable
5851 (a function or an object that has a
5854 the function will be called
5857 times a Node is evaluated.
5858 The callable will be passed the evaluated Node
5859 as its only argument.
5860 (For future compatibility,
5861 it's a good idea to also add
5865 as arguments to your function or method.
5866 This will prevent the code from breaking
5867 if SCons ever changes the interface
5868 to call the function with additional arguments in the future.)
5870 An example of a simple custom progress function
5871 that prints a string containing the Node name
5875 def my_progress_function(node, *args, **kw):
5876 print 'Evaluating node %s!' % node
5877 Progress(my_progress_function, interval=10)
5880 A more complicated example of a custom progress display object
5881 that prints a string containing a count
5882 every 100 evaluated Nodes.
5886 at the end so that the string
5887 will overwrite itself on a display:
5891 class ProgressCounter:
5893 def __call__(self, node, *args, **kw):
5895 sys.stderr.write('Evaluated %s nodes\\r' % self.count)
5896 Progress(ProgressCounter(), interval=100)
5899 If the first argument
5902 the string will be displayed
5906 The default is to print the string on standard output;
5907 an alternate output stream
5908 may be specified with the
5911 The following will print a series of dots
5912 on the error output,
5913 one dot for every 100 evaluated Nodes:
5917 Progress('.', interval=100, file=sys.stderr)
5920 If the string contains the verbatim substring
5922 it will be replaced with the Node.
5923 Note that, for performance reasons, this is
5925 a regular SCons variable substition,
5926 so you can not use other variables
5927 or use curly braces.
5928 The following example will print the name of
5929 every evaluated Node,
5932 (carriage return) to cause each line to overwritten by the next line,
5935 keyword argument to make sure the previously-printed
5936 file name is overwritten with blank spaces:
5940 Progress('$TARGET\\r', overwrite=True)
5943 If the first argument to
5945 is a list of strings,
5946 then each string in the list will be displayed
5947 in rotating fashion every
5950 This can be used to implement a "spinner"
5951 on the user's screen as follows:
5954 Progress(['-\\r', '\\\\\\r', '|\\r', '/\\r'], interval=5)
5957 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5959 .RI Precious( target ", ...)"
5961 .RI env.Precious( target ", ...)"
5964 as precious so it is not deleted before it is rebuilt. Normally
5966 deletes a target before building it.
5967 Multiple targets can be passed in to a single call to
5970 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5972 .RI env.Prepend( key = val ", [...])"
5973 Appends the specified keyword arguments
5974 to the beginning of construction variables in the environment.
5975 If the Environment does not have
5976 the specified construction variable,
5977 it is simply added to the environment.
5978 If the values of the construction variable
5979 and the keyword argument are the same type,
5980 then the two values will be simply added together.
5981 Otherwise, the construction variable
5982 and the value of the keyword argument
5983 are both coerced to lists,
5984 and the lists are added together.
5985 (See also the Append method, above.)
5990 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
5993 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
5995 .RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ])
5996 This appends new path elements to the given path in the
5997 specified external environment
6001 any particular path once (leaving the first one it encounters and
6002 ignoring the rest, to preserve path order),
6003 and to help assure this,
6004 will normalize all paths (using
6007 .BR os.path.normcase ).
6008 This can also handle the
6009 case where the given old path variable is a list instead of a
6010 string, in which case a list will be returned instead of a string.
6014 is 0, then adding a path that already exists
6015 will not move it to the beginning;
6016 it will stay where it is in the list.
6021 print 'before:',env['ENV']['INCLUDE']
6022 include_path = '/foo/bar:/foo'
6023 env.PrependENVPath('INCLUDE', include_path)
6024 print 'after:',env['ENV']['INCLUDE']
6027 The above exmaple will print:
6031 after: /foo/bar:/foo:/biz
6034 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6036 .RI env.PrependUnique( key = val ", delete_existing=0, [...])"
6037 Appends the specified keyword arguments
6038 to the beginning of construction variables in the environment.
6039 If the Environment does not have
6040 the specified construction variable,
6041 it is simply added to the environment.
6042 If the construction variable being appended to is a list,
6043 then any value(s) that already exist in the
6044 construction variable will
6046 be added again to the list.
6047 However, if delete_existing is 1,
6048 existing matching values are removed first, so
6049 existing values in the arg list move to the front of the list.
6054 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
6057 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6060 A factory function that
6061 returns a Builder object
6062 to be used to fetch source files
6064 The returned Builder
6065 is intended to be passed to the
6072 env.SourceCode('.', env.RCS())
6077 will fetch source files
6078 from RCS subdirectories automatically,
6080 as demonstrated in the above example
6081 should only be necessary if
6082 you are fetching from
6085 directory as the source files,
6086 or if you need to explicitly specify RCS
6087 for a specific subdirectory.
6089 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6091 .RI env.Replace( key = val ", [...])"
6092 Replaces construction variables in the Environment
6093 with the specified keyword arguments.
6098 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
6101 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6103 .RI Repository( directory )
6105 .RI env.Repository( directory )
6108 is a repository to be searched for files.
6112 and each one adds to the list of
6113 repositories that will be searched.
6117 a repository is a copy of the source tree,
6118 from the top-level directory on down,
6120 both source files and derived files
6121 that can be used to build targets in
6122 the local source tree.
6123 The canonical example would be an
6124 official source tree maintained by an integrator.
6125 If the repository contains derived files,
6126 then the derived files should have been built using
6128 so that the repository contains the necessary
6129 signature information to allow
6131 to figure out when it is appropriate to
6132 use the repository copy of a derived file,
6133 instead of building one locally.
6135 Note that if an up-to-date derived file
6136 already exists in a repository,
6140 make a copy in the local directory tree.
6141 In order to guarantee that a local copy
6147 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6149 .RI Requires( target ", " prerequisite )
6151 .RI env.Requires( target ", " prerequisite )
6152 Specifies an order-only relationship
6153 between the specified target file(s)
6154 and the specified prerequisite file(s).
6155 The prerequisite file(s)
6156 will be (re)built, if necessary,
6159 but the target file(s) do not actually
6160 depend on the prerequisites
6161 and will not be rebuilt simply because
6162 the prerequisite file(s) change.
6167 env.Requires('foo', 'file-that-must-be-built-before-foo')
6170 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6172 .RI Return([ vars "... , " stop= ])
6174 this stops processing the current SConscript
6175 file and returns to the calling SConscript file
6176 the values of the variables named in the
6179 Multiple strings contaning variable names may be passed to
6181 Any strings that contain white space
6185 keyword argument may be set to a false value
6186 to continue processing the rest of the SConscript
6190 This was the default behavior prior to SCons 0.98.
6191 However, the values returned
6192 are still the values of the variables in the named
6201 # Returns without returning a value.
6204 # Returns the value of the 'foo' Python variable.
6207 # Returns the values of the Python variables 'foo' and 'bar'.
6208 Return("foo", "bar")
6210 # Returns the values of Python variables 'val1' and 'val2'.
6214 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6216 .RI Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
6218 .RI env.Scanner( function ", [" argument ", " keys ", " path_function ", " node_class ", " node_factory ", " scan_check ", " recursive ])
6219 Creates a Scanner object for
6222 See the section "Scanner Objects,"
6223 below, for a complete explanation of the arguments and behavior.
6225 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6228 A factory function that
6229 returns a Builder object
6230 to be used to fetch source files
6232 The returned Builder
6233 is intended to be passed to the
6240 env.SourceCode('.', env.SCCS())
6245 will fetch source files
6246 from SCCS subdirectories automatically,
6248 as demonstrated in the above example
6249 should only be necessary if
6250 you are fetching from
6253 directory as the source files,
6254 or if you need to explicitly specify SCCS
6255 for a specific subdirectory.
6257 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6259 .RI SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
6260 '\" .RI SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
6262 .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " duplicate ])
6263 '\" .RI env.SConscript( scripts ", [" exports ", " variant_dir ", " src_dir ", " duplicate ])
6265 .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
6266 '\" .RI SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
6268 .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " duplicate ])
6269 '\" .RI env.SConscript(dirs= subdirs ", [name=" script ", " exports ", " variant_dir ", " src_dir ", " duplicate ])
6273 one or more subsidiary SConscript (configuration) files.
6274 Any variables returned by a called script using
6276 will be returned by the call to
6278 There are two ways to call the
6282 The first way you can call
6284 is to explicitly specify one or more
6286 as the first argument.
6287 A single script may be specified as a string;
6288 multiple scripts must be specified as a list
6289 (either explicitly or as created by
6294 SConscript('SConscript') # run SConscript in the current directory
6295 SConscript('src/SConscript') # run SConscript in the src directory
6296 SConscript(['src/SConscript', 'doc/SConscript'])
6297 config = SConscript('MyConfig.py')
6300 The second way you can call
6302 is to specify a list of (sub)directory names
6309 execute a subsidiary configuration file named
6311 in each of the specified directories.
6312 You may specify a name other than
6314 by supplying an optional
6317 The first three examples below have the same effect
6318 as the first three examples above:
6320 SConscript(dirs='.') # run SConscript in the current directory
6321 SConscript(dirs='src') # run SConscript in the src directory
6322 SConscript(dirs=['src', 'doc'])
6323 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
6328 argument provides a list of variable names or a dictionary of
6329 named values to export to the
6331 These variables are locally exported only to the specified
6333 and do not affect the global pool of variables used by the
6336 '\"If multiple dirs are provided, each script gets a fresh export.
6341 function to import the variables.
6344 foo = SConscript('sub/SConscript', exports='env')
6345 SConscript('dir/SConscript', exports=['env', 'variable'])
6346 SConscript(dirs='subdir', exports='env variable')
6347 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
6352 argument is present, it causes an effect equivalent to the
6354 method described below.
6360 '\" arguments are ignored.)
6361 argument is ignored.)
6366 '\" arguments are interpreted relative to the directory of the calling
6367 argument is interpreted relative to the directory of the calling
6368 .BR SConscript file.
6369 See the description of the
6371 function below for additional details and restrictions.
6374 '\" .IR variant_dir " is present, but"
6375 '\" .IR src_dir " is not,"
6376 .IR variant_dir " is present,"
6377 the source directory is relative to the called
6378 .BR SConscript " file."
6380 SConscript('src/SConscript', variant_dir = 'build')
6384 VariantDir('build', 'src')
6385 SConscript('build/SConscript')
6387 This later paradigm is often used when the sources are
6388 in the same directory as the
6389 .BR SConstruct file:
6391 SConscript('SConscript', variant_dir = 'build')
6395 VariantDir('build', '.')
6396 SConscript('build/SConscript')
6400 '\" .IR variant_dir " and"
6401 '\" .IR src_dir " are both present,"
6402 '\" xxxxx everything is in a state of confusion.
6404 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = '.')
6405 '\" runs src/SConscript in build/src, but
6406 '\" SConscript(dirs = 'lib', variant_dir = 'build', src_dir = 'src')
6407 '\" runs lib/SConscript (in lib!). However,
6408 '\" SConscript(dirs = 'src', variant_dir = 'build', src_dir = 'src')
6409 '\" runs src/SConscript in build. Moreover,
6410 '\" SConscript(dirs = 'src/lib', variant_dir = 'build', src_dir = 'src')
6411 '\" runs src/lib/SConscript in build/lib. Moreover,
6412 '\" SConscript(dirs = 'build/src/lib', variant_dir = 'build', src_dir = 'src')
6413 '\" can't find build/src/lib/SConscript, even though it ought to exist.
6415 '\" is equivalent to
6417 '\" ????????????????
6419 '\" and what about this alternative?
6420 '\"TODO??? SConscript('build/SConscript', src_dir='src')
6422 Here are some composite examples:
6425 # collect the configuration information and use it to build src and doc
6426 shared_info = SConscript('MyConfig.py')
6427 SConscript('src/SConscript', exports='shared_info')
6428 SConscript('doc/SConscript', exports='shared_info')
6432 # build debugging and production versions. SConscript
6433 # can use Dir('.').path to determine variant.
6434 SConscript('SConscript', variant_dir='debug', duplicate=0)
6435 SConscript('SConscript', variant_dir='prod', duplicate=0)
6439 # build debugging and production versions. SConscript
6440 # is passed flags to use.
6441 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
6442 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
6443 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
6444 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
6448 # build common documentation and compile for different architectures
6449 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
6450 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
6451 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
6454 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6456 .RI SConscriptChdir( value )
6458 .RI env.SConscriptChdir( value )
6461 changes its working directory
6462 to the directory in which each
6463 subsidiary SConscript file lives.
6464 This behavior may be disabled
6465 by specifying either:
6469 env.SConscriptChdir(0)
6474 will stay in the top-level directory
6475 while reading all SConscript files.
6476 (This may be necessary when building from repositories,
6477 when all the directories in which SConscript files may be found
6478 don't necessarily exist locally.)
6479 You may enable and disable
6480 this ability by calling
6489 SConscript('foo/SConscript') # will not chdir to foo
6490 env.SConscriptChdir(1)
6491 SConscript('bar/SConscript') # will chdir to bar
6494 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6496 .RI SConsignFile([ file , dbm_module ])
6498 .RI env.SConsignFile([ file , dbm_module ])
6501 to store all file signatures
6502 in the specified database
6509 (The actual file name(s) stored on disk
6510 may have an appropriated suffix appended
6515 is not an absolute path name,
6516 the file is placed in the same directory as the top-level
6526 will store file signatures
6529 file in each directory,
6530 not in one global database file.
6531 (This was the default behavior
6532 prior to SCons 0.96.91 and 0.97.)
6536 argument can be used to specify
6537 which Python database module
6538 The default is to use a custom
6540 module that uses pickled
6541 Python data structures,
6542 and which works on all Python versions from 1.5.2 on.
6547 # Explicitly stores signatures in ".sconsign.dblite"
6548 # in the top-level SConstruct directory (the
6549 # default behavior).
6552 # Stores signatures in the file "etc/scons-signatures"
6553 # relative to the top-level SConstruct directory.
6554 SConsignFile("etc/scons-signatures")
6556 # Stores signatures in the specified absolute file name.
6557 SConsignFile("/home/me/SCons/signatures")
6559 # Stores signatures in a separate .sconsign file
6560 # in each directory.
6564 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6566 .RI env.SetDefault(key = val ", [...])"
6567 Sets construction variables to default values specified with the keyword
6568 arguments if (and only if) the variables are not already set.
6569 The following statements are equivalent:
6572 env.SetDefault(FOO = 'foo')
6574 if not env.has_key('FOO'): env['FOO'] = 'foo'
6577 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6579 .RI SetOption( name ", " value )
6581 .RI env.SetOption( name ", " value )
6582 This function provides a way to set a select subset of the scons command
6583 line options from a SConscript file. The options supported are:
6588 which corresponds to -c, --clean and --remove;
6591 which corresponds to --duplicate;
6594 which corresponds to -h and --help;
6597 which corresponds to --implicit-cache;
6600 which corresponds to --max-drift;
6603 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
6606 which corresponds to -j and --jobs;
6609 which corresponds to --random; and
6612 which corresponds to --stack-size.
6616 See the documentation for the
6617 corresponding command line object for information about each specific
6623 SetOption('max_drift', 1)
6626 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6628 .RI SideEffect( side_effect ", " target )
6630 .RI env.SideEffect( side_effect ", " target )
6633 as a side effect of building
6639 can be a list, a file name, or a node.
6640 A side effect is a target file that is created or updated
6641 as a side effect of building other targets.
6642 For example, a Windows PDB
6643 file is created as a side effect of building the .obj
6644 files for a static library,
6645 and various log files are created updated
6646 as side effects of various TeX commands.
6647 If a target is a side effect of multiple build commands,
6649 will ensure that only one set of commands
6650 is executed at a time.
6651 Consequently, you only need to use this method
6652 for side-effect targets that are built as a result of
6653 multiple build commands.
6655 Because multiple build commands may update
6656 the same side effect file,
6661 automatically removed
6667 (Note, however, that the
6669 might be removed as part of
6670 cleaning the directory in which it lives.)
6671 If you want to make sure the
6673 is cleaned whenever a specific
6676 you must specify this explicitly
6683 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6685 .RI SourceCode( entries ", " builder )
6687 .RI env.SourceCode( entries ", " builder )
6688 Arrange for non-existent source files to
6689 be fetched from a source code management system
6694 may be a Node, string or list of both,
6695 and may represent either individual
6696 source files or directories in which
6697 source files can be found.
6699 For any non-existent source files,
6701 will search up the directory tree
6711 will not use a builder to fetch
6712 source files for the specified
6716 builder has been specified
6717 for a directory higher up the tree.
6721 fetch files from SCCS or RCS subdirectories
6722 without explicit configuration.
6723 This takes some extra processing time
6724 to search for the necessary
6725 source code management files on disk.
6726 You can avoid these extra searches
6727 and speed up your build a little
6728 by disabling these searches as follows:
6731 env.SourceCode('.', None)
6735 Note that if the specified
6737 is one you create by hand,
6738 it must have an associated
6739 construction environment to use
6740 when fetching a source file.
6743 provides a set of canned factory
6744 functions that return appropriate
6745 Builders for various popular
6746 source code management systems.
6747 Canonical examples of invocation include:
6750 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
6751 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
6752 env.SourceCode('/', env.RCS())
6753 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
6754 env.SourceCode('no_source.c', None)
6756 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
6758 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6760 .RI env.subst( input ", [" raw ", " target ", " source ", " conv ])
6761 Performs construction variable interpolation
6762 on the specified string or sequence argument
6766 leading or trailing white space will
6767 be removed from the result.
6768 and all sequences of white space
6769 will be compressed to a single space character.
6774 character sequences will be stripped from the returned string,
6777 argument may be set to
6779 if you want to preserve white space and
6784 argument may be set to
6786 if you want to strip
6787 all characters between
6793 (as is done for signature calculation).
6795 If the input is a sequence
6797 the individual elements of
6798 the sequence will be expanded,
6799 and the results will be returned as a list.
6806 must be set to lists of
6807 target and source nodes, respectively,
6814 to be available for expansion.
6815 This is usually necessary if you are
6818 from within a Python function used
6821 Returned string values or sequence elements
6822 are converted to their string representation by default.
6826 may specify a conversion function
6827 that will be used in place of
6829 For example, if you want Python objects
6830 (including SCons Nodes)
6831 to be returned as Python objects,
6832 you can use the Python
6834 idiom to pass in an unnamed function
6835 that simply returns its unconverted argument.
6840 print env.subst("The C compiler is: $CC")
6842 def compile(target, source, env):
6843 sourceDir = env.subst("${SOURCE.srcdir}",
6847 source_nodes = env.subst('$EXPAND_TO_NODELIST',
6851 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6853 '\".RI Subversion( repository ", " module )
6854 '\"A factory function that
6855 '\"returns a Builder object
6856 '\"to be used to fetch source files
6857 '\"from the specified Subversion
6859 '\"The returned Builder
6860 '\"is intended to be passed to the
6864 '\"The optional specified
6866 '\"will be added to the beginning
6867 '\"of all repository path names;
6868 '\"this can be used, in essence,
6869 '\"to strip initial directory names
6870 '\"from the repository path names,
6871 '\"so that you only have to
6872 '\"replicate part of the repository
6873 '\"directory hierarchy in your
6874 '\"local build directory.
6879 '\"# Will fetch foo/bar/src.c
6880 '\"# from /usr/local/Subversion/foo/bar/src.c.
6881 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
6883 '\"# Will fetch bar/src.c
6884 '\"# from /usr/local/Subversion/foo/bar/src.c.
6885 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
6887 '\"# Will fetch src.c
6888 '\"# from /usr/local/Subversion/foo/bar/src.c.
6889 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
6892 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6894 .RI SourceSignatures( type )
6896 .RI env.SourceSignatures( type )
6897 Note: Although it is not yet officially deprecated,
6898 use of this function is discouraged.
6901 function for a more flexible and straightforward way
6902 to configure SCons' decision-making.
6905 .BR SourceSignatures ()
6908 how to decide if a source file
6909 (a file that is not built from any other files)
6910 has changed since the last time it
6911 was used to build a particular target file.
6917 If the environment method is used,
6918 the specified type of source signature
6919 is only used when deciding whether targets
6920 built with that environment are up-to-date or must be rebuilt.
6921 If the global function is used,
6922 the specified type of source signature becomes the default
6923 used for all decisions
6924 about whether targets are up-to-date.
6929 decides that a source file has changed
6930 if the MD5 checksum of its contents has changed since
6931 the last time it was used to rebuild a particular target file.
6936 decides that a source file has changed
6937 if its timestamp (modification time) has changed since
6938 the last time it was used to rebuild a particular target file.
6939 (Note that although this is similar to the behavior of Make,
6940 by default it will also rebuild if the dependency is
6942 than the last time it was used to rebuild the target file.)
6944 There is no different between the two behaviors
6950 signatures take longer to compute,
6951 but are more accurate than
6954 The default value is
6957 Note that the default
6958 .BR TargetSignatures ()
6961 .BR SourceSignatures ()
6962 setting for any target files that are used
6963 to build other target files.
6964 Consequently, changing the value of
6965 .BR SourceSignatures ()
6967 affect the up-to-date decision for all files in the build
6968 (or all files built with a specific construction environment
6970 .BR env.SourceSignatures ()
6973 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
6977 .RI env.Split( arg )
6978 Returns a list of file names or other objects.
6980 it will be split on strings of white-space characters
6982 making it easier to write long lists of file names.
6983 If arg is already a list,
6984 the list will be returned untouched.
6985 If arg is any other type of object,
6986 it will be returned as a list
6987 containing just the object.
6992 files = Split("f1.c f2.c f3.c")
6993 files = env.Split("f4.c f5.c f6.c")
7001 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7003 .RI Tag( node ", " tags )
7004 Annotates file or directory Nodes with
7005 information about how the
7007 Builder should package those files or directories.
7008 All tags are optional.
7013 # makes sure the built library will be installed with 0644 file
7015 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
7017 # marks file2.txt to be a documentation file
7018 Tag( 'file2.txt', DOC )
7021 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7023 .RI TargetSignatures( type )
7025 .RI env.TargetSignatures( type )
7026 Note: Although it is not yet officially deprecated,
7027 use of this function is discouraged.
7030 function for a more flexible and straightforward way
7031 to configure SCons' decision-making.
7034 .BR TargetSignatures ()
7037 how to decide if a target file
7040 built from any other files)
7041 has changed since the last time it
7042 was used to build some other target file.
7052 If the environment method is used,
7053 the specified type of target signature is only used
7054 for targets built with that environment.
7055 If the global function is used,
7056 the specified type of signature becomes the default
7057 used for all target files that
7058 don't have an explicit target signature type
7059 specified for their environments.
7066 decides that a target file has changed
7067 if the MD5 checksum of its contents has changed since
7068 the last time it was used to rebuild some other target file.
7072 MD5 sum the contents
7073 of target files after they're built,
7074 and may decide that it does not need to rebuild
7075 "downstream" target files if a file was
7076 rebuilt with exactly the same contents as the last time.
7081 decides that a target file has changed
7082 if its timestamp (modification time) has changed since
7083 the last time it was used to rebuild some other target file.
7084 (Note that although this is similar to the behavior of Make,
7085 by default it will also rebuild if the dependency is
7087 than the last time it was used to rebuild the target file.)
7092 decides that a target file has changed
7093 as specified by the corresponding
7094 .BR SourceSignatures ()
7101 will treat all input files to a target the same way,
7102 regardless of whether they are source files
7103 or have been built from other files.
7108 decides that a target file has changed
7109 if it has been rebuilt in this invocation
7110 or if its content or timestamp have changed
7111 as specified by the corresponding
7112 .BR SourceSignatures ()
7114 This "propagates" the status of a rebuilt file
7115 so that other "downstream" target files
7116 will always be rebuilt,
7117 even if the contents or the timestamp
7121 signatures are fastest because
7125 signatures take longer to compute,
7126 but are more accurate than
7129 and can prevent unnecessary "downstream" rebuilds
7130 when a target file is rebuilt to the exact same contents
7131 as the previous build.
7134 setting provides the most consistent behavior
7135 when other target files may be rebuilt from
7136 both source and target input files.
7137 The default value is
7140 Because the default setting is
7143 .BR SourceSignatures ()
7144 is generally preferable to
7145 .BR TargetSignatures () ,
7146 so that the up-to-date decision
7147 will be consistent for all files
7148 (or all files built with a specific construction environment).
7150 .BR TargetSignatures ()
7151 provides specific control for how built target files
7152 affect their "downstream" dependencies.
7154 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7156 .RI Tool( string [, toolpath ", " **kw ])
7157 Returns a callable object
7158 that can be used to initialize
7159 a construction environment using the
7160 tools keyword of the Environment() method.
7161 The object may be called with a construction
7162 environment as an argument,
7163 in which case the object will
7164 add the necessary variables
7165 to the construction environment
7166 and the name of the tool will be added to the
7168 construction variable.
7170 Additional keyword arguments are passed to the tool's
7177 env = Environment(tools = [ Tool('msvc') ])
7181 t(env) # adds 'msvc' to the TOOLS variable
7182 u = Tool('opengl', toolpath = ['tools'])
7183 u(env) # adds 'opengl' to the TOOLS variable
7186 .RI env.Tool( string [, toolpath ", " **kw ])
7187 Applies the callable object for the specified tool
7189 to the environment through which the method was called.
7191 Additional keyword arguments are passed to the tool's
7197 env.Tool('opengl', toolpath = ['build/tools'])
7200 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7202 .RI Value( value ", [" built_value ])
7204 .RI env.Value( value ", [" built_value ])
7205 Returns a Node object representing the specified Python value. Value
7206 Nodes can be used as dependencies of targets. If the result of
7209 changes between SCons runs, any targets depending on
7212 (This is true even when using timestamps to decide if
7213 files are up-to-date.)
7214 When using timestamp source signatures, Value Nodes'
7215 timestamps are equal to the system time when the Node is created.
7217 The returned Value Node object has a
7219 method that can be used to "build" a Value Node
7220 by setting a new value.
7223 argument can be specified
7224 when the Value Node is created
7225 to indicate the Node should already be considered
7227 There is a corresponding
7229 method that will return the built value of the Node.
7236 def create(target, source, env):
7237 # A function that will write a 'prefix=$SOURCE'
7238 # string into the file name specified as the
7240 f = open(str(target[0]), 'wb')
7241 f.write('prefix=' + source[0].get_contents())
7243 # Fetch the prefix= argument, if any, from the command
7244 # line, and use /usr/local as the default.
7245 prefix = ARGUMENTS.get('prefix', '/usr/local')
7247 # Attach a .Config() builder for the above function action
7248 # to the construction environment.
7249 env['BUILDERS']['Config'] = Builder(action = create)
7250 env.Config(target = 'package-config', source = Value(prefix))
7252 def build_value(target, source, env):
7253 # A function that "builds" a Python Value by updating
7254 # the the Python value with the contents of the file
7255 # specified as the source of the Builder call ($SOURCE).
7256 target[0].write(source[0].get_contents())
7258 output = env.Value('before')
7259 input = env.Value('after')
7261 # Attach a .UpdateValue() builder for the above function
7262 # action to the construction environment.
7263 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
7264 env.UpdateValue(target = Value(output), source = Value(input))
7267 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7269 .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ])
7271 .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ])
7274 function to create a copy of your sources in another location:
7277 is not found but exists under
7279 the file or directory is copied to
7281 Target files can be built in a different directory
7282 than the original sources by simply refering to the sources (and targets)
7283 within the variant tree.
7286 can be called multiple times with the same
7288 to set up multiple builds with different options
7292 location must be in or underneath the SConstruct file's directory, and
7294 may not be underneath
7296 '\"TODO: Can the above restrictions be clarified or relaxed?
7297 '\"TODO: The latter restriction is clearly not completely right;
7298 '\"TODO: src_dir = '.' works fine with a build dir under it.
7300 The default behavior is for
7302 to physically duplicate the source files in the variant tree.
7303 Thus, a build performed in the variant tree is guaranteed to be identical
7304 to a build performed in the source tree even if
7305 intermediate source files are generated during the build,
7306 or preprocessors or other scanners search for included files
7307 relative to the source file,
7308 or individual compilers or other invoked tools are hard-coded
7309 to put derived files in the same directory as source files.
7311 If possible on the platform,
7312 the duplication is performed by linking rather than copying;
7315 command-line option.
7316 Moreover, only the files needed for the build are duplicated;
7317 files and directories that are not used are not present in
7320 Duplicating the source tree may be disabled by setting the
7322 argument to 0 (zero).
7325 to invoke Builders using the path names of source files in
7327 and the path names of derived files within
7329 This is always more efficient than
7331 and is usually safe for most builds
7332 (but see above for cases that may cause problems).
7336 works most naturally with a subsidiary SConscript file.
7337 However, you would then call the subsidiary SConscript file
7338 not in the source directory, but in the
7340 regardless of the value of
7342 This is how you tell
7344 which variant of a source tree to build:
7347 # run src/SConscript in two variant directories
7348 VariantDir('build/variant1', 'src')
7349 SConscript('build/variant1/SConscript')
7350 VariantDir('build/variant2', 'src')
7351 SConscript('build/variant2/SConscript')
7357 function, described above,
7358 for another way to specify a variant directory
7359 in conjunction with calling a subsidiary SConscript file.
7364 # use names in the build directory, not the source directory
7365 VariantDir('build', 'src', duplicate=0)
7366 Program('build/prog', 'build/source.c')
7370 # this builds both the source and docs in a separate subtree
7371 VariantDir('build', '.', duplicate=0)
7372 SConscript(dirs=['build/src','build/doc'])
7376 # same as previous example, but only uses SConscript
7377 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
7378 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
7381 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7383 .RI WhereIs( program ", [" path ", " pathext ", " reject ])
7385 .RI env.WhereIs( program ", [" path ", " pathext ", " reject ])
7387 Searches for the specified executable
7389 returning the full path name to the program
7391 and returning None if not.
7392 Searches the specified
7394 the value of the calling environment's PATH
7395 (env['ENV']['PATH']),
7396 or the user's current external PATH
7397 (os.environ['PATH'])
7399 On Windows systems, searches for executable
7400 programs with any of the file extensions
7401 listed in the specified
7403 the calling environment's PATHEXT
7404 (env['ENV']['PATHEXT'])
7405 or the user's current PATHEXT
7406 (os.environ['PATHEXT'])
7414 .SS SConscript Variables
7415 In addition to the global functions and methods,
7417 supports a number of Python variables
7418 that can be used in SConscript files
7419 to affect how you want the build to be performed.
7420 These variables may be accessed from custom Python modules that you
7421 import into an SConscript file by adding the following
7422 to the Python module:
7425 from SCons.Script import *
7428 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7433 arguments specified on the command line.
7434 Each element in the list is a tuple
7436 .RI ( keyword , value )
7442 elements of the tuple
7444 subscripting for element
7448 of the tuple, respectively.
7453 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
7454 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
7455 third_tuple = ARGLIST[2]
7456 print "third keyword, value =", third_tuple[0], third_tuple[1]
7457 for key, value in ARGLIST:
7458 # process key and value
7461 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7464 A dictionary of all the
7466 arguments specified on the command line.
7467 The dictionary is not in order,
7468 and if a given keyword has
7469 more than one value assigned to it
7470 on the command line,
7471 the last (right-most) value is
7479 if ARGUMENTS.get('debug', 0):
7480 env = Environment(CCFLAGS = '-g')
7485 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7488 A list of the targets which
7490 will actually try to build,
7491 regardless of whether they were specified on
7492 the command line or via the
7495 The elements of this list may be strings
7497 nodes, so you should run the list through the Python
7499 function to make sure any Node path names
7500 are converted to strings.
7502 Because this list may be taken from the
7503 list of targets specified using the
7506 the contents of the list may change
7507 on each successive call to
7512 for additional information.
7517 if 'foo' in BUILD_TARGETS:
7518 print "Don't forget to test the `foo' program!"
7519 if 'special/program' in BUILD_TARGETS:
7520 SConscript('special')
7525 list only contains targets expected listed
7526 on the command line or via calls to the
7531 contain all dependent targets that will be built as
7532 a result of making the sure the explicitly-specified
7533 targets are up to date.
7535 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7537 COMMAND_LINE_TARGETS
7538 A list of the targets explicitly specified on
7540 If there are no targets specified on the command line,
7542 This can be used, for example,
7543 to take specific actions only
7544 when a certain target or targets
7545 is explicitly being built.
7550 if 'foo' in COMMAND_LINE_TARGETS:
7551 print "Don't forget to test the `foo' program!"
7552 if 'special/program' in COMMAND_LINE_TARGETS:
7553 SConscript('special')
7556 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7559 A list of the target
7561 that have been specified using the
7564 The elements of the list are nodes,
7565 so you need to run them through the Python
7567 function to get at the path name for each Node.
7572 print str(DEFAULT_TARGETS[0])
7573 if 'foo' in map(str, DEFAULT_TARGETS):
7574 print "Don't forget to test the `foo' program!"
7579 list change on on each successive call to the
7584 print map(str, DEFAULT_TARGETS) # originally []
7586 print map(str, DEFAULT_TARGETS) # now a node ['foo']
7588 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
7590 print map(str, DEFAULT_TARGETS) # back to []
7593 Consequently, be sure to use
7595 only after you've made all of your
7598 or else simply be careful of the order
7599 of these statements in your SConscript files
7600 so that you don't look for a specific
7601 default target before it's actually been added to the list.
7603 .SS Construction Variables
7604 .\" XXX From Gary Ruben, 23 April 2002:
7605 .\" I think it would be good to have an example with each construction
7606 .\" variable description in the documentation.
7608 .\" CC The C compiler
7609 .\" Example: env["CC"] = "c68x"
7610 .\" Default: env["CC"] = "cc"
7612 .\" CCCOM The command line ...
7614 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
7615 .\" env["CC"] = "c68x"
7616 .\" env["CFLAGS"] = "-ps -qq -mr"
7617 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
7619 .\" (I dunno what this is ;-)
7620 A construction environment has an associated dictionary of
7621 .I construction variables
7622 that are used by built-in or user-supplied build rules.
7623 Construction variables must follow the same rules for
7625 the initial character must be an underscore or letter,
7626 followed by any number of underscores, letters, or digits.
7628 A number of useful construction variables are automatically defined by
7629 scons for each supported platform, and additional construction variables
7630 can be defined by the user. The following is a list of the automatically
7631 defined construction variables:
7633 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7634 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
7636 '\" The descriptions below of the various SCons construction variables
7637 '\" are generated from the .xml files that live next to the various
7638 '\" Python modules in the build enginer library. If you're reading
7639 '\" this [gnt]roff file with an eye towards patching this man page,
7640 '\" you can still submit a diff against this text, but it will have to
7641 '\" be translated to a diff against the underlying .xml file before the
7642 '\" patch is actually accepted. If you do that yourself, it will make
7643 '\" it easier to integrate the patch.
7645 '\" BEGIN GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
7646 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
7649 The static library archiver.
7652 Specifies the system architecture for which
7653 the package is being built.
7654 The default is the system architecture
7655 of the machine on which SCons is running.
7656 This is used to fill in the
7660 and as part of the name of a generated RPM file.
7663 The command line used to generate a static library from object files.
7666 The string displayed when an object file
7667 is generated from an assembly-language source file.
7668 If this is not set, then $ARCOM (the command line) is displayed.
7671 env = Environment(ARCOMSTR = "Archiving $TARGET")
7675 General options passed to the static library archiver.
7681 The command line used to generate an object file
7682 from an assembly-language source file.
7685 The string displayed when an object file
7686 is generated from an assembly-language source file.
7687 If this is not set, then $ASCOM (the command line) is displayed.
7690 env = Environment(ASCOMSTR = "Assembling $TARGET")
7694 General options passed to the assembler.
7697 The command line used to assemble an assembly-language
7698 source file into an object file
7699 after first running the file through the C preprocessor.
7700 Any options specified
7701 in the $ASFLAGS and $CPPFLAGS construction variables
7702 are included on this command line.
7705 The string displayed when an object file
7706 is generated from an assembly-language source file
7707 after first running the file through the C preprocessor.
7708 If this is not set, then $ASPPCOM (the command line) is displayed.
7711 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
7715 General options when an assembling an assembly-language
7716 source file into an object file
7717 after first running the file through the C preprocessor.
7718 The default is to use the value of $ASFLAGS.
7721 The bibliography generator for the TeX formatter and typesetter and the
7722 LaTeX structured formatter and typesetter.
7725 The command line used to call the bibliography generator for the
7726 TeX formatter and typesetter and the LaTeX structured formatter and
7730 The string displayed when generating a bibliography
7732 If this is not set, then $BIBTEXCOM (the command line) is displayed.
7735 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
7739 General options passed to the bibliography generator for the TeX formatter
7740 and typesetter and the LaTeX structured formatter and typesetter.
7743 The BitKeeper executable.
7746 The command line for
7747 fetching source files using BitKeeper.
7750 The string displayed when fetching
7751 a source file using BitKeeper.
7752 If this is not set, then $BITKEEPERCOM
7753 (the command line) is displayed.
7756 The command ($BITKEEPER) and subcommand
7757 for fetching source files using BitKeeper.
7759 .IP BITKEEPERGETFLAGS
7760 Options that are passed to the BitKeeper
7765 A dictionary mapping the names of the builders
7766 available through this environment
7767 to underlying Builder objects.
7769 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
7770 are available by default.
7771 If you initialize this variable when an
7772 Environment is created:
7775 env = Environment(BUILDERS = {'NewBuilder' : foo})
7778 the default Builders will no longer be available.
7779 To use a new Builder object in addition to the default Builders,
7780 add your new Builder object like this:
7784 env.Append(BUILDERS = {'NewBuilder' : foo})
7791 env['BUILDERS]['NewBuilder'] = foo
7798 The command line used to compile a C source file to a (static) object
7799 file. Any options specified in the $CFLAGS, $CCFLAGS and
7800 $CPPFLAGS construction variables are included on this command
7804 The string displayed when a C source file
7805 is compiled to a (static) object file.
7806 If this is not set, then $CCCOM (the command line) is displayed.
7809 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
7813 General options that are passed to the C and C++ compilers.
7816 Options added to the compiler command line
7817 to support building with precompiled headers.
7818 The default value expands expands to the appropriate
7819 Microsoft Visual C++ command-line options
7820 when the $PCH construction variable is set.
7823 Options added to the compiler command line
7824 to support storing debugging information in a
7825 Microsoft Visual C++ PDB file.
7826 The default value expands expands to appropriate
7827 Microsoft Visual C++ command-line options
7828 when the $PDB construction variable is set.
7830 The Visual C++ compiler option that SCons uses by default
7831 to generate PDB information is \fB/Z7\fP.
7832 This works correctly with parallel (\fB\-j\fP) builds
7833 because it embeds the debug information in the intermediate object files,
7834 as opposed to sharing a single PDB file between multiple object files.
7835 This is also the only way to get debug information
7836 embedded into a static library.
7837 Using the \fB/Zi\fP instead may yield improved
7838 link-time performance,
7839 although parallel builds will no longer work.
7841 You can generate PDB files with the \fB/Zi\fP
7842 switch by overriding the default $CCPDBFLAGS variable as follows:
7845 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
7848 An alternative would be to use the \fB/Zi\fP
7849 to put the debugging information in a separate \fB.pdb\fP
7850 file for each object file by overriding
7851 the $CCPDBFLAGS variable as follows:
7854 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
7858 The version number of the C compiler.
7859 This may or may not be set,
7860 depending on the specific C compiler being used.
7863 The suffix for C source files.
7864 This is used by the internal CFile builder
7865 when generating C files from Lex (.l) or YACC (.y) input files.
7866 The default suffix, of course, is
7869 On case-insensitive systems (like Windows),
7876 General options that are passed to the C compiler (C only; not C++).
7879 A hook for modifying the file that controls the packaging build
7880 (the \fB.spec\fP for RPM,
7881 the \fBcontrol\fP for Ipkg,
7882 the \fB.wxs\fP for MSI).
7883 If set, the function will be called
7884 after the SCons template for the file has been written.
7888 The name of a file containing the change log text
7889 to be included in the package.
7890 This is included as the
7896 A function used to produce variables like $_CPPINCFLAGS. It takes
7898 arguments: a prefix to concatenate onto each element, a list of
7899 elements, a suffix to concatenate onto each element, an environment
7900 for variable interpolation, and an optional function that will be
7901 called to transform the list before concatenation.
7904 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
7908 The name of the directory in which
7909 Configure context test files are written.
7912 in the top-level directory
7918 The name of the Configure context log file.
7921 in the top-level directory
7927 An automatically-generated construction variable
7928 containing the C preprocessor command-line options
7930 The value of $_CPPDEFFLAGS is created
7931 by appending $CPPDEFPREFIX and $CPPDEFSUFFIX
7932 to the beginning and end
7933 of each definition in $CPPDEFINES.
7936 A platform independent specification of C preprocessor definitions.
7937 The definitions will be added to command lines
7938 through the automatically-generated
7939 $_CPPDEFFLAGS construction variable (see above),
7940 which is constructed according to
7941 the type of value of $CPPDEFINES:
7943 If $CPPDEFINES is a string,
7945 $CPPDEFPREFIX and $CPPDEFSUFFIX
7946 construction variables
7947 will be added to the beginning and end.
7950 # Will add -Dxyz to POSIX compiler command lines,
7951 # and /Dxyz to Microsoft Visual C++ command lines.
7952 env = Environment(CPPDEFINES='xyz')
7955 If $CPPDEFINES is a list,
7957 $CPPDEFPREFIX and $CPPDEFSUFFIX
7958 construction variables
7959 will be appended to the beginning and end
7960 of each element in the list.
7961 If any element is a list or tuple,
7962 then the first item is the name being
7963 defined and the second item is its value:
7966 # Will add -DB=2 -DA to POSIX compiler command lines,
7967 # and /DB=2 /DA to Microsoft Visual C++ command lines.
7968 env = Environment(CPPDEFINES=[('B', 2), 'A'])
7971 If $CPPDEFINES is a dictionary,
7973 $CPPDEFPREFIX and $CPPDEFSUFFIX
7974 construction variables
7975 will be appended to the beginning and end
7976 of each item from the dictionary.
7977 The key of each dictionary item
7978 is a name being defined
7979 to the dictionary item's corresponding value;
7982 then the name is defined without an explicit value.
7983 Note that the resulting flags are sorted by keyword
7984 to ensure that the order of the options on the
7985 command line is consistent each time
7990 # Will add -DA -DB=2 to POSIX compiler command lines,
7991 # and /DA /DB=2 to Microsoft Visual C++ command lines.
7992 env = Environment(CPPDEFINES={'B':2, 'A':None})
7996 The prefix used to specify preprocessor definitions
7997 on the C compiler command line.
7998 This will be appended to the beginning of each definition
7999 in the $CPPDEFINES construction variable
8000 when the $_CPPDEFFLAGS variable is automatically generated.
8003 The suffix used to specify preprocessor definitions
8004 on the C compiler command line.
8005 This will be appended to the end of each definition
8006 in the $CPPDEFINES construction variable
8007 when the $_CPPDEFFLAGS variable is automatically generated.
8010 User-specified C preprocessor options.
8011 These will be included in any command that uses the C preprocessor,
8012 including not just compilation of C and C++ source files
8016 $SHCXXCOM command lines,
8017 but also the $FORTRANPPCOM,
8020 $SHF77PPCOM command lines
8021 used to compile a Fortran source file,
8022 and the $ASPPCOM command line
8023 used to assemble an assembly language source file,
8024 after first running each file through the C preprocessor.
8025 Note that this variable does
8029 (or similar) include search path options
8030 that scons generates automatically from $CPPPATH.
8031 See $_CPPINCFLAGS, below,
8032 for the variable that expands to those options.
8035 An automatically-generated construction variable
8036 containing the C preprocessor command-line options
8037 for specifying directories to be searched for include files.
8038 The value of $_CPPINCFLAGS is created
8039 by appending $INCPREFIX and $INCSUFFIX
8040 to the beginning and end
8041 of each directory in $CPPPATH.
8044 The list of directories that the C preprocessor will search for include
8045 directories. The C/C++ implicit dependency scanner will search these
8046 directories for include files. Don't explicitly put include directory
8047 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
8048 and the directories will not be searched by the dependency scanner. Note:
8049 directory names in CPPPATH will be looked-up relative to the SConscript
8050 directory when they are used in a command. To force
8052 to look-up a directory relative to the root of the source tree use #:
8055 env = Environment(CPPPATH='#/include')
8058 The directory look-up can also be forced using the
8063 include = Dir('include')
8064 env = Environment(CPPPATH=include)
8067 The directory list will be added to command lines
8068 through the automatically-generated
8070 construction variable,
8071 which is constructed by
8072 appending the values of the
8073 $INCPREFIX and $INCSUFFIX
8074 construction variables
8075 to the beginning and end
8076 of each directory in $CPPPATH.
8077 Any command lines you define that need
8078 the CPPPATH directory list should
8079 include $_CPPINCFLAGS:
8082 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
8086 The list of suffixes of files that will be scanned
8087 for C preprocessor implicit dependencies
8089 The default list is:
8092 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
8093 ".h", ".H", ".hxx", ".hpp", ".hh",
8094 ".F", ".fpp", ".FPP",
8096 ".S", ".spp", ".SPP"]
8103 Options that are passed to the CVS checkout subcommand.
8106 The command line used to
8107 fetch source files from a CVS repository.
8110 The string displayed when fetching
8111 a source file from a CVS repository.
8112 If this is not set, then $CVSCOM
8113 (the command line) is displayed.
8116 General options that are passed to CVS.
8117 By default, this is set to
8118 .B \-d $CVSREPOSITORY
8119 to specify from where the files must be fetched.
8122 The path to the CVS repository.
8123 This is referenced in the default
8130 The command line used to compile a C++ source file to an object file.
8131 Any options specified in the $CXXFLAGS and
8132 $CPPFLAGS construction variables
8133 are included on this command line.
8136 The string displayed when a C++ source file
8137 is compiled to a (static) object file.
8138 If this is not set, then $CXXCOM (the command line) is displayed.
8141 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
8145 The suffix for C++ source files.
8146 This is used by the internal CXXFile builder
8147 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
8148 The default suffix is
8150 SCons also treats files with the suffixes
8159 suffixes as Objective C++ files.
8160 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
8167 General options that are passed to the C++ compiler.
8168 By default, this includes the value of $CCFLAGS,
8169 so that setting $CCFLAGS affects both C and C++ compilation.
8170 If you want to add C++-specific flags,
8171 you must set or override the value of $CXXFLAGS.
8174 The version number of the C++ compiler.
8175 This may or may not be set,
8176 depending on the specific C++ compiler being used.
8179 A long description of the project being packaged.
8180 This is included in the relevant section
8181 of the file that controls the packaging build.
8183 .IP DESCRIPTION_lang
8184 A language-specific long description for
8185 the specified \fIlang\fP.
8186 This is used to populate a
8192 A function that converts a string
8193 into a Dir instance relative to the target being built.
8196 A function that converts a list of strings
8197 into a list of Dir instances relative to the target being built.
8200 The list of suffixes of files that will be scanned
8201 for imported D package files.
8202 The default list is:
8209 The TeX DVI file to PDF file converter.
8212 The command line used to convert TeX DVI files into a PDF file.
8215 The string displayed when a TeX DVI file
8216 is converted into a PDF file.
8217 If this is not set, then $DVIPDFCOM (the command line) is displayed.
8220 General options passed to the TeX DVI file to PDF file converter.
8223 The TeX DVI file to PostScript converter.
8226 General options passed to the TeX DVI file to PostScript converter.
8229 A dictionary of environment variables
8230 to use when invoking commands. When
8231 $ENV is used in a command all list
8232 values will be joined using the path separator and any other non-string
8233 values will simply be coerced to a string.
8234 Note that, by default,
8238 propagate the environment in force when you
8241 to the commands used to build target files.
8242 This is so that builds will be guaranteed
8243 repeatable regardless of the environment
8244 variables set at the time
8248 If you want to propagate your
8249 environment variables
8250 to the commands executed
8251 to build target files,
8252 you must do so explicitly:
8256 env = Environment(ENV = os.environ)
8259 Note that you can choose only to propagate
8260 certain environment variables.
8264 environment variable,
8267 uses the same utilities
8268 as the invoking shell (or other process):
8272 env = Environment(ENV = {'PATH' : os.environ['PATH']})
8276 A function that will be called to escape shell special characters in
8277 command lines. The function should take one argument: the command line
8278 string to escape; and should return the escaped command line.
8281 The Fortran 77 compiler.
8282 You should normally set the $FORTRAN variable,
8283 which specifies the default Fortran compiler
8284 for all Fortran versions.
8285 You only need to set $F77 if you need to use a specific compiler
8286 or compiler version for Fortran 77 files.
8289 The command line used to compile a Fortran 77 source file to an object file.
8290 You only need to set $F77COM if you need to use a specific
8291 command line for Fortran 77 files.
8292 You should normally set the $FORTRANCOM variable,
8293 which specifies the default command line
8294 for all Fortran versions.
8297 The string displayed when a Fortran 77 source file
8298 is compiled to an object file.
8299 If this is not set, then $F77COM or $FORTRANCOM
8300 (the command line) is displayed.
8303 The list of file extensions for which the F77 dialect will be used. By
8304 default, this is ['.f77']
8307 General user-specified options that are passed to the Fortran 77 compiler.
8308 Note that this variable does
8312 (or similar) include search path options
8313 that scons generates automatically from $F77PATH.
8317 for the variable that expands to those options.
8318 You only need to set $F77FLAGS if you need to define specific
8319 user options for Fortran 77 files.
8320 You should normally set the $FORTRANFLAGS variable,
8321 which specifies the user-specified options
8322 passed to the default Fortran compiler
8323 for all Fortran versions.
8326 An automatically-generated construction variable
8327 containing the Fortran 77 compiler command-line options
8328 for specifying directories to be searched for include files.
8329 The value of $_F77INCFLAGS is created
8330 by appending $INCPREFIX and $INCSUFFIX
8331 to the beginning and end
8332 of each directory in $F77PATH.
8335 The list of directories that the Fortran 77 compiler will search for include
8336 directories. The implicit dependency scanner will search these
8337 directories for include files. Don't explicitly put include directory
8338 arguments in $F77FLAGS because the result will be non-portable
8339 and the directories will not be searched by the dependency scanner. Note:
8340 directory names in $F77PATH will be looked-up relative to the SConscript
8341 directory when they are used in a command. To force
8343 to look-up a directory relative to the root of the source tree use #:
8344 You only need to set $F77PATH if you need to define a specific
8345 include path for Fortran 77 files.
8346 You should normally set the $FORTRANPATH variable,
8347 which specifies the include path
8348 for the default Fortran compiler
8349 for all Fortran versions.
8352 env = Environment(F77PATH='#/include')
8355 The directory look-up can also be forced using the
8360 include = Dir('include')
8361 env = Environment(F77PATH=include)
8364 The directory list will be added to command lines
8365 through the automatically-generated
8367 construction variable,
8368 which is constructed by
8369 appending the values of the
8370 $INCPREFIX and $INCSUFFIX
8371 construction variables
8372 to the beginning and end
8373 of each directory in $F77PATH.
8374 Any command lines you define that need
8375 the F77PATH directory list should
8376 include $_F77INCFLAGS:
8379 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
8383 The command line used to compile a Fortran 77 source file to an object file
8384 after first running the file through the C preprocessor.
8385 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
8386 are included on this command line.
8387 You only need to set $F77PPCOM if you need to use a specific
8388 C-preprocessor command line for Fortran 77 files.
8389 You should normally set the $FORTRANPPCOM variable,
8390 which specifies the default C-preprocessor command line
8391 for all Fortran versions.
8394 The string displayed when a Fortran 77 source file
8395 is compiled to an object file
8396 after first running the file through the C preprocessor.
8397 If this is not set, then $F77PPCOM or $FORTRANPPCOM
8398 (the command line) is displayed.
8400 .IP F77PPFILESUFFIXES
8401 The list of file extensions for which the compilation + preprocessor pass for
8402 F77 dialect will be used. By default, this is empty
8405 The Fortran 90 compiler.
8406 You should normally set the $FORTRAN variable,
8407 which specifies the default Fortran compiler
8408 for all Fortran versions.
8409 You only need to set $F90 if you need to use a specific compiler
8410 or compiler version for Fortran 90 files.
8413 The command line used to compile a Fortran 90 source file to an object file.
8414 You only need to set $F90COM if you need to use a specific
8415 command line for Fortran 90 files.
8416 You should normally set the $FORTRANCOM variable,
8417 which specifies the default command line
8418 for all Fortran versions.
8421 The string displayed when a Fortran 90 source file
8422 is compiled to an object file.
8423 If this is not set, then $F90COM or $FORTRANCOM
8424 (the command line) is displayed.
8427 The list of file extensions for which the F90 dialect will be used. By
8428 default, this is ['.f90']
8431 General user-specified options that are passed to the Fortran 90 compiler.
8432 Note that this variable does
8436 (or similar) include search path options
8437 that scons generates automatically from $F90PATH.
8441 for the variable that expands to those options.
8442 You only need to set $F90FLAGS if you need to define specific
8443 user options for Fortran 90 files.
8444 You should normally set the $FORTRANFLAGS variable,
8445 which specifies the user-specified options
8446 passed to the default Fortran compiler
8447 for all Fortran versions.
8450 An automatically-generated construction variable
8451 containing the Fortran 90 compiler command-line options
8452 for specifying directories to be searched for include files.
8453 The value of $_F90INCFLAGS is created
8454 by appending $INCPREFIX and $INCSUFFIX
8455 to the beginning and end
8456 of each directory in $F90PATH.
8459 The list of directories that the Fortran 90 compiler will search for include
8460 directories. The implicit dependency scanner will search these
8461 directories for include files. Don't explicitly put include directory
8462 arguments in $F90FLAGS because the result will be non-portable
8463 and the directories will not be searched by the dependency scanner. Note:
8464 directory names in $F90PATH will be looked-up relative to the SConscript
8465 directory when they are used in a command. To force
8467 to look-up a directory relative to the root of the source tree use #:
8468 You only need to set $F90PATH if you need to define a specific
8469 include path for Fortran 90 files.
8470 You should normally set the $FORTRANPATH variable,
8471 which specifies the include path
8472 for the default Fortran compiler
8473 for all Fortran versions.
8476 env = Environment(F90PATH='#/include')
8479 The directory look-up can also be forced using the
8484 include = Dir('include')
8485 env = Environment(F90PATH=include)
8488 The directory list will be added to command lines
8489 through the automatically-generated
8491 construction variable,
8492 which is constructed by
8493 appending the values of the
8494 $INCPREFIX and $INCSUFFIX
8495 construction variables
8496 to the beginning and end
8497 of each directory in $F90PATH.
8498 Any command lines you define that need
8499 the F90PATH directory list should
8500 include $_F90INCFLAGS:
8503 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
8507 The command line used to compile a Fortran 90 source file to an object file
8508 after first running the file through the C preprocessor.
8509 Any options specified in the $F90FLAGS and $CPPFLAGS construction variables
8510 are included on this command line.
8511 You only need to set $F90PPCOM if you need to use a specific
8512 C-preprocessor command line for Fortran 90 files.
8513 You should normally set the $FORTRANPPCOM variable,
8514 which specifies the default C-preprocessor command line
8515 for all Fortran versions.
8518 The string displayed when a Fortran 90 source file
8519 is compiled after first running the file through the C preprocessor.
8520 If this is not set, then $F90PPCOM or $FORTRANPPCOM
8521 (the command line) is displayed.
8523 .IP F90PPFILESUFFIXES
8524 The list of file extensions for which the compilation + preprocessor pass for
8525 F90 dialect will be used. By default, this is empty
8528 The Fortran 95 compiler.
8529 You should normally set the $FORTRAN variable,
8530 which specifies the default Fortran compiler
8531 for all Fortran versions.
8532 You only need to set $F95 if you need to use a specific compiler
8533 or compiler version for Fortran 95 files.
8536 The command line used to compile a Fortran 95 source file to an object file.
8537 You only need to set $F95COM if you need to use a specific
8538 command line for Fortran 95 files.
8539 You should normally set the $FORTRANCOM variable,
8540 which specifies the default command line
8541 for all Fortran versions.
8544 The string displayed when a Fortran 95 source file
8545 is compiled to an object file.
8546 If this is not set, then $F95COM or $FORTRANCOM
8547 (the command line) is displayed.
8550 The list of file extensions for which the F95 dialect will be used. By
8551 default, this is ['.f95']
8554 General user-specified options that are passed to the Fortran 95 compiler.
8555 Note that this variable does
8559 (or similar) include search path options
8560 that scons generates automatically from $F95PATH.
8564 for the variable that expands to those options.
8565 You only need to set $F95FLAGS if you need to define specific
8566 user options for Fortran 95 files.
8567 You should normally set the $FORTRANFLAGS variable,
8568 which specifies the user-specified options
8569 passed to the default Fortran compiler
8570 for all Fortran versions.
8573 An automatically-generated construction variable
8574 containing the Fortran 95 compiler command-line options
8575 for specifying directories to be searched for include files.
8576 The value of $_F95INCFLAGS is created
8577 by appending $INCPREFIX and $INCSUFFIX
8578 to the beginning and end
8579 of each directory in $F95PATH.
8582 The list of directories that the Fortran 95 compiler will search for include
8583 directories. The implicit dependency scanner will search these
8584 directories for include files. Don't explicitly put include directory
8585 arguments in $F95FLAGS because the result will be non-portable
8586 and the directories will not be searched by the dependency scanner. Note:
8587 directory names in $F95PATH will be looked-up relative to the SConscript
8588 directory when they are used in a command. To force
8590 to look-up a directory relative to the root of the source tree use #:
8591 You only need to set $F95PATH if you need to define a specific
8592 include path for Fortran 95 files.
8593 You should normally set the $FORTRANPATH variable,
8594 which specifies the include path
8595 for the default Fortran compiler
8596 for all Fortran versions.
8599 env = Environment(F95PATH='#/include')
8602 The directory look-up can also be forced using the
8607 include = Dir('include')
8608 env = Environment(F95PATH=include)
8611 The directory list will be added to command lines
8612 through the automatically-generated
8614 construction variable,
8615 which is constructed by
8616 appending the values of the
8617 $INCPREFIX and $INCSUFFIX
8618 construction variables
8619 to the beginning and end
8620 of each directory in $F95PATH.
8621 Any command lines you define that need
8622 the F95PATH directory list should
8623 include $_F95INCFLAGS:
8626 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
8630 The command line used to compile a Fortran 95 source file to an object file
8631 after first running the file through the C preprocessor.
8632 Any options specified in the $F95FLAGS and $CPPFLAGS construction variables
8633 are included on this command line.
8634 You only need to set $F95PPCOM if you need to use a specific
8635 C-preprocessor command line for Fortran 95 files.
8636 You should normally set the $FORTRANPPCOM variable,
8637 which specifies the default C-preprocessor command line
8638 for all Fortran versions.
8641 The string displayed when a Fortran 95 source file
8642 is compiled to an object file
8643 after first running the file through the C preprocessor.
8644 If this is not set, then $F95PPCOM or $FORTRANPPCOM
8645 (the command line) is displayed.
8647 .IP F95PPFILESUFFIXES
8648 The list of file extensions for which the compilation + preprocessor pass for
8649 F95 dialect will be used. By default, this is empty
8652 A function that converts a string into a File instance relative to the
8656 The default Fortran compiler
8657 for all versions of Fortran.
8660 The command line used to compile a Fortran source file to an object file.
8661 By default, any options specified
8662 in the $FORTRANFLAGS,
8665 $_FORTRANMODFLAG, and
8666 $_FORTRANINCFLAGS construction variables
8667 are included on this command line.
8670 The string displayed when a Fortran source file
8671 is compiled to an object file.
8672 If this is not set, then $FORTRANCOM
8673 (the command line) is displayed.
8675 .IP FORTRANFILESUFFIXES
8676 The list of file extensions for which the FORTRAN dialect will be used. By
8677 default, this is ['.f', '.for', '.ftn']
8680 General user-specified options that are passed to the Fortran compiler.
8681 Note that this variable does
8685 (or similar) include or module search path options
8686 that scons generates automatically from $FORTRANPATH.
8688 $_FORTRANINCFLAGS and $_FORTRANMODFLAG,
8690 for the variables that expand those options.
8692 .IP _FORTRANINCFLAGS
8693 An automatically-generated construction variable
8694 containing the Fortran compiler command-line options
8695 for specifying directories to be searched for include
8696 files and module files.
8697 The value of $_FORTRANINCFLAGS is created
8698 by prepending/appending $INCPREFIX and $INCSUFFIX
8699 to the beginning and end
8700 of each directory in $FORTRANPATH.
8703 Directory location where the Fortran compiler should place
8704 any module files it generates. This variable is empty, by default. Some
8705 Fortran compilers will internally append this directory in the search path
8706 for module files, as well.
8708 .IP FORTRANMODDIRPREFIX
8709 The prefix used to specify a module directory on the Fortran compiler command
8711 This will be appended to the beginning of the directory
8712 in the $FORTRANMODDIR construction variables
8713 when the $_FORTRANMODFLAG variables is automatically generated.
8715 .IP FORTRANMODDIRSUFFIX
8716 The suffix used to specify a module directory on the Fortran compiler command
8718 This will be appended to the beginning of the directory
8719 in the $FORTRANMODDIR construction variables
8720 when the $_FORTRANMODFLAG variables is automatically generated.
8723 An automatically-generated construction variable
8724 containing the Fortran compiler command-line option
8725 for specifying the directory location where the Fortran
8726 compiler should place any module files that happen to get
8727 generated during compilation.
8728 The value of $_FORTRANMODFLAG is created
8729 by prepending/appending $FORTRANMODDIRPREFIX and
8730 $FORTRANMODDIRSUFFIX
8731 to the beginning and end of the directory in $FORTRANMODDIR.
8733 .IP FORTRANMODPREFIX
8734 The module file prefix used by the Fortran compiler. SCons assumes that
8735 the Fortran compiler follows the quasi-standard naming convention for
8737 .BR module_name.mod .
8738 As a result, this variable is left empty, by default. For situations in
8739 which the compiler does not necessarily follow the normal convention,
8740 the user may use this variable. Its value will be appended to every
8741 module file name as scons attempts to resolve dependencies.
8743 .IP FORTRANMODSUFFIX
8744 The module file suffix used by the Fortran compiler. SCons assumes that
8745 the Fortran compiler follows the quasi-standard naming convention for
8747 .BR module_name.mod .
8748 As a result, this variable is set to ".mod", by default. For situations
8749 in which the compiler does not necessarily follow the normal convention,
8750 the user may use this variable. Its value will be appended to every
8751 module file name as scons attempts to resolve dependencies.
8754 The list of directories that the Fortran compiler will search for
8755 include files and (for some compilers) module files. The Fortran implicit
8756 dependency scanner will search these directories for include files (but
8757 not module files since they are autogenerated and, as such, may not
8758 actually exist at the time the scan takes place). Don't explicitly put
8759 include directory arguments in FORTRANFLAGS because the result will be
8760 non-portable and the directories will not be searched by the dependency
8761 scanner. Note: directory names in FORTRANPATH will be looked-up relative
8762 to the SConscript directory when they are used in a command. To force
8764 to look-up a directory relative to the root of the source tree use #:
8767 env = Environment(FORTRANPATH='#/include')
8770 The directory look-up can also be forced using the
8775 include = Dir('include')
8776 env = Environment(FORTRANPATH=include)
8779 The directory list will be added to command lines
8780 through the automatically-generated
8782 construction variable,
8783 which is constructed by
8784 appending the values of the
8785 $INCPREFIX and $INCSUFFIX
8786 construction variables
8787 to the beginning and end
8788 of each directory in $FORTRANPATH.
8789 Any command lines you define that need
8790 the FORTRANPATH directory list should
8791 include $_FORTRANINCFLAGS:
8794 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
8798 The command line used to compile a Fortran source file to an object file
8799 after first running the file through the C preprocessor.
8800 By default, any options specified in the $FORTRANFLAGS,
8803 $_FORTRANMODFLAG, and
8805 construction variables are included on this command line.
8808 The string displayed when a Fortran source file
8809 is compiled to an object file
8810 after first running the file throught the C preprocessor.
8811 If this is not set, then $FORTRANPPCOM
8812 (the command line) is displayed.
8814 .IP FORTRANPPFILESUFFIXES
8815 The list of file extensions for which the compilation + preprocessor pass for
8816 FORTRAN dialect will be used. By default, this is ['.fpp', '.FPP']
8819 The list of suffixes of files that will be scanned
8820 for Fortran implicit dependencies
8821 (INCLUDE lines and USE statements).
8822 The default list is:
8825 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
8826 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
8830 On Mac OS X with gcc,
8831 a list containing the paths to search for frameworks.
8832 Used by the compiler to find framework-style includes like
8833 #include <Fmwk/Header.h>.
8834 Used by the linker to find user-specified frameworks when linking (see
8839 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
8845 ... -Fmyframeworkdir
8848 to the compiler and linker command lines.
8851 On Mac OS X with gcc, an automatically-generated construction variable
8852 containing the linker command-line options corresponding to
8855 .IP FRAMEWORKPATHPREFIX
8856 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH entries.
8857 (see $FRAMEWORKPATH).
8858 The default value is
8862 On Mac OS X with gcc,
8863 the prefix to be used for linking in frameworks
8865 The default value is
8869 On Mac OS X with gcc,
8870 an automatically-generated construction variable
8871 containing the linker command-line options
8872 for linking with FRAMEWORKS.
8875 On Mac OS X with gcc, a list of the framework names to be linked into a
8876 program or shared library or bundle.
8877 The default value is the empty list.
8881 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
8886 On Mac OS X with gcc,
8887 general user-supplied frameworks options to be added at
8888 the end of a command
8889 line building a loadable module.
8890 (This has been largely superceded by
8891 the $FRAMEWORKPATH, $FRAMEWORKPATHPREFIX,
8892 $FRAMEWORKPREFIX and $FRAMEWORKS variables
8896 The Ghostscript program used to convert PostScript to PDF files.
8899 The Ghostscript command line used to convert PostScript to PDF files.
8902 The string displayed when
8903 Ghostscript is used to convert
8904 a PostScript file to a PDF file.
8905 If this is not set, then $GSCOM (the command line) is displayed.
8908 General options passed to the Ghostscript program
8909 when converting PostScript to PDF files.
8912 The list of suffixes of files that will be scanned
8913 for IDL implicit dependencies
8914 (#include or import lines).
8915 The default list is:
8921 .IP IMPLICIT_COMMAND_DEPENDENCIES
8922 Controls whether or not SCons will
8923 add implicit dependencies for the commands
8924 executed to build targets.
8926 By default, SCons will add
8928 an implicit dependency on the command
8929 represented by the first argument on any
8930 command line it executes.
8931 The specific file for the dependency is
8932 found by searching the
8936 environment used to execute the command.
8938 If the construction variable
8939 $IMPLICIT_COMMAND_DEPENDENCIES
8940 is set to a false value
8945 then the implicit dependency will
8946 not be added to the targets
8947 built with that construction environment.
8950 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
8954 The prefix used to specify an include directory on the C compiler command
8956 This will be appended to the beginning of each directory
8957 in the $CPPPATH and $FORTRANPATH construction variables
8958 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
8959 variables are automatically generated.
8962 The suffix used to specify an include directory on the C compiler command
8964 This will be appended to the end of each directory
8965 in the $CPPPATH and $FORTRANPATH construction variables
8966 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS
8967 variables are automatically generated.
8970 A function to be called to install a file into a
8971 destination file name.
8972 The default function copies the file into the destination
8973 (and sets the destination file's mode and permission bits
8974 to match the source file's).
8975 The function takes the following arguments:
8978 def install(dest, source, env):
8982 is the path name of the destination file.
8984 is the path name of the source file.
8986 is the construction environment
8987 (a dictionary of construction values)
8988 in force for this file installation.
8991 The string displayed when a file is
8992 installed into a destination file name.
8995 Install file: "$SOURCE" as "$TARGET"
8998 .IP INTEL_C_COMPILER_VERSION
8999 Set by the "intelc" Tool
9000 to the major version number of the Intel C compiler
9004 The Java archive tool.
9007 The directory to which the Java archive tool should change
9013 The command line used to call the Java archive tool.
9016 The string displayed when the Java archive tool
9018 If this is not set, then $JARCOM (the command line) is displayed.
9021 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
9025 General options passed to the Java archive tool.
9026 By default this is set to
9028 to create the necessary
9033 The suffix for Java archives:
9037 .IP JAVABOOTCLASSPATH
9038 Specifies the list of directories that
9039 will be added to the
9040 &javac; command line
9041 via the \fB\-bootclasspath\fP option.
9042 The individual directory names will be
9043 separated by the operating system's path separate character
9044 (\fB:\fP on UNIX/Linux/POSIX,
9045 \fB;\fP on Windows).
9051 The command line used to compile a directory tree containing
9052 Java source files to
9053 corresponding Java class files.
9054 Any options specified in the $JAVACFLAGS construction variable
9055 are included on this command line.
9058 The string displayed when compiling
9059 a directory tree of Java source files to
9060 corresponding Java class files.
9061 If this is not set, then $JAVACCOM (the command line) is displayed.
9064 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
9068 General options that are passed to the Java compiler.
9071 The directory in which Java class files may be found.
9072 This is stripped from the beginning of any Java .class
9073 file names supplied to the
9078 Specifies the list of directories that
9079 will be searched for Java
9081 The directories in this list will be added to the
9082 &javac; and &javah; command lines
9083 via the \fB\-classpath\fP option.
9084 The individual directory names will be
9085 separated by the operating system's path separate character
9086 (\fB:\fP on UNIX/Linux/POSIX,
9087 \fB;\fP on Windows).
9089 Note that this currently just adds the specified
9090 directory via the \fB\-classpath\fP option.
9091 &SCons; does not currently search the
9092 $JAVACLASSPATH directories for dependency
9096 The suffix for Java class files;
9101 The Java generator for C header and stub files.
9104 The command line used to generate C header and stub files
9106 Any options specified in the $JAVAHFLAGS construction variable
9107 are included on this command line.
9110 The string displayed when C header and stub files
9111 are generated from Java classes.
9112 If this is not set, then $JAVAHCOM (the command line) is displayed.
9115 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
9119 General options passed to the C header and stub file generator
9123 Specifies the list of directories that
9124 will be searched for input
9126 The directories in this list will be added to the
9127 &javac; command line
9128 via the \fB\-sourcepath\fP option.
9129 The individual directory names will be
9130 separated by the operating system's path separate character
9131 (\fB:\fP on UNIX/Linux/POSIX,
9132 \fB;\fP on Windows).
9134 Note that this currently just adds the specified
9135 directory via the \fB\-sourcepath\fP option.
9136 &SCons; does not currently search the
9137 $JAVASOURCEPATH directories for dependency
9141 The suffix for Java files;
9146 Specifies the Java version being used by the \fBJava\fP() builder.
9147 This is \fInot\fP currently used to select one
9148 version of the Java compiler vs. another.
9149 Instead, you should set this to specify the version of Java
9150 supported by your &javac; compiler.
9151 The default is \fB1.4\fP.
9153 This is sometimes necessary because
9154 Java 1.5 changed the file names that are created
9155 for nested anonymous inner classes,
9156 which can cause a mismatch with the files
9157 that &SCons; expects will be generated by the &javac; compiler.
9158 Setting $JAVAVERSION to \fB1.5\fP
9159 (or \fB1.6\fP, as appropriate)
9160 can make &SCons; realize that a Java 1.5 or 1.6
9161 build is actually up to date.
9164 The LaTeX structured formatter and typesetter.
9167 The command line used to call the LaTeX structured formatter and typesetter.
9170 The string displayed when calling
9171 the LaTeX structured formatter and typesetter.
9172 If this is not set, then $LATEXCOM (the command line) is displayed.
9175 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
9179 General options passed to the LaTeX structured formatter and typesetter.
9182 The maximum number of times that LaTeX
9183 will be re-run if the
9185 generated by the $LATEXCOM command
9186 indicates that there are undefined references.
9187 The default is to try to resolve undefined references
9188 by re-running LaTeX up to three times.
9191 The list of suffixes of files that will be scanned
9192 for LaTeX implicit dependencies
9193 (\fB\\include\fP or \fB\\import\fP files).
9194 The default list is:
9197 [".tex", ".ltx", ".latex"]
9201 The linker for building loadable modules.
9202 By default, this is the same as $SHLINK.
9205 The command line for building loadable modules.
9206 On Mac OS X, this uses the $LDMODULE,
9208 $FRAMEWORKSFLAGS variables.
9209 On other systems, this is the same as $SHLINK.
9212 The string displayed when building loadable modules.
9213 If this is not set, then $LDMODULECOM (the command line) is displayed.
9216 General user options passed to the linker for building loadable modules.
9219 The prefix used for loadable module file names.
9220 On Mac OS X, this is null;
9221 on other systems, this is
9222 the same as $SHLIBPREFIX.
9225 The suffix used for loadable module file names.
9226 On Mac OS X, this is null;
9227 on other systems, this is
9228 the same as $SHLIBSUFFIX.
9231 The lexical analyzer generator.
9234 The command line used to call the lexical analyzer generator
9235 to generate a source file.
9238 The string displayed when generating a source file
9239 using the lexical analyzer generator.
9240 If this is not set, then $LEXCOM (the command line) is displayed.
9243 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
9247 General options passed to the lexical analyzer generator.
9250 An automatically-generated construction variable
9251 containing the linker command-line options
9252 for specifying directories to be searched for library.
9253 The value of $_LIBDIRFLAGS is created
9254 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
9255 to the beginning and end
9256 of each directory in $LIBPATH.
9259 The prefix used to specify a library directory on the linker command line.
9260 This will be appended to the beginning of each directory
9261 in the $LIBPATH construction variable
9262 when the $_LIBDIRFLAGS variable is automatically generated.
9265 The suffix used to specify a library directory on the linker command line.
9266 This will be appended to the end of each directory
9267 in the $LIBPATH construction variable
9268 when the $_LIBDIRFLAGS variable is automatically generated.
9271 An automatically-generated construction variable
9272 containing the linker command-line options
9273 for specifying libraries to be linked with the resulting target.
9274 The value of $_LIBFLAGS is created
9275 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
9276 to the beginning and end
9277 of each filename in $LIBS.
9280 The prefix used to specify a library to link on the linker command line.
9281 This will be appended to the beginning of each library
9282 in the $LIBS construction variable
9283 when the $_LIBFLAGS variable is automatically generated.
9286 The suffix used to specify a library to link on the linker command line.
9287 This will be appended to the end of each library
9288 in the $LIBS construction variable
9289 when the $_LIBFLAGS variable is automatically generated.
9292 The list of directories that will be searched for libraries.
9293 The implicit dependency scanner will search these
9294 directories for include files. Don't explicitly put include directory
9295 arguments in $LINKFLAGS or $SHLINKFLAGS
9296 because the result will be non-portable
9297 and the directories will not be searched by the dependency scanner. Note:
9298 directory names in LIBPATH will be looked-up relative to the SConscript
9299 directory when they are used in a command. To force
9301 to look-up a directory relative to the root of the source tree use #:
9304 env = Environment(LIBPATH='#/libs')
9307 The directory look-up can also be forced using the
9313 env = Environment(LIBPATH=libs)
9316 The directory list will be added to command lines
9317 through the automatically-generated
9319 construction variable,
9320 which is constructed by
9321 appending the values of the
9322 $LIBDIRPREFIX and $LIBDIRSUFFIX
9323 construction variables
9324 to the beginning and end
9325 of each directory in $LIBPATH.
9326 Any command lines you define that need
9327 the LIBPATH directory list should
9328 include $_LIBDIRFLAGS:
9331 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
9335 The prefix used for (static) library file names.
9336 A default value is set for each platform
9337 (posix, win32, os2, etc.),
9338 but the value is overridden by individual tools
9339 (ar, mslib, sgiar, sunar, tlib, etc.)
9340 to reflect the names of the libraries they create.
9343 A list of all legal prefixes for library file names.
9344 When searching for library dependencies,
9345 SCons will look for files with these prefixes,
9346 the base library name,
9347 and suffixes in the $LIBSUFFIXES list.
9350 A list of one or more libraries
9351 that will be linked with
9352 any executable programs
9353 created by this environment.
9355 The library list will be added to command lines
9356 through the automatically-generated
9358 construction variable,
9359 which is constructed by
9360 appending the values of the
9361 $LIBLINKPREFIX and $LIBLINKSUFFIX
9362 construction variables
9363 to the beginning and end
9364 of each filename in $LIBS.
9365 Any command lines you define that need
9366 the LIBS library list should
9370 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
9377 list, the name of that file will be added to
9379 and thus the link line, as is, without
9386 env.Append(LIBS=File('/tmp/mylib.so'))
9389 In all cases, scons will add dependencies from the executable program to
9390 all the libraries in this list.
9393 The suffix used for (static) library file names.
9394 A default value is set for each platform
9395 (posix, win32, os2, etc.),
9396 but the value is overridden by individual tools
9397 (ar, mslib, sgiar, sunar, tlib, etc.)
9398 to reflect the names of the libraries they create.
9401 A list of all legal suffixes for library file names.
9402 When searching for library dependencies,
9403 SCons will look for files with prefixes, in the $LIBPREFIXES list,
9404 the base library name,
9408 The abbreviated name of the license under which
9409 this project is released (gpl, lpgl, bsd etc.).
9410 See http://www.opensource.org/licenses/alphabetical
9411 for a list of license names.
9417 The command line used to link object files into an executable.
9420 The string displayed when object files
9421 are linked into an executable.
9422 If this is not set, then $LINKCOM (the command line) is displayed.
9425 env = Environment(LINKCOMSTR = "Linking $TARGET")
9429 General user options passed to the linker.
9430 Note that this variable should
9434 (or similar) options for linking with the libraries listed in $LIBS,
9437 (or similar) library search path options
9438 that scons generates automatically from $LIBPATH.
9442 for the variable that expands to library-link options,
9446 for the variable that expands to library search path options.
9449 The M4 macro preprocessor.
9452 The command line used to pass files through the M4 macro preprocessor.
9455 The string displayed when
9456 a file is passed through the M4 macro preprocessor.
9457 If this is not set, then $M4COM (the command line) is displayed.
9460 General options passed to the M4 macro preprocessor.
9463 The makeindex generator for the TeX formatter and typesetter and the
9464 LaTeX structured formatter and typesetter.
9467 The command line used to call the makeindex generator for the
9468 TeX formatter and typesetter and the LaTeX structured formatter and
9472 The string displayed when calling the makeindex generator for the
9473 TeX formatter and typesetter
9474 and the LaTeX structured formatter and typesetter.
9475 If this is not set, then $MAKEINDEXCOM (the command line) is displayed.
9478 General options passed to the makeindex generator for the TeX formatter
9479 and typesetter and the LaTeX structured formatter and typesetter.
9482 The maximum number of characters allowed on an external command line.
9484 link lines longer than this many characters
9485 are linked via a temporary file name.
9488 The Microsoft IDL compiler.
9491 The command line used to pass files to the Microsoft IDL compiler.
9494 The string displayed when
9495 the Microsoft IDL copmiler is called.
9496 If this is not set, then $MIDLCOM (the command line) is displayed.
9499 General options passed to the Microsoft IDL compiler.
9502 When the Microsoft Visual Studio tools are initialized, they set up
9503 this dictionary with the following keys:
9506 the version of MSVS being used (can be set via
9510 the available versions of MSVS installed
9513 installed directory of Visual C++
9516 installed directory of Visual Studio
9519 installed directory of the .NET framework
9521 .BR FRAMEWORKVERSIONS :
9522 list of installed versions of the .NET framework, sorted latest to oldest.
9524 .BR FRAMEWORKVERSION :
9525 latest installed version of the .NET framework
9527 .BR FRAMEWORKSDKDIR :
9528 installed location of the .NET SDK.
9530 .BR PLATFORMSDKDIR :
9531 installed location of the Platform SDK.
9533 .BR PLATFORMSDK_MODULES :
9534 dictionary of installed Platform SDK modules,
9535 where the dictionary keys are keywords for the various modules, and
9536 the values are 2-tuples where the first is the release date, and the
9537 second is the version number.
9539 If a value isn't set, it wasn't available in the registry.
9541 .IP MSVS_IGNORE_IDE_PATHS
9542 Tells the MS Visual Studio tools to use minimal INCLUDE, LIB, and PATH settings,
9543 instead of the settings from the IDE.
9545 For Visual Studio, SCons will (by default) automatically determine
9546 where MSVS is installed, and use the LIB, INCLUDE, and PATH variables
9547 set by the IDE. You can override this behavior by setting these
9548 variables after Environment initialization, or by setting
9549 .B MSVS_IGNORE_IDE_PATHS = 1
9550 in the Environment initialization.
9551 Specifying this will not leave these unset, but will set them to a
9552 minimal set of paths needed to run the tools successfully.
9554 For VS6, the mininimal set is:
9556 INCLUDE:'<VSDir>\\VC98\\ATL\\include;<VSDir>\\VC98\\MFC\\include;<VSDir>\\VC98\\include'
9557 LIB:'<VSDir>\\VC98\\MFC\\lib;<VSDir>\\VC98\\lib'
9558 PATH:'<VSDir>\\Common\\MSDev98\\bin;<VSDir>\\VC98\\bin'
9562 INCLUDE:'<VSDir>\\Vc7\\atlmfc\\include;<VSDir>\\Vc7\\include'
9563 LIB:'<VSDir>\\Vc7\\atlmfc\\lib;<VSDir>\\Vc7\\lib'
9564 PATH:'<VSDir>\\Common7\\Tools\\bin;<VSDir>\\Common7\\Tools;<VSDir>\\Vc7\\bin'
9567 Where '<VSDir>' is the installed location of Visual Studio.
9569 .IP MSVS_PROJECT_BASE_PATH
9571 placed in a generated Microsoft Visual Studio solution file
9573 .B SccProjectFilePathRelativizedFromConnection0
9575 .B SccProjectFilePathRelativizedFromConnection1
9577 .B GlobalSection(SourceCodeControl)
9579 There is no default value.
9581 .IP MSVS_PROJECT_GUID
9583 placed in a generated Microsoft Visual Studio project file
9587 The string is also placed in the
9590 .B GlobalSection(SourceCodeControl)
9591 section of the Microsoft Visual Studio solution file.
9592 There is no default value.
9594 .IP MSVS_SCC_AUX_PATH
9596 placed in a generated Microsoft Visual Studio project file
9601 .B MSVS_SCC_PROVIDER
9602 construction variable is also set.
9603 There is no default value.
9605 .IP MSVS_SCC_LOCAL_PATH
9607 placed in a generated Microsoft Visual Studio project file
9612 .B MSVS_SCC_PROVIDER
9613 construction variable is also set.
9614 The path name is also placed in the
9619 .B GlobalSection(SourceCodeControl)
9620 section of the Microsoft Visual Studio solution file.
9621 There is no default value.
9623 .IP MSVS_SCC_PROJECT_NAME
9625 placed in a generated Microsoft Visual Studio project file
9629 There is no default value.
9631 .IP MSVS_SCC_PROVIDER
9633 placed in a generated Microsoft Visual Studio project file
9637 The string is also placed in the
9640 .B GlobalSection(SourceCodeControl)
9641 section of the Microsoft Visual Studio solution file.
9642 There is no default value.
9644 .IP MSVS_USE_MFC_DIRS
9645 Tells the MS Visual Studio tool(s) to use
9646 the MFC directories in its default paths
9647 for compiling and linking.
9648 The $MSVS_USE_MFC_DIRS variable has no effect if the
9652 environment variables are set explictly.
9654 Under Visual Studio version 6,
9665 external environment variable,
9671 external environment variable.
9673 Under Visual Studio version 7,
9678 .B "atlmfc\\\\atlmfc"
9679 directory to the default
9681 external environment variable,
9683 .B "atlmfc\\\\atlmfc"
9684 directory to the default
9686 external environment variable.
9688 Under Visual Studio version 8,
9691 to a non-zero value will,
9694 .B "atlmfc\\\\atlmfc"
9695 directory to the default
9697 external environment variable,
9699 .B "atlmfc\\\\atlmfc"
9700 directory to the default
9702 external environment variable.
9704 .B ['MSVS']['PLATFORMSDKDIR']
9710 subdirectories of the
9712 are added to the default value of the
9714 external environment variable,
9715 and the default value of the
9717 external environment variable is left untouched.
9720 Sets the preferred version of MSVS to use.
9722 SCons will (by default) select the latest version of MSVS
9723 installed on your machine.
9724 So, if you have version 6 and version 7 (MSVS .NET) installed,
9725 it will prefer version 7.
9726 You can override this by
9729 variable in the Environment initialization, setting it to the
9730 appropriate version ('6.0' or '7.0', for example).
9731 If the given version isn't installed, tool initialization will fail.
9734 The build command line placed in
9735 a generated Microsoft Visual Studio project file.
9736 The default is to have Visual Studio invoke SCons with any specified
9740 The clean command line placed in
9741 a generated Microsoft Visual Studio project file.
9742 The default is to have Visual Studio invoke SCons with the -c option
9743 to remove any specified targets.
9746 The encoding string placed in
9747 a generated Microsoft Visual Studio project file.
9748 The default is encoding
9752 The action used to generate Microsoft Visual Studio project files.
9754 .IP MSVSPROJECTSUFFIX
9755 The suffix used for Microsoft Visual Studio project (DSP) files.
9756 The default value is
9758 when using Visual Studio version 7.x (.NET)
9762 when using earlier versions of Visual Studio.
9765 The rebuild command line placed in
9766 a generated Microsoft Visual Studio project file.
9767 The default is to have Visual Studio invoke SCons with any specified
9771 The SCons used in generated Microsoft Visual Studio project files.
9772 The default is the version of SCons being
9773 used to generate the project file.
9776 The default SCons command used in generated Microsoft Visual Studio
9786 that will be invoked by Visual Studio
9791 The default is the same sconscript file
9792 that contains the call to
9794 to build the project file.
9797 The SCons flags used in generated Microsoft Visual Studio
9801 The action used to generate Microsoft Visual Studio solution files.
9803 .IP MSVSSOLUTIONSUFFIX
9804 The suffix used for Microsoft Visual Studio solution (DSW) files.
9805 The default value is
9807 when using Visual Studio version 7.x (.NET),
9810 when using earlier versions of Visual Studio.
9813 The version number of the MetroWerks CodeWarrior C compiler
9817 A list of installed versions of the MetroWerks CodeWarrior C compiler
9821 Specfies the name of the project to package.
9824 When set to non-zero,
9825 suppresses creation of a corresponding Windows static import lib by the
9827 builder when used with
9828 MinGW, Microsoft Visual Studio or Metrowerks.
9829 This also suppresses creation
9830 of an export (.exp) file
9831 when using Microsoft Visual Studio.
9834 The prefix used for (static) object file names.
9837 The suffix used for (static) object file names.
9840 The Perforce executable.
9843 The command line used to
9844 fetch source files from Perforce.
9847 The string displayed when
9848 fetching a source file from Perforce.
9849 If this is not set, then $P4COM (the command line) is displayed.
9852 General options that are passed to Perforce.
9855 Specifies the directory where all files in resulting archive will be
9856 placed if applicable. The default value is "$NAME-$VERSION".
9859 Selects the package type to build. Currently these are available:
9861 * msi - Microsoft Installer
9862 * rpm - Redhat Package Manger
9863 * ipkg - Itsy Package Management System
9864 * tarbz2 - compressed tar
9865 * targz - compressed tar
9867 * src_tarbz2 - compressed tar source
9868 * src_targz - compressed tar source
9869 * src_zip - zip file source
9871 This may be overridden with the "package_type" command line option.
9874 The version of the package (not the underlying project).
9875 This is currently only used by the rpm packager
9876 and should reflect changes in the packaging,
9877 not the underlying project code itself.
9880 The Microsoft Visual C++ precompiled header that will be used when compiling
9881 object files. This variable is ignored by tools other than Microsoft Visual C++.
9882 When this variable is
9883 defined SCons will add options to the compiler command line to
9884 cause it to use the precompiled header, and will also set up the
9885 dependencies for the PCH file.
9889 env['PCH'] = 'StdAfx.pch'
9893 The command line used by the
9895 builder to generated a precompiled header.
9898 The string displayed when generating a precompiled header.
9899 If this is not set, then $PCHCOM (the command line) is displayed.
9902 A construction variable that, when expanded,
9903 adds the \fB/yD\fP flag to the command line
9904 only if the $PDB construction variable is set.
9907 This variable specifies how much of a source file is precompiled. This
9908 variable is ignored by tools other than Microsoft Visual C++, or when
9909 the PCH variable is not being used. When this variable is define it
9910 must be a string that is the name of the header that
9911 is included at the end of the precompiled portion of the source files, or
9912 the empty string if the "#pragma hrdstop" construct is being used:
9915 env['PCHSTOP'] = 'StdAfx.h'
9919 The Microsoft Visual C++ PDB file that will store debugging information for
9920 object files, shared libraries, and programs. This variable is ignored by
9921 tools other than Microsoft Visual C++.
9922 When this variable is
9923 defined SCons will add options to the compiler and linker command line to
9924 cause them to generate external debugging information, and will also set up the
9925 dependencies for the PDB file.
9929 env['PDB'] = 'hello.pdb'
9932 The Visual C++ compiler switch that SCons uses by default
9933 to generate PDB information is \fB/Z7\fP.
9934 This works correctly with parallel (\fB\-j\fP) builds
9935 because it embeds the debug information in the intermediate object files,
9936 as opposed to sharing a single PDB file between multiple object files.
9937 This is also the only way to get debug information
9938 embedded into a static library.
9939 Using the \fB/Zi\fP instead may yield improved
9940 link-time performance,
9941 although parallel builds will no longer work.
9942 You can generate PDB files with the \fB/Zi\fP
9943 switch by overriding the default $CCPDBFLAGS variable;
9944 see the entry for that variable for specific examples.
9947 A deprecated synonym for $DVIPDFCOM.
9950 The &pdflatex; utility.
9953 The command line used to call the &pdflatex; utility.
9956 The string displayed when calling the &pdflatex; utility.
9957 If this is not set, then $PDFLATEXCOM (the command line) is displayed.
9960 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
9964 General options passed to the &pdflatex; utility.
9967 The prefix used for PDF file names.
9970 The suffix used for PDF file names.
9973 The &pdftex; utility.
9976 The command line used to call the &pdftex; utility.
9979 The string displayed when calling the &pdftex; utility.
9980 If this is not set, then $PDFTEXCOM (the command line) is displayed.
9983 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
9987 General options passed to the &pdftex; utility.
9991 the package-checking program that will
9992 be used (along with $PKGINFO)
9993 to look for installed versions of
9994 the Sun PRO C++ compiler.
9996 .BR /usr/sbin/pgkchk .
10000 the package information program that will
10001 be used (along with $PKGCHK)
10002 to look for installed versions of
10003 the Sun PRO C++ compiler.
10008 The name of the platform used to create the Environment. If no platform is
10009 specified when the Environment is created,
10011 autodetects the platform.
10014 env = Environment(tools = [])
10015 if env['PLATFORM'] == 'cygwin':
10021 .IP PRINT_CMD_LINE_FUNC
10022 A Python function used to print the command lines as they are executed
10023 (assuming command printing is not disabled by the
10027 options or their equivalents).
10028 The function should take four arguments:
10030 the command being executed (a string),
10032 the target being built (file node, list, or string name(s)),
10034 the source(s) used (file node, list, or string name(s)), and
10036 the environment being used.
10038 The function must do the printing itself. The default implementation,
10039 used if this variable is not set or is None, is:
10041 def print_cmd_line(s, target, source, env):
10042 sys.stdout.write(s + "\\n")
10045 Here's an example of a more interesting function:
10048 def print_cmd_line(s, target, source, env):
10049 sys.stdout.write("Building %s -> %s...\\n" %
10050 (' and '.join([str(x) for x in source]),
10051 ' and '.join([str(x) for x in target])))
10052 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
10053 env.Program('foo', 'foo.c')
10056 This just prints "Building \fItargetname\fP from \fIsourcename\fP..." instead
10057 of the actual commands.
10058 Such a function could also log the actual commands to a log file,
10062 The prefix used for executable file names.
10065 The suffix used for executable file names.
10068 The command line used to convert TeX DVI files into a PostScript file.
10071 The string displayed when a TeX DVI file
10072 is converted into a PostScript file.
10073 If this is not set, then $PSCOM (the command line) is displayed.
10076 The prefix used for PostScript file names.
10079 The prefix used for PostScript file names.
10082 Turn off scanning for mocable files. Use the Moc Builder to explicitely
10083 specify files to run moc on.
10086 The path where the qt binaries are installed.
10087 The default value is '$QTDIR/bin'.
10090 The path where the qt header files are installed.
10091 The default value is '$QTDIR/include'.
10092 Note: If you set this variable to None,
10093 the tool won't change the $CPPPATH
10094 construction variable.
10097 Prints lots of debugging information while scanning for moc files.
10100 Default value is 'qt'. You may want to set this to 'qt-mt'. Note: If you set
10101 this variable to None, the tool won't change the $LIBS variable.
10104 The path where the qt libraries are installed.
10105 The default value is '$QTDIR/lib'.
10106 Note: If you set this variable to None,
10107 the tool won't change the $LIBPATH
10108 construction variable.
10111 Default value is '$QT_BINPATH/moc'.
10113 .IP QT_MOCCXXPREFIX
10114 Default value is ''. Prefix for moc output files, when source is a cxx file.
10116 .IP QT_MOCCXXSUFFIX
10117 Default value is '.moc'. Suffix for moc output files, when source is a cxx
10120 .IP QT_MOCFROMCXXCOM
10121 Command to generate a moc file from a cpp file.
10123 .IP QT_MOCFROMCXXCOMSTR
10124 The string displayed when generating a moc file from a cpp file.
10125 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is displayed.
10127 .IP QT_MOCFROMCXXFLAGS
10128 Default value is '-i'. These flags are passed to moc, when moccing a
10132 Command to generate a moc file from a header.
10134 .IP QT_MOCFROMHCOMSTR
10135 The string displayed when generating a moc file from a cpp file.
10136 If this is not set, then $QT_MOCFROMHCOM (the command line) is displayed.
10138 .IP QT_MOCFROMHFLAGS
10139 Default value is ''. These flags are passed to moc, when moccing a header
10143 Default value is 'moc_'. Prefix for moc output files, when source is a header.
10146 Default value is '$CXXFILESUFFIX'. Suffix for moc output files, when source is
10150 Default value is '$QT_BINPATH/uic'.
10153 Command to generate header files from .ui files.
10156 The string displayed when generating header files from .ui files.
10157 If this is not set, then $QT_UICCOM (the command line) is displayed.
10159 .IP QT_UICDECLFLAGS
10160 Default value is ''. These flags are passed to uic, when creating a a h
10161 file from a .ui file.
10163 .IP QT_UICDECLPREFIX
10164 Default value is ''. Prefix for uic generated header files.
10166 .IP QT_UICDECLSUFFIX
10167 Default value is '.h'. Suffix for uic generated header files.
10169 .IP QT_UICIMPLFLAGS
10170 Default value is ''. These flags are passed to uic, when creating a cxx
10171 file from a .ui file.
10173 .IP QT_UICIMPLPREFIX
10174 Default value is 'uic_'. Prefix for uic generated implementation files.
10176 .IP QT_UICIMPLSUFFIX
10177 Default value is '$CXXFILESUFFIX'. Suffix for uic generated implementation
10181 Default value is '.ui'. Suffix of designer input files.
10184 The qt tool tries to take this from os.environ.
10185 It also initializes all QT_*
10186 construction variables listed below.
10187 (Note that all paths are constructed
10188 with python's os.path.join() method,
10189 but are listed here with the '/' separator
10190 for easier reading.)
10191 In addition, the construction environment
10192 variables $CPPPATH,
10194 $LIBS may be modified
10196 PROGEMITTER, SHLIBEMITTER and LIBEMITTER
10197 are modified. Because the build-performance is affected when using this tool,
10198 you have to explicitly specify it at Environment creation:
10201 Environment(tools=['default','qt'])
10204 The qt tool supports the following operations:
10206 .I Automatic moc file generation from header files.
10207 You do not have to specify moc files explicitly, the tool does it for you.
10208 However, there are a few preconditions to do so: Your header file must have
10209 the same filebase as your implementation file and must stay in the same
10210 directory. It must have one of the suffixes .h, .hpp, .H, .hxx, .hh. You
10211 can turn off automatic moc file generation by setting QT_AUTOSCAN to 0.
10212 See also the corresponding builder method
10215 .I Automatic moc file generation from cxx files.
10216 As stated in the qt documentation, include the moc file at the end of
10217 the cxx file. Note that you have to include the file, which is generated
10218 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by default
10219 <basename>.moc. A warning is generated after building the moc file, if you
10220 do not include the correct file. If you are using VariantDir, you may
10221 need to specify duplicate=1. You can turn off automatic moc file generation
10222 by setting QT_AUTOSCAN to 0. See also the corresponding
10226 .I Automatic handling of .ui files.
10227 The implementation files generated from .ui files are handled much the same
10228 as yacc or lex files. Each .ui file given as a source of Program, Library or
10229 SharedLibrary will generate three files, the declaration file, the
10230 implementation file and a moc file. Because there are also generated headers,
10231 you may need to specify duplicate=1 in calls to VariantDir.
10232 See also the corresponding
10237 The archive indexer.
10240 The command line used to index a static library archive.
10243 The string displayed when a static library archive is indexed.
10244 If this is not set, then $RANLIBCOM (the command line) is displayed.
10247 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
10251 General options passed to the archive indexer.
10254 The resource compiler used to build
10255 a Microsoft Visual C++ resource file.
10258 The command line used to build
10259 a Microsoft Visual C++ resource file.
10262 The string displayed when invoking the resource compiler
10263 to build a Microsoft Visual C++ resource file.
10264 If this is not set, then $RCCOM (the command line) is displayed.
10267 The flags passed to the resource compiler by the RES builder.
10270 An automatically-generated construction variable
10271 containing the command-line options
10272 for specifying directories to be searched
10273 by the resource compiler.
10274 The value of $RCINCFLAGS is created
10275 by appending $RCINCPREFIX and $RCINCSUFFIX
10276 to the beginning and end
10277 of each directory in $CPPPATH.
10280 The prefix (flag) used to specify an include directory
10281 on the resource compiler command line.
10282 This will be appended to the beginning of each directory
10283 in the $CPPPATH construction variable
10284 when the $RCINCFLAGS variable is expanded.
10287 The suffix used to specify an include directory
10288 on the resource compiler command line.
10289 This will be appended to the end of each directory
10290 in the $CPPPATH construction variable
10291 when the $RCINCFLAGS variable is expanded.
10294 The RCS executable.
10295 Note that this variable is not actually used
10296 for the command to fetch source files from RCS;
10299 construction variable, below.
10302 The RCS "checkout" executable,
10303 used to fetch source files from RCS.
10306 The command line used to
10307 fetch (checkout) source files from RCS.
10310 The string displayed when fetching
10311 a source file from RCS.
10312 If this is not set, then $RCS_COCOM
10313 (the command line) is displayed.
10316 Options that are passed to the $RCS_CO command.
10319 A function that converts a string into a list of Dir instances by
10320 searching the repositories.
10323 The program used on Windows systems
10324 to register a newly-built DLL library
10325 whenever the \fBSharedLibrary\fP() builder
10326 is passed a keyword argument of \fBregister=1\fP.
10329 The command line used on Windows systems
10330 to register a newly-built DLL library
10331 whenever the \fBSharedLibrary\fP() builder
10332 is passed a keyword argument of \fBregister=1\fP.
10335 The string displayed when registering a newly-built DLL file.
10336 If this is not set, then $REGSVRCOM (the command line) is displayed.
10339 Flags passed to the DLL registration program
10340 on Windows systems when a newly-built DLL library is registered.
10342 this includes the \fB/s\fP
10343 that prevents dialog boxes from popping up
10344 and requiring user attention.
10347 The Java RMI stub compiler.
10350 The command line used to compile stub
10351 and skeleton class files
10352 from Java classes that contain RMI implementations.
10353 Any options specified in the $RMICFLAGS construction variable
10354 are included on this command line.
10357 The string displayed when compiling
10358 stub and skeleton class files
10359 from Java classes that contain RMI implementations.
10360 If this is not set, then $RMICCOM (the command line) is displayed.
10363 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
10367 General options passed to the Java RMI stub compiler.
10370 An automatically-generated construction variable
10371 containing the rpath flags to be used when linking
10372 a program with shared libraries.
10373 The value of $_RPATH is created
10374 by appending $RPATHPREFIX and $RPATHSUFFIX
10375 to the beginning and end
10376 of each directory in $RPATH.
10379 A list of paths to search for shared libraries when running programs.
10380 Currently only used in the GNU (gnulink),
10381 IRIX (sgilink) and Sun (sunlink) linkers.
10382 Ignored on platforms and toolchains that don't support it.
10383 Note that the paths added to RPATH
10384 are not transformed by
10386 in any way: if you want an absolute
10387 path, you must make it absolute yourself.
10390 The prefix used to specify a directory to be searched for
10391 shared libraries when running programs.
10392 This will be appended to the beginning of each directory
10393 in the $RPATH construction variable
10394 when the $_RPATH variable is automatically generated.
10397 The suffix used to specify a directory to be searched for
10398 shared libraries when running programs.
10399 This will be appended to the end of each directory
10400 in the $RPATH construction variable
10401 when the $_RPATH variable is automatically generated.
10404 The RPC protocol compiler.
10406 .IP RPCGENCLIENTFLAGS
10407 Options passed to the RPC protocol compiler
10408 when generating client side stubs.
10409 These are in addition to any flags specified in the
10411 construction variable.
10414 General options passed to the RPC protocol compiler.
10416 .IP RPCGENHEADERFLAGS
10417 Options passed to the RPC protocol compiler
10418 when generating a header file.
10419 These are in addition to any flags specified in the
10421 construction variable.
10423 .IP RPCGENSERVICEFLAGS
10424 Options passed to the RPC protocol compiler
10425 when generating server side stubs.
10426 These are in addition to any flags specified in the
10428 construction variable.
10431 Options passed to the RPC protocol compiler
10432 when generating XDR routines.
10433 These are in addition to any flags specified in the
10435 construction variable.
10438 A list of the available implicit dependency scanners.
10439 New file scanners may be added by
10440 appending to this list,
10441 although the more flexible approach
10442 is to associate scanners
10443 with a specific Builder.
10444 See the sections "Builder Objects"
10445 and "Scanner Objects,"
10446 below, for more information.
10449 The SCCS executable.
10452 The command line used to
10453 fetch source files from SCCS.
10456 The string displayed when fetching
10457 a source file from a CVS repository.
10458 If this is not set, then $SCCSCOM
10459 (the command line) is displayed.
10462 General options that are passed to SCCS.
10465 Options that are passed specifically to the SCCS "get" subcommand.
10466 This can be set, for example, to
10468 to check out editable files from SCCS.
10471 The (optional) path to the SCons library directory,
10472 initialized from the external environment.
10473 If set, this is used to construct a shorter and more
10474 efficient search path in the
10476 command line executed
10477 from Microsoft Visual Studio project files.
10480 The C compiler used for generating shared-library objects.
10483 The command line used to compile a C source file
10484 to a shared-library object file.
10485 Any options specified in the $SHCFLAGS,
10487 $CPPFLAGS construction variables
10488 are included on this command line.
10491 The string displayed when a C source file
10492 is compiled to a shared object file.
10493 If this is not set, then $SHCCCOM (the command line) is displayed.
10496 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
10500 Options that are passed to the C and C++ compilers
10501 to generate shared-library objects.
10504 Options that are passed to the C compiler (only; not C++)
10505 to generate shared-library objects.
10508 The C++ compiler used for generating shared-library objects.
10511 The command line used to compile a C++ source file
10512 to a shared-library object file.
10513 Any options specified in the $SHCXXFLAGS and
10514 $CPPFLAGS construction variables
10515 are included on this command line.
10518 The string displayed when a C++ source file
10519 is compiled to a shared object file.
10520 If this is not set, then $SHCXXCOM (the command line) is displayed.
10523 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
10527 Options that are passed to the C++ compiler
10528 to generate shared-library objects.
10531 A string naming the shell program that will be passed to the
10536 construction variable for more information.
10539 The Fortran 77 compiler used for generating shared-library objects.
10540 You should normally set the $SHFORTRAN variable,
10541 which specifies the default Fortran compiler
10542 for all Fortran versions.
10543 You only need to set $SHF77 if you need to use a specific compiler
10544 or compiler version for Fortran 77 files.
10547 The command line used to compile a Fortran 77 source file
10548 to a shared-library object file.
10549 You only need to set $SHF77COM if you need to use a specific
10550 command line for Fortran 77 files.
10551 You should normally set the $SHFORTRANCOM variable,
10552 which specifies the default command line
10553 for all Fortran versions.
10556 The string displayed when a Fortran 77 source file
10557 is compiled to a shared-library object file.
10558 If this is not set, then $SHF77COM or $SHFORTRANCOM
10559 (the command line) is displayed.
10562 Options that are passed to the Fortran 77 compiler
10563 to generated shared-library objects.
10564 You only need to set $SHF77FLAGS if you need to define specific
10565 user options for Fortran 77 files.
10566 You should normally set the $SHFORTRANFLAGS variable,
10567 which specifies the user-specified options
10568 passed to the default Fortran compiler
10569 for all Fortran versions.
10572 The command line used to compile a Fortran 77 source file to a
10573 shared-library object file
10574 after first running the file through the C preprocessor.
10575 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
10576 are included on this command line.
10577 You only need to set $SHF77PPCOM if you need to use a specific
10578 C-preprocessor command line for Fortran 77 files.
10579 You should normally set the $SHFORTRANPPCOM variable,
10580 which specifies the default C-preprocessor command line
10581 for all Fortran versions.
10584 The string displayed when a Fortran 77 source file
10585 is compiled to a shared-library object file
10586 after first running the file through the C preprocessor.
10587 If this is not set, then $SHF77PPCOM or $SHFORTRANPPCOM
10588 (the command line) is displayed.
10591 The Fortran 90 compiler used for generating shared-library objects.
10592 You should normally set the $SHFORTRAN variable,
10593 which specifies the default Fortran compiler
10594 for all Fortran versions.
10595 You only need to set $SHF90 if you need to use a specific compiler
10596 or compiler version for Fortran 90 files.
10599 The command line used to compile a Fortran 90 source file
10600 to a shared-library object file.
10601 You only need to set $SHF90COM if you need to use a specific
10602 command line for Fortran 90 files.
10603 You should normally set the $SHFORTRANCOM variable,
10604 which specifies the default command line
10605 for all Fortran versions.
10608 The string displayed when a Fortran 90 source file
10609 is compiled to a shared-library object file.
10610 If this is not set, then $SHF90COM or $SHFORTRANCOM
10611 (the command line) is displayed.
10614 Options that are passed to the Fortran 90 compiler
10615 to generated shared-library objects.
10616 You only need to set $SHF90FLAGS if you need to define specific
10617 user options for Fortran 90 files.
10618 You should normally set the $SHFORTRANFLAGS variable,
10619 which specifies the user-specified options
10620 passed to the default Fortran compiler
10621 for all Fortran versions.
10624 The command line used to compile a Fortran 90 source file to a
10625 shared-library object file
10626 after first running the file through the C preprocessor.
10627 Any options specified in the $SHF90FLAGS and $CPPFLAGS construction variables
10628 are included on this command line.
10629 You only need to set $SHF90PPCOM if you need to use a specific
10630 C-preprocessor command line for Fortran 90 files.
10631 You should normally set the $SHFORTRANPPCOM variable,
10632 which specifies the default C-preprocessor command line
10633 for all Fortran versions.
10636 The string displayed when a Fortran 90 source file
10637 is compiled to a shared-library object file
10638 after first running the file through the C preprocessor.
10639 If this is not set, then $SHF90PPCOM or $SHFORTRANPPCOM
10640 (the command line) is displayed.
10643 The Fortran 95 compiler used for generating shared-library objects.
10644 You should normally set the $SHFORTRAN variable,
10645 which specifies the default Fortran compiler
10646 for all Fortran versions.
10647 You only need to set $SHF95 if you need to use a specific compiler
10648 or compiler version for Fortran 95 files.
10651 The command line used to compile a Fortran 95 source file
10652 to a shared-library object file.
10653 You only need to set $SHF95COM if you need to use a specific
10654 command line for Fortran 95 files.
10655 You should normally set the $SHFORTRANCOM variable,
10656 which specifies the default command line
10657 for all Fortran versions.
10660 The string displayed when a Fortran 95 source file
10661 is compiled to a shared-library object file.
10662 If this is not set, then $SHF95COM or $SHFORTRANCOM
10663 (the command line) is displayed.
10666 Options that are passed to the Fortran 95 compiler
10667 to generated shared-library objects.
10668 You only need to set $SHF95FLAGS if you need to define specific
10669 user options for Fortran 95 files.
10670 You should normally set the $SHFORTRANFLAGS variable,
10671 which specifies the user-specified options
10672 passed to the default Fortran compiler
10673 for all Fortran versions.
10676 The command line used to compile a Fortran 95 source file to a
10677 shared-library object file
10678 after first running the file through the C preprocessor.
10679 Any options specified in the $SHF95FLAGS and $CPPFLAGS construction variables
10680 are included on this command line.
10681 You only need to set $SHF95PPCOM if you need to use a specific
10682 C-preprocessor command line for Fortran 95 files.
10683 You should normally set the $SHFORTRANPPCOM variable,
10684 which specifies the default C-preprocessor command line
10685 for all Fortran versions.
10688 The string displayed when a Fortran 95 source file
10689 is compiled to a shared-library object file
10690 after first running the file through the C preprocessor.
10691 If this is not set, then $SHF95PPCOM or $SHFORTRANPPCOM
10692 (the command line) is displayed.
10695 The default Fortran compiler used for generating shared-library objects.
10698 The command line used to compile a Fortran source file
10699 to a shared-library object file.
10701 .IP SHFORTRANCOMSTR
10702 The string displayed when a Fortran source file
10703 is compiled to a shared-library object file.
10704 If this is not set, then $SHFORTRANCOM
10705 (the command line) is displayed.
10708 Options that are passed to the Fortran compiler
10709 to generate shared-library objects.
10712 The command line used to compile a Fortran source file to a
10713 shared-library object file
10714 after first running the file through the C preprocessor.
10715 Any options specified
10716 in the $SHFORTRANFLAGS and
10717 $CPPFLAGS construction variables
10718 are included on this command line.
10720 .IP SHFORTRANPPCOMSTR
10721 The string displayed when a Fortran source file
10722 is compiled to a shared-library object file
10723 after first running the file throught the C preprocessor.
10724 If this is not set, then $SHFORTRANPPCOM
10725 (the command line) is displayed.
10728 The prefix used for shared library file names.
10731 The suffix used for shared library file names.
10734 The linker for programs that use shared libraries.
10737 The command line used to link programs using shared libaries.
10740 The string displayed when programs using shared libraries are linked.
10741 If this is not set, then $SHLINKCOM (the command line) is displayed.
10744 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
10748 General user options passed to the linker for programs using shared libraries.
10749 Note that this variable should
10753 (or similar) options for linking with the libraries listed in $LIBS,
10756 (or similar) include search path options
10757 that scons generates automatically from $LIBPATH.
10761 for the variable that expands to library-link options,
10765 for the variable that expands to library search path options.
10768 The prefix used for shared object file names.
10771 The suffix used for shared object file names.
10774 A reserved variable name
10775 that may not be set or used in a construction environment.
10776 (See "Variable Substitution," below.)
10781 of the location from which the project was retrieved.
10782 This is used to fill in the
10784 field in the controlling information for Ipkg and RPM packages.
10787 A reserved variable name
10788 that may not be set or used in a construction environment.
10789 (See "Variable Substitution," below.)
10792 A command interpreter function that will be called to execute command line
10793 strings. The function must expect the following arguments:
10796 def spawn(shell, escape, cmd, args, env):
10800 is a string naming the shell program to use.
10802 is a function that can be called to escape shell special characters in
10805 is the path to the command to be executed.
10807 is the arguments to the command.
10809 is a dictionary of the environment variables
10810 in which the command should be executed.
10813 A short summary of what the project is about.
10814 This is used to fill in the
10816 field in the controlling information for Ipkg and RPM packages,
10819 field in MSI packages.
10822 The scripting language wrapper and interface generator.
10824 .IP SWIGCFILESUFFIX
10825 The suffix that will be used for intermediate C
10826 source files generated by
10827 the scripting language wrapper and interface generator.
10828 The default value is
10829 .BR _wrap $CFILESUFFIX.
10830 By default, this value is used whenever the
10834 specified as part of the
10836 construction variable.
10839 The command line used to call
10840 the scripting language wrapper and interface generator.
10843 The string displayed when calling
10844 the scripting language wrapper and interface generator.
10845 If this is not set, then $SWIGCOM (the command line) is displayed.
10847 .IP SWIGCXXFILESUFFIX
10848 The suffix that will be used for intermediate C++
10849 source files generated by
10850 the scripting language wrapper and interface generator.
10851 The default value is
10852 .BR _wrap $CFILESUFFIX.
10853 By default, this value is used whenever the
10855 option is specified as part of the
10857 construction variable.
10860 General options passed to
10861 the scripting language wrapper and interface generator.
10862 This is where you should set
10866 or whatever other options you want to specify to SWIG.
10869 option in this variable,
10872 generate a C++ intermediate source file
10873 with the extension that is specified as the
10878 An automatically-generated construction variable
10879 containing the SWIG command-line options
10880 for specifying directories to be searched for included files.
10881 The value of $_SWIGINCFLAGS is created
10882 by appending $SWIGINCPREFIX and $SWIGINCSUFFIX
10883 to the beginning and end
10884 of each directory in $SWIGPATH.
10887 The prefix used to specify an include directory on the SWIG command line.
10888 This will be appended to the beginning of each directory
10889 in the $SWIGPATH construction variable
10890 when the $_SWIGINCFLAGS variable is automatically generated.
10893 The suffix used to specify an include directory on the SWIG command line.
10894 This will be appended to the end of each directory
10895 in the $SWIGPATH construction variable
10896 when the $_SWIGINCFLAGS variable is automatically generated.
10899 Specifies the output directory in which
10900 the scripting language wrapper and interface generator
10901 should place generated language-specific files.
10902 This will be used by SCons to identify
10903 the files that will be generated by the &swig; call,
10904 and translated into the
10905 \fBswig -outdir\fP option on the command line.
10908 The list of directories that the scripting language wrapper
10909 and interface generate will search for included files.
10910 The SWIG implicit dependency scanner will search these
10911 directories for include files.
10912 The default is to use the same path
10913 specified as $CPPPATH.
10915 Don't explicitly put include directory
10916 arguments in SWIGFLAGS;
10917 the result will be non-portable
10918 and the directories will not be searched by the dependency scanner.
10919 Note: directory names in SWIGPATH will be looked-up relative to the SConscript
10920 directory when they are used in a command.
10923 to look-up a directory relative to the root of the source tree use #:
10926 env = Environment(SWIGPATH='#/include')
10929 The directory look-up can also be forced using the
10934 include = Dir('include')
10935 env = Environment(SWIGPATH=include)
10938 The directory list will be added to command lines
10939 through the automatically-generated
10941 construction variable,
10942 which is constructed by
10943 appending the values of the
10944 $SWIGINCPREFIX and $SWIGINCSUFFIX
10945 construction variables
10946 to the beginning and end
10947 of each directory in $SWIGPATH.
10948 Any command lines you define that need
10949 the SWIGPATH directory list should
10950 include $_SWIGINCFLAGS:
10953 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")
10960 The command line used to call the tar archiver.
10963 The string displayed when archiving files
10964 using the tar archiver.
10965 If this is not set, then $TARCOM (the command line) is displayed.
10968 env = Environment(TARCOMSTR = "Archiving $TARGET")
10972 General options passed to the tar archiver.
10975 A reserved variable name
10976 that may not be set or used in a construction environment.
10977 (See "Variable Substitution," below.)
10980 A reserved variable name
10981 that may not be set or used in a construction environment.
10982 (See "Variable Substitution," below.)
10985 The suffix used for tar file names.
10988 The prefix for a temporary file used
10989 to execute lines longer than $MAXLINELENGTH.
10990 The default is '@'.
10991 This may be set for toolchains that use other values,
10992 such as '-@' for the diab compiler
10993 or '-via' for ARM toolchain.
10996 The TeX formatter and typesetter.
10999 The command line used to call the TeX formatter and typesetter.
11002 The string displayed when calling
11003 the TeX formatter and typesetter.
11004 If this is not set, then $TEXCOM (the command line) is displayed.
11007 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
11011 General options passed to the TeX formatter and typesetter.
11014 List of directories that the LaTeX programm will search
11015 for include directories.
11016 The LaTeX implicit dependency scanner will search these
11017 directories for \\include and \\import files.
11020 A list of the names of the Tool specifications
11021 that are part of this construction environment.
11024 The person or organization who supply the packaged software.
11025 This is used to fill in the
11027 field in the controlling information for RPM packages,
11030 field in the controlling information for MSI packages.
11033 The version of the project, specified as a string.
11035 .IP WIN32_INSERT_DEF
11036 A deprecated synonym for $WINDOWS_INSERT_DEF.
11039 A deprecated synonym for $WINDOWSDEFPREFIX.
11042 A deprecated synonym for $WINDOWSDEFSUFFIX.
11045 A deprecated synonym for $WINDOWSEXPSUFFIX.
11048 A deprecated synonym for $WINDOWSEXPSUFFIX.
11050 .IP WINDOWS_INSERT_DEF
11051 When this is set to true,
11052 a library build of a Windows shared library
11054 will also build a corresponding \fB.def\fP file
11056 if a \fB.def\fP file
11057 is not already listed as a build target.
11058 The default is 0 (do not build a \fB.def\fP file).
11060 .IP WINDOWS_INSERT_MANIFEST
11061 When this is set to true,
11063 will be aware of the
11065 files generated by Microsoft Visua C/C++ 8.
11067 .IP WINDOWSDEFPREFIX
11068 The prefix used for Windows \fB.def\fPfile names.
11070 .IP WINDOWSDEFSUFFIX
11071 The suffix used for Windows \fB.def\fP file names.
11073 .IP WINDOWSEXPPREFIX
11074 The prefix used for Windows \fB.exp\fP file names.
11076 .IP WINDOWSEXPSUFFIX
11077 The suffix used for Windows \fB.exp\fP file names.
11079 .IP WINDOWSPROGMANIFESTPREFIX
11080 The prefix used for executable program \fB.manifest\fP files
11081 generated by Microsoft Visual C/C++.
11083 .IP WINDOWSPROGMANIFESTSUFFIX
11084 The suffix used for executable program \fB.manifest\fP files
11085 generated by Microsoft Visual C/C++.
11087 .IP WINDOWSSHLIBMANIFESTPREFIX
11088 The prefix used for shared library \fB.manifest\fP files
11089 generated by Microsoft Visual C/C++.
11091 .IP WINDOWSSHLIBMANIFESTSUFFIX
11092 The suffix used for shared library \fB.manifest\fP files
11093 generated by Microsoft Visual C/C++.
11096 This is used to fill in the
11098 field in the controlling information for Ipkg packages.
11100 .IP X_IPK_DESCRIPTION
11101 This is used to fill in the
11103 field in the controlling information for Ipkg packages.
11104 The default value is
11105 .B "$SUMMARY\\\\$SUMMARY"
11106 .IP X_IPK_MAINTAINER
11107 This is used to fill in the
11109 field in the controlling information for Ipkg packages.
11112 This is used to fill in the
11114 field in the controlling information for Ipkg packages.
11117 This is used to fill in the
11119 field in the controlling information for Ipkg packages.
11122 This is used to fill in the
11124 attribute in the controlling information for MSI packages.
11126 .IP X_MSI_LICENSE_TEXT
11127 The text of the software license in RTF format.
11128 Carriage return characters will be
11129 replaced with the RTF equivalent \\\par.
11131 .IP X_MSI_UPGRADE_CODE
11134 .IP X_RPM_AUTOREQPROV
11135 This is used to fill in the
11141 internal, but overridable
11143 .IP X_RPM_BUILDREQUIRES
11144 This is used to fill in the
11149 .IP X_RPM_BUILDROOT
11150 internal, but overridable
11153 internal, but overridable
11155 .IP X_RPM_CONFLICTS
11156 This is used to fill in the
11162 This value is used as the default attributes
11163 for the files in the RPM package.
11164 The default value is
11165 .BR (-,root,root) .
11167 .IP X_RPM_DISTRIBUTION
11168 This is used to fill in the
11174 This is used to fill in the
11176 field in the controlling information for RPM packages.
11178 .IP X_RPM_EXCLUDEARCH
11179 This is used to fill in the
11184 .IP X_RPM_EXLUSIVEARCH
11185 This is used to fill in the
11191 This is used to fill in the
11196 .IP X_RPM_GROUP_lang
11197 This is used to fill in the
11204 and should be replaced by
11205 the appropriate language code.
11208 This is used to fill in the
11214 internal, but overridable
11217 This is used to fill in the
11222 .IP X_RPM_POSTINSTALL
11223 This is used to fill in the
11228 .IP X_RPM_POSTUNINSTALL
11229 This is used to fill in the
11235 This is used to fill in the
11240 .IP X_RPM_PREINSTALL
11241 This is used to fill in the
11247 internal, but overridable
11249 .IP X_RPM_PREUNINSTALL
11250 This is used to fill in the
11256 This is used to fill in the
11262 This is used to fill in the
11268 This is used to fill in the
11274 This is used to fill in the
11280 The parser generator.
11283 The command line used to call the parser generator
11284 to generate a source file.
11287 The string displayed when generating a source file
11288 using the parser generator.
11289 If this is not set, then $YACCCOM (the command line) is displayed.
11292 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
11296 General options passed to the parser generator.
11297 If $YACCFLAGS contains a \fB\-d\fP option,
11298 SCons assumes that the call will also create a .h file
11299 (if the yacc source file ends in a .y suffix)
11301 (if the yacc source file ends in a .yy suffix)
11303 .IP YACCHFILESUFFIX
11304 The suffix of the C
11305 header file generated by the parser generator
11309 Note that setting this variable does not cause
11310 the parser generator to generate a header
11311 file with the specified suffix,
11312 it exists to allow you to specify
11313 what suffix the parser generator will use of its own accord.
11314 The default value is
11317 .IP YACCHXXFILESUFFIX
11318 The suffix of the C++
11319 header file generated by the parser generator
11323 Note that setting this variable does not cause
11324 the parser generator to generate a header
11325 file with the specified suffix,
11326 it exists to allow you to specify
11327 what suffix the parser generator will use of its own accord.
11328 The default value is
11330 except on Mac OS X,
11331 where the default is
11332 .BR ${TARGET.suffix}.h .
11333 because the default &bison; parser generator just
11335 to the name of the generated C++ file.
11337 .IP YACCVCGFILESUFFIX
11338 The suffix of the file
11339 containing the VCG grammar automaton definition
11343 Note that setting this variable does not cause
11344 the parser generator to generate a VCG
11345 file with the specified suffix,
11346 it exists to allow you to specify
11347 what suffix the parser generator will use of its own accord.
11348 The default value is
11352 The zip compression and file packaging utility.
11355 The command line used to call the zip utility,
11356 or the internal Python function used to create a
11365 module used by the internal Python function
11366 to control whether the zip archive
11367 is compressed or not.
11368 The default value is
11369 .BR zipfile.ZIP_DEFLATED ,
11370 which creates a compressed zip archive.
11371 This value has no effect when using Python 1.5.2
11374 module is otherwise unavailable.
11377 The string displayed when archiving files
11378 using the zip utility.
11379 If this is not set, then $ZIPCOM
11380 (the command line or internal Python function) is displayed.
11383 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
11387 General options passed to the zip utility.
11390 The suffix used for zip file names.
11391 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
11392 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
11394 '\" The descriptions above of the various SCons construction variables
11395 '\" are generated from the .xml files that live next to the various
11396 '\" Python modules in the build enginer library. If you're reading
11397 '\" this [gnt]roff file with an eye towards patching this man page,
11398 '\" you can still submit a diff against this text, but it will have to
11399 '\" be translated to a diff against the underlying .xml file before the
11400 '\" patch is actually accepted. If you do that yourself, it will make
11401 '\" it easier to integrate the patch.
11403 '\" END GENERATED CONSTRUCTION VARIABLE DESCRIPTIONS
11404 '\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
11407 Construction variables can be retrieved and set using the
11409 method of the construction environment:
11412 dict = env.Dictionary()
11416 or using the [] operator:
11422 Construction variables can also be passed to the construction environment
11426 env = Environment(CC="cc")
11429 or when copying a construction environment using the
11434 env2 = env.Clone(CC="cl.exe")
11437 .SS Configure Contexts
11441 .I configure contexts,
11442 an integrated mechanism similar to the
11443 various AC_CHECK macros in GNU autoconf
11444 for testing for the existence of C header
11445 files, libraries, etc.
11446 In contrast to autoconf,
11448 does not maintain an explicit cache of the tested values,
11449 but uses its normal dependency tracking to keep the checked values
11450 up to date. However, users may override this behaviour with the
11452 command line option.
11454 The following methods can be used to perform checks:
11457 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
11459 .RI env.Configure([ custom_tests ", " conf_dir ", " log_file ", " config_h ", " clean ", " help])
11460 This creates a configure context, which can be used to perform checks.
11462 specifies the environment for building the tests.
11463 This environment may be modified when performing checks.
11465 is a dictionary containing custom tests.
11466 See also the section about custom tests below.
11467 By default, no custom tests are added to the configure context.
11469 specifies a directory where the test cases are built.
11470 Note that this directory is not used for building
11472 The default value is the directory
11475 specifies a file which collects the output from commands
11476 that are executed to check for the existence of header files, libraries, etc.
11477 The default is the file #/config.log.
11478 If you are using the
11481 you may want to specify a subdirectory under your variant directory.
11483 specifies a C header file where the results of tests
11484 will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc.
11485 The default is to not write a
11488 You can specify the same
11490 file in multiple calls to Configure,
11493 will concatenate all results in the specified file.
11495 uses its normal dependency checking
11496 to decide if it's necessary to rebuild
11500 This means that the file is not necessarily re-built each
11502 but is only rebuilt if its contents will have changed
11503 and some target that depends on the
11505 file is being built.
11511 arguments can be used to suppress execution of the configuration
11516 options are used, respectively.
11517 The default behavior is always to execute
11518 configure context tests,
11519 since the results of the tests may
11520 affect the list of targets to be cleaned
11522 If the configure tests do not affect these,
11523 then you may add the
11529 to avoid unnecessary test execution.
11534 instance has the following associated methods:
11537 .RI SConf.Finish( context )
11539 .IR sconf .Finish()
11540 This method should be called after configuration is done.
11541 It returns the environment as modified
11542 by the configuration checks performed.
11543 After this method is called, no further checks can be performed
11544 with this configuration context.
11545 However, you can create a new
11547 context to perform additional checks.
11548 Only one context should be active at a time.
11550 The following Checks are predefined.
11551 (This list will likely grow larger as time
11552 goes by and developers contribute new useful tests.)
11555 .RI SConf.CheckHeader( context ", " header ", [" include_quotes ", " language ])
11557 .IR sconf .CheckHeader( header ", [" include_quotes ", " language ])
11560 is usable in the specified language.
11563 in which case the last item in the list
11564 is the header file to be checked,
11565 and the previous list items are
11568 lines should precede the
11569 header line being checked for.
11570 The optional argument
11573 a two character string, where the first character denotes the opening
11574 quote and the second character denotes the closing quote.
11575 By default, both characters are " (double quote).
11576 The optional argument
11582 and selects the compiler to be used for the check.
11583 Returns 1 on success and 0 on failure.
11586 .RI SConf.CheckCHeader( context ", " header ", [" include_quotes ])
11588 .IR sconf .CheckCHeader( header ", [" include_quotes ])
11589 This is a wrapper around
11590 .B SConf.CheckHeader
11593 is usable in the C language.
11596 in which case the last item in the list
11597 is the header file to be checked,
11598 and the previous list items are
11601 lines should precede the
11602 header line being checked for.
11603 The optional argument
11606 a two character string, where the first character denotes the opening
11607 quote and the second character denotes the closing quote (both default
11609 Returns 1 on success and 0 on failure.
11612 .RI SConf.CheckCXXHeader( context ", " header ", [" include_quotes ])
11614 .IR sconf .CheckCXXHeader( header ", [" include_quotes ])
11615 This is a wrapper around
11616 .B SConf.CheckHeader
11619 is usable in the C++ language.
11622 in which case the last item in the list
11623 is the header file to be checked,
11624 and the previous list items are
11627 lines should precede the
11628 header line being checked for.
11629 The optional argument
11632 a two character string, where the first character denotes the opening
11633 quote and the second character denotes the closing quote (both default
11635 Returns 1 on success and 0 on failure.
11638 .RI SConf.CheckFunc( context, ", " function_name ", [" header ", " language ])
11640 .IR sconf .CheckFunc( function_name ", [" header ", " language ])
11641 Checks if the specified
11642 C or C++ function is available.
11644 is the name of the function to check for.
11647 argument is a string
11651 that will be compiled
11652 to check if the function exists;
11658 char function_name();
11666 and selects the compiler to be used for the check;
11667 the default is "C".
11670 .RI SConf.CheckLib( context ", [" library ", " symbol ", " header ", " language ", " autoadd=1 ])
11672 .IR sconf .CheckLib([ library ", " symbol ", " header ", " language ", " autoadd=1 ])
11679 is 1 and the library provides the specified
11681 appends the library to the LIBS construction environment variable.
11683 may also be None (the default),
11686 is checked with the current LIBS variable,
11687 or a list of library names,
11688 in which case each library in the list
11689 will be checked for
11696 .BR SConf.CheckLib ()
11698 you can link against the specified
11706 and selects the compiler to be used for the check;
11707 the default is "C".
11708 The default value for
11711 This method returns 1 on success and 0 on error.
11714 .RI SConf.CheckLibWithHeader( context ", " library ", " header ", " language ", [" call ", " autoadd ])
11716 .IR sconf .CheckLibWithHeader( library ", " header ", " language ", [" call ", " autoadd ])
11720 call, this call provides a more sophisticated way to check against libraries.
11723 specifies the library or a list of libraries to check.
11725 specifies a header to check for.
11728 in which case the last item in the list
11729 is the header file to be checked,
11730 and the previous list items are
11733 lines should precede the
11734 header line being checked for.
11736 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
11738 can be any valid expression (with a trailing ';').
11742 the default simply checks that you
11743 can link against the specified
11746 specifies whether to add the library to the environment (only if the check
11747 succeeds). This method returns 1 on success and 0 on error.
11750 .RI SConf.CheckType( context ", " type_name ", [" includes ", " language ])
11752 .IR sconf .CheckType( type_name ", [" includes ", " language ])
11753 Checks for the existence of a type defined by
11756 specifies the typedef name to check for.
11758 is a string containing one or more
11760 lines that will be inserted into the program
11761 that will be run to test for the existence of the type.
11768 and selects the compiler to be used for the check;
11769 the default is "C".
11772 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
11776 .RI Configure.CheckCC( self )
11777 Checks whether the C compiler (as defined by the CC construction variable) works
11778 by trying to compile a small source file.
11780 By default, SCons only detects if there is a program with the correct name, not
11781 if it is a functioning compiler.
11783 This uses the exact same command than the one used by the object builder for C
11784 source file, so it can be used to detect if a particular compiler flag works or
11788 .RI Configure.CheckCXX( self )
11789 Checks whether the C++ compiler (as defined by the CXX construction variable)
11790 works by trying to compile a small source file. By default, SCons only detects
11791 if there is a program with the correct name, not if it is a functioning compiler.
11793 This uses the exact same command than the one used by the object builder for
11794 CXX source files, so it can be used to detect if a particular compiler flag
11798 .RI Configure.CheckSHCC( self )
11799 Checks whether the C compiler (as defined by the SHCC construction variable) works
11800 by trying to compile a small source file. By default, SCons only detects if
11801 there is a program with the correct name, not if it is a functioning compiler.
11803 This uses the exact same command than the one used by the object builder for C
11804 source file, so it can be used to detect if a particular compiler flag works or
11805 not. This does not check whether the object code can be used to build a shared
11806 library, only that the compilation (not link) succeeds.
11809 .RI Configure.CheckSHCXX( self )
11810 Checks whether the C++ compiler (as defined by the SHCXX construction variable)
11811 works by trying to compile a small source file. By default, SCons only detects
11812 if there is a program with the correct name, not if it is a functioning compiler.
11814 This uses the exact same command than the one used by the object builder for
11815 CXX source files, so it can be used to detect if a particular compiler flag
11816 works or not. This does not check whether the object code can be used to build
11817 a shared library, only that the compilation (not link) succeeds.
11820 Example of a typical Configure usage:
11823 env = Environment()
11824 conf = Configure( env )
11825 if not conf.CheckCHeader( 'math.h' ):
11826 print 'We really need math.h!'
11828 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
11829 'QApplication qapp(0,0);' ):
11830 # do stuff for qt - usage, e.g.
11831 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
11832 env = conf.Finish()
11836 .RI SConf.CheckTypeSize( context ", " type_name ", [" header ", " language ", " expect ])
11838 .IR sconf .CheckTypeSize( type_name ", [" header ", " language ", " expect ])
11839 Checks for the size of a type defined by
11842 specifies the typedef name to check for.
11845 argument is a string
11849 that will be compiled
11850 to check if the function exists;
11851 the default is empty.
11858 and selects the compiler to be used for the check;
11859 the default is "C".
11862 argument should be an integer.
11863 If this argument is used,
11864 the function will only check whether the type
11865 given in type_name has the expected size (in bytes).
11867 .B "CheckTypeSize('short', expect = 2)"
11868 will return success only if short is two bytes.
11874 .RI SConf.CheckDeclaration( context ", " symbol ", [" includes ", " language ])
11876 .IR sconf .CheckDeclaration( symbol ", [" includes ", " language ])
11877 Checks if the specified
11881 is a string containing one or more
11883 lines that will be inserted into the program
11884 that will be run to test for the existence of the type.
11891 and selects the compiler to be used for the check;
11892 the default is "C".
11895 .RI SConf.Define( context ", " symbol ", [" value ", " comment ])
11897 .IR sconf .Define( symbol ", [" value ", " comment ])
11898 This function does not check for anything, but defines a
11899 preprocessor symbol that will be added to the configuration header file.
11900 It is the equivalent of AC_DEFINE,
11901 and defines the symbol
11905 and the optional comment
11912 env = Environment()
11913 conf = Configure( env )
11915 # Puts the following line in the config header file:
11917 conf.Define('A_SYMBOL')
11919 # Puts the following line in the config header file:
11920 # #define A_SYMBOL 1
11921 conf.Define('A_SYMBOL', 1)
11925 Be careful about quoting string values, though:
11928 env = Environment()
11929 conf = Configure( env )
11931 # Puts the following line in the config header file:
11932 # #define A_SYMBOL YA
11933 conf.Define('A_SYMBOL', "YA")
11935 # Puts the following line in the config header file:
11936 # #define A_SYMBOL "YA"
11937 conf.Define('A_SYMBOL', '"YA"')
11944 env = Environment()
11945 conf = Configure( env )
11947 # Puts the following lines in the config header file:
11948 # /* Set to 1 if you have a symbol */
11949 # #define A_SYMBOL 1
11950 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
11954 You can define your own custom checks.
11955 in addition to the predefined checks.
11956 These are passed in a dictionary to the Configure function.
11957 This dictionary maps the names of the checks
11958 to user defined Python callables
11959 (either Python functions or class instances implementing the
11962 The first argument of the call is always a
11964 instance followed by the arguments,
11965 which must be supplied by the user of the check.
11966 These CheckContext instances define the following methods:
11969 .RI CheckContext.Message( self ", " text )
11971 Usually called before the check is started.
11973 will be displayed to the user, e.g. 'Checking for library X...'
11976 .RI CheckContext.Result( self, ", " res )
11978 Usually called after the check is done.
11980 can be either an integer or a string. In the former case, 'ok' (res != 0)
11981 or 'failed' (res == 0) is displayed to the user, in the latter case the
11982 given string is displayed.
11985 .RI CheckContext.TryCompile( self ", " text ", " extension )
11986 Checks if a file with the specified
11988 (e.g. '.c') containing
11990 can be compiled using the environment's
11992 builder. Returns 1 on success and 0 on failure.
11995 .RI CheckContext.TryLink( self ", " text ", " extension )
11996 Checks, if a file with the specified
11998 (e.g. '.c') containing
12000 can be compiled using the environment's
12002 builder. Returns 1 on success and 0 on failure.
12005 .RI CheckContext.TryRun( self ", " text ", " extension )
12006 Checks, if a file with the specified
12008 (e.g. '.c') containing
12010 can be compiled using the environment's
12012 builder. On success, the program is run. If the program
12013 executes successfully
12014 (that is, its return status is 0),
12019 is the standard output of the
12021 If the program fails execution
12022 (its return status is non-zero),
12023 then (0, '') is returned.
12026 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
12027 Checks if the specified
12029 with an optional source file (contents
12036 may be anything which can be converted to a
12043 is the content of the target file.
12049 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
12050 Low level implementation for testing specific builds;
12051 the methods above are based on this method.
12052 Given the Builder instance
12056 of a source file with optional
12058 this method returns 1 on success and 0 on failure. In addition,
12060 is set to the build target node, if the build was successful.
12063 Example for implementing and using custom tests:
12066 def CheckQt(context, qtdir):
12067 context.Message( 'Checking for qt ...' )
12068 lastLIBS = context.env['LIBS']
12069 lastLIBPATH = context.env['LIBPATH']
12070 lastCPPPATH= context.env['CPPPATH']
12071 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
12072 ret = context.TryLink("""
12074 int main(int argc, char **argv) {
12075 QApplication qapp(argc, argv);
12080 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
12081 context.Result( ret )
12084 env = Environment()
12085 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
12086 if not conf.CheckQt('/usr/lib/qt'):
12087 print 'We really need qt!'
12089 env = conf.Finish()
12092 .SS Command-Line Construction Variables
12094 Often when building software,
12095 some variables must be specified at build time.
12096 For example, libraries needed for the build may be in non-standard
12097 locations, or site-specific compiler options may need to be passed to the
12102 object to support overriding construction variables
12103 on the command line:
12105 $ scons VARIABLE=foo
12107 The variable values can also be specified in a text-based SConscript file.
12108 To create a Variables object, call the Variables() function:
12111 .RI Variables([ files "], [" args ])
12112 This creates a Variables object that will read construction variables from
12113 the file or list of filenames specified in
12115 If no files are specified,
12120 then no files will be read.
12121 The optional argument
12124 values that will override anything read from the specified files;
12125 it is primarily intended to be passed the
12127 dictionary that holds variables
12128 specified on the command line.
12132 vars = Variables('custom.py')
12133 vars = Variables('overrides.py', ARGUMENTS)
12134 vars = Variables(None, {FOO:'expansion', BAR:7})
12137 Variables objects have the following methods:
12140 .RI Add( key ", [" help ", " default ", " validator ", " converter ])
12141 This adds a customizable construction variable to the Variables object.
12143 is the name of the variable.
12145 is the help text for the variable.
12147 is the default value of the variable;
12148 if the default value is
12150 and there is no explicit value specified,
12151 the construction variable will
12153 be added to the construction environment.
12155 is called to validate the value of the variable, and should take three
12156 arguments: key, value, and environment.
12157 The recommended way to handle an invalid value is
12158 to raise an exception (see example below).
12160 is called to convert the value before putting it in the environment, and
12161 should take either a value, or the value and environment, as parameters.
12164 must return a value,
12165 which will be converted into a string
12166 before being validated by the
12169 and then added to the environment.
12174 vars.Add('CC', 'The C compiler')
12176 def validate_color(key, val, env):
12177 if not val in ['red', 'blue', 'yellow']:
12178 raise "Invalid color value '%s'" % val
12179 vars.Add('COLOR', validator=valid_color)
12183 .RI AddVariables( list )
12184 A wrapper script that adds
12185 multiple customizable construction variables
12186 to a Variables object.
12188 is a list of tuple or list objects
12189 that contain the arguments
12190 for an individual call to the
12197 ('CC', 'The C compiler'),
12198 ('VALIDATE', 'An option for testing validation',
12199 'notset', validator, None),
12204 .RI Update( env ", [" args ])
12205 This updates a construction environment
12207 with the customized construction variables.
12208 Any specified variables that are
12210 configured for the Variables object
12211 will be saved and may be
12213 .BR UnknownVariables ()
12216 Normally this method is not called directly,
12217 but is called indirectly by passing the Variables object to
12218 the Environment() function:
12221 env = Environment(variables=vars)
12225 The text file(s) that were specified
12226 when the Variables object was created
12227 are executed as Python scripts,
12228 and the values of (global) Python variables set in the file
12229 are added to the construction environment.
12238 .RI UnknownVariables( )
12239 Returns a dictionary containing any
12240 variables that were specified
12241 either in the files or the dictionary
12242 with which the Variables object was initialized,
12243 but for which the Variables object was
12247 env = Environment(variables=vars)
12248 for key, value in vars.UnknownVariables():
12249 print "unknown variable: %s=%s" % (key, value)
12253 .RI Save( filename ", " env )
12254 This saves the currently set variables into a script file named
12256 that can be used on the next invocation to automatically load the current
12257 settings. This method combined with the Variables method can be used to
12258 support caching of variables between runs.
12261 env = Environment()
12262 vars = Variables(['variables.cache', 'custom.py'])
12265 vars.Save('variables.cache', env)
12269 .RI GenerateHelpText( env ", [" sort ])
12270 This generates help text documenting the customizable construction
12271 variables suitable to passing in to the Help() function.
12273 is the construction environment that will be used to get the actual values
12274 of customizable variables. Calling with
12278 will cause the output to be sorted
12279 by the specified argument.
12283 should take two arguments
12286 (like the standard Python
12291 Help(vars.GenerateHelpText(env))
12292 Help(vars.GenerateHelpText(env, sort=cmp))
12296 .RI FormatVariableHelpText( env ", " opt ", " help ", " default ", " actual )
12297 This method returns a formatted string
12298 containing the printable help text
12300 It is normally not called directly,
12301 but is called by the
12302 .IR GenerateHelpText ()
12303 method to create the returned help text.
12304 It may be overridden with your own
12305 function that takes the arguments specified above
12306 and returns a string of help text formatted to your liking.
12308 .IR GenerateHelpText ()
12309 will not put any blank lines or extra
12310 characters in between the entries,
12311 so you must add those characters to the returned
12312 string if you want the entries separated.
12315 def my_format(env, opt, help, default, actual):
12316 fmt = "\n%s: default=%s actual=%s (%s)\n"
12317 return fmt % (opt, default. actual, help)
12318 vars.FormatVariableHelpText = my_format
12321 To make it more convenient to work with customizable Variables,
12323 provides a number of functions
12324 that make it easy to set up
12325 various types of Variables:
12328 .RI BoolVariable( key ", " help ", " default )
12329 Return a tuple of arguments
12330 to set up a Boolean option.
12331 The option will use
12334 have a default value of
12336 and display the specified
12339 The option will interpret the values
12361 .RI EnumVariable( key ", " help ", " default ", " allowed_values ", [" map ", " ignorecase ])
12362 Return a tuple of arguments
12363 to set up an option
12364 whose value may be one
12365 of a specified list of legal enumerated values.
12366 The option will use
12369 have a default value of
12371 and display the specified
12374 The option will only support those
12380 argument is a dictionary
12381 that can be used to convert
12382 input values into specific legal values
12391 then the values are case-sensitive.
12396 then values will be matched
12402 then values will be matched
12404 and all input values will be
12405 converted to lower case.
12408 .RI ListVariable( key ", " help ", " default ", " names ", [", map ])
12409 Return a tuple of arguments
12410 to set up an option
12411 whose value may be one or more
12412 of a specified list of legal enumerated values.
12413 The option will use
12416 have a default value of
12418 and display the specified
12421 The option will only support the values
12424 or the values in the
12427 More than one value may be specified,
12428 with all values separated by commas.
12429 The default may be a string of
12430 comma-separated default values,
12431 or a list of the default values.
12434 argument is a dictionary
12435 that can be used to convert
12436 input values into specific legal values
12442 .RI PackageVariable( key ", " help ", " default )
12443 Return a tuple of arguments
12444 to set up an option
12445 whose value is a path name
12446 of a package that may be
12447 enabled, disabled or
12448 given an explicit path name.
12449 The option will use
12452 have a default value of
12454 and display the specified
12457 The option will support the values
12464 in which case the specified
12467 or the option may be set to an
12469 (typically the path name to a package
12470 that is being enabled).
12471 The option will also support the values
12477 to disable use of the specified option.
12480 .RI PathVariable( key ", " help ", " default ", [" validator ])
12481 Return a tuple of arguments
12482 to set up an option
12483 whose value is expected to be a path name.
12484 The option will use
12487 have a default value of
12489 and display the specified
12495 that will be called to
12496 verify that the specified path
12499 following ready-made validators:
12500 .BR PathVariable.PathExists
12502 which verifies that the specified path exists;
12503 .BR PathVariable.PathIsFile ,
12504 which verifies that the specified path is an existing file;
12505 .BR PathVariable.PathIsDir ,
12506 which verifies that the specified path is an existing directory;
12507 .BR PathVariable.PathIsDirCreate ,
12508 which verifies that the specified path is a directory
12509 and will create the specified directory if the path does not exist;
12511 .BR PathVariable.PathAccept ,
12512 which simply accepts the specific path name argument without validation,
12513 and which is suitable if you want your users
12514 to be able to specify a directory path that will be
12515 created as part of the build process, for example.
12516 You may supply your own
12519 which must take three arguments
12521 the name of the variable to be set;
12523 the specified value being checked;
12526 the construction environment)
12527 and should raise an exception
12528 if the specified value is not acceptable.
12531 These functions make it
12532 convenient to create a number
12533 of variables with consistent behavior
12534 in a single call to the
12540 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
12541 EnumVariable('debug', 'debug output and symbols', 'no'
12542 allowed_values=('yes', 'no', 'full'),
12543 map={}, ignorecase=0), # case sensitive
12544 ListVariable('shared',
12545 'libraries to build as shared libraries',
12547 names = list_of_libs),
12548 PackageVariable('x11',
12549 'use X11 installed here (yes = search some places)',
12551 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
12552 PathVariable('foopath', 'where the foo library is installed', foopath,
12553 PathVariable.PathIsDir),
12558 .SS File and Directory Nodes
12568 Nodes, respectively.
12569 python objects, respectively.
12570 Those objects have several user-visible attributes
12571 and methods that are often useful:
12577 This path is relative to the top-level directory
12581 The build path is the same as the source path if
12586 The absolute build path of the given file or directory.
12596 object representing the
12605 # Get the current build dir's path, relative to top.
12607 # Current dir's absolute path
12609 # Next line is always '.', because it is the top dir's path relative to itself.
12611 File('foo.c').srcnode().path # source path of the given source file.
12613 # Builders also return File objects:
12614 foo = env.Program('foo.c')
12615 print "foo will be built in %s"%foo.path
12622 Node can also be used to create
12623 file and subdirectory Nodes relative to the generating Node.
12626 Node will place the new Nodes within the directory it represents.
12629 node will place the new Nodes within its parent directory
12630 (that is, "beside" the file in question).
12635 (directory) Node and
12640 then these methods are available:
12644 Returns a directory Node for a subdirectory of
12650 .IR d .File( name )
12651 Returns a file Node for a file within
12657 .IR d .Entry( name )
12658 Returns an unresolved Node within
12665 Returns a directory named
12667 within the parent directory of
12671 .IR f .File( name )
12672 Returns a file named
12674 within the parent directory of
12678 .IR f .Entry( name )
12679 Returns an unresolved Node named
12681 within the parent directory of
12688 # Get a Node for a file within a directory
12689 incl = Dir('include')
12690 f = incl.File('header.h')
12692 # Get a Node for a subdirectory within a directory
12693 dist = Dir('project-3.2.1)
12694 src = dist.Dir('src')
12696 # Get a Node for a file in the same directory
12697 cfile = File('sample.c')
12698 hfile = cfile.File('sample.h')
12702 html = docs.Dir('html')
12703 index = html.File('index.html')
12704 css = index.File('app.css')
12707 .SH EXTENDING SCONS
12708 .SS Builder Objects
12710 can be extended to build different types of targets
12711 by adding new Builder objects
12712 to a construction environment.
12714 you should only need to add a new Builder object
12715 when you want to build a new type of file or other external target.
12716 If you just want to invoke a different compiler or other tool
12717 to build a Program, Object, Library, or any other
12718 type of output file for which
12720 already has an existing Builder,
12721 it is generally much easier to
12722 use those existing Builders
12723 in a construction environment
12724 that sets the appropriate construction variables
12727 Builder objects are created
12733 function accepts the following arguments:
12736 The command line string used to build the target from the source.
12739 a list of strings representing the command
12740 to be executed and its arguments
12741 (suitable for enclosing white space in an argument),
12743 mapping source file name suffixes to
12744 any combination of command line strings
12745 (if the builder should accept multiple source file extensions),
12748 (see the next section);
12749 or a list of any of the above.
12752 takes three arguments:
12754 - a list of source nodes,
12756 - a list of target nodes,
12758 - the construction environment.
12761 The prefix that will be prepended to the target file name.
12762 This may be specified as a:
12772 - a function or other callable that takes
12773 two arguments (a construction environment and a list of sources)
12774 and returns a prefix,
12779 - specifies a mapping from a specific source suffix (of the first
12780 source specified) to a corresponding target prefix. Both the source
12781 suffix and target prefix specifications may use environment variable
12782 substitution, and the target prefix (the 'value' entries in the
12783 dictionary) may also be a callable object. The default target prefix
12784 may be indicated by a dictionary entry with a key value of None.
12789 b = Builder("build_it < $SOURCE > $TARGET"
12792 def gen_prefix(env, sources):
12793 return "file-" + env['PLATFORM'] + '-'
12794 b = Builder("build_it < $SOURCE > $TARGET",
12795 prefix = gen_prefix)
12797 b = Builder("build_it < $SOURCE > $TARGET",
12798 suffix = { None: "file-",
12799 "$SRC_SFX_A": gen_prefix })
12803 The suffix that will be appended to the target file name.
12804 This may be specified in the same manner as the prefix above.
12805 If the suffix is a string, then
12807 will append a '.' to the beginning of the suffix if it's not already
12808 there. The string returned by callable object (or obtained from the
12809 dictionary) is untouched and must append its own '.' to the beginning
12813 b = Builder("build_it < $SOURCE > $TARGET"
12816 def gen_suffix(env, sources):
12817 return "." + env['PLATFORM'] + "-file"
12818 b = Builder("build_it < $SOURCE > $TARGET",
12819 suffix = gen_suffix)
12821 b = Builder("build_it < $SOURCE > $TARGET",
12822 suffix = { None: ".sfx1",
12823 "$SRC_SFX_A": gen_suffix })
12827 When set to any true value, causes
12829 to add the target suffix specified by the
12831 keyword to any target strings
12832 that have a different suffix.
12833 (The default behavior is to leave untouched
12834 any target file name that looks like it already has any suffix.)
12837 b1 = Builder("build_it < $SOURCE > $TARGET"
12839 b2 = Builder("build_it < $SOURCE > $TARGET"
12842 env = Environment()
12843 env['BUILDERS']['B1'] = b1
12844 env['BUILDERS']['B2'] = b2
12846 # Builds "foo.txt" because ensure_suffix is not set.
12847 env.B1('foo.txt', 'foo.in')
12849 # Builds "bar.txt.out" because ensure_suffix is set.
12850 env.B2('bar.txt', 'bar.in')
12854 The expected source file name suffix. This may be a string or a list
12858 A Scanner object that
12859 will be invoked to find
12860 implicit dependencies for this target file.
12861 This keyword argument should be used
12862 for Scanner objects that find
12863 implicit dependencies
12864 based only on the target file
12865 and the construction environment,
12868 (See the section "Scanner Objects," below,
12869 for information about creating Scanner objects.)
12872 A Scanner object that
12874 find implicit dependences in
12876 used to build this target file.
12877 This is where you would
12878 specify a scanner to
12881 lines in source files.
12884 Scanner object may be used to
12885 indicate that this Builder
12886 should scan directory trees
12887 for on-disk changes to files
12890 does not know about from other Builder or function calls.
12891 (See the section "Scanner Objects," below,
12892 for information about creating your own Scanner objects.)
12895 A factory function that the Builder will use
12896 to turn any targets specified as strings into SCons Nodes.
12898 SCons assumes that all targets are files.
12899 Other useful target_factory
12902 for when a Builder creates a directory target,
12905 for when a Builder can create either a file
12906 or directory target.
12911 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
12912 env = Environment()
12913 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
12914 env.MakeDirectory('new_directory', [])
12918 Note that the call to the MakeDirectory Builder
12919 needs to specify an empty source list
12920 to make the string represent the builder's target;
12921 without that, it would assume the argument is the source,
12922 and would try to deduce the target name from it,
12923 which in the absence of an automatically-added prefix or suffix
12924 would lead to a matching target and source name
12925 and a circular dependency.
12928 A factory function that the Builder will use
12929 to turn any sources specified as strings into SCons Nodes.
12931 SCons assumes that all source are files.
12932 Other useful source_factory
12935 for when a Builder uses a directory as a source,
12938 for when a Builder can use files
12939 or directories (or both) as sources.
12944 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
12945 env = Environment()
12946 env.Append(BUILDERS = {'Collect':CollectBuilder})
12947 env.Collect('archive', ['directory_name', 'file_name'])
12951 A function or list of functions to manipulate the target and source
12952 lists before dependencies are established
12953 and the target(s) are actually built.
12955 can also be a string containing a construction variable to expand
12956 to an emitter function or list of functions,
12957 or a dictionary mapping source file suffixes
12958 to emitter functions.
12959 (Only the suffix of the first source file
12960 is used to select the actual emitter function
12961 from an emitter dictionary.)
12963 An emitter function
12964 takes three arguments:
12966 - a list of source nodes,
12968 - a list of target nodes,
12970 - the construction environment.
12971 An emitter must return a tuple containing two lists,
12972 the list of targets to be built by this builder,
12973 and the list of sources for this builder.
12978 def e(target, source, env):
12979 return (target + ['foo.foo'], source + ['foo.src'])
12981 # Simple association of an emitter function with a Builder.
12982 b = Builder("my_build < $TARGET > $SOURCE",
12985 def e2(target, source, env):
12986 return (target + ['bar.foo'], source + ['bar.src'])
12988 # Simple association of a list of emitter functions with a Builder.
12989 b = Builder("my_build < $TARGET > $SOURCE",
12992 # Calling an emitter function through a construction variable.
12993 env = Environment(MY_EMITTER = e)
12994 b = Builder("my_build < $TARGET > $SOURCE",
12995 emitter = '$MY_EMITTER')
12997 # Calling a list of emitter functions through a construction variable.
12998 env = Environment(EMITTER_LIST = [e, e2])
12999 b = Builder("my_build < $TARGET > $SOURCE",
13000 emitter = '$EMITTER_LIST')
13002 # Associating multiple emitters with different file
13003 # suffixes using a dictionary.
13004 def e_suf1(target, source, env):
13005 return (target + ['another_target_file'], source)
13006 def e_suf2(target, source, env):
13007 return (target, source + ['another_source_file'])
13008 b = Builder("my_build < $TARGET > $SOURCE",
13009 emitter = {'.suf1' : e_suf1,
13014 Specifies whether this builder is allowed to be called multiple times for
13015 the same target file(s). The default is 0, which means the builder
13016 can not be called multiple times for the same target file(s). Calling a
13017 builder multiple times for the same target simply adds additional source
13018 files to the target; it is not allowed to change the environment associated
13019 with the target, specify addition environment overrides, or associate a different
13020 builder with the target.
13023 A construction environment that can be used
13024 to fetch source code using this Builder.
13025 (Note that this environment is
13027 used for normal builds of normal target files,
13028 which use the environment that was
13029 used to call the Builder for the target file.)
13032 A function that returns a list of actions that will be executed to build
13033 the target(s) from the source(s).
13034 The returned action(s) may be
13035 an Action object, or anything that
13036 can be converted into an Action object
13037 (see the next section).
13039 The generator function
13040 takes four arguments:
13042 - a list of source nodes,
13044 - a list of target nodes,
13046 - the construction environment,
13048 - a Boolean value that specifies
13049 whether the generator is being called
13050 for generating a build signature
13051 (as opposed to actually executing the command).
13055 def g(source, target, env, for_signature):
13056 return [["gcc", "-c", "-o"] + target + source]
13058 b = Builder(generator=g)
13066 arguments must not both be used for the same Builder.
13069 Specifies a builder to use when a source file name suffix does not match
13070 any of the suffixes of the builder. Using this argument produces a
13071 multi-stage builder.
13074 Specifies that this builder expects exactly one source file per call. Giving
13075 more than one source files without target files results in implicitely calling
13076 the builder multiple times (once for each source given). Giving multiple
13077 source files together with target files results in a UserError exception.
13085 arguments must not both be used for the same Builder.
13087 .IP source_ext_match
13090 argument is a dictionary,
13091 the default behavior when a builder is passed
13092 multiple source files is to make sure that the
13093 extensions of all the source files match.
13094 If it is legal for this builder to be
13095 called with a list of source files with different extensions,
13096 this check can be suppressed by setting
13097 .B source_ext_match
13100 or some other non-true value.
13102 .B source_ext_match
13105 will use the suffix of the first specified
13106 source file to select the appropriate action from the
13110 In the following example,
13112 .B source_ext_match
13115 from exiting with an error
13116 due to the mismatched suffixes of
13122 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
13123 source_ext_match = None)
13125 env = Environment(BUILDERS = {'MyBuild':b})
13126 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
13130 A construction environment that can be used
13131 to fetch source code using this Builder.
13132 (Note that this environment is
13134 used for normal builds of normal target files,
13135 which use the environment that was
13136 used to call the Builder for the target file.)
13139 b = Builder(action="build < $SOURCE > $TARGET")
13140 env = Environment(BUILDERS = {'MyBuild' : b})
13141 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
13145 A directory from which scons
13147 action(s) specified
13152 a string or a directory Node,
13153 scons will change to the specified directory.
13156 is not a string or Node
13158 then scons will change to the
13159 target file's directory.
13161 Note that scons will
13163 automatically modify
13165 construction variables like
13169 when using the chdir
13170 keyword argument--that is,
13171 the expanded file names
13172 will still be relative to
13173 the top-level SConstruct directory,
13174 and consequently incorrect
13175 relative to the chdir directory.
13176 Builders created using chdir keyword argument,
13177 will need to use construction variable
13182 to use just the filename portion of the
13183 targets and source.
13186 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
13188 env = Environment(BUILDERS = {'MyBuild' : b})
13189 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
13193 Python only keeps one current directory
13194 location for all of the threads.
13195 This means that use of the
13200 work with the SCons
13203 because individual worker threads spawned
13204 by SCons interfere with each other
13205 when they start changing directory.
13208 Any additional keyword arguments supplied
13209 when a Builder object is created
13210 (that is, when the Builder() function is called)
13211 will be set in the executing construction
13212 environment when the Builder object is called.
13213 The canonical example here would be
13214 to set a construction variable to
13215 the repository of a source code system.
13217 Any additional keyword arguments supplied
13221 will only be associated with the target
13222 created by that particular Builder call
13223 (and any other files built as a
13224 result of the call).
13226 These extra keyword arguments are passed to the
13227 following functions:
13228 command generator functions,
13230 and emitter functions.
13236 function will turn its
13238 keyword argument into an appropriate
13239 internal Action object.
13240 You can also explicity create Action objects
13244 which can then be passed to the
13247 This can be used to configure
13248 an Action object more flexibly,
13249 or it may simply be more efficient
13250 than letting each separate Builder object
13251 create a separate Action
13253 Builder objects need to do the same thing.
13258 returns an appropriate object for the action
13259 represented by the type of the first argument:
13262 If the first argument is already an Action object,
13263 the object is simply returned.
13266 If the first argument is a string,
13267 a command-line Action is returned.
13268 Note that the command-line string
13269 may be preceded by an
13272 to suppress printing of the specified command line,
13276 to ignore the exit status from the specified command:
13279 Action('$CC -c -o $TARGET $SOURCES')
13281 # Doesn't print the line being executed.
13282 Action('@build $TARGET $SOURCES')
13284 # Ignores return value
13285 Action('-build $TARGET $SOURCES')
13287 .\" XXX From Gary Ruben, 23 April 2002:
13288 .\" What would be useful is a discussion of how you execute command
13289 .\" shell commands ie. what is the process used to spawn the shell, pass
13290 .\" environment variables to it etc., whether there is one shell per
13291 .\" environment or one per command etc. It might help to look at the Gnu
13292 .\" make documentation to see what they think is important to discuss about
13293 .\" a build system. I'm sure you can do a better job of organising the
13294 .\" documentation than they have :-)
13297 If the first argument is a list,
13298 then a list of Action objects is returned.
13299 An Action object is created as necessary
13300 for each element in the list.
13303 the list is itself a list,
13304 the internal list is the
13305 command and arguments to be executed via
13307 This allows white space to be enclosed
13308 in an argument by defining
13309 a command in a list within a list:
13312 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
13316 If the first argument is a Python function,
13317 a function Action is returned.
13318 The Python function must take three keyword arguments,
13320 (a Node object representing the target file),
13322 (a Node object representing the source file)
13325 (the construction environment
13326 used for building the target file).
13331 arguments may be lists of Node objects if there is
13332 more than one target file or source file.
13333 The actual target and source file name(s) may
13334 be retrieved from their Node objects
13335 via the built-in Python str() function:
13338 target_file_name = str(target)
13339 source_file_names = map(lambda x: str(x), source)
13342 The function should return
13346 to indicate a successful build of the target file(s).
13347 The function may raise an exception
13348 or return a non-zero exit status
13349 to indicate an unsuccessful build.
13352 def build_it(target = None, source = None, env = None):
13353 # build the target from the source
13356 a = Action(build_it)
13359 If the action argument is not one of the above,
13363 The second argument is optional and is used to define the output
13364 which is printed when the Action is actually performed.
13365 In the absence of this parameter,
13366 or if it's an empty string,
13367 a default output depending on the type of the action is used.
13368 For example, a command-line action will print the executed command.
13369 The argument must be either a Python function or a string.
13372 it's a function that returns a string to be printed
13373 to describe the action being executed.
13374 The function may also be specified by the
13377 Like a function to build a file,
13378 this function must take three keyword arguments:
13380 (a Node object representing the target file),
13382 (a Node object representing the source file)
13385 (a construction environment).
13390 arguments may be lists of Node objects if there is
13391 more than one target file or source file.
13393 In the second case, you provide the string itself.
13394 The string may also be specified by the
13397 The string typically contains variables, notably
13398 $TARGET(S) and $SOURCE(S), or consists of just a single
13399 variable, which is optionally defined somewhere else.
13400 SCons itself heavily uses the latter variant.
13405 def build_it(target, source, env):
13406 # build the target from the source
13409 def string_it(target, source, env):
13410 return "building '%s' from '%s'" % (target[0], source[0])
13412 # Use a positional argument.
13413 f = Action(build_it, string_it)
13414 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
13416 # Alternatively, use a keyword argument.
13417 f = Action(build_it, strfunction=string_it)
13418 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
13420 # You can provide a configurable variable.
13421 l = Action(build_it, '$STRINGIT')
13424 The third and succeeding arguments, if present,
13425 may either be a construction variable or a list of construction variables
13426 whose values will be included in the signature of the Action
13427 when deciding whether a target should be rebuilt because the action changed.
13428 The variables may also be specified by a
13431 if both are present, they are combined.
13432 This is necessary whenever you want a target to be rebuilt
13433 when a specific construction variable changes.
13434 This is not often needed for a string action,
13435 as the expanded variables will normally be part of the command line,
13436 but may be needed if a Python function action uses
13437 the value of a construction variable when generating the command line.
13440 def build_it(target, source, env):
13441 # build the target from the 'XXX' construction variable
13442 open(target[0], 'w').write(env['XXX'])
13445 # Use positional arguments.
13446 a = Action(build_it, '$STRINGIT', ['XXX'])
13448 # Alternatively, use a keyword argument.
13449 a = Action(build_it, varlist=['XXX'])
13458 which specifies that
13459 scons will execute the action
13460 after changing to the specified directory.
13461 If the chdir argument is
13462 a string or a directory Node,
13463 scons will change to the specified directory.
13464 If the chdir argument
13465 is not a string or Node
13467 then scons will change to the
13468 target file's directory.
13470 Note that scons will
13472 automatically modify
13474 construction variables like
13478 when using the chdir
13479 keyword argument--that is,
13480 the expanded file names
13481 will still be relative to
13482 the top-level SConstruct directory,
13483 and consequently incorrect
13484 relative to the chdir directory.
13485 Builders created using chdir keyword argument,
13486 will need to use construction variable
13491 to use just the filename portion of the
13492 targets and source.
13495 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
13505 which specifies a function
13506 that is passed the exit status
13508 from the specified action
13509 and can return an arbitrary
13511 This can be used, for example,
13512 to specify that an Action object's
13513 return value should be ignored
13514 and SCons should, therefore,
13515 consider that the action always suceeds:
13518 def always_succeed(s):
13519 # Always return 0, which indicates success.
13521 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
13522 exitstatfunc=always_succeed)
13525 .SS Miscellaneous Action Functions
13528 supplies a number of functions
13529 that arrange for various common
13530 file and directory manipulations
13532 These are similar in concept to "tasks" in the
13534 although the implementation is slightly different.
13535 These functions do not actually
13536 perform the specified action
13537 at the time the function is called,
13538 but instead return an Action object
13539 that can be executed at the
13541 (In Object-Oriented terminology,
13546 that return Action objects.)
13549 there are two natural ways
13552 are intended to be used.
13556 to perform the action
13557 at the time the SConscript
13558 file is being read,
13561 global function to do so:
13563 Execute(Touch('file'))
13567 you can use these functions
13568 to supply Actions in a list
13572 This can allow you to
13573 perform more complicated
13574 sequences of file manipulation
13576 on platform-specific
13580 env = Environment(TMPBUILD = '/tmp/builddir')
13581 env.Command('foo.out', 'foo.in',
13582 [Mkdir('$TMPBUILD'),
13583 Copy('$TMPBUILD', '${SOURCE.dir}'),
13584 "cd $TMPBUILD && make",
13585 Delete('$TMPBUILD')])
13589 .RI Chmod( dest ", " mode )
13590 Returns an Action object that
13591 changes the permissions on the specified
13593 file or directory to the specified
13598 Execute(Chmod('file', 0755))
13600 env.Command('foo.out', 'foo.in',
13601 [Copy('$TARGET', '$SOURCE'),
13602 Chmod('$TARGET', 0755)])
13606 .RI Copy( dest ", " src )
13607 Returns an Action object
13610 source file or directory to the
13612 destination file or directory.
13616 Execute(Copy('foo.output', 'foo.input'))
13618 env.Command('bar.out', 'bar.in',
13619 Copy('$TARGET', '$SOURCE'))
13623 .RI Delete( entry ", [" must_exist ])
13624 Returns an Action that
13625 deletes the specified
13627 which may be a file or a directory tree.
13628 If a directory is specified,
13629 the entire directory tree
13634 then a Python error will be thrown
13635 if the specified entry does not exist;
13638 that is, the Action will silently do nothing
13639 if the entry does not exist.
13643 Execute(Delete('/tmp/buildroot'))
13645 env.Command('foo.out', 'foo.in',
13646 [Delete('${TARGET.dir}'),
13649 Execute(Delete('file_that_must_exist', must_exist=1))
13655 that creates the specified
13661 Execute(Mkdir('/tmp/outputdir'))
13663 env.Command('foo.out', 'foo.in',
13664 [Mkdir('/tmp/builddir',
13665 Copy('$SOURCE', '/tmp/builddir/foo.in')
13666 "cd /tmp/builddir && make",
13667 Copy('/tmp/builddir/foo.out', '$TARGET')])
13671 .RI Move( dest ", " src )
13673 that moves the specified
13675 file or directory to
13682 Execute(Move('file.destination', 'file.source'))
13684 env.Command('output_file', 'input_file',
13686 Move('$TARGET', 'file_created_by_MyBuildAction')])
13692 that updates the modification time
13698 Execute(Touch('file_to_be_touched'))
13700 env.Command('marker', 'input_file',
13705 .SS Variable Substitution
13707 Before executing a command,
13709 performs construction variable interpolation on the strings that make up
13710 the command line of builders.
13711 Variables are introduced by a
13714 Besides construction variables, scons provides the following
13715 variables for each command execution:
13718 The file name of the target being built, or the file name of the first
13719 target if multiple targets are being built.
13722 The file names of all targets being built.
13725 The file name of the source of the build command, or the file name of the
13726 first source if multiple sources are being built.
13729 The file names of the sources of the build command.
13731 (Note that the above variables are reserved
13732 and may not be set in a construction environment.)
13735 For example, given the construction variable CC='cc', targets=['foo'], and
13736 sources=['foo.c', 'bar.c']:
13739 action='$CC -c -o $TARGET $SOURCES'
13742 would produce the command line:
13745 cc -c -o foo foo.c bar.c
13748 Variable names may be surrounded by curly braces ({})
13749 to separate the name from the trailing characters.
13750 Within the curly braces, a variable name may have
13751 a Python slice subscript appended to select one
13752 or more items from a list.
13753 In the previous example, the string:
13765 Additionally, a variable name may
13766 have the following special
13767 modifiers appended within the enclosing curly braces
13768 to modify the interpolated string:
13771 The base path of the file name,
13772 including the directory path
13773 but excluding any suffix.
13776 The name of the directory in which the file exists.
13780 minus any directory portion.
13783 Just the basename of the file,
13785 and minus the directory.
13788 Just the file suffix.
13791 The absolute path name of the file.
13794 The POSIX form of the path,
13795 with directories separated by
13799 This is sometimes necessary on Windows systems
13800 when a path references a file on other (POSIX) systems.
13803 The directory and file name to the source file linked to this file through
13805 If this file isn't linked,
13806 it just returns the directory and filename unchanged.
13809 The directory containing the source file linked to this file through
13811 If this file isn't linked,
13812 it just returns the directory part of the filename.
13815 The directory and file name to the source file linked to this file through
13817 If the file does not exist locally but exists in a Repository,
13818 the path in the Repository is returned.
13819 If this file isn't linked, it just returns the
13820 directory and filename unchanged.
13823 The Repository directory containing the source file linked to this file through
13825 If this file isn't linked,
13826 it just returns the directory part of the filename.
13829 For example, the specified target will
13830 expand as follows for the corresponding modifiers:
13833 $TARGET => sub/dir/file.x
13834 ${TARGET.base} => sub/dir/file
13835 ${TARGET.dir} => sub/dir
13836 ${TARGET.file} => file.x
13837 ${TARGET.filebase} => file
13838 ${TARGET.suffix} => .x
13839 ${TARGET.abspath} => /top/dir/sub/dir/file.x
13841 SConscript('src/SConscript', variant_dir='sub/dir')
13842 $SOURCE => sub/dir/file.x
13843 ${SOURCE.srcpath} => src/file.x
13844 ${SOURCE.srcdir} => src
13846 Repository('/usr/repository')
13847 $SOURCE => sub/dir/file.x
13848 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
13849 ${SOURCE.rsrcdir} => /usr/repository/src
13852 Note that curly braces braces may also be used
13853 to enclose arbitrary Python code to be evaluated.
13854 (In fact, this is how the above modifiers are substituted,
13855 they are simply attributes of the Python objects
13856 that represent TARGET, SOURCES, etc.)
13857 See the section "Python Code Substitution," below,
13858 for more thorough examples of
13859 how this can be used.
13861 Lastly, a variable name
13862 may be a callable Python function
13864 construction variable in the environment.
13865 The function should
13866 take four arguments:
13868 - a list of target nodes,
13870 - a list of source nodes,
13872 - the construction environment,
13874 - a Boolean value that specifies
13875 whether the function is being called
13876 for generating a build signature.
13877 SCons will insert whatever
13878 the called function returns
13879 into the expanded string:
13882 def foo(target, source, env, for_signature):
13885 # Will expand $BAR to "bar baz"
13886 env=Environment(FOO=foo, BAR="$FOO baz")
13889 You can use this feature to pass arguments to a
13890 Python function by creating a callable class
13891 that stores one or more arguments in an object,
13892 and then uses them when the
13895 Note that in this case,
13896 the entire variable expansion must
13897 be enclosed by curly braces
13898 so that the arguments will
13899 be associated with the
13900 instantiation of the class:
13904 def __init__(self, arg):
13907 def __call__(self, target, source, env, for_signature):
13908 return self.arg + " bar"
13910 # Will expand $BAR to "my argument bar baz"
13911 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
13915 The special pseudo-variables
13919 may be used to surround parts of a command line
13922 causing a rebuild--that is,
13923 which are not included in the signature
13924 of target files built with this command.
13929 will be removed from the command line
13930 before it is added to file signatures,
13935 will be removed before the command is executed.
13936 For example, the command line:
13939 echo Last build occurred $( $TODAY $). > $TARGET
13943 would execute the command:
13946 echo Last build occurred $TODAY. > $TARGET
13950 but the command signature added to any target files would be:
13953 echo Last build occurred . > $TARGET
13956 .SS Python Code Substitution
13958 Any python code within
13960 pairs gets evaluated by python 'eval', with the python globals set to
13961 the current environment's set of construction variables.
13962 So in the following case:
13965 env.Command('foo.out', 'foo.in',
13966 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
13968 the command executed will be either
13976 according to the current value of env['COND'] when the command is
13977 executed. The evaluation occurs when the target is being
13978 built, not when the SConscript is being read. So if env['COND'] is changed
13979 later in the SConscript, the final value will be used.
13981 Here's a more interesting example. Note that all of COND, FOO, and
13982 BAR are environment variables, and their values are substituted into
13983 the final command. FOO is a list, so its elements are interpolated
13984 separated by spaces.
13989 env['FOO'] = ['foo1', 'foo2']
13990 env['BAR'] = 'barbar'
13991 env.Command('foo.out', 'foo.in',
13992 'echo ${COND==1 and FOO or BAR} > $TARGET')
13994 # Will execute this:
13995 # echo foo1 foo2 > foo.out
13998 SCons uses the following rules when converting construction variables into
14002 When the value is a string it is interpreted as a space delimited list of
14003 command line arguments.
14006 When the value is a list it is interpreted as a list of command line
14007 arguments. Each element of the list is converted to a string.
14010 Anything that is not a list or string is converted to a string and
14011 interpreted as a single command line argument.
14014 Newline characters (\\n) delimit lines. The newline parsing is done after
14015 all other parsing, so it is not possible for arguments (e.g. file names) to
14016 contain embedded newline characters. This limitation will likely go away in
14017 a future version of SCons.
14019 .SS Scanner Objects
14025 new file types for implicit dependencies.
14026 Scanner accepts the following arguments:
14029 This can be either:
14030 1) a Python function that will process
14032 and return a list of strings (file names)
14033 representing the implicit
14034 dependencies found in the contents;
14036 2) a dictionary that maps keys
14037 (typically the file suffix, but see below for more discussion)
14038 to other Scanners that should be called.
14040 If the argument is actually a Python function,
14041 the function must take three or four arguments:
14043 def scanner_function(node, env, path):
14045 def scanner_function(node, env, path, arg=None):
14049 argument is the internal
14050 SCons node representing the file.
14053 to fetch the name of the file, and
14054 .B node.get_contents()
14055 to fetch contents of the file.
14056 Note that the file is
14058 guaranteed to exist before the scanner is called,
14059 so the scanner function should check that
14060 if there's any chance that the scanned file
14062 (for example, if it's built from other files).
14066 argument is the construction environment for the scan.
14067 Fetch values from it using the
14068 .B env.Dictionary()
14073 argument is a tuple (or list)
14074 of directories that can be searched
14076 This will usually be the tuple returned by the
14078 argument (see below).
14082 argument is the argument supplied
14083 when the scanner was created, if any.
14086 The name of the Scanner.
14087 This is mainly used
14088 to identify the Scanner internally.
14091 An optional argument that, if specified,
14092 will be passed to the scanner function
14094 and the path function
14098 An optional list that can be used to
14099 determine which scanner should be used for
14101 In the usual case of scanning for file names,
14102 this argument will be a list of suffixes
14103 for the different file types that this
14104 Scanner knows how to scan.
14105 If the argument is a string,
14106 then it will be expanded
14107 into a list by the current environment.
14110 A Python function that takes four or five arguments:
14111 a construction environment,
14112 a Node for the directory containing
14113 the SConscript file in which
14114 the first target was defined,
14115 a list of target nodes,
14116 a list of source nodes,
14117 and an optional argument supplied
14118 when the scanner was created.
14121 returns a tuple of directories
14122 that can be searched for files to be returned
14123 by this Scanner object.
14125 .BR FindPathDirs ()
14126 function can be used to return a ready-made
14128 for a given construction variable name,
14129 instead of having to write your own function from scratch.)
14132 The class of Node that should be returned
14133 by this Scanner object.
14134 Any strings or other objects returned
14135 by the scanner function
14136 that are not of this class
14137 will be run through the
14142 A Python function that will take a string
14144 and turn it into the appropriate class of Node
14145 to be returned by this Scanner object.
14148 An optional Python function that takes two arguments,
14149 a Node (file) and a construction environment,
14150 and returns whether the
14151 Node should, in fact,
14152 be scanned for dependencies.
14153 This check can be used to eliminate unnecessary
14154 calls to the scanner function when,
14155 for example, the underlying file
14156 represented by a Node does not yet exist.
14159 An optional flag that
14160 specifies whether this scanner should be re-invoked
14161 on the dependency files returned by the scanner.
14162 When this flag is not set,
14163 the Node subsystem will
14164 only invoke the scanner on the file being scanned,
14165 and not (for example) also on the files
14166 specified by the #include lines
14167 in the file being scanned.
14169 may be a callable function,
14170 in which case it will be called with a list of
14172 should return a list of Nodes
14173 that should be scanned recursively;
14174 this can be used to select a specific subset of
14175 Nodes for additional scanning.
14180 .B SourceFileScanner
14181 object that is used by
14184 .BR SharedObject (),
14186 .BR StaticObject ()
14188 which scanner should be used
14189 for different file extensions.
14191 .BR SourceFileScanner.add_scanner ()
14192 method to add your own Scanner object
14196 that builds target programs or
14197 libraries from a list of
14198 source files of different types:
14201 def xyz_scan(node, env, path):
14202 contents = node.get_contents()
14203 # Scan the contents and return the included files.
14205 XYZScanner = Scanner(xyz_scan)
14207 SourceFileScanner.add_scanner('.xyx', XYZScanner)
14209 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
14212 .SH SYSTEM-SPECIFIC BEHAVIOR
14213 SCons and its configuration files are very portable,
14214 due largely to its implementation in Python.
14215 There are, however, a few portability
14216 issues waiting to trap the unwary.
14218 SCons handles the upper-case
14220 file suffix differently,
14221 depending on the capabilities of
14222 the underlying system.
14223 On a case-sensitive system
14224 such as Linux or UNIX,
14225 SCons treats a file with a
14227 suffix as a C++ source file.
14228 On a case-insensitive system
14230 SCons treats a file with a
14232 suffix as a C source file.
14234 SCons handles the upper-case
14236 file suffix differently,
14237 depending on the capabilities of
14238 the underlying system.
14239 On a case-sensitive system
14240 such as Linux or UNIX,
14241 SCons treats a file with a
14243 suffix as a Fortran source file
14244 that is to be first run through
14245 the standard C preprocessor.
14246 On a case-insensitive system
14248 SCons treats a file with a
14250 suffix as a Fortran source file that should
14252 be run through the C preprocessor.
14253 .SS Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
14254 Cygwin supplies a set of tools and utilities
14255 that let users work on a
14256 Windows system using a more POSIX-like environment.
14257 The Cygwin tools, including Cygwin Python,
14259 by sharing an ability to interpret UNIX-like path names.
14260 For example, the Cygwin tools
14261 will internally translate a Cygwin path name
14262 like /cygdrive/c/mydir
14263 to an equivalent Windows pathname
14264 of C:/mydir (equivalent to C:\\mydir).
14267 that are built for native Windows execution,
14268 such as the python.org and ActiveState versions,
14269 do not have the Cygwin path name semantics.
14270 This means that using a native Windows version of Python
14271 to build compiled programs using Cygwin tools
14272 (such as gcc, bison, and flex)
14273 may yield unpredictable results.
14274 "Mixing and matching" in this way
14275 can be made to work,
14276 but it requires careful attention to the use of path names
14277 in your SConscript files.
14279 In practice, users can sidestep
14280 the issue by adopting the following rules:
14282 use the Cygwin-supplied Python interpreter
14284 when using Microsoft Visual C/C++
14285 (or some other Windows compiler)
14286 use the python.org or ActiveState version of Python
14288 .SS Windows: scons.bat file
14289 On Windows systems,
14290 SCons is executed via a wrapper
14293 This has (at least) two ramifications:
14295 First, Windows command-line users
14296 that want to use variable assignment
14297 on the command line
14298 may have to put double quotes
14299 around the assignments:
14302 scons "FOO=BAR" "BAZ=BLEH"
14305 Second, the Cygwin shell does not
14306 recognize this file as being the same
14309 command issued at the command-line prompt.
14310 You can work around this either by
14313 from the Cygwin command line,
14314 or by creating a wrapper shell
14320 The MinGW bin directory must be in your PATH environment variable or the
14321 PATH variable under the ENV construction variable for SCons
14322 to detect and use the MinGW tools. When running under the native Windows
14323 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
14324 tools, if they are both installed, regardless of the order of the bin
14325 directories in the PATH variable. If you have both MSVC and MinGW
14326 installed and you want to use MinGW instead of MSVC,
14327 then you must explictly tell SCons to use MinGW by passing
14333 to the Environment() function, because SCons will prefer the MSVC tools
14334 over the MinGW tools.
14338 To help you get started using SCons,
14339 this section contains a brief overview of some common tasks.
14341 .SS Basic Compilation From a Single Source File
14344 env = Environment()
14345 env.Program(target = 'foo', source = 'foo.c')
14348 Note: Build the file by specifying
14349 the target as an argument
14350 ("scons foo" or "scons foo.exe").
14351 or by specifying a dot ("scons .").
14353 .SS Basic Compilation From Multiple Source Files
14356 env = Environment()
14357 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
14360 .SS Setting a Compilation Flag
14363 env = Environment(CCFLAGS = '-g')
14364 env.Program(target = 'foo', source = 'foo.c')
14367 .SS Search The Local Directory For .h Files
14371 need to set CCFLAGS to specify -I options by hand.
14372 SCons will construct the right -I options from CPPPATH.
14375 env = Environment(CPPPATH = ['.'])
14376 env.Program(target = 'foo', source = 'foo.c')
14379 .SS Search Multiple Directories For .h Files
14382 env = Environment(CPPPATH = ['include1', 'include2'])
14383 env.Program(target = 'foo', source = 'foo.c')
14386 .SS Building a Static Library
14389 env = Environment()
14390 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
14391 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
14394 .SS Building a Shared Library
14397 env = Environment()
14398 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
14399 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
14402 .SS Linking a Local Library Into a Program
14405 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
14406 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
14407 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
14410 .SS Defining Your Own Builder Object
14412 Notice that when you invoke the Builder,
14413 you can leave off the target file suffix,
14414 and SCons will add it automatically.
14417 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
14419 src_suffix = '.tex')
14420 env = Environment(BUILDERS = {'PDFBuilder' : bld})
14421 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
14423 # The following creates "bar.pdf" from "bar.tex"
14424 env.PDFBuilder(target = 'bar', source = 'bar')
14427 Note also that the above initialization
14428 overwrites the default Builder objects,
14429 so the Environment created above
14430 can not be used call Builders like env.Program(),
14431 env.Object(), env.StaticLibrary(), etc.
14433 .SS Adding Your Own Builder Object to an Environment
14436 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
14438 src_suffix = '.tex')
14439 env = Environment()
14440 env.Append(BUILDERS = {'PDFBuilder' : bld})
14441 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
14442 env.Program(target = 'bar', source = 'bar.c')
14445 You also can use other Pythonic techniques to add
14446 to the BUILDERS construction variable, such as:
14449 env = Environment()
14450 env['BUILDERS]['PDFBuilder'] = bld
14453 .SS Defining Your Own Scanner Object
14455 The following example shows an extremely simple scanner (the
14458 that doesn't use a search path at all
14459 and simply returns the
14460 file names present on any
14462 lines in the scanned file.
14463 This would implicitly assume that all included
14464 files live in the top-level directory:
14469 '\" Note: the \\ in the following are for the benefit of nroff/troff,
14470 '\" not inappropriate doubled escape characters within the r'' raw string.
14471 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
14473 def kfile_scan(node, env, path, arg):
14474 contents = node.get_contents()
14475 includes = include_re.findall(contents)
14478 kscan = Scanner(name = 'kfile',
14479 function = kfile_scan,
14482 scanners = Environment().Dictionary('SCANNERS')
14483 env = Environment(SCANNERS = scanners + [kscan])
14485 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
14487 bar_in = File('bar.in')
14488 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
14489 bar_in.target_scanner = kscan
14492 Here is a similar but more complete example that searches
14493 a path of directories
14496 construction variable)
14497 for files that actually exist:
14500 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
14502 def my_scan(node, env, path, arg):
14503 contents = node.get_contents()
14504 includes = include_re.findall(contents)
14508 for inc in includes:
14510 file = dir + os.sep + inc
14511 if os.path.exists(file):
14512 results.append(file)
14516 scanner = Scanner(name = 'myscanner',
14517 function = my_scan,
14520 path_function = FindPathDirs('MYPATH'),
14522 scanners = Environment().Dictionary('SCANNERS')
14523 env = Environment(SCANNERS = scanners + [scanner])
14527 .BR FindPathDirs ()
14528 function used in the previous example returns a function
14529 (actually a callable Python object)
14530 that will return a list of directories
14533 construction variable.
14534 If you need to customize how the search path is derived,
14535 you would provide your own
14537 argument when creating the Scanner object,
14541 # MYPATH is a list of directories to search for files in
14542 def pf(env, dir, target, source, arg):
14543 top_dir = Dir('#').abspath
14545 if env.has_key('MYPATH'):
14546 for p in env['MYPATH']:
14547 results.append(top_dir + os.sep + p)
14550 scanner = Scanner(name = 'myscanner',
14551 function = my_scan,
14554 path_function = pf,
14558 .SS Creating a Hierarchical Build
14560 Notice that the file names specified in a subdirectory's
14562 file are relative to that subdirectory.
14567 env = Environment()
14568 env.Program(target = 'foo', source = 'foo.c')
14570 SConscript('sub/SConscript')
14574 env = Environment()
14575 # Builds sub/foo from sub/foo.c
14576 env.Program(target = 'foo', source = 'foo.c')
14578 SConscript('dir/SConscript')
14580 sub/dir/SConscript:
14582 env = Environment()
14583 # Builds sub/dir/foo from sub/dir/foo.c
14584 env.Program(target = 'foo', source = 'foo.c')
14587 .SS Sharing Variables Between SConscript Files
14589 You must explicitly Export() and Import() variables that
14590 you want to share between SConscript files.
14595 env = Environment()
14596 env.Program(target = 'foo', source = 'foo.c')
14599 SConscript('subdirectory/SConscript')
14601 subdirectory/SConscript:
14604 env.Program(target = 'foo', source = 'foo.c')
14607 .SS Building Multiple Variants From the Same Source
14609 Use the variant_dir keyword argument to
14610 the SConscript function to establish
14611 one or more separate variant build directory trees
14612 for a given source directory:
14617 cppdefines = ['FOO']
14618 Export("cppdefines")
14619 SConscript('src/SConscript', variant_dir='foo')
14621 cppdefines = ['BAR']
14622 Export("cppdefines")
14623 SConscript('src/SConscript', variant_dir='bar')
14627 Import("cppdefines")
14628 env = Environment(CPPDEFINES = cppdefines)
14629 env.Program(target = 'src', source = 'src.c')
14632 Note the use of the Export() method
14633 to set the "cppdefines" variable to a different
14634 value each time we call the SConscript function.
14636 .SS Hierarchical Build of Two Libraries Linked With a Program
14641 env = Environment(LIBPATH = ['#libA', '#libB'])
14643 SConscript('libA/SConscript')
14644 SConscript('libB/SConscript')
14645 SConscript('Main/SConscript')
14650 env.Library('a', Split('a1.c a2.c a3.c'))
14655 env.Library('b', Split('b1.c b2.c b3.c'))
14660 e = env.Copy(LIBS = ['a', 'b'])
14661 e.Program('foo', Split('m1.c m2.c m3.c'))
14664 The '#' in the LIBPATH directories specify that they're relative to the
14665 top-level directory, so they don't turn into "Main/libA" when they're
14666 used in Main/SConscript.
14668 Specifying only 'a' and 'b' for the library names
14669 allows SCons to append the appropriate library
14670 prefix and suffix for the current platform
14671 (for example, 'liba.a' on POSIX systems,
14672 \&'a.lib' on Windows).
14674 .SS Customizing construction variables from the command line.
14676 The following would allow the C compiler to be specified on the command
14677 line or in the file custom.py.
14680 vars = Variables('custom.py')
14681 vars.Add('CC', 'The C compiler.')
14682 env = Environment(variables=vars)
14683 Help(vars.GenerateHelpText(env))
14686 The user could specify the C compiler on the command line:
14692 or in the custom.py file:
14698 or get documentation on the options:
14703 CC: The C compiler.
14709 .SS Using Microsoft Visual C++ precompiled headers
14711 Since windows.h includes everything and the kitchen sink, it can take quite
14712 some time to compile it over and over again for a bunch of object files, so
14713 Microsoft provides a mechanism to compile a set of headers once and then
14714 include the previously compiled headers in any object file. This
14715 technology is called precompiled headers. The general recipe is to create a
14716 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
14717 then include every header you want to precompile in "StdAfx.h", and finally
14718 include "StdAfx.h" as the first header in all the source files you are
14719 compiling to object files. For example:
14723 #include <windows.h>
14724 #include <my_big_header.h>
14729 #include <StdAfx.h>
14734 #include <StdAfx.h>
14736 /* do some stuff */
14741 #include <StdAfx.h>
14743 /* do some other stuff */
14749 env['PCHSTOP'] = 'StdAfx.h'
14750 env['PCH'] = env.PCH('StdAfx.cpp')[0]
14751 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
14754 For more information see the document for the PCH builder, and the PCH and
14755 PCHSTOP construction variables. To learn about the details of precompiled
14756 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
14758 .SS Using Microsoft Visual C++ external debugging information
14760 Since including debugging information in programs and shared libraries can
14761 cause their size to increase significantly, Microsoft provides a mechanism
14762 for including the debugging information in an external file called a PDB
14763 file. SCons supports PDB files through the PDB construction
14769 env['PDB'] = 'MyApp.pdb'
14770 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
14773 For more information see the document for the PDB construction variable.
14778 Specifies the directory that contains the SCons Python module directory
14779 (e.g. /home/aroach/scons-src-0.01/src/engine).
14782 A string of options that will be used by scons in addition to those passed
14783 on the command line.
14794 Steven Knight <knight@baldmt.com>
14796 Anthony Roach <aroach@electriceyeball.com>