1SCONS(1) General Commands Manual SCONS(1)
2
6 scons - a software construction tool
7
9 scons [ options... ] [ name=val... ] [ targets... ]
10
12 The scons utility builds software (or other files) by determining which
13 component pieces must be rebuilt and executing the necessary commands
14 to rebuild them.
15 By default, scons searches for a file named SConstruct, Sconstruct, or
17 sconstruct (in that order) in the current directory and reads its con‐
18 figuration from the first file found. An alternate file name may be
19 specified via the -f option.
20 The SConstruct file can specify subsidiary configuration files using
22 the SConscript() function. By convention, these subsidiary files are
23 named SConscript, although any name may be used. (Because of this nam‐
24 ing convention, the term "SConscript files" is sometimes used to refer
25 generically to all scons configuration files, regardless of actual file
26 name.)
27 The configuration files specify the target files to be built, and
29 (optionally) the rules to build those targets. Reasonable default
30 rules exist for building common software components (executable pro‐
31 grams, object files, libraries), so that for most software projects,
32 only the target and input files need be specified.
33 Before reading the SConstruct file, scons looks for a directory named
35 site_scons in the directory containing the SConstruct file; if it
36 exists, site_scons is added to sys.path, the file
37 site_scons/site_init.py, is evaluated if it exists, and the directory
38 site_scons/site_tools is added to the default toolpath if it exist.
39 See the --no-site-dir and --site-dir options for more details.
40 scons reads and executes the SConscript files as Python scripts, so you
42 may use normal Python scripting capabilities (such as flow control,
43 data manipulation, and imported Python libraries) to handle complicated
44 build situations. scons, however, reads and executes all of the SCon‐
45 script files before it begins building any targets. To make this obvi‐
46 ous, scons prints the following messages about what it is doing:
47 $ scons foo.out
49 scons: Reading SConscript files ...
50 scons: done reading SConscript files.
51 scons: Building targets ...
52 cp foo.in foo.out
53 scons: done building targets.
54 $
55 The status messages (everything except the line that reads "cp foo.in
57 foo.out") may be suppressed using the -Q option.
58 scons does not automatically propagate the external environment used to
60 execute scons to the commands used to build target files. This is so
61 that builds will be guaranteed repeatable regardless of the environment
62 variables set at the time scons is invoked. This also means that if
63 the compiler or other commands that you want to use to build your tar‐
64 get files are not in standard system locations, scons will not find
65 them unless you explicitly set the PATH to include those locations.
66 Whenever you create an scons construction environment, you can propa‐
67 gate the value of PATH from your external environment as follows:
68 import os
70 env = Environment(ENV = {'PATH' : os.environ['PATH']})
71 Similarly, if the commands use external environment variables like
73 $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables
74 can also be explicitly propagated:
75 import os
77 env = Environment(ENV = {'PATH' : os.environ['PATH'],
78 'HOME' : os.environ['HOME']})
79 Or you may explicitly propagate the invoking user's complete external
81 environment:
82 import os
84 env = Environment(ENV = os.environ)
85 This comes at the expense of making your build dependent on the user's
87 environment being set correctly, but it may be more convenient for many
88 configurations.
89 scons can scan known input files automatically for dependency informa‐
91 tion (for example, #include statements in C or C++ files) and will
92 rebuild dependent files appropriately whenever any "included" input
93 file changes. scons supports the ability to define new scanners for
94 unknown input file types.
95 scons knows how to fetch files automatically from SCCS or RCS subdirec‐
97 tories using SCCS, RCS or BitKeeper.
98 scons is normally executed in a top-level directory containing a SCon‐
100 struct file, optionally specifying as command-line arguments the target
101 file or files to be built.
102 By default, the command
104 scons
106 will build all target files in or below the current directory.
108 Explicit default targets (to be built when no targets are specified on
109 the command line) may be defined the SConscript file(s) using the
110 Default() function, described below.
111 Even when Default() targets are specified in the SConscript file(s),
113 all target files in or below the current directory may be built by
114 explicitly specifying the current directory (.) as a command-line tar‐
115 get:
116 scons .
118 Building all target files, including any files outside of the current
120 directory, may be specified by supplying a command-line target of the
121 root directory (on POSIX systems):
122 scons /
124 or the path name(s) of the volume(s) in which all the targets should be
126 built (on Windows systems):
127 scons C:\ D:\
129 To build only specific targets, supply them as command-line arguments:
131 scons foo bar
133 in which case only the specified targets will be built (along with any
135 derived files on which they depend).
136 Specifying "cleanup" targets in SConscript files is not usually neces‐
138 sary. The -c flag removes all files necessary to build the specified
139 target:
140 scons -c .
142 to remove all target files, or:
144 scons -c build export
146 to remove target files under build and export. Additional files or
148 directories to remove can be specified using the Clean() function.
149 Conversely, targets that would normally be removed by the -c invocation
150 can be prevented from being removed by using the NoClean() function.
151 A subset of a hierarchical tree may be built by remaining at the top-
153 level directory (where the SConstruct file lives) and specifying the
154 subdirectory as the target to be built:
155 scons src/subdir
157 or by changing directory and invoking scons with the -u option, which
159 traverses up the directory hierarchy until it finds the SConstruct
160 file, and then builds targets relatively to the current subdirectory:
161 cd src/subdir
163 scons -u .
164 scons supports building multiple targets in parallel via a -j option
166 that takes, as its argument, the number of simultaneous tasks that may
167 be spawned:
168 scons -j 4
170 builds four targets in parallel, for example.
172 scons can maintain a cache of target (derived) files that can be shared
174 between multiple builds. When caching is enabled in a SConscript file,
175 any target files built by scons will be copied to the cache. If an up-
176 to-date target file is found in the cache, it will be retrieved from
177 the cache instead of being rebuilt locally. Caching behavior may be
178 disabled and controlled in other ways by the --cache-force, --cache-
179 disable, and --cache-show command-line options. The --random option is
180 useful to prevent multiple builds from trying to update the cache
181 simultaneously.
182 Values of variables to be passed to the SConscript file(s) may be spec‐
184 ified on the command line:
185 scons debug=1 .
187 These variables are available in SConscript files through the ARGUMENTS
189 dictionary, and can be used in the SConscript file(s) to modify the
190 build in any way:
191 if ARGUMENTS.get('debug', 0):
193 env = Environment(CCFLAGS = '-g')
194 else:
195 env = Environment()
196 The command-line variable arguments are also available in the ARGLIST
198 list, indexed by their order on the command line. This allows you to
199 process them in order rather than by name, if necessary. ARGLIST[0]
200 returns a tuple containing (argname, argvalue). A Python exception is
201 thrown if you try to access a list member that does not exist.
202 scons requires Python version 2.4 or later. There should be no other
204 dependencies or requirements to run scons.
205 By default, scons knows how to search for available programming tools
207 on various systems. On Windows systems, scons searches in order for
208 the Microsoft Visual C++ tools, the MinGW tool chain, the Intel com‐
209 piler tools, and the PharLap ETS compiler. On OS/2 systems, scons
210 searches in order for the OS/2 compiler, the GCC tool chain, and the
211 Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-
212 UX, and Sun Solaris systems, scons searches for the native compiler
213 tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and the
214 GCC tool chain. On all other platforms, including POSIX (Linux and
215 UNIX) platforms, scons searches in order for the GCC tool chain, the
216 Microsoft Visual C++ tools, and the Intel compiler tools. You may, of
217 course, override these default values by appropriate configuration of
218 Environment construction variables.
219
222 In general, scons supports the same command-line options as GNU make,
223 and many of those supported by cons.
224 -b Ignored for compatibility with non-GNU versions of make.
227 -c, --clean, --remove
230 Clean up by removing all target files for which a construction
231 command is specified. Also remove any files or directories
232 associated to the construction command using the Clean() func‐
233 tion. Will not remove any targets specified by the NoClean()
234 function.
235 --cache-debug=file
238 Print debug information about the CacheDir() derived-file
239 caching to the specified file. If file is - (a hyphen), the
240 debug information are printed to the standard output. The
241 printed messages describe what signature file names are being
242 looked for in, retrieved from, or written to the CacheDir()
243 directory tree.
244 --cache-disable, --no-cache
247 Disable the derived-file caching specified by CacheDir(). scons
248 will neither retrieve files from the cache nor copy files to the
249 cache.
250 --cache-force, --cache-populate
253 When using CacheDir(), populate a cache by copying any already-
254 existing, up-to-date derived files to the cache, in addition to
255 files built by this invocation. This is useful to populate a
256 new cache with all the current derived files, or to add to the
257 cache any derived files recently built with caching disabled via
258 the --cache-disable option.
259 --cache-show
262 When using CacheDir() and retrieving a derived file from the
263 cache, show the command that would have been executed to build
264 the file, instead of the usual report, "Retrieved `file' from
265 cache." This will produce consistent output for build logs,
266 regardless of whether a target file was rebuilt or retrieved
267 from the cache.
268 --config=mode
271 This specifies how the Configure call should use or generate the
272 results of configuration tests. The option should be specified
273 from among the following choices:
274 --config=auto
277 scons will use its normal dependency mechanisms to decide if a
278 test must be rebuilt or not. This saves time by not running the
279 same configuration tests every time you invoke scons, but will
280 overlook changes in system header files or external commands
281 (such as compilers) if you don't specify those dependecies
282 explicitly. This is the default behavior.
283 --config=force
286 If this option is specified, all configuration tests will be re-
287 run regardless of whether the cached results are out of date.
288 This can be used to explicitly force the configuration tests to
289 be updated in response to an otherwise unconfigured change in a
290 system header file or compiler.
291 --config=cache
294 If this option is specified, no configuration tests will be
295 rerun and all results will be taken from cache. Note that scons
296 will still consider it an error if --config=cache is specified
297 and a necessary test does not yet have any results in the cache.
298 -C directory, --directory=directory
301 Change to the specified directory before searching for the SCon‐
302 struct, Sconstruct, or sconstruct file, or doing anything else.
303 Multiple -C options are interpreted relative to the previous
304 one, and the right-most -C option wins. (This option is nearly
305 equivalent to -f directory/SConstruct, except that it will
306 search for SConstruct, Sconstruct, or sconstruct in the speci‐
307 fied directory.)
308 -D Works exactly the same way as the -u option except for the way
312 default targets are handled. When this option is used and no
313 targets are specified on the command line, all default targets
314 are built, whether or not they are below the current directory.
315 --debug=type
318 Debug the build process. type specifies what type of debugging:
319 --debug=count
322 Print how many objects are created of the various classes used
323 internally by SCons before and after reading the SConscript
324 files and before and after building targets. This is not sup‐
325 ported when SCons is executed with the Python -O (optimized)
326 option or when the SCons modules have been compiled with opti‐
327 mization (that is, when executing from *.pyo files).
328 --debug=dtree
331 A synonym for the newer --tree=derived option. This will be
332 deprecated in some future release and ultimately removed.
333 --debug=explain
336 Print an explanation of precisely why scons is deciding to
337 (re-)build any targets. (Note: this does not print anything
338 for targets that are not rebuilt.)
339 --debug=findlibs
342 Instruct the scanner that searches for libraries to print a mes‐
343 sage about each potential library name it is searching for, and
344 about the actual libraries it finds.
345 --debug=includes
348 Print the include tree after each top-level target is built.
349 This is generally used to find out what files are included by
350 the sources of a given derived file:
351 $ scons --debug=includes foo.o
353 --debug=memoizer
356 Prints a summary of hits and misses using the Memoizer, an
357 internal subsystem that counts how often SCons uses cached val‐
358 ues in memory instead of recomputing them each time they're
359 needed.
360 --debug=memory
363 Prints how much memory SCons uses before and after reading the
364 SConscript files and before and after building targets.
365 --debug=nomemoizer
368 A deprecated option preserved for backwards compatibility.
369 --debug=objects
372 Prints a list of the various objects of the various classes used
373 internally by SCons.
374 --debug=pdb
377 Re-run SCons under the control of the pdb Python debugger.
378 --debug=presub
381 Print the raw command line used to build each target before the
382 construction environment variables are substituted. Also shows
383 which targets are being built by this command. Output looks
384 something like this:
385 $ scons --debug=presub
386 Building myprog.o with action(s):
387 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
388 ...
389 --debug=stacktrace
392 Prints an internal Python stack trace when encountering an oth‐
393 erwise unexplained error.
394 --debug=stree
397 A synonym for the newer --tree=all,status option. This will be
398 deprecated in some future release and ultimately removed.
399 --debug=time
402 Prints various time profiling information: the time spent exe‐
403 cuting each individual build command; the total build time (time
404 SCons ran from beginning to end); the total time spent reading
405 and executing SConscript files; the total time spent SCons
406 itself spend running (that is, not counting reading and execut‐
407 ing SConscript files); and both the total time spent executing
408 all build commands and the elapsed wall-clock time spent execut‐
409 ing those build commands. (When scons is executed without the
410 -j option, the elapsed wall-clock time will typically be
411 slightly longer than the total time spent executing all the
412 build commands, due to the SCons processing that takes place in
413 between executing each command. When scons is executed with the
414 -j option, and your build configuration allows good paralleliza‐
415 tion, the elapsed wall-clock time should be significantly
416 smaller than the total time spent executing all the build com‐
417 mands, since multiple build commands and intervening SCons pro‐
418 cessing should take place in parallel.)
419 --debug=tree
422 A synonym for the newer --tree=all option. This will be depre‐
423 cated in some future release and ultimately removed.
424 --diskcheck=types
427 Enable specific checks for whether or not there is a file on
428 disk where the SCons configuration expects a directory (or vice
429 versa), and whether or not RCS or SCCS sources exist when
430 searching for source and include files. The types argument can
431 be set to: all, to enable all checks explicitly (the default
432 behavior); none, to disable all such checks; match, to check
433 that files and directories on disk match SCons' expected config‐
434 uration; rcs, to check for the existence of an RCS source for
435 any missing source or include files; sccs, to check for the
436 existence of an SCCS source for any missing source or include
437 files. Multiple checks can be specified separated by commas;
438 for example, --diskcheck=sccs,rcs would still check for SCCS and
439 RCS sources, but disable the check for on-disk matches of files
440 and directories. Disabling some or all of these checks can pro‐
441 vide a performance boost for large configurations, or when the
442 configuration will check for files and/or directories across
443 networked or shared file systems, at the slight increased risk
444 of an incorrect build or of not handling errors gracefully (if
445 include files really should be found in SCCS or RCS, for exam‐
446 ple, or if a file really does exist where the SCons configura‐
447 tion expects a directory).
448 --duplicate=ORDER
451 There are three ways to duplicate files in a build tree: hard
452 links, soft (symbolic) links and copies. The default behaviour
453 of SCons is to prefer hard links to soft links to copies. You
454 can specify different behaviours with this option. ORDER must
455 be one of hard-soft-copy (the default), soft-hard-copy, hard-
456 copy, soft-copy or copy. SCons will attempt to duplicate files
457 using the mechanisms in the specified order.
458 -f file, --file=file, --makefile=file, --sconstruct=file
462 Use file as the initial SConscript file. Multiple -f options
463 may be specified, in which case scons will read all of the spec‐
464 ified files.
465 -h, --help
468 Print a local help message for this build, if one is defined in
469 the SConscript file(s), plus a line that describes the -H option
470 for command-line option help. If no local help message is
471 defined, prints the standard help message about command-line
472 options. Exits after displaying the appropriate message.
473 -H, --help-options
476 Print the standard help message about command-line options and
477 exit.
478 -i, --ignore-errors
481 Ignore all errors from commands executed to rebuild files.
482 -I directory, --include-dir=directory
485 Specifies a directory to search for imported Python modules. If
486 several -I options are used, the directories are searched in the
487 order specified.
488 --implicit-cache
491 Cache implicit dependencies. This causes scons to use the
492 implicit (scanned) dependencies from the last time it was run
493 instead of scanning the files for implicit dependencies. This
494 can significantly speed up SCons, but with the following limita‐
495 tions:
496 scons will not detect changes to implicit dependency search
498 paths (e.g. CPPPATH, LIBPATH) that would ordinarily cause dif‐
499 ferent versions of same-named files to be used.
500 scons will miss changes in the implicit dependencies in cases
502 where a new implicit dependency is added earlier in the implicit
503 dependency search path (e.g. CPPPATH, LIBPATH) than a current
504 implicit dependency with the same name.
505 --implicit-deps-changed
508 Forces SCons to ignore the cached implicit dependencies. This
509 causes the implicit dependencies to be rescanned and recached.
510 This implies --implicit-cache.
511 --implicit-deps-unchanged
514 Force SCons to ignore changes in the implicit dependencies.
515 This causes cached implicit dependencies to always be used.
516 This implies --implicit-cache.
517 --interactive
520 Starts SCons in interactive mode. The SConscript files are read
521 once and a scons>>> prompt is printed. Targets may now be
522 rebuilt by typing commands at interactive prompt without having
523 to re-read the SConscript files and re-initialize the dependency
524 graph from scratch.
525 SCons interactive mode supports the following commands:
527 build[OPTIONS] [TARGETS] ...
530 Builds the specified TARGETS (and their dependencies)
531 with the specified SCons command-line OPTIONS. b and
532 scons are synonyms.
533 The following SCons command-line options affect the
535 build command:
536 --cache-debug=FILE
538 --cache-disable, --no-cache
539 --cache-force, --cache-populate
540 --cache-show
541 --debug=TYPE
542 -i, --ignore-errors
543 -j N, --jobs=N
544 -k, --keep-going
545 -n, --no-exec, --just-print, --dry-run, --recon
546 -Q
547 -s, --silent, --quiet
548 --taskmastertrace=FILE
549 --tree=OPTIONS
550 Any other SCons command-line options that are specified
553 do not cause errors but have no effect on the build
554 command (mainly because they affect how the SConscript
555 files are read, which only happens once at the begin‐
556 ning of interactive mode).
557 clean[OPTIONS] [TARGETS] ...
560 Cleans the specified TARGETS (and their dependencies)
561 with the specified options. c is a synonym. This com‐
562 mand is itself a synonym for build --clean
563 exit Exits SCons interactive mode. You can also exit by
566 terminating input (CTRL+D on UNIX or Linux systems,
567 CTRL+Z on Windows systems).
568 help[COMMAND]
571 Provides a help message about the commands available in
572 SCons interactive mode. If COMMAND is specified, h and
573 ? are synonyms.
574 shell[COMMANDLINE]
577 Executes the specified COMMANDLINE in a subshell. If
578 no COMMANDLINE is specified, executes the interactive
579 command interpreter specified in the SHELL environment
580 variable (on UNIX and Linux systems) or the COMSPEC
581 environment variable (on Windows systems). sh and !
582 are synonyms.
583 version
586 Prints SCons version information.
587 An empty line repeats the last typed command. Command-line
590 editing can be used if the readline module is available.
591 $ scons --interactive
593 scons: Reading SConscript files ...
594 scons: done reading SConscript files.
595 scons>>> build -n prog
596 scons>>> exit
597 -j N, --jobs=N
600 Specifies the number of jobs (commands) to run simultaneously.
601 If there is more than one -j option, the last one is effective.
602 -k, --keep-going
605 Continue as much as possible after an error. The target that
606 failed and those that depend on it will not be remade, but other
607 targets specified on the command line will still be processed.
608 -m Ignored for compatibility with non-GNU versions of make.
613 --max-drift=SECONDS
616 Set the maximum expected drift in the modification time of files
617 to SECONDS. This value determines how long a file must be
618 unmodified before its cached content signature will be used
619 instead of calculating a new content signature (MD5 checksum) of
620 the file's contents. The default value is 2 days, which means a
621 file must have a modification time of at least two days ago in
622 order to have its cached content signature used. A negative
623 value means to never cache the content signature and to ignore
624 the cached value if there already is one. A value of 0 means to
625 always use the cached signature, no matter how old the file is.
626 --md5-chunksize=KILOBYTES
629 Set the block size used to compute MD5 signatures to KILOBYTES.
630 This value determines the size of the chunks which are read in
631 at once when computing MD5 signatures. Files below that size
632 are fully stored in memory before performing the signature com‐
633 putation while bigger files are read in block-by-block. A huge
634 block-size leads to high memory consumption while a very small
635 block-size slows down the build considerably.
636 The default value is to use a chunk size of 64 kilobytes, which
638 should be appropriate for most uses.
639 -n, --just-print, --dry-run, --recon
642 No execute. Print the commands that would be executed to build
643 any out-of-date target files, but do not execute the commands.
644 --no-site-dir
647 Prevents the automatic addition of the standard site_scons dir
648 to sys.path. Also prevents loading the site_scons/site_init.py
649 module if it exists, and prevents adding site_scons/site_tools
650 to the toolpath.
651 --profile=file
655 Run SCons under the Python profiler and save the results in the
656 specified file. The results may be analyzed using the Python
657 pstats module.
658 -q, --question
661 Do not run any commands, or print anything. Just return an exit
662 status that is zero if the specified targets are already up to
663 date, non-zero otherwise.
664 -Q Quiets SCons status messages about reading SConscript files,
666 building targets and entering directories. Commands that are
667 executed to rebuild target files are still printed.
668 --random
672 Build dependencies in a random order. This is useful when
673 building multiple trees simultaneously with caching enabled, to
674 prevent multiple builds from simultaneously trying to build or
675 retrieve the same target files.
676 -s, --silent, --quiet
679 Silent. Do not print commands that are executed to rebuild tar‐
680 get files. Also suppresses SCons status messages.
681 -S, --no-keep-going, --stop
684 Ignored for compatibility with GNU make.
685 --site-dir=dir
688 Uses the named dir as the site dir rather than the default
689 site_scons dir. This dir will get prepended to sys.path, the
690 module dir/site_init.py will get loaded if it exists, and
691 dir/site_tools will get added to the default toolpath.
692 --stack-size=KILOBYTES
695 Set the size stack used to run threads to KILOBYTES. This value
696 determines the stack size of the threads used to run jobs.
697 These are the threads that execute the actions of the builders
698 for the nodes that are out-of-date. Note that this option has
699 no effect unless the num_jobs option, which corresponds to -j
700 and --jobs, is larger than one. Using a stack size that is too
701 small may cause stack overflow errors. This usually shows up as
702 segmentation faults that cause scons to abort before building
703 anything. Using a stack size that is too large will cause scons
704 to use more memory than required and may slow down the entire
705 build process.
706 The default value is to use a stack size of 256 kilobytes, which
708 should be appropriate for most uses. You should not need to
709 increase this value unless you encounter stack overflow errors.
710 -t, --touch
713 Ignored for compatibility with GNU make. (Touching a file to
714 make it appear up-to-date is unnecessary when using scons.)
715 --taskmastertrace=file
718 Prints trace information to the specified file about how the
719 internal Taskmaster object evaluates and controls the order in
720 which Nodes are built. A file name of - may be used to specify
721 the standard output.
722 -tree=options
725 Prints a tree of the dependencies after each top-level target is
726 built. This prints out some or all of the tree, in various for‐
727 mats, depending on the options specified:
728 --tree=all
731 Print the entire dependency tree after each top-level target is
732 built. This prints out the complete dependency tree, including
733 implicit dependencies and ignored dependencies.
734 --tree=derived
737 Restricts the tree output to only derived (target) files, not
738 source files.
739 --tree=status
742 Prints status information for each displayed node.
743 --tree=prune
746 Prunes the tree to avoid repeating dependency information for
747 nodes that have already been displayed. Any node that has
748 already been displayed will have its name printed in [square
749 brackets], as an indication that the dependencies for that node
750 can be found by searching for the relevant output higher up in
751 the tree.
752 Multiple options may be specified, separated by commas:
755 # Prints only derived files, with status information:
757 scons --tree=derived,status
758 # Prints all dependencies of target, with status information
760 # and pruning dependencies of already-visited Nodes:
761 scons --tree=all,prune,status target
762 -u, --up, --search-up
765 Walks up the directory structure until an SConstruct , Scon‐
766 struct or sconstruct file is found, and uses that as the top of
767 the directory tree. If no targets are specified on the command
768 line, only targets at or below the current directory will be
769 built.
770 -U Works exactly the same way as the -u option except for the way
773 default targets are handled. When this option is used and no
774 targets are specified on the command line, all default targets
775 that are defined in the SConscript(s) in the current directory
776 are built, regardless of what directory the resultant targets
777 end up in.
778 -v, --version
781 Print the scons version, copyright information, list of authors,
782 and any other relevant information. Then exit.
783 -w, --print-directory
786 Print a message containing the working directory before and
787 after other processing.
788 --no-print-directory
791 Turn off -w, even if it was turned on implicitly.
792 --warn=type, --warn=no-type
795 Enable or disable warnings. type specifies the type of warnings
796 to be enabled or disabled:
797 --warn=all, --warn=no-all
800 Enables or disables all warnings.
801 --warn=cache-write-error, --warn=no-cache-write-error
804 Enables or disables warnings about errors trying to write a copy
805 of a built file to a specified CacheDir(). These warnings are
806 disabled by default.
807 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
810 Enables or disables warnings about unfamiliar signature data in
811 .sconsign files. These warnings are enabled by default.
812 --warn=dependency, --warn=no-dependency
815 Enables or disables warnings about dependencies. These warnings
816 are disabled by default.
817 --warn=deprecated, --warn=no-deprecated
820 Enables or disables all warnings about use of currently depre‐
821 cated features. These warnings are enabled by default. Note
822 that the --warn=no-deprecated option does not disable warnings
823 about absolutely all deprecated features. Warnings for some
824 deprecated features that have already been through several
825 releases with deprecation warnings may be mandatory for a
826 release or two before they are officially no longer supported by
827 SCons. Warnings for some specific deprecated features may be
828 enabled or disabled individually; see below.
829 --warn=deprecated-copy, --warn=no-deprecated-copy
832 Enables or disables warnings about use of the deprecated
833 env.Copy() method.
834 --warn=deprecated-source-signatures, --warn=no-deprecated-
837 source-signatures
838 Enables or disables warnings about use of the deprecated
839 SourceSignatures() function or env.SourceSignatures()
840 method.
841 --warn=deprecated-target-signatures, --warn=no-deprecated-tar‐
844 get-signatures
845 Enables or disables warnings about use of the deprecated
846 TargetSignatures() function or env.TargetSignatures()
847 method.
848 --warn=duplicate-environment, --warn=no-duplicate-environment
851 Enables or disables warnings about attempts to specify a build
852 of a target with two different construction environments that
853 use the same action. These warnings are enabled by default.
854 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
857 Enables or disables the specific warning about linking Fortran
858 and C++ object files in a single executable, which can yield
859 unpredictable behavior with some compilers.
860 --warn=future-deprecated, --warn=no-future-deprecated
863 Enables or disables warnings about features that will be depre‐
864 cated in the future. These warnings are disabled by default.
865 Enabling this warning is especially recommended for projects
866 that redistribute SCons configurations for other users to build,
867 so that the project can be warned as soon as possible about to-
868 be-deprecated features that may require changes to the configu‐
869 ration.
870 --warn=link, --warn=no-link
873 Enables or disables warnings about link steps.
874 --warn=misleading-keywords, --warn=no-misleading-keywords
877 Enables or disables warnings about use of the misspelled key‐
878 words targets and sources when calling Builders. (Note the last
879 s characters, the correct spellings are target and source.)
880 These warnings are enabled by default.
881 --warn=missing-sconscript, --warn=no-missing-sconscript
884 Enables or disables warnings about missing SConscript files.
885 These warnings are enabled by default.
886 --warn=no-md5-module, --warn=no-no-md5-module
889 Enables or disables warnings about the version of Python not
890 having an MD5 checksum module available. These warnings are
891 enabled by default.
892 --warn=no-metaclass-support, --warn=no-no-metaclass-support
895 Enables or disables warnings about the version of Python not
896 supporting metaclasses when the --debug=memoizer option is used.
897 These warnings are enabled by default.
898 --warn=no-object-count, --warn=no-no-object-count
901 Enables or disables warnings about the --debug=object feature
902 not working when scons is run with the python -O option or from
903 optimized Python (.pyo) modules.
904 --warn=no-parallel-support, --warn=no-no-parallel-support
907 Enables or disables warnings about the version of Python not
908 being able to support parallel builds when the -j option is
909 used. These warnings are enabled by default.
910 --warn=python-version, --warn=no-python-version
913 Enables or disables the warning about running SCons with a dep‐
914 recated version of Python. These warnings are enabled by
915 default.
916 --warn=reserved-variable, --warn=no-reserved-variable
919 Enables or disables warnings about attempts to set the reserved
920 construction variable names CHANGED_SOURCES, CHANGED_TARGETS,
921 TARGET, TARGETS, SOURCE, SOURCES, UNCHANGED_SOURCES or
922 UNCHANGED_TARGETS. These warnings are disabled by default.
923 --warn=stack-size, --warn=no-stack-size
926 Enables or disables warnings about requests to set the stack
927 size that could not be honored. These warnings are enabled by
928 default.
929 -Y repository, --repository=repository, --srcdir=repository
933 Search the specified repository for any input and target files
934 not found in the local directory hierarchy. Multiple -Y options
935 may be specified, in which case the repositories are searched in
936 the order specified.
937
940 Construction Environments
941 A construction environment is the basic means by which the SConscript
942 files communicate build information to scons. A new construction envi‐
943 ronment is created using the Environment function:
944 env = Environment()
946 Variables, called construction variables, may be set in a construction
948 environment either by specifying them as keywords when the object is
949 created or by assigning them a value after the object is created:
950 env = Environment(FOO = 'foo')
952 env['BAR'] = 'bar'
953 As a convenience, construction variables may also be set or modified by
955 the parse_flags keyword argument, which applies the ParseFlags method
956 (described below) to the argument value after all other processing is
957 completed. This is useful either if the exact content of the flags is
958 unknown (for example, read from a control file) or if the flags are
959 distributed to a number of construction variables.
960 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
962 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
964 to LIBS.
965 By default, a new construction environment is initialized with a set of
967 builder methods and construction variables that are appropriate for the
968 current platform. An optional platform keyword argument may be used to
969 specify that an environment should be initialized for a different plat‐
970 form:
971 env = Environment(platform = 'cygwin')
973 env = Environment(platform = 'os2')
974 env = Environment(platform = 'posix')
975 env = Environment(platform = 'win32')
976 Specifying a platform initializes the appropriate construction vari‐
978 ables in the environment to use and generate file names with prefixes
979 and suffixes appropriate for the platform.
980 Note that the win32 platform adds the SystemDrive and SystemRoot vari‐
982 ables from the user's external environment to the construction environ‐
983 ment's ENV dictionary. This is so that any executed commands that use
984 sockets to connect with other systems (such as fetching source files
985 from external CVS repository specifications like :pserver:anony‐
986 mous@cvs.sourceforge.net:/cvsroot/scons) will work on Windows systems.
987 The platform argument may be function or callable object, in which case
989 the Environment() method will call the specified argument to update the
990 new construction environment:
991 def my_platform(env):
993 env['VAR'] = 'xyzzy'
994 env = Environment(platform = my_platform)
996 Additionally, a specific set of tools with which to initialize the
998 environment may be specified as an optional keyword argument:
999 env = Environment(tools = ['msvc', 'lex'])
1001 Non-built-in tools may be specified using the toolpath argument:
1003 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1005 This looks for a tool specification in tools/foo.py (as well as using
1007 the ordinary default tools for the platform). foo.py should have two
1008 functions: generate(env, **kw) and exists(env). The generate() func‐
1009 tion modifies the passed-in environment to set up variables so that the
1010 tool can be executed; it may use any keyword arguments that the user
1011 supplies (see below) to vary its initialization. The exists() function
1012 should return a true value if the tool is available. Tools in the
1013 toolpath are used before any of the built-in ones. For example, adding
1014 gcc.py to the toolpath would override the built-in gcc tool. Also note
1015 that the toolpath is stored in the environment for use by later calls
1016 to Clone() and Tool() methods:
1017 base = Environment(toolpath=['custom_path'])
1019 derived = base.Clone(tools=['custom_tool'])
1020 derived.CustomBuilder()
1021 The elements of the tools list may also be functions or callable
1023 objects, in which case the Environment() method will call the specified
1024 elements to update the new construction environment:
1025 def my_tool(env):
1027 env['XYZZY'] = 'xyzzy'
1028 env = Environment(tools = [my_tool])
1030 The individual elements of the tools list may also themselves be two-
1032 element lists of the form (toolname, kw_dict). SCons searches for the
1033 toolname specification file as described above, and passes kw_dict,
1034 which must be a dictionary, as keyword arguments to the tool's generate
1035 function. The generate function can use the arguments to modify the
1036 tool's behavior by setting up the environment in different ways or oth‐
1037 erwise changing its initialization.
1038 # in tools/my_tool.py:
1040 def generate(env, **kw):
1041 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1042 env['MY_TOOL'] = kw.get('arg1', '1')
1043 def exists(env):
1044 return 1
1045 # in SConstruct:
1047 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1048 toolpath=['tools'])
1049 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1051 the environment it receives to customize the tool for different plat‐
1052 forms.
1053 If no tool list is specified, then SCons will auto-detect the installed
1055 tools using the PATH variable in the ENV construction variable and the
1056 platform name when the Environment is constructed. Changing the PATH
1057 variable after the Environment is constructed will not cause the tools
1058 to be redetected.
1059 SCons supports the following tool specifications out of the box:
1061 386asm
1063 aixc++
1064 aixcc
1065 aixf77
1066 aixlink
1067 ar
1068 as
1069 bcc32
1070 c++
1071 cc
1072 cvf
1073 dmd
1074 dvipdf
1075 dvips
1076 f77
1077 f90
1078 f95
1079 fortran
1080 g++
1081 g77
1082 gas
1083 gcc
1084 gfortran
1085 gnulink
1086 gs
1087 hpc++
1088 hpcc
1089 hplink
1090 icc
1091 icl
1092 ifl
1093 ifort
1094 ilink
1095 ilink32
1096 intelc
1097 jar
1098 javac
1099 javah
1100 latex
1101 lex
1102 link
1103 linkloc
1104 m4
1105 masm
1106 midl
1107 mingw
1108 mslib
1109 mslink
1110 mssdk
1111 msvc
1112 msvs
1113 mwcc
1114 mwld
1115 nasm
1116 pdflatex
1117 pdftex
1118 qt
1119 rmic
1120 rpcgen
1121 sgiar
1122 sgic++
1123 sgicc
1124 sgilink
1125 sunar
1126 sunc++
1127 suncc
1128 sunf77
1129 sunf90
1130 sunf95
1131 sunlink
1132 swig
1133 tar
1134 tex
1135 textfile
1136 tlib
1137 yacc
1138 zip
1139 Additionally, there is a "tool" named default which configures the
1141 environment with a default set of tools for the current platform.
1142 On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by
1144 SCons, on Windows the Microsoft tools (e.g. msvc) followed by MinGW are
1145 preferred by SCons, and in OS/2 the IBM tools (e.g. icc) are preferred
1146 by SCons.
1147 Builder Methods
1150 Build rules are specified by calling a construction environment's
1151 builder methods. The arguments to the builder methods are target (a
1152 list of targets to be built, usually file names) and source (a list of
1153 sources to be built, usually file names).
1154 Because long lists of file names can lead to a lot of quoting, scons
1156 supplies a Split() global function and a same-named environment method
1157 that split a single string into a list, separated on strings of white-
1158 space characters. (These are similar to the split() member function of
1159 Python strings but work even if the input isn't a string.)
1160 Like all Python arguments, the target and source arguments to a builder
1162 method can be specified either with or without the "target" and
1163 "source" keywords. When the keywords are omitted, the target is first,
1164 followed by the source. The following are equivalent examples of call‐
1165 ing the Program builder method:
1166 env.Program('bar', ['bar.c', 'foo.c'])
1168 env.Program('bar', Split('bar.c foo.c'))
1169 env.Program('bar', env.Split('bar.c foo.c'))
1170 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1171 env.Program(target = 'bar', Split('bar.c foo.c'))
1172 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1173 env.Program('bar', source = 'bar.c foo.c'.split())
1174 Target and source file names that are not absolute path names (that is,
1176 do not begin with / on POSIX systems or on Windows systems, with or
1177 without an optional drive letter) are interpreted relative to the
1178 directory containing the SConscript file being read. An initial #
1179 (hash mark) on a path name means that the rest of the file name is
1180 interpreted relative to the directory containing the top-level SCon‐
1181 struct file, even if the # is followed by a directory separator charac‐
1182 ter (slash or backslash).
1183 Examples:
1185 # The comments describing the targets that will be built
1187 # assume these calls are in a SConscript file in the
1188 # a subdirectory named "subdir".
1189 # Builds the program "subdir/foo" from "subdir/foo.c":
1191 env.Program('foo', 'foo.c')
1192 # Builds the program "/tmp/bar" from "subdir/bar.c":
1194 env.Program('/tmp/bar', 'bar.c')
1195 # An initial '#' or '#/' are equivalent; the following
1197 # calls build the programs "foo" and "bar" (in the
1198 # top-level SConstruct directory) from "subdir/foo.c" and
1199 # "subdir/bar.c", respectively:
1200 env.Program('#foo', 'foo.c')
1201 env.Program('#/bar', 'bar.c')
1202 # Builds the program "other/foo" (relative to the top-level
1204 # SConstruct directory) from "subdir/foo.c":
1205 env.Program('#other/foo', 'foo.c')
1206 When the target shares the same base name as the source and only the
1208 suffix varies, and if the builder method has a suffix defined for the
1209 target file type, then the target argument may be omitted completely,
1210 and scons will deduce the target file name from the source file name.
1211 The following examples all build the executable program bar (on POSIX
1212 systems) or bar.exe (on Windows systems) from the bar.c source file:
1213 env.Program(target = 'bar', source = 'bar.c')
1215 env.Program('bar', source = 'bar.c')
1216 env.Program(source = 'bar.c')
1217 env.Program('bar.c')
1218 As a convenience, a srcdir keyword argument may be specified when call‐
1220 ing a Builder. When specified, all source file strings that are not
1221 absolute paths will be interpreted relative to the specified srcdir.
1222 The following example will build the build/prog (or build/prog.exe on
1223 Windows) program from the files src/f1.c and src/f2.c:
1224 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1226 It is possible to override or add construction variables when calling a
1228 builder method by passing additional keyword arguments. These overrid‐
1229 den or added variables will only be in effect when building the target,
1230 so they will not affect other parts of the build. For example, if you
1231 want to add additional libraries for just one program:
1232 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1234 or generate a shared library with a non-standard suffix:
1236 env.SharedLibrary('word', 'word.cpp',
1238 SHLIBSUFFIX='.ocx',
1239 LIBSUFFIXES=['.ocx'])
1240 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1242 if you want SCons to search automatically for dependencies on the non-
1243 standard library names; see the descriptions of these variables, below,
1244 for more information.)
1245 It is also possible to use the parse_flags keyword argument in an over‐
1247 ride:
1248 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1250 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
1252 to LIBS.
1253 Although the builder methods defined by scons are, in fact, methods of
1255 a construction environment object, they may also be called without an
1256 explicit environment:
1257 Program('hello', 'hello.c')
1259 SharedLibrary('word', 'word.cpp')
1260 In this case, the methods are called internally using a default con‐
1262 struction environment that consists of the tools and values that scons
1263 has determined are appropriate for the local system.
1264 Builder methods that can be called without an explicit environment may
1266 be called from custom Python modules that you import into an SConscript
1267 file by adding the following to the Python module:
1268 from SCons.Script import *
1270 All builder methods return a list-like object containing Nodes that
1272 represent the target or targets that will be built. A Node is an
1273 internal SCons object which represents build targets or sources.
1274 The returned Node-list object can be passed to other builder methods as
1276 source(s) or passed to any SCons function or method where a filename
1277 would normally be accepted. For example, if it were necessary to add a
1278 specific -D flag when compiling one specific object file:
1279 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1281 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1282 Using a Node in this way makes for a more portable build by avoiding
1284 having to specify a platform-specific object suffix when calling the
1285 Program() builder method.
1286 Note that Builder calls will automatically "flatten" the source and
1288 target file lists, so it's all right to have the bar_obj list return by
1289 the StaticObject() call in the middle of the source file list. If you
1290 need to manipulate a list of lists returned by Builders directly using
1291 Python, you can either build the list by hand:
1292 foo = Object('foo.c')
1294 bar = Object('bar.c')
1295 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1296 for object in objects:
1297 print str(object)
1298 Or you can use the Flatten() function supplied by scons to create a
1300 list containing just the Nodes, which may be more convenient:
1301 foo = Object('foo.c')
1303 bar = Object('bar.c')
1304 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1305 for object in objects:
1306 print str(object)
1307 Note also that because Builder calls return a list-like object, not an
1309 actual Python list, you should not use the Python += operator to append
1310 Builder results to a Python list. Because the list and the object are
1311 different types, Python will not update the original list in place, but
1312 will instead create a new Node-list object containing the concatenation
1313 of the list elements and the Builder results. This will cause problems
1314 for any other Python variables in your SCons configuration that still
1315 hold on to a reference to the original list. Instead, use the Python
1316 .extend() method to make sure the list is updated in-place. Example:
1317 object_files = []
1319 # Do NOT use += as follows:
1321 #
1322 # object_files += Object('bar.c')
1323 #
1324 # It will not update the object_files list in place.
1325 #
1326 # Instead, use the .extend() method:
1327 object_files.extend(Object('bar.c'))
1328 The path name for a Node's file may be used by passing the Node to the
1331 Python-builtin str() function:
1332 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1334 print "The path to bar_obj is:", str(bar_obj_list[0])
1335 Note again that because the Builder call returns a list, we have to
1337 access the first element in the list (bar_obj_list[0]) to get at the
1338 Node that actually represents the object file.
1339 Builder calls support a chdir keyword argument that specifies that the
1341 Builder's action(s) should be executed after changing directory. If
1342 the chdir argument is a string or a directory Node, scons will change
1343 to the specified directory. If the chdir is not a string or Node and
1344 is non-zero, then scons will change to the target file's directory.
1345 # scons will change to the "sub" subdirectory
1347 # before executing the "cp" command.
1348 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1349 "cp dir/foo.in dir/foo.out",
1350 chdir='sub')
1351 # Because chdir is not a string, scons will change to the
1353 # target's directory ("sub/dir") before executing the
1354 # "cp" command.
1355 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1356 "cp foo.in foo.out",
1357 chdir=1)
1358 Note that scons will not automatically modify its expansion of con‐
1360 struction variables like $TARGET and $SOURCE when using the chdir key‐
1361 word argument--that is, the expanded file names will still be relative
1362 to the top-level SConstruct directory, and consequently incorrect rela‐
1363 tive to the chdir directory. If you use the chdir keyword argument,
1364 you will typically need to supply a different command line using expan‐
1365 sions like ${TARGET.file} and ${SOURCE.file} to use just the filename
1366 portion of the targets and source.
1367 scons provides the following builder methods:
1369 CFile()
1373 env.CFile()
1375 Builds a C source file given a lex (.l) or yacc (.y) input file.
1376 The suffix specified by the $CFILESUFFIX construction variable
1377 (.c by default) is automatically added to the target if it is
1378 not already present. Example:
1379 # builds foo.c
1381 env.CFile(target = 'foo.c', source = 'foo.l')
1382 # builds bar.c
1383 env.CFile(target = 'bar', source = 'bar.y')
1384 CXXFile()
1387 env.CXXFile()
1389 Builds a C++ source file given a lex (.ll) or yacc (.yy) input
1390 file. The suffix specified by the $CXXFILESUFFIX construction
1391 variable (.cc by default) is automatically added to the target
1392 if it is not already present. Example:
1393 # builds foo.cc
1395 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1396 # builds bar.cc
1397 env.CXXFile(target = 'bar', source = 'bar.yy')
1398 DVI()
1401 env.DVI()
1403 Builds a .dvi file from a .tex, .ltx or .latex input file. If
1404 the source file suffix is .tex, scons will examine the contents
1405 of the file; if the string ocumentclass or ocumentstyle is
1406 found, the file is assumed to be a LaTeX file and the target is
1407 built by invoking the $LATEXCOM command line; otherwise, the
1408 $TEXCOM command line is used. If the file is a LaTeX file, the
1409 DVI() builder method will also examine the contents of the .aux
1410 file and invoke the $BIBTEX command line if the string bibdata
1411 is found, start $MAKEINDEX to generate an index if a .ind file
1412 is found and will examine the contents .log file and re-run the
1413 $LATEXCOM command if the log file says it is necessary.
1414 The suffix .dvi (hard-coded within TeX itself) is automatically
1416 added to the target if it is not already present. Examples:
1417 # builds from aaa.tex
1419 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1420 # builds bbb.dvi
1421 env.DVI(target = 'bbb', source = 'bbb.ltx')
1422 # builds from ccc.latex
1423 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1424 Install()
1427 env.Install()
1429 Installs one or more source files or directories in the speci‐
1430 fied target, which must be a directory. The names of the speci‐
1431 fied source files or directories remain the same within the des‐
1432 tination directory.
1433 env.Install('/usr/local/bin', source = ['foo', 'bar'])
1435 InstallAs()
1438 env.InstallAs()
1440 Installs one or more source files or directories to specific
1441 names, allowing changing a file or directory name as part of the
1442 installation. It is an error if the target and source arguments
1443 list different numbers of files or directories.
1444 env.InstallAs(target = '/usr/local/bin/foo',
1446 source = 'foo_debug')
1447 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
1448 source = ['libFOO.a', 'libBAR.a'])
1449 Jar()
1452 env.Jar()
1454 Builds a Java archive (.jar) file from the specified list of
1455 sources. Any directories in the source list will be searched
1456 for .class files). Any .java files in the source list will be
1457 compiled to .class files by calling the Java() Builder.
1458 If the $JARCHDIR value is set, the jar command will change to
1460 the specified directory using the -C option. If $JARCHDIR is
1461 not set explicitly, &SCons; will use the top of any subdirectory
1462 tree in which Java .class were built by the Java() Builder.
1463 If the contents any of the source files begin with the string
1465 Manifest-Version, the file is assumed to be a manifest and is
1466 passed to the jar command with the m option set.
1467 env.Jar(target = 'foo.jar', source = 'classes')
1469 env.Jar(target = 'bar.jar',
1471 source = ['bar1.java', 'bar2.java'])
1472 Java()
1475 env.Java()
1477 Builds one or more Java class files. The sources may be any
1478 combination of explicit .java files, or directory trees which
1479 will be scanned for .java files.
1480 SCons will parse each source .java file to find the classes
1482 (including inner classes) defined within that file, and from
1483 that figure out the target .class files that will be created.
1484 The class files will be placed underneath the specified target
1485 directory.
1486 SCons will also search each Java file for the Java package name,
1488 which it assumes can be found on a line beginning with the
1489 string package in the first column; the resulting .class files
1490 will be placed in a directory reflecting the specified package
1491 name. For example, the file Foo.java defining a single public
1492 Foo class and containing a package name of sub.dir will generate
1493 a corresponding sub/dir/Foo.class class file.
1494 Examples:
1496 env.Java(target = 'classes', source = 'src')
1498 env.Java(target = 'classes', source = ['src1', 'src2'])
1499 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
1500 Java source files can use the native encoding for the underlying
1502 OS. Since SCons compiles in simple ASCII mode by default, the
1503 compiler will generate warnings about unmappable characters,
1504 which may lead to errors as the file is processed further. In
1505 this case, the user must specify the LANG environment variable
1506 to tell the compiler what encoding is used. For portibility,
1507 it's best if the encoding is hard-coded so that the compile will
1508 work if it is done on a system with a different encoding.
1509 env = Environment()
1511 env['ENV']['LANG'] = 'en_GB.UTF-8'
1512 JavaH()
1515 env.JavaH()
1517 Builds C header and source files for implementing Java native
1518 methods. The target can be either a directory in which the
1519 header files will be written, or a header file name which will
1520 contain all of the definitions. The source can be the names of
1521 .class files, the names of .java files to be compiled into
1522 .class files by calling the Java() builder method, or the
1523 objects returned from the Java() builder method.
1524 If the construction variable $JAVACLASSDIR is set, either in the
1526 environment or in the call to the JavaH() builder method itself,
1527 then the value of the variable will be stripped from the begin‐
1528 ning of any .class file names.
1529 Examples:
1531 # builds java_native.h
1533 classes = env.Java(target = 'classdir', source = 'src')
1534 env.JavaH(target = 'java_native.h', source = classes)
1535 # builds include/package_foo.h and include/package_bar.h
1537 env.JavaH(target = 'include',
1538 source = ['package/foo.class', 'package/bar.class'])
1539 # builds export/foo.h and export/bar.h
1541 env.JavaH(target = 'export',
1542 source = ['classes/foo.class', 'classes/bar.class'],
1543 JAVACLASSDIR = 'classes')
1544 Library()
1547 env.Library()
1549 A synonym for the StaticLibrary() builder method.
1550 LoadableModule()
1553 env.LoadableModule()
1555 On most systems, this is the same as SharedLibrary(). On Mac OS
1556 X (Darwin) platforms, this creates a loadable module bundle.
1557 M4()
1560 env.M4()
1562 Builds an output file from an M4 input file. This uses a
1563 default $M4FLAGS value of -E, which considers all warnings to be
1564 fatal and stops on the first warning when using the GNU version
1565 of m4. Example:
1566 env.M4(target = 'foo.c', source = 'foo.c.m4')
1568 Moc()
1571 env.Moc()
1573 Builds an output file from a moc input file. Moc input files are
1574 either header files or cxx files. This builder is only available
1575 after using the tool 'qt'. See the $QTDIR variable for more
1576 information. Example:
1577 env.Moc('foo.h') # generates moc_foo.cc
1579 env.Moc('foo.cpp') # generates foo.moc
1580 MSVSProject()
1583 env.MSVSProject()
1585 Builds a Microsoft Visual Studio project file, and by default
1586 builds a solution file as well.
1587 This builds a Visual Studio project file, based on the version
1589 of Visual Studio that is configured (either the latest installed
1590 version, or the version specified by $MSVS_VERSION in the Envi‐
1591 ronment constructor). For Visual Studio 6, it will generate a
1592 .dsp file. For Visual Studio 7 (.NET) and later versions, it
1593 will generate a .vcproj file.
1594 By default, this also generates a solution file for the speci‐
1596 fied project, a .dsw file for Visual Studio 6 or a .sln file for
1597 Visual Studio 7 (.NET). This behavior may be disabled by speci‐
1598 fying auto_build_solution=0 when you call MSVSProject(), in
1599 which case you presumably want to build the solution file(s) by
1600 calling the MSVSSolution() Builder (see below).
1601 The MSVSProject() builder takes several lists of filenames to be
1603 placed into the project file. These are currently limited to
1604 srcs, incs, localincs, resources, and misc. These are pretty
1605 self-explanatory, but it should be noted that these lists are
1606 added to the $SOURCES construction variable as strings, NOT as
1607 SCons File Nodes. This is because they represent file names to
1608 be added to the project file, not the source files used to build
1609 the project file.
1610 The above filename lists are all optional, although at least one
1612 must be specified for the resulting project file to be non-
1613 empty.
1614 In addition to the above lists of values, the following values
1616 may be specified:
1617 target: The name of the target .dsp or .vcproj file. The cor‐
1619 rect suffix for the version of Visual Studio must be used, but
1620 the $MSVSPROJECTSUFFIX construction variable will be defined to
1621 the correct value (see example below).
1622 variant: The name of this particular variant. For Visual Studio
1624 7 projects, this can also be a list of variant names. These are
1625 typically things like "Debug" or "Release", but really can be
1626 anything you want. For Visual Studio 7 projects, they may also
1627 specify a target platform separated from the variant name by a |
1628 (vertical pipe) character: Debug|Xbox. The default target plat‐
1629 form is Win32. Multiple calls to MSVSProject() with different
1630 variants are allowed; all variants will be added to the project
1631 file with their appropriate build targets and sources.
1632 buildtarget: An optional string, node, or list of strings or
1634 nodes (one per build variant), to tell the Visual Studio debug‐
1635 ger what output target to use in what build variant. The number
1636 of buildtarget entries must match the number of variant entries.
1637 runfile: The name of the file that Visual Studio 7 and later
1639 will run and debug. This appears as the value of the Output
1640 field in the resutling Visual Studio project file. If this is
1641 not specified, the default is the same as the specified build‐
1642 target value.
1643 Note that because &SCons; always executes its build commands
1645 from the directory in which the SConstruct file is located, if
1646 you generate a project file in a different directory than the
1647 SConstruct directory, users will not be able to double-click on
1648 the file name in compilation error messages displayed in the
1649 Visual Studio console output window. This can be remedied by
1650 adding the Visual C/C++ /FC compiler option to the $CCFLAGS
1651 variable so that the compiler will print the full path name of
1652 any files that cause compilation errors.
1653 Example usage:
1655 barsrcs = ['bar.cpp'],
1657 barincs = ['bar.h'],
1658 barlocalincs = ['StdAfx.h']
1659 barresources = ['bar.rc','resource.h']
1660 barmisc = ['bar_readme.txt']
1661 dll = env.SharedLibrary(target = 'bar.dll',
1663 source = barsrcs)
1664 env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1666 srcs = barsrcs,
1667 incs = barincs,
1668 localincs = barlocalincs,
1669 resources = barresources,
1670 misc = barmisc,
1671 buildtarget = dll,
1672 variant = 'Release')
1673 MSVSSolution()
1676 env.MSVSSolution()
1678 Builds a Microsoft Visual Studio solution file.
1679 This builds a Visual Studio solution file, based on the version
1681 of Visual Studio that is configured (either the latest installed
1682 version, or the version specified by $MSVS_VERSION in the con‐
1683 struction environment). For Visual Studio 6, it will generate a
1684 .dsw file. For Visual Studio 7 (.NET), it will generate a .sln
1685 file.
1686 The following values must be specified:
1688 target: The name of the target .dsw or .sln file. The correct
1690 suffix for the version of Visual Studio must be used, but the
1691 value $MSVSSOLUTIONSUFFIX will be defined to the correct value
1692 (see example below).
1693 variant: The name of this particular variant, or a list of vari‐
1695 ant names (the latter is only supported for MSVS 7 solutions).
1696 These are typically things like "Debug" or "Release", but really
1697 can be anything you want. For MSVS 7 they may also specify tar‐
1698 get platform, like this "Debug|Xbox". Default platform is Win32.
1699 projects: A list of project file names, or Project nodes
1701 returned by calls to the MSVSProject() Builder, to be placed
1702 into the solution file. It should be noted that these file
1703 names are NOT added to the $SOURCES environment variable in form
1704 of files, but rather as strings. This is because they repre‐
1705 sent file names to be added to the solution file, not the source
1706 files used to build the solution file.
1707 (NOTE: Currently only one project is supported per solution.)
1709 Example Usage:
1711 env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
1713 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
1714 variant = 'Release')
1715 Object()
1718 env.Object()
1720 A synonym for the StaticObject() builder method.
1721 Package()
1724 env.Package()
1726 Builds software distribution packages. Packages consist of
1727 files to install and packaging information. The former may be
1728 specified with the source parameter and may be left out, in
1729 which case the &FindInstalledFiles; function will collect all
1730 files that have an Install() or InstallAs() Builder attached.
1731 If the target is not specified it will be deduced from addi‐
1732 tional information given to this Builder.
1733 The packaging information is specified with the help of con‐
1735 struction variables documented below. This information is
1736 called a tag to stress that some of them can also be attached to
1737 files with the &Tag; function. The mandatory ones will complain
1738 if they were not specified. They vary depending on chosen tar‐
1739 get packager.
1740 The target packager may be selected with the "PACKAGETYPE" com‐
1742 mand line option or with the $PACKAGETYPE construction variable.
1743 Currently the following packagers available:
1744 * msi - Microsoft Installer
1746 * rpm - Redhat Package Manger
1747 * ipkg - Itsy Package Management System
1748 * tarbz2 - compressed tar
1749 * targz - compressed tar
1750 * zip - zip file
1751 * src_tarbz2 - compressed tar source
1752 * src_targz - compressed tar source
1753 * src_zip - zip file source
1754 An updated list is always available under the "package_type"
1756 option when running "scons --help" on a project that has packag‐
1757 ing activated.
1758 env = Environment(tools=['default', 'packaging'])
1759 env.Install('/bin/', 'my_program')
1760 env.Package( NAME = 'foo',
1761 VERSION = '1.2.3',
1762 PACKAGEVERSION = 0,
1763 PACKAGETYPE = 'rpm',
1764 LICENSE = 'gpl',
1765 SUMMARY = 'balalalalal',
1766 DESCRIPTION = 'this should be really really long',
1767 X_RPM_GROUP = 'Application/fu',
1768 SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
1769 )
1770 PCH()
1773 env.PCH()
1775 Builds a Microsoft Visual C++ precompiled header. Calling this
1776 builder method returns a list of two targets: the PCH as the
1777 first element, and the object file as the second element. Nor‐
1778 mally the object file is ignored. This builder method is only
1779 provided when Microsoft Visual C++ is being used as the com‐
1780 piler. The PCH builder method is generally used in conjuction
1781 with the PCH construction variable to force object files to use
1782 the precompiled header:
1783 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1785 PDF()
1788 env.PDF()
1790 Builds a .pdf file from a .dvi input file (or, by extension, a
1791 .tex, .ltx, or .latex input file). The suffix specified by the
1792 $PDFSUFFIX construction variable (.pdf by default) is added
1793 automatically to the target if it is not already present. Exam‐
1794 ple:
1795 # builds from aaa.tex
1797 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1798 # builds bbb.pdf from bbb.dvi
1799 env.PDF(target = 'bbb', source = 'bbb.dvi')
1800 PostScript()
1803 env.PostScript()
1805 Builds a .ps file from a .dvi input file (or, by extension, a
1806 .tex, .ltx, or .latex input file). The suffix specified by the
1807 $PSSUFFIX construction variable (.ps by default) is added auto‐
1808 matically to the target if it is not already present. Example:
1809 # builds from aaa.tex
1811 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1812 # builds bbb.ps from bbb.dvi
1813 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1814 Program()
1817 env.Program()
1819 Builds an executable given one or more object files or C, C++,
1820 D, or Fortran source files. If any C, C++, D or Fortran source
1821 files are specified, then they will be automatically compiled to
1822 object files using the Object() builder method; see that builder
1823 method's description for a list of legal source file suffixes
1824 and how they are interpreted. The target executable file prefix
1825 (specified by the $PROGPREFIX construction variable; nothing by
1826 default) and suffix (specified by the $PROGSUFFIX construction
1827 variable; by default, .exe on Windows systems, nothing on POSIX
1828 systems) are automatically added to the target if not already
1829 present. Example:
1830 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1832 RES()
1835 env.RES()
1837 Builds a Microsoft Visual C++ resource file. This builder
1838 method is only provided when Microsoft Visual C++ or MinGW is
1839 being used as the compiler. The .res (or .o for MinGW) suffix is
1840 added to the target name if no other suffix is given. The
1841 source file is scanned for implicit dependencies as though it
1842 were a C file. Example:
1843 env.RES('resource.rc')
1845 RMIC()
1848 env.RMIC()
1850 Builds stub and skeleton class files for remote objects from
1851 Java .class files. The target is a directory relative to which
1852 the stub and skeleton class files will be written. The source
1853 can be the names of .class files, or the objects return from the
1854 Java() builder method.
1855 If the construction variable $JAVACLASSDIR is set, either in the
1857 environment or in the call to the RMIC() builder method itself,
1858 then the value of the variable will be stripped from the begin‐
1859 ning of any .class file names.
1860 classes = env.Java(target = 'classdir', source = 'src')
1862 env.RMIC(target = 'outdir1', source = classes)
1863 env.RMIC(target = 'outdir2',
1865 source = ['package/foo.class', 'package/bar.class'])
1866 env.RMIC(target = 'outdir3',
1868 source = ['classes/foo.class', 'classes/bar.class'],
1869 JAVACLASSDIR = 'classes')
1870 RPCGenClient()
1873 env.RPCGenClient()
1875 Generates an RPC client stub (_clnt.c) file from a specified RPC
1876 (.x) source file. Because rpcgen only builds output files in
1877 the local directory, the command will be executed in the source
1878 file's directory by default.
1879 # Builds src/rpcif_clnt.c
1881 env.RPCGenClient('src/rpcif.x')
1882 RPCGenHeader()
1885 env.RPCGenHeader()
1887 Generates an RPC header (.h) file from a specified RPC (.x)
1888 source file. Because rpcgen only builds output files in the
1889 local directory, the command will be executed in the source
1890 file's directory by default.
1891 # Builds src/rpcif.h
1893 env.RPCGenHeader('src/rpcif.x')
1894 RPCGenService()
1897 env.RPCGenService()
1899 Generates an RPC server-skeleton (_svc.c) file from a specified
1900 RPC (.x) source file. Because rpcgen only builds output files
1901 in the local directory, the command will be executed in the
1902 source file's directory by default.
1903 # Builds src/rpcif_svc.c
1905 env.RPCGenClient('src/rpcif.x')
1906 RPCGenXDR()
1909 env.RPCGenXDR()
1911 Generates an RPC XDR routine (_xdr.c) file from a specified RPC
1912 (.x) source file. Because rpcgen only builds output files in
1913 the local directory, the command will be executed in the source
1914 file's directory by default.
1915 # Builds src/rpcif_xdr.c
1917 env.RPCGenClient('src/rpcif.x')
1918 SharedLibrary()
1921 env.SharedLibrary()
1923 Builds a shared library (.so on a POSIX system, .dll on Windows)
1924 given one or more object files or C, C++, D or Fortran source
1925 files. If any source files are given, then they will be auto‐
1926 matically compiled to object files. The static library prefix
1927 and suffix (if any) are automatically added to the target. The
1928 target library file prefix (specified by the $SHLIBPREFIX con‐
1929 struction variable; by default, lib on POSIX systems, nothing on
1930 Windows systems) and suffix (specified by the $SHLIBSUFFIX con‐
1931 struction variable; by default, .dll on Windows systems, .so on
1932 POSIX systems) are automatically added to the target if not
1933 already present. Example:
1934 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1936 On Windows systems, the SharedLibrary() builder method will
1938 always build an import (.lib) library in addition to the shared
1939 (.dll) library, adding a .lib library with the same basename if
1940 there is not already a .lib file explicitly listed in the tar‐
1941 gets.
1942 Any object files listed in the source must have been built for a
1944 shared library (that is, using the SharedObject() builder
1945 method). scons will raise an error if there is any mismatch.
1946 On some platforms, there is a distinction between a shared
1948 library (loaded automatically by the system to resolve external
1949 references) and a loadable module (explicitly loaded by user
1950 action). For maximum portability, use the LoadableModule()
1951 builder for the latter.
1952 On Windows systems, specifying register=1 will cause the .dll to
1954 be registered after it is built using REGSVR32. The command
1955 that is run ("regsvr32" by default) is determined by $REGSVR
1956 construction variable, and the flags passed are determined by
1957 $REGSVRFLAGS. By default, $REGSVRFLAGS includes the /s option,
1958 to prevent dialogs from popping up and requiring user attention
1959 when it is run. If you change $REGSVRFLAGS, be sure to include
1960 the /s option. For example,
1961 env.SharedLibrary(target = 'bar',
1963 source = ['bar.cxx', 'foo.obj'],
1964 register=1)
1965 will register bar.dll as a COM object when it is done linking
1967 it.
1968 SharedObject()
1971 env.SharedObject()
1973 Builds an object file for inclusion in a shared library. Source
1974 files must have one of the same set of extensions specified
1975 above for the StaticObject() builder method. On some platforms
1976 building a shared object requires additional compiler option
1977 (e.g. -fPIC for gcc) in addition to those needed to build a nor‐
1978 mal (static) object, but on some platforms there is no differ‐
1979 ence between a shared object and a normal (static) one. When
1980 there is a difference, SCons will only allow shared objects to
1981 be linked into a shared library, and will use a different suffix
1982 for shared objects. On platforms where there is no difference,
1983 SCons will allow both normal (static) and shared objects to be
1984 linked into a shared library, and will use the same suffix for
1985 shared and normal (static) objects. The target object file pre‐
1986 fix (specified by the $SHOBJPREFIX construction variable; by
1987 default, the same as $OBJPREFIX) and suffix (specified by the
1988 $SHOBJSUFFIX construction variable) are automatically added to
1989 the target if not already present. Examples:
1990 env.SharedObject(target = 'ddd', source = 'ddd.c')
1992 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1993 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1994 Note that the source files will be scanned according to the suf‐
1996 fix mappings in the SourceFileScanner object. See the section
1997 "Scanner Objects," below, for more information.
1998 StaticLibrary()
2001 env.StaticLibrary()
2003 Builds a static library given one or more object files or C,
2004 C++, D or Fortran source files. If any source files are given,
2005 then they will be automatically compiled to object files. The
2006 static library prefix and suffix (if any) are automatically
2007 added to the target. The target library file prefix (specified
2008 by the $LIBPREFIX construction variable; by default, lib on
2009 POSIX systems, nothing on Windows systems) and suffix (specified
2010 by the $LIBSUFFIX construction variable; by default, .lib on
2011 Windows systems, .a on POSIX systems) are automatically added to
2012 the target if not already present. Example:
2013 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2015 Any object files listed in the source must have been built for a
2017 static library (that is, using the StaticObject() builder
2018 method). scons will raise an error if there is any mismatch.
2019 StaticObject()
2022 env.StaticObject()
2024 Builds a static object file from one or more C, C++, D, or For‐
2025 tran source files. Source files must have one of the following
2026 extensions:
2027 .asm assembly language file
2029 .ASM assembly language file
2030 .c C file
2031 .C Windows: C file
2032 POSIX: C++ file
2033 .cc C++ file
2034 .cpp C++ file
2035 .cxx C++ file
2036 .cxx C++ file
2037 .c++ C++ file
2038 .C++ C++ file
2039 .d D file
2040 .f Fortran file
2041 .F Windows: Fortran file
2042 POSIX: Fortran file + C pre-processor
2043 .for Fortran file
2044 .FOR Fortran file
2045 .fpp Fortran file + C pre-processor
2046 .FPP Fortran file + C pre-processor
2047 .m Object C file
2048 .mm Object C++ file
2049 .s assembly language file
2050 .S Windows: assembly language file
2051 ARM: CodeSourcery Sourcery Lite
2052 .sx assembly language file + C pre-processor
2053 POSIX: assembly language file + C pre-processor
2054 .spp assembly language file + C pre-processor
2055 .SPP assembly language file + C pre-processor
2056 The target object file prefix (specified by the $OBJPREFIX con‐
2058 struction variable; nothing by default) and suffix (specified by
2059 the $OBJSUFFIX construction variable; .obj on Windows systems,
2060 .o on POSIX systems) are automatically added to the target if
2061 not already present. Examples:
2062 env.StaticObject(target = 'aaa', source = 'aaa.c')
2064 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2065 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2066 Note that the source files will be scanned according to the suf‐
2068 fix mappings in SourceFileScanner object. See the section
2069 "Scanner Objects," below, for more information.
2070 Substfile()
2073 env.Substfile()
2075 The Substfile() builder generates a single text file by concate‐
2076 nating the source files. Nested lists of sources are flattened.
2077 $LINESEPARATOR is used to separate the source files; see the
2078 description of Textfile() for details.
2079 If a single source file is present with an .in suffix, the suf‐
2081 fix is stripped and the remainder is used as the default target
2082 name.
2083 The prefix and suffix specified by the $SUBSTFILEPREFIX and
2085 $SUBSTFILESUFFIX construction variables (the null string by
2086 default in both cases) are automatically added to the target if
2087 they are not already present.
2088 If a construction variable named $SUBST_DICT is present, it may
2090 be either a Python dictionary or a sequence of (key,value)
2091 tuples. If the former, the dictionary is converted into a list
2092 of tuples in an arbitrary order, so if one key is a prefix of
2093 another key or if one substitution could be further expanded by
2094 another subsitition, it is unpredictible whether the expansion
2095 will occur.
2096 Any occurences in the source of a key are replaced by the corre‐
2098 sponding value, which may be a Python callable function or a
2099 string. If a value is a function, it is first called (with no
2100 arguments) to produce a string. The string is subst-expanded
2101 and the result replaces the key.
2102 env = Environment(tools = ['default', 'textfile'])
2104 env['prefix'] = '/usr/bin'
2106 script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
2107 env.Substfile('script.in', SUBST_DICT = script_dict)
2108 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
2110 env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
2111 # UNPREDICTABLE - one key is a prefix of another
2113 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
2114 env.Substfile('foo.in', SUBST_DICT = bad_foo)
2115 # PREDICTABLE - keys are applied longest first
2117 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
2118 env.Substfile('foo.in', SUBST_DICT = good_foo)
2119 # UNPREDICTABLE - one substitution could be futher expanded
2121 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
2122 env.Substfile('bar.in', SUBST_DICT = bad_bar)
2123 # PREDICTABLE - substitutions are expanded in order
2125 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
2126 env.Substfile('bar.in', SUBST_DICT = good_bar)
2127 # the SUBST_DICT may be in common (and not an override)
2129 substutions = {}
2130 subst = Environment(tools = ['textfile', SUBST_DICT = substitutions)
2131 substitutions['@foo@'] = 'foo'
2132 subst['SUBST_DICT']['@bar@'] = 'bar'
2133 subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
2134 Value('#include "@bar@.h"'),
2135 "common.in",
2136 "pgm1.in"
2137 ])
2138 subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
2139 Value('#include "@bar@.h"'),
2140 "common.in",
2141 "pgm2.in"
2142 ])
2143 Tar()
2147 env.Tar()
2149 Builds a tar archive of the specified files and/or directories.
2150 Unlike most builder methods, the Tar() builder method may be
2151 called multiple times for a given target; each additional call
2152 adds to the list of entries that will be built into the archive.
2153 Any source directories will be scanned for changes to any on-
2154 disk files, regardless of whether or not scons knows about them
2155 from other Builder or function calls.
2156 env.Tar('src.tar', 'src')
2158 # Create the stuff.tar file.
2160 env.Tar('stuff', ['subdir1', 'subdir2'])
2161 # Also add "another" to the stuff.tar file.
2162 env.Tar('stuff', 'another')
2163 # Set TARFLAGS to create a gzip-filtered archive.
2165 env = Environment(TARFLAGS = '-c -z')
2166 env.Tar('foo.tar.gz', 'foo')
2167 # Also set the suffix to .tgz.
2169 env = Environment(TARFLAGS = '-c -z',
2170 TARSUFFIX = '.tgz')
2171 env.Tar('foo')
2172 Textfile()
2175 env.Textfile()
2177 The Textfile() builder generates a single text file. The source
2178 strings constitute the lines; nested lists of sources are flat‐
2179 tened. $LINESEPARATOR is used to separate the strings.
2180 If present, the $SUBST_DICT construction variable is used to
2182 modify the strings before they are written; see the Substfile()
2183 description for details.
2184 The prefix and suffix specified by the $TEXTFILEPREFIX and
2186 $TEXTFILESUFFIX construction variables (the null string and .txt
2187 by default, respectively) are automatically added to the target
2188 if they are not already present. Examples:
2189 # builds/writes foo.txt
2191 env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
2192 # builds/writes bar.txt
2194 env.Textfile(target = 'bar',
2195 source = ['lalala', 'tanteratei'],
2196 LINESEPARATOR='|*')
2197 # nested lists are flattened automatically
2199 env.Textfile(target = 'blob',
2200 source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
2201 # files may be used as input by wraping them in File()
2203 env.Textfile(target = 'concat', # concatenate files with a marker between
2204 source = [File('concat1'), File('concat2')],
2205 LINESEPARATOR = '====================\n')
2206 Results are:
2208 foo.txt
2209 ....8<----
2210 Goethe
2211 42
2212 Schiller
2213 ....8<---- (no linefeed at the end)
2214 bar.txt:
2216 ....8<----
2217 lalala|*tanteratei
2218 ....8<---- (no linefeed at the end)
2219 blob.txt
2221 ....8<----
2222 lalala
2223 Goethe
2224 42
2225 Schiller
2226 tanteratei
2227 ....8<---- (no linefeed at the end)
2228 TypeLibrary()
2231 env.TypeLibrary()
2233 Builds a Windows type library (.tlb) file from an input IDL file
2234 (.idl). In addition, it will build the associated inteface stub
2235 and proxy source files, naming them according to the base name
2236 of the .idl file. For example,
2237 env.TypeLibrary(source="foo.idl")
2239 Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c
2241 files.
2242 Uic()
2245 env.Uic()
2247 Builds a header file, an implementation file and a moc file from
2248 an ui file. and returns the corresponding nodes in the above
2249 order. This builder is only available after using the tool
2250 'qt'. Note: you can specify .ui files directly as source files
2251 to the Program(), Library() and SharedLibrary() builders without
2252 using this builder. Using this builder lets you override the
2253 standard naming conventions (be careful: prefixes are always
2254 prepended to names of built files; if you don't want prefixes,
2255 you may set them to ``). See the $QTDIR variable for more
2256 information. Example:
2257 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2259 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2260 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2261 Zip()
2264 env.Zip()
2266 Builds a zip archive of the specified files and/or directories.
2267 Unlike most builder methods, the Zip() builder method may be
2268 called multiple times for a given target; each additional call
2269 adds to the list of entries that will be built into the archive.
2270 Any source directories will be scanned for changes to any on-
2271 disk files, regardless of whether or not scons knows about them
2272 from other Builder or function calls.
2273 env.Zip('src.zip', 'src')
2275 # Create the stuff.zip file.
2277 env.Zip('stuff', ['subdir1', 'subdir2'])
2278 # Also add "another" to the stuff.tar file.
2279 env.Zip('stuff', 'another')
2280 All targets of builder methods automatically depend on their sources.
2283 An explicit dependency can be specified using the Depends method of a
2284 construction environment (see below).
2285 In addition, scons automatically scans source files for various pro‐
2287 gramming languages, so the dependencies do not need to be specified
2288 explicitly. By default, SCons can C source files, C++ source files,
2289 Fortran source files with .F (POSIX systems only), .fpp, or .FPP file
2290 extensions, and assembly language files with .S (POSIX systems only),
2291 .spp, or .SPP files extensions for C preprocessor dependencies. SCons
2292 also has default support for scanning D source files, You can also
2293 write your own Scanners to add support for additional source file
2294 types. These can be added to the default Scanner object used by the
2295 Object(), StaticObject(), and SharedObject() Builders by adding them to
2296 the SourceFileScanner object. See the section "Scanner Objects,"
2297 below, for more information about defining your own Scanner objects and
2298 using the SourceFileScanner object.
2299 Methods and Functions to Do Things
2302 In addition to Builder methods, scons provides a number of other con‐
2303 struction environment methods and global functions to manipulate the
2304 build configuration.
2305 Usually, a construction environment method and global function with the
2307 same name both exist so that you don't have to remember whether to a
2308 specific bit of functionality must be called with or without a con‐
2309 struction environment. In the following list, if you call something as
2310 a global function it looks like:
2311 Function(arguments)
2312 and if you call something through a construction environment it looks
2313 like:
2314 env.Function(arguments)
2315 If you can call the functionality in both ways, then both forms are
2316 listed.
2317 Global functions may be called from custom Python modules that you
2319 import into an SConscript file by adding the following to the Python
2320 module:
2321 from SCons.Script import *
2323 Except where otherwise noted, the same-named construction environment
2325 method and global function provide the exact same functionality. The
2326 only difference is that, where appropriate, calling the functionality
2327 through a construction environment will substitute construction vari‐
2328 ables into any supplied strings. For example:
2329 env = Environment(FOO = 'foo')
2331 Default('$FOO')
2332 env.Default('$FOO')
2333 In the above example, the first call to the global Default() function
2335 will actually add a target named $FOO to the list of default targets,
2336 while the second call to the env.Default() construction environment
2337 method will expand the value and add a target named foo to the list of
2338 default targets. For more on construction variable expansion, see the
2339 next section on construction variables.
2340 Construction environment methods and global functions supported by
2342 scons include:
2343 Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])
2346 env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])
2348 Creates an Action object for the specified action. See the sec‐
2349 tion "Action Objects," below, for a complete explanation of the
2350 arguments and behavior.
2351 Note that the env.Action() form of the invocation will expand
2353 construction variables in any argument strings, including the
2354 action argument, at the time it is called using the construction
2355 variables in the env construction environment through which
2356 env.Action() was called. The Action() form delays all variable
2357 expansion until the Action object is actually used.
2358 AddMethod(object,function, [name])
2361 env.AddMethod(function, [name])
2363 When called with the AddMethod() form, adds the specified func‐
2364 tion to the specified object as the specified method name. When
2365 called with the env.AddMethod() form, adds the specified func‐
2366 tion to the construction environment env as the specified method
2367 name. In both cases, if name is omitted or None, the name of
2368 the specified function itself is used for the method name.
2369 Examples:
2371 # Note that the first argument to the function to
2373 # be attached as a method must be the object through
2374 # which the method will be called; the Python
2375 # convention is to call it 'self'.
2376 def my_method(self, arg):
2377 print "my_method() got", arg
2378 # Use the global AddMethod() function to add a method
2380 # to the Environment class. This
2381 AddMethod(Environment, my_method)
2382 env = Environment()
2383 env.my_method('arg')
2384 # Add the function as a method, using the function
2386 # name for the method call.
2387 env = Environment()
2388 env.AddMethod(my_method, 'other_method_name')
2389 env.other_method_name('another arg')
2390 AddOption(arguments)
2393 This function adds a new command-line option to be recognized.
2394 The specified arguments are the same as supported by the stan‐
2395 dard Python optparse.add_option() method (with a few additional
2396 capabilities noted below); see the documentation for optparse
2397 for a thorough discussion of its option-processing capabities.
2398 In addition to the arguments and values supported by the opt‐
2400 parse.add_option () method, the SCons AddOption() function
2401 allows you to set the nargs keyword value to '?' (a string with
2402 just the question mark) to indicate that the specified long
2403 option(s) take(s) an optional argument. When nargs = '?' is
2404 passed to the AddOption() function, the const keyword argument
2405 may be used to supply the "default" value that should be used
2406 when the option is specified on the command line without an
2407 explicit argument.
2408 If no default= keyword argument is supplied when calling AddOp‐
2410 tion(), the option will have a default value of None.
2411 Once a new command-line option has been added with AddOption(),
2413 the option value may be accessed using GetOption() or env.GetOp‐
2414 tion().
2415 Any specified help= strings for the new option(s) will be dis‐
2430 played by the -H or -h options (the latter only if no other help
2431 text is specified in the SConscript files). The help text for
2432 the local options specified by AddOption() will appear below the
2433 SCons options themselves, under a separate Local Options head‐
2434 ing. The options will appear in the help text in the order in
2435 which the AddOption() calls occur.
2436 Example:
2438 AddOption('--prefix',
2440 dest='prefix',
2441 nargs=1, type='string',
2442 action='store',
2443 metavar='DIR',
2444 help='installation prefix')
2445 env = Environment(PREFIX = GetOption('prefix'))
2446 AddPostAction(target, action)
2449 env.AddPostAction(target, action)
2451 Arranges for the specified action to be performed after the
2452 specified target has been built. The specified action(s) may be
2453 an Action object, or anything that can be converted into an
2454 Action object (see below).
2455 When multiple targets are supplied, the action may be called
2457 multiple times, once after each action that generates one or
2458 more targets in the list.
2459 AddPreAction(target, action)
2462 env.AddPreAction(target, action)
2464 Arranges for the specified action to be performed before the
2465 specified target is built. The specified action(s) may be an
2466 Action object, or anything that can be converted into an Action
2467 object (see below).
2468 When multiple targets are specified, the action(s) may be called
2470 multiple times, once before each action that generates one or
2471 more targets in the list.
2472 Note that if any of the targets are built in multiple steps, the
2474 action will be invoked just before the "final" action that
2475 specifically generates the specified target(s). For example,
2476 when building an executable program from a specified source .c
2477 file via an intermediate object file:
2478 foo = Program('foo.c')
2480 AddPreAction(foo, 'pre_action')
2481 The specified pre_action would be executed before scons calls the link
2483 command that actually generates the executable program binary foo, not
2484 before compiling the foo.c file into an object file.
2485 Alias(alias, [targets, [action]])
2488 env.Alias(alias, [targets, [action]])
2490 Creates one or more phony targets that expand to one or more
2491 other targets. An optional action (command) or list of actions
2492 can be specified that will be executed whenever the any of the
2493 alias targets are out-of-date. Returns the Node object repre‐
2494 senting the alias, which exists outside of any file system.
2495 This Node object, or the alias name, may be used as a dependency
2496 of any other target, including another alias. Alias can be
2497 called multiple times for the same alias to add additional tar‐
2498 gets to the alias, or additional actions to the list for this
2499 alias.
2500 Examples:
2502 Alias('install')
2504 Alias('install', '/usr/bin')
2505 Alias(['install', 'install-lib'], '/usr/local/lib')
2506 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2508 env.Alias('install', ['/usr/local/man'])
2509 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2511 AllowSubstExceptions([exception, ...])
2514 Specifies the exceptions that will be allowed when expanding
2515 construction variables. By default, any construction variable
2516 expansions that generate a NameError or IndexError exception
2517 will expand to a '' (a null string) and not cause scons to fail.
2518 All exceptions not in the specified list will generate an error
2519 message and terminate processing.
2520 If AllowSubstExceptions is called multiple times, each call com‐
2522 pletely overwrites the previous list of allowed exceptions.
2523 Example:
2525 # Requires that all construction variable names exist.
2527 # (You may wish to do this if you want to enforce strictly
2528 # that all construction variables must be defined before use.)
2529 AllowSubstExceptions()
2530 # Also allow a string containing a zero-division expansion
2532 # like '${1 / 0}' to evalute to ''.
2533 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2534 AlwaysBuild(target, ...)
2537 env.AlwaysBuild(target, ...)
2539 Marks each given target so that it is always assumed to be out
2540 of date, and will always be rebuilt if needed. Note, however,
2541 that AlwaysBuild() does not add its target(s) to the default
2542 target list, so the targets will only be built if they are spec‐
2543 ified on the command line, or are a dependent of a target speci‐
2544 fied on the command line--but they will always be built if so
2545 specified. Multiple targets can be passed in to a single call
2546 to AlwaysBuild().
2547 env.Append(key=val, [...])
2550 Appends the specified keyword arguments to the end of construc‐
2551 tion variables in the environment. If the Environment does not
2552 have the specified construction variable, it is simply added to
2553 the environment. If the values of the construction variable and
2554 the keyword argument are the same type, then the two values will
2555 be simply added together. Otherwise, the construction variable
2556 and the value of the keyword argument are both coerced to lists,
2557 and the lists are added together. (See also the Prepend method,
2558 below.)
2559 Example:
2561 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2563 env.AppendENVPath(name, newpath, [envname, sep, delete_existing])
2566 This appends new path elements to the given path in the speci‐
2567 fied external environment (ENV by default). This will only add
2568 any particular path once (leaving the last one it encounters and
2569 ignoring the rest, to preserve path order), and to help assure
2570 this, will normalize all paths (using os.path.normpath and
2571 os.path.normcase). This can also handle the case where the
2572 given old path variable is a list instead of a string, in which
2573 case a list will be returned instead of a string.
2574 If delete_existing is 0, then adding a path that already exists
2576 will not move it to the end; it will stay where it is in the
2577 list.
2578 Example:
2580 print 'before:',env['ENV']['INCLUDE']
2582 include_path = '/foo/bar:/foo'
2583 env.AppendENVPath('INCLUDE', include_path)
2584 print 'after:',env['ENV']['INCLUDE']
2585 yields:
2587 before: /foo:/biz
2588 after: /biz:/foo/bar:/foo
2589 env.AppendUnique(key=val, [...], delete_existing=0)
2592 Appends the specified keyword arguments to the end of construc‐
2593 tion variables in the environment. If the Environment does not
2594 have the specified construction variable, it is simply added to
2595 the environment. If the construction variable being appended to
2596 is a list, then any value(s) that already exist in the construc‐
2597 tion variable will not be added again to the list. However, if
2598 delete_existing is 1, existing matching values are removed
2599 first, so existing values in the arg list move to the end of the
2600 list.
2601 Example:
2603 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2605 env.BitKeeper()
2608 A factory function that returns a Builder object to be used to
2609 fetch source files using BitKeeper. The returned Builder is
2610 intended to be passed to the SourceCode function.
2611 This function is deprecated. For details, see the entry for the
2613 SourceCode function.
2614 Example:
2616 env.SourceCode('.', env.BitKeeper())
2618 BuildDir(build_dir, src_dir, [duplicate])
2621 env.BuildDir(build_dir, src_dir, [duplicate])
2623 Deprecated synonyms for VariantDir() and env.VariantDir(). The
2624 build_dir argument becomes the variant_dir argument of Variant‐
2625 Dir() or env.VariantDir().
2626 Builder(action, [arguments])
2629 env.Builder(action, [arguments])
2631 Creates a Builder object for the specified action. See the sec‐
2632 tion "Builder Objects," below, for a complete explanation of the
2633 arguments and behavior.
2634 Note that the env.Builder() form of the invocation will expand
2636 construction variables in any arguments strings, including the
2637 action argument, at the time it is called using the construction
2638 variables in the env construction environment through which
2639 env.Builder() was called. The Builder() form delays all vari‐
2640 able expansion until after the Builder object is actually
2641 called.
2642 CacheDir(cache_dir)
2645 env.CacheDir(cache_dir)
2647 Specifies that scons will maintain a cache of derived files in
2648 cache_dir . The derived files in the cache will be shared among
2649 all the builds using the same CacheDir() call. Specifying a
2650 cache_dir of None disables derived file caching.
2651 Calling env.CacheDir() will only affect targets built through
2653 the specified construction environment. Calling CacheDir() sets
2654 a global default that will be used by all targets built through
2655 construction environments that do not have an env.CacheDir()
2656 specified.
2657 When a CacheDir() is being used and scons finds a derived file
2659 that needs to be rebuilt, it will first look in the cache to see
2660 if a derived file has already been built from identical input
2661 files and an identical build action (as incorporated into the
2662 MD5 build signature). If so, scons will retrieve the file from
2663 the cache. If the derived file is not present in the cache,
2664 scons will rebuild it and then place a copy of the built file in
2665 the cache (identified by its MD5 build signature), so that it
2666 may be retrieved by other builds that need to build the same
2667 derived file from identical inputs.
2668 Use of a specified CacheDir() may be disabled for any invocation
2670 by using the --cache-disable option.
2671 If the --cache-force option is used, scons will place a copy of
2673 all derived files in the cache, even if they already existed and
2674 were not built by this invocation. This is useful to populate a
2675 cache the first time CacheDir() is added to a build, or after
2676 using the --cache-disable option.
2677 When using CacheDir(), scons will report, "Retrieved `file' from
2679 cache," unless the --cache-show option is being used. When the
2680 --cache-show option is used, scons will print the action that
2681 would have been used to build the file, without any indication
2682 that the file was actually retrieved from the cache. This is
2683 useful to generate build logs that are equivalent regardless of
2684 whether a given derived file has been built in-place or
2685 retrieved from the cache.
2686 The NoCache() method can be used to disable caching of specific
2688 files. This can be useful if inputs and/or outputs of some tool
2689 are impossible to predict or prohibitively large.
2690 Clean(targets, files_or_dirs)
2693 env.Clean(targets, files_or_dirs)
2695 This specifies a list of files or directories which should be
2696 removed whenever the targets are specified with the -c command
2697 line option. The specified targets may be a list or an individ‐
2698 ual target. Multiple calls to Clean() are legal, and create new
2699 targets or add files and directories to the clean list for the
2700 specified targets.
2701 Multiple files or directories should be specified either as sep‐
2703 arate arguments to the Clean() method, or as a list. Clean()
2704 will also accept the return value of any of the construction
2705 environment Builder methods. Examples:
2706 The related NoClean() function overrides calling Clean() for the
2708 same target, and any targets passed to both functions will not
2709 be removed by the -c option.
2710 Examples:
2712 Clean('foo', ['bar', 'baz'])
2714 Clean('dist', env.Program('hello', 'hello.c'))
2715 Clean(['foo', 'bar'], 'something_else_to_clean')
2716 In this example, installing the project creates a subdirectory for the
2718 documentation. This statement causes the subdirectory to be removed if
2719 the project is deinstalled.
2720 Clean(docdir, os.path.join(docdir, projectname))
2721 Command(target, source, action, [key=val, ...])
2724 env.Command(target, source, action, [key=val, ...])
2726 Executes a specific action (or list of actions) to build a tar‐
2727 get file or files. This is more convenient than defining a sep‐
2728 arate Builder object for a single special-case build.
2729 As a special case, the source_scanner keyword argument can be
2731 used to specify a Scanner object that will be used to scan the
2732 sources. (The global DirScanner object can be used if any of
2733 the sources will be directories that must be scanned on-disk for
2734 changes to files that aren't already specified in other Builder
2735 of function calls.)
2736 Any other keyword arguments specified override any same-named
2738 existing construction variables.
2739 An action can be an external command, specified as a string, or
2741 a callable Python object; see "Action Objects," below, for more
2742 complete information. Also note that a string specifying an
2743 external command may be preceded by an @ (at-sign) to suppress
2744 printing the command in question, or by a - (hyphen) to ignore
2745 the exit status of the external command.
2746 Examples:
2748 env.Command('foo.out', 'foo.in',
2750 "$FOO_BUILD < $SOURCES > $TARGET")
2751 env.Command('bar.out', 'bar.in',
2753 ["rm -f $TARGET",
2754 "$BAR_BUILD < $SOURCES > $TARGET"],
2755 ENV = {'PATH' : '/usr/local/bin/'})
2756 def rename(env, target, source):
2758 import os
2759 os.rename('.tmp', str(target[0]))
2760 env.Command('baz.out', 'baz.in',
2762 ["$BAZ_BUILD < $SOURCES > .tmp",
2763 rename ])
2764 Note that the Command() function will usually assume, by
2767 default, that the specified targets and/or sources are Files, if
2768 no other part of the configuration identifies what type of entry
2769 it is. If necessary, you can explicitly specify that targets or
2770 source nodes should be treated as directoriese by using the
2771 Dir() or env.Dir() functions.
2772 Examples:
2774 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2776 env['DISTDIR'] = 'destination/directory'
2778 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2779 (Also note that SCons will usually automatically create any
2782 directory necessary to hold a target file, so you normally don't
2783 need to create directories by hand.)
2784 Configure(env, [custom_tests, conf_dir, log_file, config_h])
2787 env.Configure([custom_tests, conf_dir, log_file, config_h])
2789 Creates a Configure object for integrated functionality similar
2790 to GNU autoconf. See the section "Configure Contexts," below,
2791 for a complete explanation of the arguments and behavior.
2792 env.Clone([key=val, ...])
2795 Return a separate copy of a construction environment. If there
2796 are any keyword arguments specified, they are added to the
2797 returned copy, overwriting any existing values for the keywords.
2798 Example:
2800 env2 = env.Clone()
2802 env3 = env.Clone(CCFLAGS = '-g')
2803 Additionally, a list of tools and a toolpath may be specified,
2805 as in the Environment constructor:
2806 def MyTool(env): env['FOO'] = 'bar'
2808 env4 = env.Clone(tools = ['msvc', MyTool])
2809 The parse_flags keyword argument is also recognized:
2811 # create an environment for compiling programs that use wxWidgets
2813 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
2814 env.Copy([key=val, ...])
2817 A now-deprecated synonym for env.Clone().
2818 env.CVS(repository, module)
2821 A factory function that returns a Builder object to be used to
2822 fetch source files from the specified CVS repository. The
2823 returned Builder is intended to be passed to the SourceCode
2824 function.
2825 The optional specified module will be added to the beginning of
2827 all repository path names; this can be used, in essence, to
2828 strip initial directory names from the repository path names, so
2829 that you only have to replicate part of the repository directory
2830 hierarchy in your local build directory.
2831 This function is deprecated. For details, see the entry for the
2833 SourceCode function.
2834 Examples:
2836 # Will fetch foo/bar/src.c
2838 # from /usr/local/CVSROOT/foo/bar/src.c.
2839 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2840 # Will fetch bar/src.c
2842 # from /usr/local/CVSROOT/foo/bar/src.c.
2843 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2844 # Will fetch src.c
2846 # from /usr/local/CVSROOT/foo/bar/src.c.
2847 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2848 Decider(function)
2851 env.Decider(function)
2853 Specifies that all up-to-date decisions for targets built
2854 through this construction environment will be handled by the
2855 specified function. The function can be one of the following
2856 strings that specify the type of decision function to be per‐
2857 formed:
2858 timestamp-newer Specifies that a target shall be considered
2861 out of date and rebuilt if the dependency's timestamp
2862 is newer than the target file's timestamp. This is the
2863 behavior of the classic Make utility, and make can be
2864 used a synonym for timestamp-newer.
2865 timestamp-match Specifies that a target shall be considered
2868 out of date and rebuilt if the dependency's timestamp
2869 is different than the timestamp recorded the last time
2870 the target was built. This provides behavior very sim‐
2871 ilar to the classic Make utility (in particular, files
2872 are not opened up so that their contents can be check‐
2873 summed) except that the target will also be rebuilt if
2874 a dependency file has been restored to a version with
2875 an earlier timestamp, such as can happen when restoring
2876 files from backup archives.
2877 MD5 Specifies that a target shall be considered out of date
2880 and rebuilt if the dependency's content has changed
2881 sine the last time the target was built, as determined
2882 be performing an MD5 checksum on the dependency's con‐
2883 tents and comparing it to the checksum recorded the
2884 last time the target was built. content can be used as
2885 a synonym for MD5.
2886 MD5-timestamp Specifies that a target shall be considered out
2889 of date and rebuilt if the dependency's content has
2890 changed sine the last time the target was built, except
2891 that dependencies with a timestamp that matches the
2892 last time the target was rebuilt will be assumed to be
2893 up-to-date and not rebuilt. This provides behavior
2894 very similar to the MD5 behavior of always checksumming
2895 file contents, with an optimization of not checking the
2896 contents of files whose timestamps haven't changed.
2897 The drawback is that SCons will not detect if a file's
2898 content has changed but its timestamp is the same, as
2899 might happen in an automated script that runs a build,
2900 updates a file, and runs the build again, all within a
2901 single second.
2902 Examples:
2905 # Use exact timestamp matches by default.
2907 Decider('timestamp-match')
2908 # Use MD5 content signatures for any targets built
2910 # with the attached construction environment.
2911 env.Decider('content')
2912 In addition to the above already-available functions, the func‐
2915 tion argument may be an actual Python function that takes the
2916 following three arguments:
2917 dependency
2920 The Node (file) which should cause the target to be
2921 rebuilt if it has "changed" since the last tme target
2922 was built.
2923 target The Node (file) being built. In the normal case, this
2926 is what should get rebuilt if the dependency has
2927 "changed."
2928 prev_ni
2931 Stored information about the state of the dependency
2932 the last time the target was built. This can be con‐
2933 sulted to match various file characteristics such as
2934 the timestamp, size, or content signature.
2935 The function should return a True (non-zero) value if the depen‐
2938 dency has "changed" since the last time the target was built
2939 (indicating that the target should be rebuilt), and False (zero)
2940 otherwise (indicating that the target should not be rebuilt).
2941 Note that the decision can be made using whatever criteria are
2942 appopriate. Ignoring some or all of the function arguments is
2943 perfectly normal.
2944 Example:
2946 def my_decider(dependency, target, prev_ni):
2948 return not os.path.exists(str(target))
2949 env.Decider(my_decider)
2951 Default(targets)
2954 env.Default(targets)
2956 This specifies a list of default targets, which will be built by
2957 scons if no explicit targets are given on the command line.
2958 Multiple calls to Default() are legal, and add to the list of
2959 default targets.
2960 Multiple targets should be specified as separate arguments to
2962 the Default() method, or as a list. Default() will also accept
2963 the Node returned by any of a construction environment's builder
2964 methods.
2965 Examples:
2967 Default('foo', 'bar', 'baz')
2969 env.Default(['a', 'b', 'c'])
2970 hello = env.Program('hello', 'hello.c')
2971 env.Default(hello)
2972 An argument to Default() of None will clear all default targets.
2974 Later calls to Default() will add to the (now empty) default-
2975 target list like normal.
2976 The current list of targets added using the Default() function
2978 or method is available in the DEFAULT_TARGETS list; see below.
2979 DefaultEnvironment([args])
2982 Creates and returns a default construction environment object.
2983 This construction environment is used internally by SCons in
2984 order to execute many of the global functions in this list, and
2985 to fetch source files transparently from source code management
2986 systems.
2987 Depends(target, dependency)
2990 env.Depends(target, dependency)
2992 Specifies an explicit dependency; the target will be rebuilt
2993 whenever the dependency has changed. Both the specified target
2994 and dependency can be a string (usually the path name of a file
2995 or directory) or Node objects, or a list of strings or Node
2996 objects (such as returned by a Builder call). This should only
2997 be necessary for cases where the dependency is not caught by a
2998 Scanner for the file.
2999 Example:
3001 env.Depends('foo', 'other-input-file-for-foo')
3003 mylib = env.Library('mylib.c')
3005 installed_lib = env.Install('lib', mylib)
3006 bar = env.Program('bar.c')
3007 # Arrange for the library to be copied into the installation
3009 # directory before trying to build the "bar" program.
3010 # (Note that this is for example only. A "real" library
3011 # dependency would normally be configured through the $LIBS
3012 # and $LIBPATH variables, not using an env.Depends() call.)
3013 env.Depends(bar, installed_lib)
3015 env.Dictionary([vars])
3018 Returns a dictionary object containing copies of all of the con‐
3019 struction variables in the environment. If there are any vari‐
3020 able names specified, only the specified construction variables
3021 are returned in the dictionary.
3022 Example:
3024 dict = env.Dictionary()
3026 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3027 Dir(name, [directory])
3030 env.Dir(name, [directory])
3032 This returns a Directory Node, an object that represents the
3033 specified directory name. name can be a relative or absolute
3034 path. directory is an optional directory that will be used as
3035 the parent directory. If no directory is specified, the current
3036 script's directory is used as the parent.
3037 If name is a list, SCons returns a list of Dir nodes. Construc‐
3039 tion variables are expanded in name.
3040 Directory Nodes can be used anywhere you would supply a string
3042 as a directory name to a Builder method or function. Directory
3043 Nodes have attributes and methods that are useful in many situa‐
3044 tions; see "File and Directory Nodes," below.
3045 env.Dump([key])
3048 Returns a pretty printable representation of the environment.
3049 key, if not None, should be a string containing the name of the
3050 variable of interest.
3051 This SConstruct:
3053 env=Environment()
3054 print env.Dump('CCCOM')
3055 will print:
3057 '$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
3058 env=Environment()
3060 print env.Dump()
3061 will print:
3063 { 'AR': 'ar',
3064 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES0RANLIB $RANLIBFLAGS $TARGET',
3065 'ARFLAGS': ['r'],
3066 'AS': 'as',
3067 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3068 'ASFLAGS': [],
3069 ...
3070 EnsurePythonVersion(major, minor)
3073 env.EnsurePythonVersion(major, minor)
3075 Ensure that the Python version is at least major.minor. This
3076 function will print out an error message and exit SCons with a
3077 non-zero exit code if the actual Python version is not late
3078 enough.
3079 Example:
3081 EnsurePythonVersion(2,2)
3083 EnsureSConsVersion(major, minor, [revision])
3086 env.EnsureSConsVersion(major, minor, [revision])
3088 Ensure that the SCons version is at least major.minor, or
3089 major.minor.revision. if revision is specified. This function
3090 will print out an error message and exit SCons with a non-zero
3091 exit code if the actual SCons version is not late enough.
3092 Examples:
3094 EnsureSConsVersion(0,14)
3096 EnsureSConsVersion(0,96,90)
3098 Environment([key=value, ...])
3101 env.Environment([key=value, ...])
3103 Return a new construction environment initialized with the spec‐
3104 ified key=value pairs.
3105 Execute(action, [strfunction, varlist])
3108 env.Execute(action, [strfunction, varlist])
3110 Executes an Action object. The specified action may be an
3111 Action object (see the section "Action Objects," below, for a
3112 complete explanation of the arguments and behavior), or it may
3113 be a command-line string, list of commands, or executable Python
3114 function, each of which will be converted into an Action object
3115 and then executed. The exit value of the command or return
3116 value of the Python function will be returned.
3117 Note that scons will print an error message if the executed
3119 action fails--that is, exits with or returns a non-zero value.
3120 scons will not , however, automatically terminate the build if
3121 the specified action fails. If you want the build to stop in
3122 response to a failed Execute() call, you must explicitly check
3123 for a non-zero return value:
3124 Execute(Copy('file.out', 'file.in'))
3126 if Execute("mkdir sub/dir/ectory"):
3128 # The mkdir failed, don't try to build.
3129 Exit(1)
3130 Exit([value])
3133 env.Exit([value])
3135 This tells scons to exit immediately with the specified value.
3136 A default exit value of 0 (zero) is used if no value is speci‐
3137 fied.
3138 Export(vars)
3141 env.Export(vars)
3143 This tells scons to export a list of variables from the current
3144 SConscript file to all other SConscript files. The exported
3145 variables are kept in a global collection, so subsequent calls
3146 to Export() will over-write previous exports that have the same
3147 name. Multiple variable names can be passed to Export() as sep‐
3148 arate arguments or as a list. Keyword arguments can be used to
3149 provide names and their values. A dictionary can be used to map
3150 variables to a different name when exported. Both local vari‐
3151 ables and global variables can be exported.
3152 Examples:
3154 env = Environment()
3156 # Make env available for all SConscript files to Import().
3157 Export("env")
3158 package = 'my_name'
3160 # Make env and package available for all SConscript files:.
3161 Export("env", "package")
3162 # Make env and package available for all SConscript files:
3164 Export(["env", "package"])
3165 # Make env available using the name debug:
3167 Export(debug = env)
3168 # Make env available using the name debug:
3170 Export({"debug":env})
3171 Note that the SConscript() function supports an exports argument
3174 that makes it easier to to export a variable or set of variables
3175 to a single SConscript file. See the description of the SCon‐
3176 script() function, below.
3177 File(name, [directory])
3180 env.File(name, [directory])
3182 This returns a File Node, an object that represents the speci‐
3183 fied file name. name can be a relative or absolute path.
3184 directory is an optional directory that will be used as the par‐
3185 ent directory.
3186 If name is a list, SCons returns a list of File nodes. Con‐
3188 struction variables are expanded in name.
3189 File Nodes can be used anywhere you would supply a string as a
3191 file name to a Builder method or function. File Nodes have
3192 attributes and methods that are useful in many situations; see
3193 "File and Directory Nodes," below.
3194 FindFile(file, dirs)
3197 env.FindFile(file, dirs)
3199 Search for file in the path specified by dirs. dirs may be a
3200 list of directory names or a single directory name. In addition
3201 to searching for files that exist in the filesystem, this func‐
3202 tion also searches for derived files that have not yet been
3203 built.
3204 Example:
3206 foo = env.FindFile('foo', ['dir1', 'dir2'])
3208 FindInstalledFiles()
3211 env.FindInstalledFiles()
3213 Returns the list of targets set up by the Install() or Instal‐
3214 lAs() builders.
3215 This function serves as a convenient method to select the con‐
3217 tents of a binary package.
3218 Example:
3220 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3222 # will return the file node list
3224 # [ '/bin/executable_a', '/bin/executable_b' ]
3225 FindInstalledFiles()
3226 Install( '/lib', [ 'some_library' ] )
3228 # will return the file node list
3230 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3231 FindInstalledFiles()
3232 FindSourceFiles(node='"."')
3235 env.FindSourceFiles(node='"."')
3237 Returns the list of nodes which serve as the source of the built
3239 files. It does so by inspecting the dependency tree starting at
3240 the optional argument node which defaults to the '"."'-node. It
3241 will then return all leaves of node. These are all children
3242 which have no further children.
3243 This function is a convenient method to select the contents of a
3245 Source Package.
3246 Example:
3248 Program( 'src/main_a.c' )
3250 Program( 'src/main_b.c' )
3251 Program( 'main_c.c' )
3252 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3254 FindSourceFiles()
3255 # returns ['src/main_b.c', 'src/main_a.c' ]
3257 FindSourceFiles( 'src' )
3258 As you can see build support files (SConstruct in the above
3261 example) will also be returned by this function.
3262 FindPathDirs(variable)
3265 Returns a function (actually a callable Python object) intended
3266 to be used as the path_function of a Scanner object. The
3267 returned object will look up the specified variable in a con‐
3268 struction environment and treat the construction variable's
3269 value as a list of directory paths that should be searched (like
3270 CPPPATH, LIBPATH, etc.).
3271 Note that use of FindPathDirs() is generally preferable to writ‐
3273 ing your own path_function for the following reasons: 1) The
3274 returned list will contain all appropriate directories found in
3275 source trees (when VariantDir() is used) or in code repositories
3276 (when Repository() or the -Y option are used). 2) scons will
3277 identify expansions of variable that evaluate to the same list
3278 of directories as, in fact, the same list, and avoid re-scanning
3279 the directories for files, when possible.
3280 Example:
3282 def my_scan(node, env, path, arg):
3284 # Code to scan file contents goes here...
3285 return include_files
3286 scanner = Scanner(name = 'myscanner',
3288 function = my_scan,
3289 path_function = FindPathDirs('MYPATH'))
3290 Flatten(sequence)
3293 env.Flatten(sequence)
3295 Takes a sequence (that is, a Python list or tuple) that may con‐
3296 tain nested sequences and returns a flattened list containing
3297 all of the individual elements in any sequence. This can be
3298 helpful for collecting the lists returned by calls to Builders;
3299 other Builders will automatically flatten lists specified as
3300 input, but direct Python manipulation of these lists does not.
3301 Examples:
3303 foo = Object('foo.c')
3305 bar = Object('bar.c')
3306 # Because `foo' and `bar' are lists returned by the Object() Builder,
3308 # `objects' will be a list containing nested lists:
3309 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3310 # Passing such a list to another Builder is all right because
3312 # the Builder will flatten the list automatically:
3313 Program(source = objects)
3314 # If you need to manipulate the list directly using Python, you need to
3316 # call Flatten() yourself, or otherwise handle nested lists:
3317 for object in Flatten(objects):
3318 print str(object)
3319 GetBuildFailures()
3322 Returns a list of exceptions for the actions that failed while
3323 attempting to build targets. Each element in the returned list
3324 is a BuildError object with the following attributes that record
3325 various aspects of the build failure:
3326 .node The node that was being built when the build failure
3328 occurred.
3329 .status The numeric exit status returned by the command or
3331 Python function that failed when trying to build the specified
3332 Node.
3333 .errstr The SCons error string describing the build failure.
3335 (This is often a generic message like "Error 2" to indicate that
3336 an executed command exited with a status of 2.)
3337 .filename The name of the file or directory that actually caused
3339 the failure. This may be different from the .node attribute.
3340 For example, if an attempt to build a target named sub/dir/tar‐
3341 get fails because the sub/dir directory could not be created,
3342 then the .node attribute will be sub/dir/target but the .file‐
3343 name attribute will be sub/dir.
3344 .executor The SCons Executor object for the target Node being
3346 built. This can be used to retrieve the construction environ‐
3347 ment used for the failed action.
3348 .action The actual SCons Action object that failed. This will
3350 be one specific action out of the possible list of actions that
3351 would have been executed to build the target.
3352 .command The actual expanded command that was executed and
3354 failed, after expansion of $TARGET, $SOURCE, and other construc‐
3355 tion variables.
3356 Note that the GetBuildFailures() function will always return an
3358 empty list until any build failure has occurred, which means
3359 that GetBuildFailures() will always return an empty list while
3360 the SConscript files are being read. Its primary intended use
3361 is for functions that will be executed before SCons exits by
3362 passing them to the standard Python atexit.register() function.
3363 Example:
3364 import atexit
3366 def print_build_failures():
3368 from SCons.Script import GetBuildFailures
3369 for bf in GetBuildFailures():
3370 print "%s failed: %s" % (bf.node, bf.errstr)
3371 atexit.register(print_build_failures)
3373 GetBuildPath(file, [...])
3376 env.GetBuildPath(file, [...])
3378 Returns the scons path name (or names) for the specified file
3379 (or files). The specified file or files may be scons Nodes or
3380 strings representing path names.
3381 GetLaunchDir()
3384 env.GetLaunchDir()
3386 Returns the absolute path name of the directory from which scons
3387 was initially invoked. This can be useful when using the -u, -U
3388 or -D options, which internally change to the directory in which
3389 the SConstruct file is found.
3390 GetOption(name)
3393 env.GetOption(name)
3395 This function provides a way to query the value of SCons options
3396 set on scons command line (or set using the SetOption() func‐
3397 tion). The options supported are:
3398 cache_debug
3401 which corresponds to --cache-debug;
3402 cache_disable
3404 which corresponds to --cache-disable;
3405 cache_force
3407 which corresponds to --cache-force;
3408 cache_show
3410 which corresponds to --cache-show;
3411 clean which corresponds to -c, --clean and --remove;
3413 config
3415 which corresponds to --config;
3416 directory
3418 which corresponds to -C and --directory;
3419 diskcheck
3421 which corresponds to --diskcheck
3422 duplicate
3424 which corresponds to --duplicate;
3425 file which corresponds to -f, --file, --makefile and --scon‐
3427 struct;
3428 help which corresponds to -h and --help;
3430 ignore_errors
3432 which corresponds to --ignore-errors;
3433 implicit_cache
3435 which corresponds to --implicit-cache;
3436 implicit_deps_changed
3438 which corresponds to --implicit-deps-changed;
3439 implicit_deps_unchanged
3441 which corresponds to --implicit-deps-unchanged;
3442 interactive
3444 which corresponds to --interact and --interactive;
3445 keep_going
3447 which corresponds to -k and --keep-going;
3448 max_drift
3450 which corresponds to --max-drift;
3451 no_exec
3453 which corresponds to -n, --no-exec, --just-print,
3454 --dry-run and --recon;
3455 no_site_dir
3457 which corresponds to --no-site-dir;
3458 num_jobs
3460 which corresponds to -j and --jobs;
3461 profile_file
3463 which corresponds to --profile;
3464 question
3466 which corresponds to -q and --question;
3467 random
3469 which corresponds to --random;
3470 repository
3472 which corresponds to -Y, --repository and --srcdir;
3473 silent
3475 which corresponds to -s, --silent and --quiet;
3476 site_dir
3478 which corresponds to --site-dir;
3479 stack_size
3481 which corresponds to --stack-size;
3482 taskmastertrace_file
3484 which corresponds to --taskmastertrace; and
3485 warn which corresponds to --warn and --warning.
3487 See the documentation for the corresponding command line object
3490 for information about each specific option.
3491 Glob(pattern, [ondisk, source, strings])
3494 env.Glob(pattern, [ondisk, source, strings])
3496 Returns Nodes (or strings) that match the specified pattern,
3497 relative to the directory of the current SConscript file. The
3498 env.Glob() form performs string substition on pattern and
3499 returns whatever matches the resulting expanded pattern.
3500 The specified pattern uses Unix shell style metacharacters for
3502 matching:
3503 * matches everything
3505 ? matches any single character
3506 [seq] matches any character in seq
3507 [!seq] matches any char not in seq
3508 If the first character of a filename is a dot, it must be
3511 matched explicitly. Character matches do not span directory
3512 separators.
3513 The Glob() knows about repositories (see the Repository() func‐
3515 tion) and source directories (see the VariantDir() function) and
3516 returns a Node (or string, if so configured) in the local (SCon‐
3517 script) directory if matching Node is found anywhere in a corre‐
3518 sponding repository or source directory.
3519 The ondisk argument may be set to False (or any other non-true
3521 value) to disable the search for matches on disk, thereby only
3522 returning matches among already-configured File or Dir Nodes.
3523 The default behavior is to return corresponding Nodes for any
3524 on-disk matches found.
3525 The source argument may be set to True (or any equivalent value)
3527 to specify that, when the local directory is a VariantDir(), the
3528 returned Nodes should be from the corresponding source direc‐
3529 tory, not the local directory.
3530 The strings argument may be set to True (or any equivalent
3532 value) to have the Glob() function return strings, not Nodes,
3533 that represent the matched files or directories. The returned
3534 strings will be relative to the local (SConscript) directory.
3535 (Note that This may make it easier to perform arbitrary manipu‐
3536 lation of file names, but if the returned strings are passed to
3537 a different SConscript file, any Node translation will be rela‐
3538 tive to the other SConscript directory, not the original SCon‐
3539 script directory.)
3540 Examples:
3542 Program('foo', Glob('*.c'))
3544 Zip('/tmp/everything', Glob('.??*') + Glob('*'))
3545 Help(text)
3549 env.Help(text)
3551 This specifies help text to be printed if the -h argument is
3552 given to scons. If Help is called multiple times, the text is
3553 appended together in the order that Help is called.
3554 Ignore(target, dependency)
3557 env.Ignore(target, dependency)
3559 The specified dependency file(s) will be ignored when deciding
3560 if the target file(s) need to be rebuilt.
3561 You can also use Ignore() to remove a target from the default
3563 build. In order to do this you must specify the directory the
3564 target will be built in as the target, and the file you want to
3565 skip building as the dependency.
3566 Note that this will only remove the dependencies listed from the
3568 files built by default. It will still be built if that depen‐
3569 dency is needed by another object being built. See the third
3570 and forth examples below.
3571 Examples:
3573 env.Ignore('foo', 'foo.c')
3575 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3576 env.Ignore('.','foobar.obj')
3577 env.Ignore('bar','bar/foobar.obj')
3578 Import(vars)
3581 env.Import(vars)
3583 This tells scons to import a list of variables into the current
3584 SConscript file. This will import variables that were exported
3585 with Export() or in the exports argument to SConscript(). Vari‐
3586 ables exported by SConscript() have precedence. Multiple vari‐
3587 able names can be passed to Import() as separate arguments or as
3588 a list. The variable "*" can be used to import all variables.
3589 Examples:
3591 Import("env")
3593 Import("env", "variable")
3594 Import(["env", "variable"])
3595 Import("*")
3596 Literal(string)
3599 env.Literal(string)
3601 The specified string will be preserved as-is and not have con‐
3602 struction variables expanded.
3603 Local(targets)
3606 env.Local(targets)
3608 The specified targets will have copies made in the local tree,
3609 even if an already up-to-date copy exists in a repository.
3610 Returns a list of the target Node or Nodes.
3611 env.MergeFlags(arg, [unique])
3651 Merges the specified arg values to the construction environ‐
3652 ment's construction variables. If the arg argument is not a
3653 dictionary, it is converted to one by calling env.ParseFlags()
3654 on the argument before the values are merged. Note that arg
3655 must be a single value, so multiple strings must be passed in as
3656 a list, not as separate arguments to env.MergeFlags().
3657 By default, duplicate values are eliminated; you can, however,
3659 specify unique=0 to allow duplicate values to be added. When
3660 eliminating duplicate values, any construction variables that
3661 end with the string PATH keep the left-most unique value. All
3662 other construction variables keep the right-most unique value.
3663 Examples:
3665 # Add an optimization flag to $CCFLAGS.
3667 env.MergeFlags('-O3')
3668 # Combine the flags returned from running pkg-config with an optimization
3670 # flag and merge the result into the construction variables.
3671 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
3672 # Combine an optimization flag with the flags returned from running pkg-config
3674 # twice and merge the result into the construction variables.
3675 env.MergeFlags(['-O3',
3676 '!pkg-config gtk+-2.0 --cflags --libs',
3677 '!pkg-config libpng12 --cflags --libs'])
3678 NoCache(target, ...)
3681 env.NoCache(target, ...)
3683 Specifies a list of files which should not be cached whenever
3684 the CacheDir() method has been activated. The specified targets
3685 may be a list or an individual target.
3686 Multiple files should be specified either as separate arguments
3688 to the NoCache() method, or as a list. NoCache() will also
3689 accept the return value of any of the construction environment
3690 Builder methods.
3691 Calling NoCache() on directories and other non-File Node types
3693 has no effect because only File Nodes are cached.
3694 Examples:
3696 NoCache('foo.elf')
3698 NoCache(env.Program('hello', 'hello.c'))
3699 NoClean(target, ...)
3702 env.NoClean(target, ...)
3704 Specifies a list of files or directories which should not be
3705 removed whenever the targets (or their dependencies) are speci‐
3706 fied with the -c command line option. The specified targets may
3707 be a list or an individual target. Multiple calls to NoClean()
3708 are legal, and prevent each specified target from being removed
3709 by calls to the -c option.
3710 Multiple files or directories should be specified either as sep‐
3712 arate arguments to the NoClean() method, or as a list.
3713 NoClean() will also accept the return value of any of the con‐
3714 struction environment Builder methods.
3715 Calling NoClean() for a target overrides calling Clean() for the
3717 same target, and any targets passed to both functions will not
3718 be removed by the -c option.
3719 Examples:
3721 NoClean('foo.elf')
3723 NoClean(env.Program('hello', 'hello.c'))
3724 env.ParseConfig(command, [function, unique])
3727 Calls the specified function to modify the environment as speci‐
3728 fied by the output of command . The default function is
3729 env.MergeFlags(), which expects the output of a typical *-config
3730 command (for example, gtk-config) and adds the options to the
3731 appropriate construction variables. By default, duplicate val‐
3732 ues are not added to any construction variables; you can specify
3733 unique=0 to allow duplicate values to be added.
3734 Interpreted options and the construction variables they affect
3736 are as specified for the env.ParseFlags() method (which this
3737 method calls). See that method's description, below, for a ta‐
3738 ble of options and construction variables.
3739 ParseDepends(filename, [must_exist, only_one])
3742 env.ParseDepends(filename, [must_exist, only_one])
3744 Parses the contents of the specified filename as a list of
3745 dependencies in the style of Make or mkdep, and explicitly
3746 establishes all of the listed dependencies.
3747 By default, it is not an error if the specified filename does
3749 not exist. The optional must_exist argument may be set to a
3750 non-zero value to have scons throw an exception and generate an
3751 error if the file does not exist, or is otherwise inaccessible.
3752 The optional only_one argument may be set to a non-zero value to
3754 have scons thrown an exception and generate an error if the file
3755 contains dependency information for more than one target. This
3756 can provide a small sanity check for files intended to be gener‐
3757 ated by, for example, the gcc -M flag, which should typically
3758 only write dependency information for one output file into a
3759 corresponding .d file.
3760 The filename and all of the files listed therein will be inter‐
3762 preted relative to the directory of the SConscript file which
3763 calls the ParseDepends function.
3764 env.ParseFlags(flags, ...)
3767 Parses one or more strings containing typical command-line flags
3768 for GCC tool chains and returns a dictionary with the flag val‐
3769 ues separated into the appropriate SCons construction variables.
3770 This is intended as a companion to the env.MergeFlags() method,
3771 but allows for the values in the returned dictionary to be modi‐
3772 fied, if necessary, before merging them into the construction
3773 environment. (Note that env.MergeFlags() will call this method
3774 if its argument is not a dictionary, so it is usually not neces‐
3775 sary to call env.ParseFlags() directly unless you want to manip‐
3776 ulate the values.)
3777 If the first character in any string is an exclamation mark (!),
3779 the rest of the string is executed as a command, and the output
3780 from the command is parsed as GCC tool chain command-line flags
3781 and added to the resulting dictionary.
3782 Flag values are translated accordig to the prefix found, and
3784 added to the following construction variables:
3785 -arch CCFLAGS, LINKFLAGS
3787 -D CPPDEFINES
3788 -framework FRAMEWORKS
3789 -frameworkdir= FRAMEWORKPATH
3790 -include CCFLAGS
3791 -isysroot CCFLAGS, LINKFLAGS
3792 -I CPPPATH
3793 -l LIBS
3794 -L LIBPATH
3795 -mno-cygwin CCFLAGS, LINKFLAGS
3796 -mwindows LINKFLAGS
3797 -pthread CCFLAGS, LINKFLAGS
3798 -std= CFLAGS
3799 -Wa, ASFLAGS, CCFLAGS
3800 -Wl,-rpath= RPATH
3801 -Wl,-R, RPATH
3802 -Wl,-R RPATH
3803 -Wl, LINKFLAGS
3804 -Wp, CPPFLAGS
3805 - CCFLAGS
3806 + CCFLAGS, LINKFLAGS
3807 Any other strings not associated with options are assumed to be
3810 the names of libraries and added to the LIBS construction vari‐
3811 able.
3812 Examples (all of which produce the same result):
3814 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3816 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3817 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3818 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3819 env.Perforce()
3822 A factory function that returns a Builder object to be used to
3823 fetch source files from the Perforce source code management sys‐
3824 tem. The returned Builder is intended to be passed to the
3825 SourceCode function.
3826 This function is deprecated. For details, see the entry for the
3828 SourceCode function.
3829 Example:
3831 env.SourceCode('.', env.Perforce())
3833 Perforce uses a number of external environment variables for its
3835 operation. Consequently, this function adds the following vari‐
3836 ables from the user's external environment to the construction
3837 environment's ENV dictionary: P4CHARSET, P4CLIENT, P4LANGUAGE,
3838 P4PASSWD, P4PORT, P4USER, SystemRoot, USER, and USERNAME.
3839 Platform(string)
3842 Returns a callable object that can be used to initialize a con‐
3843 struction environment using the platform keyword of the Environ‐
3844 ment() method.
3845 Example:
3847 env = Environment(platform = Platform('win32'))
3849 env.Platform(string)
3851 Applies the callable object for the specified platform string to
3852 the environment through which the method was called.
3853 env.Platform('posix')
3855 Note that the win32 platform adds the SystemDrive and SystemRoot
3857 variables from the user's external environment to the construc‐
3858 tion environment's ENV dictionary. This is so that any executed
3859 commands that use sockets to connect with other systems (such as
3860 fetching source files from external CVS repository specifica‐
3861 tions like :pserver:anonymous@cvs.sourceforge.net:/cvs‐
3862 root/scons) will work on Windows systems.
3863 Progress(callable, [interval])
3866 Progress(string, [interval, file, overwrite])
3868 Progress(list_of_strings, [interval, file, overwrite])
3870 Allows SCons to show progress made during the build by display‐
3871 ing a string or calling a function while evaluating Nodes (e.g.
3872 files).
3873 If the first specified argument is a Python callable (a function
3875 or an object that has a __call__() method), the function will be
3876 called once every interval times a Node is evaluated. The
3877 callable will be passed the evaluated Node as its only argument.
3878 (For future compatibility, it's a good idea to also add *args
3879 and **kw as arguments to your function or method. This will
3880 prevent the code from breaking if SCons ever changes the inter‐
3881 face to call the function with additional arguments in the
3882 future.)
3883 An example of a simple custom progress function that prints a
3885 string containing the Node name every 10 Nodes:
3886 def my_progress_function(node, *args, **kw):
3888 print 'Evaluating node %s!' % node
3889 Progress(my_progress_function, interval=10)
3890 A more complicated example of a custom progress display object
3892 that prints a string containing a count every 100 evaluated
3893 Nodes. Note the use of \r (a carriage return) at the end so
3894 that the string will overwrite itself on a display:
3895 import sys
3897 class ProgressCounter(object):
3898 count = 0
3899 def __call__(self, node, *args, **kw):
3900 self.count += 100
3901 sys.stderr.write('Evaluated %s nodes\r' % self.count)
3902 Progress(ProgressCounter(), interval=100)
3903 If the first argument Progress() is a string, the string will be
3905 displayed every interval evaluated Nodes. The default is to
3906 print the string on standard output; an alternate output stream
3907 may be specified with the file= argument. The following will
3908 print a series of dots on the error output, one dot for every
3909 100 evaluated Nodes:
3910 import sys
3912 Progress('.', interval=100, file=sys.stderr)
3913 If the string contains the verbatim substring $TARGET, it will
3915 be replaced with the Node. Note that, for performance reasons,
3916 this is not a regular SCons variable substition, so you can not
3917 use other variables or use curly braces. The following example
3918 will print the name of every evaluated Node, using a \r (car‐
3919 riage return) to cause each line to overwritten by the next
3920 line, and the overwrite= keyword argument to make sure the pre‐
3921 viously-printed file name is overwritten with blank spaces:
3922 import sys
3924 Progress('$TARGET\r', overwrite=True)
3925 If the first argument to Progress() is a list of strings, then
3927 each string in the list will be displayed in rotating fashion
3928 every interval evaluated Nodes. This can be used to implement a
3929 "spinner" on the user's screen as follows:
3930 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
3932 Precious(target, ...)
3935 env.Precious(target, ...)
3937 Marks each given target as precious so it is not deleted before
3938 it is rebuilt. Normally scons deletes a target before building
3939 it. Multiple targets can be passed in to a single call to Pre‐
3940 cious().
3941 env.Prepend(key=val, [...])
3944 Appends the specified keyword arguments to the beginning of con‐
3945 struction variables in the environment. If the Environment does
3946 not have the specified construction variable, it is simply added
3947 to the environment. If the values of the construction variable
3948 and the keyword argument are the same type, then the two values
3949 will be simply added together. Otherwise, the construction
3950 variable and the value of the keyword argument are both coerced
3951 to lists, and the lists are added together. (See also the
3952 Append method, above.)
3953 Example:
3955 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3957 env.PrependENVPath(name, newpath, [envname, sep, delete_existing])
3960 This appends new path elements to the given path in the speci‐
3961 fied external environment (ENV by default). This will only add
3962 any particular path once (leaving the first one it encounters
3963 and ignoring the rest, to preserve path order), and to help
3964 assure this, will normalize all paths (using os.path.normpath
3965 and os.path.normcase). This can also handle the case where the
3966 given old path variable is a list instead of a string, in which
3967 case a list will be returned instead of a string.
3968 If delete_existing is 0, then adding a path that already exists
3970 will not move it to the beginning; it will stay where it is in
3971 the list.
3972 Example:
3974 print 'before:',env['ENV']['INCLUDE']
3976 include_path = '/foo/bar:/foo'
3977 env.PrependENVPath('INCLUDE', include_path)
3978 print 'after:',env['ENV']['INCLUDE']
3979 The above exmaple will print:
3981 before: /biz:/foo
3983 after: /foo/bar:/foo:/biz
3984 env.PrependUnique(key=val, delete_existing=0, [...])
3987 Appends the specified keyword arguments to the beginning of con‐
3988 struction variables in the environment. If the Environment does
3989 not have the specified construction variable, it is simply added
3990 to the environment. If the construction variable being appended
3991 to is a list, then any value(s) that already exist in the con‐
3992 struction variable will not be added again to the list. How‐
3993 ever, if delete_existing is 1, existing matching values are
3994 removed first, so existing values in the arg list move to the
3995 front of the list.
3996 Example:
3998 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4000 env.RCS()
4003 A factory function that returns a Builder object to be used to
4004 fetch source files from RCS. The returned Builder is intended
4005 to be passed to the SourceCode function:
4006 This function is deprecated. For details, see the entry for the
4008 SourceCode function.
4009 Examples:
4011 env.SourceCode('.', env.RCS())
4013 Note that scons will fetch source files from RCS subdirectories
4015 automatically, so configuring RCS as demonstrated in the above
4016 example should only be necessary if you are fetching from RCS,v
4017 files in the same directory as the source files, or if you need
4018 to explicitly specify RCS for a specific subdirectory.
4019 env.Replace(key=val, [...])
4022 Replaces construction variables in the Environment with the
4023 specified keyword arguments.
4024 Example:
4026 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
4028 Repository(directory)
4031 env.Repository(directory)
4033 Specifies that directory is a repository to be searched for
4034 files. Multiple calls to Repository() are legal, and each one
4035 adds to the list of repositories that will be searched.
4036 To scons, a repository is a copy of the source tree, from the
4038 top-level directory on down, which may contain both source files
4039 and derived files that can be used to build targets in the local
4040 source tree. The canonical example would be an official source
4041 tree maintained by an integrator. If the repository contains
4042 derived files, then the derived files should have been built
4043 using scons, so that the repository contains the necessary sig‐
4044 nature information to allow scons to figure out when it is
4045 appropriate to use the repository copy of a derived file,
4046 instead of building one locally.
4047 Note that if an up-to-date derived file already exists in a
4049 repository, scons will not make a copy in the local directory
4050 tree. In order to guarantee that a local copy will be made, use
4051 the Local() method.
4052 Requires(target, prerequisite)
4055 env.Requires(target, prerequisite)
4057 Specifies an order-only relationship between the specified tar‐
4058 get file(s) and the specified prerequisite file(s). The prereq‐
4059 uisite file(s) will be (re)built, if necessary, before the tar‐
4060 get file(s), but the target file(s) do not actually depend on
4061 the prerequisites and will not be rebuilt simply because the
4062 prerequisite file(s) change.
4063 Example:
4065 env.Requires('foo', 'file-that-must-be-built-before-foo')
4067 Return([vars... , stop=])
4070 By default, this stops processing the current SConscript file
4071 and returns to the calling SConscript file the values of the
4072 variables named in the vars string arguments. Multiple strings
4073 contaning variable names may be passed to Return(). Any strings
4074 that contain white space
4075 The optional stop= keyword argument may be set to a false value
4077 to continue processing the rest of the SConscript file after the
4078 Return() call. This was the default behavior prior to SCons
4079 0.98. However, the values returned are still the values of the
4080 variables in the named vars at the point Return() is called.
4081 Examples:
4083 # Returns without returning a value.
4085 Return()
4086 # Returns the value of the 'foo' Python variable.
4088 Return("foo")
4089 # Returns the values of the Python variables 'foo' and 'bar'.
4091 Return("foo", "bar")
4092 # Returns the values of Python variables 'val1' and 'val2'.
4094 Return('val1 val2')
4095 Scanner(function, [argument, keys, path_function, node_class, node_fac‐
4098 tory, scan_check, recursive])
4099 env.Scanner(function, [argument, keys, path_function, node_class,
4101 node_factory, scan_check, recursive])
4102 Creates a Scanner object for the specified function. See the
4103 section "Scanner Objects," below, for a complete explanation of
4104 the arguments and behavior.
4105 env.SCCS()
4108 A factory function that returns a Builder object to be used to
4109 fetch source files from SCCS. The returned Builder is intended
4110 to be passed to the SourceCode function.
4111 This function is deprecated. For details, see the entry for the
4113 SourceCode function.
4114 Example:
4116 env.SourceCode('.', env.SCCS())
4118 Note that scons will fetch source files from SCCS subdirectories
4120 automatically, so configuring SCCS as demonstrated in the above
4121 example should only be necessary if you are fetching from s.SCCS
4122 files in the same directory as the source files, or if you need
4123 to explicitly specify SCCS for a specific subdirectory.
4124 SConscript(scripts, [exports, variant_dir, duplicate])
4127 env.SConscript(scripts, [exports, variant_dir, duplicate])
4129 SConscript(dirs=subdirs, [name=script, exports, variant_dir, dupli‐
4131 cate])
4132 env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, dupli‐
4134 cate])
4135 This tells scons to execute one or more subsidiary SConscript
4136 (configuration) files. Any variables returned by a called
4137 script using Return() will be returned by the call to SCon‐
4138 script(). There are two ways to call the SConscript() function.
4139 The first way you can call SConscript() is to explicitly specify
4141 one or more scripts as the first argument. A single script may
4142 be specified as a string; multiple scripts must be specified as
4143 a list (either explicitly or as created by a function like
4144 Split()). Examples:
4145 SConscript('SConscript') # run SConscript in the current directory
4146 SConscript('src/SConscript') # run SConscript in the src directory
4147 SConscript(['src/SConscript', 'doc/SConscript'])
4148 config = SConscript('MyConfig.py')
4149 The second way you can call SConscript() is to specify a list of
4151 (sub)directory names as a dirs=subdirs keyword argument. In this case,
4152 scons will, by default, execute a subsidiary configuration file named
4153 SConscript in each of the specified directories. You may specify a
4154 name other than SConscript by supplying an optional name=script keyword
4155 argument. The first three examples below have the same effect as the
4156 first three examples above:
4157 SConscript(dirs='.') # run SConscript in the current directory
4158 SConscript(dirs='src') # run SConscript in the src directory
4159 SConscript(dirs=['src', 'doc'])
4160 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
4161 The optional exports argument provides a list of variable names or a
4163 dictionary of named values to export to the script(s). These variables
4164 are locally exported only to the specified script(s), and do not affect
4165 the global pool of variables used by the Export() function. The sub‐
4166 sidiary script(s) must use the Import() function to import the vari‐
4167 ables. Examples:
4168 foo = SConscript('sub/SConscript', exports='env')
4169 SConscript('dir/SConscript', exports=['env', 'variable'])
4170 SConscript(dirs='subdir', exports='env variable')
4171 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
4172 If the optional variant_dir argument is present, it causes an effect
4174 equivalent to the VariantDir() method described below. (If variant_dir
4175 is not present, the duplicate argument is ignored.) The variant_dir
4176 argument is interpreted relative to the directory of the calling SCon‐
4177 script file. See the description of the VariantDir() function below
4178 for additional details and restrictions.
4179 If variant_dir is present, the source directory is the directory in
4181 which the SConscript file resides and the SConscript file is evaluated
4182 as if it were in the variant_dir directory:
4183 SConscript('src/SConscript', variant_dir = 'build')
4184 is equivalent to
4185 VariantDir('build', 'src')
4186 SConscript('build/SConscript')
4187 This later paradigm is often used when the sources are in the same
4188 directory as the SConstruct:
4189 SConscript('SConscript', variant_dir = 'build')
4190 is equivalent to
4191 VariantDir('build', '.')
4192 SConscript('build/SConscript')
4193 Here are some composite examples:
4196 # collect the configuration information and use it to build src and doc
4198 shared_info = SConscript('MyConfig.py')
4199 SConscript('src/SConscript', exports='shared_info')
4200 SConscript('doc/SConscript', exports='shared_info')
4201 # build debugging and production versions. SConscript
4203 # can use Dir('.').path to determine variant.
4204 SConscript('SConscript', variant_dir='debug', duplicate=0)
4205 SConscript('SConscript', variant_dir='prod', duplicate=0)
4206 # build debugging and production versions. SConscript
4208 # is passed flags to use.
4209 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
4210 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
4211 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
4212 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
4213 # build common documentation and compile for different architectures
4215 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
4216 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
4217 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
4218 SConscriptChdir(value)
4221 env.SConscriptChdir(value)
4223 By default, scons changes its working directory to the directory
4224 in which each subsidiary SConscript file lives. This behavior
4225 may be disabled by specifying either:
4226 SConscriptChdir(0)
4228 env.SConscriptChdir(0)
4229 in which case scons will stay in the top-level directory while
4231 reading all SConscript files. (This may be necessary when
4232 building from repositories, when all the directories in which
4233 SConscript files may be found don't necessarily exist locally.)
4234 You may enable and disable this ability by calling SCon‐
4235 scriptChdir() multiple times.
4236 Example:
4238 env = Environment()
4240 SConscriptChdir(0)
4241 SConscript('foo/SConscript') # will not chdir to foo
4242 env.SConscriptChdir(1)
4243 SConscript('bar/SConscript') # will chdir to bar
4244 SConsignFile([file,dbm_module])
4247 env.SConsignFile([file,dbm_module])
4249 This tells scons to store all file signatures in the specified
4250 database file. If the file name is omitted, .sconsign is used
4251 by default. (The actual file name(s) stored on disk may have an
4252 appropriated suffix appended by the dbm_module.) If file is not
4253 an absolute path name, the file is placed in the same directory
4254 as the top-level SConstruct file.
4255 If file is None, then scons will store file signatures in a sep‐
4257 arate .sconsign file in each directory, not in one global data‐
4258 base file. (This was the default behavior prior to SCons
4259 0.96.91 and 0.97.)
4260 The optional dbm_module argument can be used to specify which
4262 Python database module The default is to use a custom
4263 SCons.dblite module that uses pickled Python data structures,
4264 and which works on all Python versions.
4265 Examples:
4267 # Explicitly stores signatures in ".sconsign.dblite"
4269 # in the top-level SConstruct directory (the
4270 # default behavior).
4271 SConsignFile()
4272 # Stores signatures in the file "etc/scons-signatures"
4274 # relative to the top-level SConstruct directory.
4275 SConsignFile("etc/scons-signatures")
4276 # Stores signatures in the specified absolute file name.
4278 SConsignFile("/home/me/SCons/signatures")
4279 # Stores signatures in a separate .sconsign file
4281 # in each directory.
4282 SConsignFile(None)
4283 env.SetDefault(key=val, [...])
4286 Sets construction variables to default values specified with the
4287 keyword arguments if (and only if) the variables are not already
4288 set. The following statements are equivalent:
4289 env.SetDefault(FOO = 'foo')
4291 if 'FOO' not in env: env['FOO'] = 'foo'
4293 SetOption(name, value)
4296 env.SetOption(name, value)
4298 This function provides a way to set a select subset of the scons
4299 command line options from a SConscript file. The options sup‐
4300 ported are:
4301 clean which corresponds to -c, --clean and --remove;
4304 duplicate
4306 which corresponds to --duplicate;
4307 help which corresponds to -h and --help;
4309 implicit_cache
4311 which corresponds to --implicit-cache;
4312 max_drift
4314 which corresponds to --max-drift;
4315 no_exec
4317 which corresponds to -n, --no-exec, --just-print,
4318 --dry-run and --recon;
4319 num_jobs
4321 which corresponds to -j and --jobs;
4322 random
4324 which corresponds to --random; and
4325 stack_size
4327 which corresponds to --stack-size.
4328 See the documentation for the corresponding command line object
4331 for information about each specific option.
4332 Example:
4334 SetOption('max_drift', 1)
4336 SideEffect(side_effect, target)
4339 env.SideEffect(side_effect, target)
4341 Declares side_effect as a side effect of building target. Both
4342 side_effect and target can be a list, a file name, or a node. A
4343 side effect is a target file that is created or updated as a
4344 side effect of building other targets. For example, a Windows
4345 PDB file is created as a side effect of building the .obj files
4346 for a static library, and various log files are created updated
4347 as side effects of various TeX commands. If a target is a side
4348 effect of multiple build commands, scons will ensure that only
4349 one set of commands is executed at a time. Consequently, you
4350 only need to use this method for side-effect targets that are
4351 built as a result of multiple build commands.
4352 Because multiple build commands may update the same side effect
4354 file, by default the side_effect target is not automatically
4355 removed when the target is removed by the -c option. (Note,
4356 however, that the side_effect might be removed as part of clean‐
4357 ing the directory in which it lives.) If you want to make sure
4358 the side_effect is cleaned whenever a specific target is
4359 cleaned, you must specify this explicitly with the Clean() or
4360 env.Clean() function.
4361 SourceCode(entries, builder)
4364 env.SourceCode(entries, builder)
4366 This function and its associate factory functions are depre‐
4367 cated. There is no replacement. The intended use was to keep a
4368 local tree in sync with an archive, but in actuality the func‐
4369 tion only causes the archive to be fetched on the first run.
4370 Synchronizing with the archive is best done external to SCons.
4371 Arrange for non-existent source files to be fetched from a
4373 source code management system using the specified builder. The
4374 specified entries may be a Node, string or list of both, and may
4375 represent either individual source files or directories in which
4376 source files can be found.
4377 For any non-existent source files, scons will search up the
4379 directory tree and use the first SourceCode builder it finds.
4380 The specified builder may be None, in which case scons will not
4381 use a builder to fetch source files for the specified entries,
4382 even if a SourceCode builder has been specified for a directory
4383 higher up the tree.
4384 scons will, by default, fetch files from SCCS or RCS subdirecto‐
4386 ries without explicit configuration. This takes some extra pro‐
4387 cessing time to search for the necessary source code management
4388 files on disk. You can avoid these extra searches and speed up
4389 your build a little by disabling these searches as follows:
4390 env.SourceCode('.', None)
4392 Note that if the specified builder is one you create by hand, it
4395 must have an associated construction environment to use when
4396 fetching a source file.
4397 scons provides a set of canned factory functions that return
4399 appropriate Builders for various popular source code management
4400 systems. Canonical examples of invocation include:
4401 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4403 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4404 env.SourceCode('/', env.RCS())
4405 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4406 env.SourceCode('no_source.c', None)
4407 env.subst(input, [raw, target, source, conv])
4410 Performs construction variable interpolation on the specified
4411 string or sequence argument input.
4412 By default, leading or trailing white space will be removed from
4414 the result. and all sequences of white space will be compressed
4415 to a single space character. Additionally, any $( and $) char‐
4416 acter sequences will be stripped from the returned string, The
4417 optional raw argument may be set to 1 if you want to preserve
4418 white space and $(-$) sequences. The raw argument may be set to
4419 2 if you want to strip all characters between any $( and $)
4420 pairs (as is done for signature calculation).
4421 If the input is a sequence (list or tuple), the individual ele‐
4423 ments of the sequence will be expanded, and the results will be
4424 returned as a list.
4425 The optional target and source keyword arguments must be set to
4427 lists of target and source nodes, respectively, if you want the
4428 $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for
4429 expansion. This is usually necessary if you are calling
4430 env.subst() from within a Python function used as an SCons
4431 action.
4432 Returned string values or sequence elements are converted to
4434 their string representation by default. The optional conv argu‐
4435 ment may specify a conversion function that will be used in
4436 place of the default. For example, if you want Python objects
4437 (including SCons Nodes) to be returned as Python objects, you
4438 can use the Python lambda idiom to pass in an unnamed function
4439 that simply returns its unconverted argument.
4440 Example:
4442 print env.subst("The C compiler is: $CC")
4444 def compile(target, source, env):
4446 sourceDir = env.subst("${SOURCE.srcdir}",
4447 target=target,
4448 source=source)
4449 source_nodes = env.subst('$EXPAND_TO_NODELIST',
4451 conv=lambda x: x)
4452 SourceSignatures(type)
4456 env.SourceSignatures(type)
4458 Note: Although it is not yet officially deprecated, use of this
4459 function is discouraged. See the Decider() function for a more
4460 flexible and straightforward way to configure SCons' decision-
4461 making.
4462 The SourceSignatures() function tells scons how to decide if a
4464 source file (a file that is not built from any other files) has
4465 changed since the last time it was used to build a particular
4466 target file. Legal values are MD5 or timestamp.
4467 If the environment method is used, the specified type of source
4469 signature is only used when deciding whether targets built with
4470 that environment are up-to-date or must be rebuilt. If the
4471 global function is used, the specified type of source signature
4472 becomes the default used for all decisions about whether targets
4473 are up-to-date.
4474 MD5 means scons decides that a source file has changed if the
4476 MD5 checksum of its contents has changed since the last time it
4477 was used to rebuild a particular target file.
4478 timestamp means scons decides that a source file has changed if
4480 its timestamp (modification time) has changed since the last
4481 time it was used to rebuild a particular target file. (Note
4482 that although this is similar to the behavior of Make, by
4483 default it will also rebuild if the dependency is older than the
4484 last time it was used to rebuild the target file.)
4485 There is no different between the two behaviors for Python
4487 Value() node objects.
4488 MD5 signatures take longer to compute, but are more accurate
4490 than timestamp signatures. The default value is MD5.
4491 Note that the default TargetSignatures() setting (see below) is
4493 to use this SourceSignatures() setting for any target files that
4494 are used to build other target files. Consequently, changing
4495 the value of SourceSignatures() will, by default, affect the up-
4496 to-date decision for all files in the build (or all files built
4497 with a specific construction environment when env.SourceSigna‐
4498 tures() is used).
4499 Split(arg)
4502 env.Split(arg)
4504 Returns a list of file names or other objects. If arg is a
4505 string, it will be split on strings of white-space characters
4506 within the string, making it easier to write long lists of file
4507 names. If arg is already a list, the list will be returned
4508 untouched. If arg is any other type of object, it will be
4509 returned as a list containing just the object.
4510 Example:
4512 files = Split("f1.c f2.c f3.c")
4514 files = env.Split("f4.c f5.c f6.c")
4515 files = Split("""
4516 f7.c
4517 f8.c
4518 f9.c
4519 """)
4520 Tag(node, tags)
4523 Annotates file or directory Nodes with information about how the
4524 Package() Builder should package those files or directories.
4525 All tags are optional.
4526 Examples:
4528 # makes sure the built library will be installed with 0644 file
4530 # access mode
4531 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
4532 # marks file2.txt to be a documentation file
4534 Tag( 'file2.txt', DOC )
4535 TargetSignatures(type)
4538 env.TargetSignatures(type)
4540 Note: Although it is not yet officially deprecated, use of this
4541 function is discouraged. See the Decider() function for a more
4542 flexible and straightforward way to configure SCons' decision-
4543 making.
4544 The TargetSignatures() function tells scons how to decide if a
4546 target file (a file that is built from any other files) has
4547 changed since the last time it was used to build some other tar‐
4548 get file. Legal values are build; content (or its synonym MD5);
4549 timestamp; or source.
4550 If the environment method is used, the specified type of target
4552 signature is only used for targets built with that environment.
4553 If the global function is used, the specified type of signature
4554 becomes the default used for all target files that don't have an
4555 explicit target signature type specified for their environments.
4556 content (or its synonym MD5) means scons decides that a target
4558 file has changed if the MD5 checksum of its contents has changed
4559 since the last time it was used to rebuild some other target
4560 file. This means scons will open up MD5 sum the contents of
4561 target files after they're built, and may decide that it does
4562 not need to rebuild "downstream" target files if a file was
4563 rebuilt with exactly the same contents as the last time.
4564 timestamp means scons decides that a target file has changed if
4566 its timestamp (modification time) has changed since the last
4567 time it was used to rebuild some other target file. (Note that
4568 although this is similar to the behavior of Make, by default it
4569 will also rebuild if the dependency is older than the last time
4570 it was used to rebuild the target file.)
4571 source means scons decides that a target file has changed as
4573 specified by the corresponding SourceSignatures() setting (MD5
4574 or timestamp). This means that scons will treat all input files
4575 to a target the same way, regardless of whether they are source
4576 files or have been built from other files.
4577 build means scons decides that a target file has changed if it
4579 has been rebuilt in this invocation or if its content or time‐
4580 stamp have changed as specified by the corresponding SourceSig‐
4581 natures() setting. This "propagates" the status of a rebuilt
4582 file so that other "downstream" target files will always be
4583 rebuilt, even if the contents or the timestamp have not changed.
4584 build signatures are fastest because content (or MD5) signatures
4586 take longer to compute, but are more accurate than timestamp
4587 signatures, and can prevent unnecessary "downstream" rebuilds
4588 when a target file is rebuilt to the exact same contents as the
4589 previous build. The source setting provides the most consistent
4590 behavior when other target files may be rebuilt from both source
4591 and target input files. The default value is source.
4592 Because the default setting is source, using SourceSignatures()
4594 is generally preferable to TargetSignatures(), so that the up-
4595 to-date decision will be consistent for all files (or all files
4596 built with a specific construction environment). Use of Tar‐
4597 getSignatures() provides specific control for how built target
4598 files affect their "downstream" dependencies.
4599 Tool(string[,toolpath, **kw])
4602 Returns a callable object that can be used to initialize a con‐
4603 struction environment using the tools keyword of the Environ‐
4604 ment() method. The object may be called with a construction
4605 environment as an argument, in which case the object will add
4606 the necessary variables to the construction environment and the
4607 name of the tool will be added to the $TOOLS construction vari‐
4608 able.
4609 Additional keyword arguments are passed to the tool's generate()
4611 method.
4612 Examples:
4614 env = Environment(tools = [ Tool('msvc') ])
4616 env = Environment()
4618 t = Tool('msvc')
4619 t(env) # adds 'msvc' to the TOOLS variable
4620 u = Tool('opengl', toolpath = ['tools'])
4621 u(env) # adds 'opengl' to the TOOLS variable
4622 env.Tool(string[,toolpath, **kw])
4624 Applies the callable object for the specified tool string to the
4625 environment through which the method was called.
4626 Additional keyword arguments are passed to the tool's generate()
4628 method.
4629 env.Tool('gcc')
4631 env.Tool('opengl', toolpath = ['build/tools'])
4632 Value(value, [built_value])
4635 env.Value(value, [built_value])
4637 Returns a Node object representing the specified Python value.
4638 Value Nodes can be used as dependencies of targets. If the
4639 result of calling str(value) changes between SCons runs, any
4640 targets depending on Value(value) will be rebuilt. (This is
4641 true even when using timestamps to decide if files are up-to-
4642 date.) When using timestamp source signatures, Value Nodes'
4643 timestamps are equal to the system time when the Node is cre‐
4644 ated.
4645 The returned Value Node object has a write() method that can be
4647 used to "build" a Value Node by setting a new value. The
4648 optional built_value argument can be specified when the Value
4649 Node is created to indicate the Node should already be consid‐
4650 ered "built." There is a corresponding read() method that will
4651 return the built value of the Node.
4652 Examples:
4654 env = Environment()
4656 def create(target, source, env):
4658 # A function that will write a 'prefix=$SOURCE'
4659 # string into the file name specified as the
4660 # $TARGET.
4661 f = open(str(target[0]), 'wb')
4662 f.write('prefix=' + source[0].get_contents())
4663 # Fetch the prefix= argument, if any, from the command
4665 # line, and use /usr/local as the default.
4666 prefix = ARGUMENTS.get('prefix', '/usr/local')
4667 # Attach a .Config() builder for the above function action
4669 # to the construction environment.
4670 env['BUILDERS']['Config'] = Builder(action = create)
4671 env.Config(target = 'package-config', source = Value(prefix))
4672 def build_value(target, source, env):
4674 # A function that "builds" a Python Value by updating
4675 # the the Python value with the contents of the file
4676 # specified as the source of the Builder call ($SOURCE).
4677 target[0].write(source[0].get_contents())
4678 output = env.Value('before')
4680 input = env.Value('after')
4681 # Attach a .UpdateValue() builder for the above function
4683 # action to the construction environment.
4684 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
4685 env.UpdateValue(target = Value(output), source = Value(input))
4686 VariantDir(variant_dir, src_dir, [duplicate])
4689 env.VariantDir(variant_dir, src_dir, [duplicate])
4691 Use the VariantDir() function to create a copy of your sources
4692 in another location: if a name under variant_dir is not found
4693 but exists under src_dir, the file or directory is copied to
4694 variant_dir. Target files can be built in a different directory
4695 than the original sources by simply refering to the sources (and
4696 targets) within the variant tree.
4697 VariantDir() can be called multiple times with the same src_dir
4699 to set up multiple builds with different options (variants).
4700 The src_dir location must be in or underneath the SConstruct
4701 file's directory, and variant_dir may not be underneath src_dir.
4702 The default behavior is for scons to physically duplicate the
4704 source files in the variant tree. Thus, a build performed in
4705 the variant tree is guaranteed to be identical to a build per‐
4706 formed in the source tree even if intermediate source files are
4707 generated during the build, or preprocessors or other scanners
4708 search for included files relative to the source file, or indi‐
4709 vidual compilers or other invoked tools are hard-coded to put
4710 derived files in the same directory as source files.
4711 If possible on the platform, the duplication is performed by
4713 linking rather than copying; see also the --duplicate command-
4714 line option. Moreover, only the files needed for the build are
4715 duplicated; files and directories that are not used are not
4716 present in variant_dir.
4717 Duplicating the source tree may be disabled by setting the
4719 duplicate argument to 0 (zero). This will cause scons to invoke
4720 Builders using the path names of source files in src_dir and the
4721 path names of derived files within variant_dir. This is always
4722 more efficient than duplicate=1, and is usually safe for most
4723 builds (but see above for cases that may cause problems).
4724 Note that VariantDir() works most naturally with a subsidiary
4726 SConscript file. However, you would then call the subsidiary
4727 SConscript file not in the source directory, but in the vari‐
4728 ant_dir , regardless of the value of duplicate. This is how you
4729 tell scons which variant of a source tree to build:
4730 # run src/SConscript in two variant directories
4732 VariantDir('build/variant1', 'src')
4733 SConscript('build/variant1/SConscript')
4734 VariantDir('build/variant2', 'src')
4735 SConscript('build/variant2/SConscript')
4736 See also the SConscript() function, described above, for another
4739 way to specify a variant directory in conjunction with calling a
4740 subsidiary SConscript file.
4741 Examples:
4743 # use names in the build directory, not the source directory
4745 VariantDir('build', 'src', duplicate=0)
4746 Program('build/prog', 'build/source.c')
4747 # this builds both the source and docs in a separate subtree
4749 VariantDir('build', '.', duplicate=0)
4750 SConscript(dirs=['build/src','build/doc'])
4751 # same as previous example, but only uses SConscript
4753 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
4754 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
4755 WhereIs(program, [path, pathext, reject])
4758 env.WhereIs(program, [path, pathext, reject])
4760 Searches for the specified executable program, returning the
4762 full path name to the program if it is found, and returning None
4763 if not. Searches the specified path, the value of the calling
4764 environment's PATH (env['ENV']['PATH']), or the user's current
4765 external PATH (os.environ['PATH']) by default. On Windows sys‐
4766 tems, searches for executable programs with any of the file
4767 extensions listed in the specified pathext, the calling environ‐
4768 ment's PATHEXT (env['ENV']['PATHEXT']) or the user's current
4769 PATHEXT (os.environ['PATHEXT']) by default. Will not select any
4770 path name or names in the specified reject list, if any.
4771 SConscript Variables
4774 In addition to the global functions and methods, scons supports a num‐
4775 ber of Python variables that can be used in SConscript files to affect
4776 how you want the build to be performed. These variables may be
4777 accessed from custom Python modules that you import into an SConscript
4778 file by adding the following to the Python module:
4779 from SCons.Script import *
4781 ARGLIST
4784 A list keyword=value arguments specified on the command line.
4785 Each element in the list is a tuple containing the (key‐
4786 word,value) of the argument. The separate keyword and value
4787 elements of the tuple can be accessed by subscripting for ele‐
4788 ment [0] and [1] of the tuple, respectively.
4789 Example:
4791 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4793 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4794 third_tuple = ARGLIST[2]
4795 print "third keyword, value =", third_tuple[0], third_tuple[1]
4796 for key, value in ARGLIST:
4797 # process key and value
4798 ARGUMENTS
4801 A dictionary of all the keyword=value arguments specified on the
4802 command line. The dictionary is not in order, and if a given
4803 keyword has more than one value assigned to it on the command
4804 line, the last (right-most) value is the one in the ARGUMENTS
4805 dictionary.
4806 Example:
4808 if ARGUMENTS.get('debug', 0):
4810 env = Environment(CCFLAGS = '-g')
4811 else:
4812 env = Environment()
4813 BUILD_TARGETS
4816 A list of the targets which scons will actually try to build,
4817 regardless of whether they were specified on the command line or
4818 via the Default() function or method. The elements of this list
4819 may be strings or nodes, so you should run the list through the
4820 Python str function to make sure any Node path names are con‐
4821 verted to strings.
4822 Because this list may be taken from the list of targets speci‐
4824 fied using the Default() function or method, the contents of the
4825 list may change on each successive call to Default(). See the
4826 DEFAULT_TARGETS list, below, for additional information.
4827 Example:
4829 if 'foo' in BUILD_TARGETS:
4831 print "Don't forget to test the `foo' program!"
4832 if 'special/program' in BUILD_TARGETS:
4833 SConscript('special')
4834 Note that the BUILD_TARGETS list only contains targets expected
4836 listed on the command line or via calls to the Default() func‐
4837 tion or method. It does not contain all dependent targets that
4838 will be built as a result of making the sure the explicitly-
4839 specified targets are up to date.
4840 COMMAND_LINE_TARGETS
4843 A list of the targets explicitly specified on the command line.
4844 If there are no targets specified on the command line, the list
4845 is empty. This can be used, for example, to take specific
4846 actions only when a certain target or targets is explicitly
4847 being built.
4848 Example:
4850 if 'foo' in COMMAND_LINE_TARGETS:
4852 print "Don't forget to test the `foo' program!"
4853 if 'special/program' in COMMAND_LINE_TARGETS:
4854 SConscript('special')
4855 DEFAULT_TARGETS
4858 A list of the target nodes that have been specified using the
4859 Default() function or method. The elements of the list are
4860 nodes, so you need to run them through the Python str function
4861 to get at the path name for each Node.
4862 Example:
4864 print str(DEFAULT_TARGETS[0])
4866 if 'foo' in map(str, DEFAULT_TARGETS):
4867 print "Don't forget to test the `foo' program!"
4868 The contents of the DEFAULT_TARGETS list change on on each suc‐
4870 cessive call to the Default() function:
4871 print map(str, DEFAULT_TARGETS) # originally []
4873 Default('foo')
4874 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4875 Default('bar')
4876 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4877 Default(None)
4878 print map(str, DEFAULT_TARGETS) # back to []
4879 Consequently, be sure to use DEFAULT_TARGETS only after you've
4881 made all of your Default() calls, or else simply be careful of
4882 the order of these statements in your SConscript files so that
4883 you don't look for a specific default target before it's actu‐
4884 ally been added to the list.
4885 Construction Variables
4888 A construction environment has an associated dictionary of construction
4889 variables that are used by built-in or user-supplied build rules. Con‐
4890 struction variables must follow the same rules for Python identifiers:
4891 the initial character must be an underscore or letter, followed by any
4892 number of underscores, letters, or digits.
4893 A number of useful construction variables are automatically defined by
4895 scons for each supported platform, and additional construction vari‐
4896 ables can be defined by the user. The following is a list of the auto‐
4897 matically defined construction variables:
4898 AR The static library archiver.
4902 ARCHITECTURE
4905 Specifies the system architecture for which the package is being
4906 built. The default is the system architecture of the machine on
4907 which SCons is running. This is used to fill in the Architec‐
4908 ture: field in an Ipkg control file, and as part of the name of
4909 a generated RPM file.
4910 ARCOM The command line used to generate a static library from object
4913 files.
4914 ARCOMSTR
4917 The string displayed when an object file is generated from an
4918 assembly-language source file. If this is not set, then $ARCOM
4919 (the command line) is displayed.
4920 env = Environment(ARCOMSTR = "Archiving $TARGET")
4922 ARFLAGS
4925 General options passed to the static library archiver.
4926 AS The assembler.
4929 ASCOM The command line used to generate an object file from an assem‐
4932 bly-language source file.
4933 ASCOMSTR
4936 The string displayed when an object file is generated from an
4937 assembly-language source file. If this is not set, then $ASCOM
4938 (the command line) is displayed.
4939 env = Environment(ASCOMSTR = "Assembling $TARGET")
4941 ASFLAGS
4944 General options passed to the assembler.
4945 ASPPCOM
4948 The command line used to assemble an assembly-language source
4949 file into an object file after first running the file through
4950 the C preprocessor. Any options specified in the $ASFLAGS and
4951 $CPPFLAGS construction variables are included on this command
4952 line.
4953 ASPPCOMSTR
4956 The string displayed when an object file is generated from an
4957 assembly-language source file after first running the file
4958 through the C preprocessor. If this is not set, then $ASPPCOM
4959 (the command line) is displayed.
4960 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4962 ASPPFLAGS
4965 General options when an assembling an assembly-language source
4966 file into an object file after first running the file through
4967 the C preprocessor. The default is to use the value of
4968 $ASFLAGS.
4969 BIBTEX The bibliography generator for the TeX formatter and typesetter
4972 and the LaTeX structured formatter and typesetter.
4973 BIBTEXCOM
4976 The command line used to call the bibliography generator for the
4977 TeX formatter and typesetter and the LaTeX structured formatter
4978 and typesetter.
4979 BIBTEXCOMSTR
4982 The string displayed when generating a bibliography for TeX or
4983 LaTeX. If this is not set, then $BIBTEXCOM (the command line)
4984 is displayed.
4985 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4987 BIBTEXFLAGS
4990 General options passed to the bibliography generator for the TeX
4991 formatter and typesetter and the LaTeX structured formatter and
4992 typesetter.
4993 BITKEEPER
4996 The BitKeeper executable.
4997 BITKEEPERCOM
5000 The command line for fetching source files using BitKeeper.
5001 BITKEEPERCOMSTR
5004 The string displayed when fetching a source file using Bit‐
5005 Keeper. If this is not set, then $BITKEEPERCOM (the command
5006 line) is displayed.
5007 BITKEEPERGET
5010 The command ($BITKEEPER) and subcommand for fetching source
5011 files using BitKeeper.
5012 BITKEEPERGETFLAGS
5015 Options that are passed to the BitKeeper get subcommand.
5016 BUILDERS
5019 A dictionary mapping the names of the builders available through
5020 this environment to underlying Builder objects. Builders named
5021 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript,
5022 and Program are available by default. If you initialize this
5023 variable when an Environment is created:
5024 env = Environment(BUILDERS = {'NewBuilder' : foo})
5026 the default Builders will no longer be available. To use a new
5028 Builder object in addition to the default Builders, add your new
5029 Builder object like this:
5030 env = Environment()
5032 env.Append(BUILDERS = {'NewBuilder' : foo})
5033 or this:
5035 env = Environment()
5037 env['BUILDERS]['NewBuilder'] = foo
5038 CC The C compiler.
5041 CCCOM The command line used to compile a C source file to a (static)
5044 object file. Any options specified in the $CFLAGS, $CCFLAGS and
5045 $CPPFLAGS construction variables are included on this command
5046 line.
5047 CCCOMSTR
5050 The string displayed when a C source file is compiled to a
5051 (static) object file. If this is not set, then $CCCOM (the com‐
5052 mand line) is displayed.
5053 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
5055 CCFLAGS
5058 General options that are passed to the C and C++ compilers.
5059 CCPCHFLAGS
5062 Options added to the compiler command line to support building
5063 with precompiled headers. The default value expands expands to
5064 the appropriate Microsoft Visual C++ command-line options when
5065 the $PCH construction variable is set.
5066 CCPDBFLAGS
5069 Options added to the compiler command line to support storing
5070 debugging information in a Microsoft Visual C++ PDB file. The
5071 default value expands expands to appropriate Microsoft Visual
5072 C++ command-line options when the $PDB construction variable is
5073 set.
5074 The Visual C++ compiler option that SCons uses by default to
5076 generate PDB information is /Z7. This works correctly with par‐
5077 allel (-j) builds because it embeds the debug information in the
5078 intermediate object files, as opposed to sharing a single PDB
5079 file between multiple object files. This is also the only way
5080 to get debug information embedded into a static library. Using
5081 the /Zi instead may yield improved link-time performance,
5082 although parallel builds will no longer work.
5083 You can generate PDB files with the /Zi switch by overriding the
5085 default $CCPDBFLAGS variable as follows:
5086 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
5088 An alternative would be to use the /Zi to put the debugging
5090 information in a separate .pdb file for each object file by
5091 overriding the $CCPDBFLAGS variable as follows:
5092 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
5094 CCVERSION
5097 The version number of the C compiler. This may or may not be
5098 set, depending on the specific C compiler being used.
5099 CFILESUFFIX
5102 The suffix for C source files. This is used by the internal
5103 CFile builder when generating C files from Lex (.l) or YACC (.y)
5104 input files. The default suffix, of course, is .c (lower case).
5105 On case-insensitive systems (like Windows), SCons also treats .C
5106 (upper case) files as C files.
5107 CFLAGS General options that are passed to the C compiler (C only; not
5110 C++).
5111 CHANGE_SPECFILE
5114 A hook for modifying the file that controls the packaging build
5115 (the .spec for RPM, the control for Ipkg, the .wxs for MSI). If
5116 set, the function will be called after the SCons template for
5117 the file has been written. XXX
5118 CHANGED_SOURCES
5121 A reserved variable name that may not be set or used in a con‐
5122 struction environment. (See "Variable Substitution," below.)
5123 CHANGED_TARGETS
5126 A reserved variable name that may not be set or used in a con‐
5127 struction environment. (See "Variable Substitution," below.)
5128 CHANGELOG
5131 The name of a file containing the change log text to be included
5132 in the package. This is included as the %changelog section of
5133 the RPM .spec file.
5134 _concat
5137 A function used to produce variables like $_CPPINCFLAGS. It
5138 takes four or five arguments: a prefix to concatenate onto each
5139 element, a list of elements, a suffix to concatenate onto each
5140 element, an environment for variable interpolation, and an
5141 optional function that will be called to transform the list
5142 before concatenation.
5143 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
5145 CONFIGUREDIR
5148 The name of the directory in which Configure context test files
5149 are written. The default is .sconf_temp in the top-level direc‐
5150 tory containing the SConstruct file.
5151 CONFIGURELOG
5154 The name of the Configure context log file. The default is con‐
5155 fig.log in the top-level directory containing the SConstruct
5156 file.
5157 _CPPDEFFLAGS
5160 An automatically-generated construction variable containing the
5161 C preprocessor command-line options to define values. The value
5162 of $_CPPDEFFLAGS is created by appending $CPPDEFPREFIX and
5163 $CPPDEFSUFFIX to the beginning and end of each definition in
5164 $CPPDEFINES.
5165 CPPDEFINES
5168 A platform independent specification of C preprocessor defini‐
5169 tions. The definitions will be added to command lines through
5170 the automatically-generated $_CPPDEFFLAGS construction variable
5171 (see above), which is constructed according to the type of value
5172 of $CPPDEFINES:
5173 If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and
5175 $CPPDEFSUFFIX construction variables will be added to the begin‐
5176 ning and end.
5177 # Will add -Dxyz to POSIX compiler command lines,
5179 # and /Dxyz to Microsoft Visual C++ command lines.
5180 env = Environment(CPPDEFINES='xyz')
5181 If $CPPDEFINES is a list, the values of the $CPPDEFPREFIX and
5183 $CPPDEFSUFFIX construction variables will be appended to the
5184 beginning and end of each element in the list. If any element
5185 is a list or tuple, then the first item is the name being
5186 defined and the second item is its value:
5187 # Will add -DB=2 -DA to POSIX compiler command lines,
5189 # and /DB=2 /DA to Microsoft Visual C++ command lines.
5190 env = Environment(CPPDEFINES=[('B', 2), 'A'])
5191 If $CPPDEFINES is a dictionary, the values of the $CPPDEFPREFIX
5193 and $CPPDEFSUFFIX construction variables will be appended to the
5194 beginning and end of each item from the dictionary. The key of
5195 each dictionary item is a name being defined to the dictionary
5196 item's corresponding value; if the value is None, then the name
5197 is defined without an explicit value. Note that the resulting
5198 flags are sorted by keyword to ensure that the order of the
5199 options on the command line is consistent each time scons is
5200 run.
5201 # Will add -DA -DB=2 to POSIX compiler command lines,
5203 # and /DA /DB=2 to Microsoft Visual C++ command lines.
5204 env = Environment(CPPDEFINES={'B':2, 'A':None})
5205 CPPDEFPREFIX
5208 The prefix used to specify preprocessor definitions on the C
5209 compiler command line. This will be appended to the beginning
5210 of each definition in the $CPPDEFINES construction variable when
5211 the $_CPPDEFFLAGS variable is automatically generated.
5212 CPPDEFSUFFIX
5215 The suffix used to specify preprocessor definitions on the C
5216 compiler command line. This will be appended to the end of each
5217 definition in the $CPPDEFINES construction variable when the
5218 $_CPPDEFFLAGS variable is automatically generated.
5219 CPPFLAGS
5222 User-specified C preprocessor options. These will be included
5223 in any command that uses the C preprocessor, including not just
5224 compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
5225 $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
5226 $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
5227 compile a Fortran source file, and the $ASPPCOM command line
5228 used to assemble an assembly language source file, after first
5229 running each file through the C preprocessor. Note that this
5230 variable does not contain -I (or similar) include search path
5231 options that scons generates automatically from $CPPPATH. See
5232 $_CPPINCFLAGS, below, for the variable that expands to those
5233 options.
5234 _CPPINCFLAGS
5237 An automatically-generated construction variable containing the
5238 C preprocessor command-line options for specifying directories
5239 to be searched for include files. The value of $_CPPINCFLAGS is
5240 created by appending $INCPREFIX and $INCSUFFIX to the beginning
5241 and end of each directory in $CPPPATH.
5242 CPPPATH
5245 The list of directories that the C preprocessor will search for
5246 include directories. The C/C++ implicit dependency scanner will
5247 search these directories for include files. Don't explicitly put
5248 include directory arguments in CCFLAGS or CXXFLAGS because the
5249 result will be non-portable and the directories will not be
5250 searched by the dependency scanner. Note: directory names in
5251 CPPPATH will be looked-up relative to the SConscript directory
5252 when they are used in a command. To force scons to look-up a
5253 directory relative to the root of the source tree use #:
5254 env = Environment(CPPPATH='#/include')
5256 The directory look-up can also be forced using the Dir() func‐
5258 tion:
5259 include = Dir('include')
5261 env = Environment(CPPPATH=include)
5262 The directory list will be added to command lines through the
5264 automatically-generated $_CPPINCFLAGS construction variable,
5265 which is constructed by appending the values of the $INCPREFIX
5266 and $INCSUFFIX construction variables to the beginning and end
5267 of each directory in $CPPPATH. Any command lines you define
5268 that need the CPPPATH directory list should include
5269 $_CPPINCFLAGS:
5270 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5272 CPPSUFFIXES
5275 The list of suffixes of files that will be scanned for C pre‐
5276 processor implicit dependencies (#include lines). The default
5277 list is:
5278 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5280 ".h", ".H", ".hxx", ".hpp", ".hh",
5281 ".F", ".fpp", ".FPP",
5282 ".m", ".mm",
5283 ".S", ".spp", ".SPP"]
5284 CVS The CVS executable.
5287 CVSCOFLAGS
5290 Options that are passed to the CVS checkout subcommand.
5291 CVSCOM The command line used to fetch source files from a CVS reposi‐
5294 tory.
5295 CVSCOMSTR
5298 The string displayed when fetching a source file from a CVS
5299 repository. If this is not set, then $CVSCOM (the command line)
5300 is displayed.
5301 CVSFLAGS
5304 General options that are passed to CVS. By default, this is set
5305 to -d $CVSREPOSITORY to specify from where the files must be
5306 fetched.
5307 CVSREPOSITORY
5310 The path to the CVS repository. This is referenced in the
5311 default $CVSFLAGS value.
5312 CXX The C++ compiler.
5315 CXXCOM The command line used to compile a C++ source file to an object
5318 file. Any options specified in the $CXXFLAGS and $CPPFLAGS con‐
5319 struction variables are included on this command line.
5320 CXXCOMSTR
5323 The string displayed when a C++ source file is compiled to a
5324 (static) object file. If this is not set, then $CXXCOM (the
5325 command line) is displayed.
5326 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5328 CXXFILESUFFIX
5331 The suffix for C++ source files. This is used by the internal
5332 CXXFile builder when generating C++ files from Lex (.ll) or YACC
5333 (.yy) input files. The default suffix is .cc. SCons also
5334 treats files with the suffixes .cpp, .cxx, .c++, and .C++ as C++
5335 files, and files with .mm suffixes as Objective C++ files. On
5336 case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5337 SCons also treats .C (upper case) files as C++ files.
5338 CXXFLAGS
5341 General options that are passed to the C++ compiler. By
5342 default, this includes the value of $CCFLAGS, so that setting
5343 $CCFLAGS affects both C and C++ compilation. If you want to add
5344 C++-specific flags, you must set or override the value of
5345 $CXXFLAGS.
5346 CXXVERSION
5349 The version number of the C++ compiler. This may or may not be
5350 set, depending on the specific C++ compiler being used.
5351 DESCRIPTION
5354 A long description of the project being packaged. This is
5355 included in the relevant section of the file that controls the
5356 packaging build.
5357 DESCRIPTION_lang
5360 A language-specific long description for the specified lang.
5361 This is used to populate a %description -l section of an RPM
5362 .spec file.
5363 Dir A function that converts a string into a Dir instance relative
5366 to the target being built.
5367 Dirs A function that converts a list of strings into a list of Dir
5370 instances relative to the target being built.
5371 DSUFFIXES
5374 The list of suffixes of files that will be scanned for imported
5375 D package files. The default list is:
5376 ['.d']
5378 DVIPDF The TeX DVI file to PDF file converter.
5381 DVIPDFCOM
5384 The command line used to convert TeX DVI files into a PDF file.
5385 DVIPDFCOMSTR
5388 The string displayed when a TeX DVI file is converted into a PDF
5389 file. If this is not set, then $DVIPDFCOM (the command line) is
5390 displayed.
5391 DVIPDFFLAGS
5394 General options passed to the TeX DVI file to PDF file con‐
5395 verter.
5396 DVIPS The TeX DVI file to PostScript converter.
5399 DVIPSFLAGS
5402 General options passed to the TeX DVI file to PostScript con‐
5403 verter.
5404 ENV A dictionary of environment variables to use when invoking com‐
5407 mands. When $ENV is used in a command all list values will be
5408 joined using the path separator and any other non-string values
5409 will simply be coerced to a string. Note that, by default,
5410 scons does not propagate the environment in force when you exe‐
5411 cute scons to the commands used to build target files. This is
5412 so that builds will be guaranteed repeatable regardless of the
5413 environment variables set at the time scons is invoked.
5414 If you want to propagate your environment variables to the com‐
5416 mands executed to build target files, you must do so explicitly:
5417 import os
5419 env = Environment(ENV = os.environ)
5420 Note that you can choose only to propagate certain environment
5422 variables. A common example is the system PATH environment
5423 variable, so that scons uses the same utilities as the invoking
5424 shell (or other process):
5425 import os
5427 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5428 ESCAPE A function that will be called to escape shell special charac‐
5431 ters in command lines. The function should take one argument:
5432 the command line string to escape; and should return the escaped
5433 command line.
5434 F77 The Fortran 77 compiler. You should normally set the $FORTRAN
5437 variable, which specifies the default Fortran compiler for all
5438 Fortran versions. You only need to set $F77 if you need to use
5439 a specific compiler or compiler version for Fortran 77 files.
5440 F77COM The command line used to compile a Fortran 77 source file to an
5443 object file. You only need to set $F77COM if you need to use a
5444 specific command line for Fortran 77 files. You should normally
5445 set the $FORTRANCOM variable, which specifies the default com‐
5446 mand line for all Fortran versions.
5447 F77COMSTR
5450 The string displayed when a Fortran 77 source file is compiled
5451 to an object file. If this is not set, then $F77COM or $FOR‐
5452 TRANCOM (the command line) is displayed.
5453 F77FILESUFFIXES
5456 The list of file extensions for which the F77 dialect will be
5457 used. By default, this is ['.f77']
5458 F77FLAGS
5461 General user-specified options that are passed to the Fortran 77
5462 compiler. Note that this variable does not contain -I (or simi‐
5463 lar) include search path options that scons generates automati‐
5464 cally from $F77PATH. See $_F77INCFLAGS below, for the variable
5465 that expands to those options. You only need to set $F77FLAGS
5466 if you need to define specific user options for Fortran 77
5467 files. You should normally set the $FORTRANFLAGS variable,
5468 which specifies the user-specified options passed to the default
5469 Fortran compiler for all Fortran versions.
5470 _F77INCFLAGS
5473 An automatically-generated construction variable containing the
5474 Fortran 77 compiler command-line options for specifying directo‐
5475 ries to be searched for include files. The value of
5476 $_F77INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
5477 to the beginning and end of each directory in $F77PATH.
5478 F77PATH
5481 The list of directories that the Fortran 77 compiler will search
5482 for include directories. The implicit dependency scanner will
5483 search these directories for include files. Don't explicitly put
5484 include directory arguments in $F77FLAGS because the result will
5485 be non-portable and the directories will not be searched by the
5486 dependency scanner. Note: directory names in $F77PATH will be
5487 looked-up relative to the SConscript directory when they are
5488 used in a command. To force scons to look-up a directory rela‐
5489 tive to the root of the source tree use #: You only need to set
5490 $F77PATH if you need to define a specific include path for For‐
5491 tran 77 files. You should normally set the $FORTRANPATH vari‐
5492 able, which specifies the include path for the default Fortran
5493 compiler for all Fortran versions.
5494 env = Environment(F77PATH='#/include')
5496 The directory look-up can also be forced using the Dir() func‐
5498 tion:
5499 include = Dir('include')
5501 env = Environment(F77PATH=include)
5502 The directory list will be added to command lines through the
5504 automatically-generated $_F77INCFLAGS construction variable,
5505 which is constructed by appending the values of the $INCPREFIX
5506 and $INCSUFFIX construction variables to the beginning and end
5507 of each directory in $F77PATH. Any command lines you define
5508 that need the F77PATH directory list should include
5509 $_F77INCFLAGS:
5510 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5512 F77PPCOM
5515 The command line used to compile a Fortran 77 source file to an
5516 object file after first running the file through the C pre‐
5517 processor. Any options specified in the $F77FLAGS and $CPPFLAGS
5518 construction variables are included on this command line. You
5519 only need to set $F77PPCOM if you need to use a specific C-pre‐
5520 processor command line for Fortran 77 files. You should nor‐
5521 mally set the $FORTRANPPCOM variable, which specifies the
5522 default C-preprocessor command line for all Fortran versions.
5523 F77PPCOMSTR
5526 The string displayed when a Fortran 77 source file is compiled
5527 to an object file after first running the file through the C
5528 preprocessor. If this is not set, then $F77PPCOM or $FORTRANPP‐
5529 COM (the command line) is displayed.
5530 F77PPFILESUFFIXES
5533 The list of file extensions for which the compilation + pre‐
5534 processor pass for F77 dialect will be used. By default, this is
5535 empty
5536 F90 The Fortran 90 compiler. You should normally set the $FORTRAN
5539 variable, which specifies the default Fortran compiler for all
5540 Fortran versions. You only need to set $F90 if you need to use
5541 a specific compiler or compiler version for Fortran 90 files.
5542 F90COM The command line used to compile a Fortran 90 source file to an
5545 object file. You only need to set $F90COM if you need to use a
5546 specific command line for Fortran 90 files. You should normally
5547 set the $FORTRANCOM variable, which specifies the default com‐
5548 mand line for all Fortran versions.
5549 F90COMSTR
5552 The string displayed when a Fortran 90 source file is compiled
5553 to an object file. If this is not set, then $F90COM or $FOR‐
5554 TRANCOM (the command line) is displayed.
5555 F90FILESUFFIXES
5558 The list of file extensions for which the F90 dialect will be
5559 used. By default, this is ['.f90']
5560 F90FLAGS
5563 General user-specified options that are passed to the Fortran 90
5564 compiler. Note that this variable does not contain -I (or simi‐
5565 lar) include search path options that scons generates automati‐
5566 cally from $F90PATH. See $_F90INCFLAGS below, for the variable
5567 that expands to those options. You only need to set $F90FLAGS
5568 if you need to define specific user options for Fortran 90
5569 files. You should normally set the $FORTRANFLAGS variable,
5570 which specifies the user-specified options passed to the default
5571 Fortran compiler for all Fortran versions.
5572 _F90INCFLAGS
5575 An automatically-generated construction variable containing the
5576 Fortran 90 compiler command-line options for specifying directo‐
5577 ries to be searched for include files. The value of
5578 $_F90INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
5579 to the beginning and end of each directory in $F90PATH.
5580 F90PATH
5583 The list of directories that the Fortran 90 compiler will search
5584 for include directories. The implicit dependency scanner will
5585 search these directories for include files. Don't explicitly put
5586 include directory arguments in $F90FLAGS because the result will
5587 be non-portable and the directories will not be searched by the
5588 dependency scanner. Note: directory names in $F90PATH will be
5589 looked-up relative to the SConscript directory when they are
5590 used in a command. To force scons to look-up a directory rela‐
5591 tive to the root of the source tree use #: You only need to set
5592 $F90PATH if you need to define a specific include path for For‐
5593 tran 90 files. You should normally set the $FORTRANPATH vari‐
5594 able, which specifies the include path for the default Fortran
5595 compiler for all Fortran versions.
5596 env = Environment(F90PATH='#/include')
5598 The directory look-up can also be forced using the Dir() func‐
5600 tion:
5601 include = Dir('include')
5603 env = Environment(F90PATH=include)
5604 The directory list will be added to command lines through the
5606 automatically-generated $_F90INCFLAGS construction variable,
5607 which is constructed by appending the values of the $INCPREFIX
5608 and $INCSUFFIX construction variables to the beginning and end
5609 of each directory in $F90PATH. Any command lines you define
5610 that need the F90PATH directory list should include
5611 $_F90INCFLAGS:
5612 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5614 F90PPCOM
5617 The command line used to compile a Fortran 90 source file to an
5618 object file after first running the file through the C pre‐
5619 processor. Any options specified in the $F90FLAGS and $CPPFLAGS
5620 construction variables are included on this command line. You
5621 only need to set $F90PPCOM if you need to use a specific C-pre‐
5622 processor command line for Fortran 90 files. You should nor‐
5623 mally set the $FORTRANPPCOM variable, which specifies the
5624 default C-preprocessor command line for all Fortran versions.
5625 F90PPCOMSTR
5628 The string displayed when a Fortran 90 source file is compiled
5629 after first running the file through the C preprocessor. If
5630 this is not set, then $F90PPCOM or $FORTRANPPCOM (the command
5631 line) is displayed.
5632 F90PPFILESUFFIXES
5635 The list of file extensions for which the compilation + pre‐
5636 processor pass for F90 dialect will be used. By default, this is
5637 empty
5638 F95 The Fortran 95 compiler. You should normally set the $FORTRAN
5641 variable, which specifies the default Fortran compiler for all
5642 Fortran versions. You only need to set $F95 if you need to use
5643 a specific compiler or compiler version for Fortran 95 files.
5644 F95COM The command line used to compile a Fortran 95 source file to an
5647 object file. You only need to set $F95COM if you need to use a
5648 specific command line for Fortran 95 files. You should normally
5649 set the $FORTRANCOM variable, which specifies the default com‐
5650 mand line for all Fortran versions.
5651 F95COMSTR
5654 The string displayed when a Fortran 95 source file is compiled
5655 to an object file. If this is not set, then $F95COM or $FOR‐
5656 TRANCOM (the command line) is displayed.
5657 F95FILESUFFIXES
5660 The list of file extensions for which the F95 dialect will be
5661 used. By default, this is ['.f95']
5662 F95FLAGS
5665 General user-specified options that are passed to the Fortran 95
5666 compiler. Note that this variable does not contain -I (or simi‐
5667 lar) include search path options that scons generates automati‐
5668 cally from $F95PATH. See $_F95INCFLAGS below, for the variable
5669 that expands to those options. You only need to set $F95FLAGS
5670 if you need to define specific user options for Fortran 95
5671 files. You should normally set the $FORTRANFLAGS variable,
5672 which specifies the user-specified options passed to the default
5673 Fortran compiler for all Fortran versions.
5674 _F95INCFLAGS
5677 An automatically-generated construction variable containing the
5678 Fortran 95 compiler command-line options for specifying directo‐
5679 ries to be searched for include files. The value of
5680 $_F95INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
5681 to the beginning and end of each directory in $F95PATH.
5682 F95PATH
5685 The list of directories that the Fortran 95 compiler will search
5686 for include directories. The implicit dependency scanner will
5687 search these directories for include files. Don't explicitly put
5688 include directory arguments in $F95FLAGS because the result will
5689 be non-portable and the directories will not be searched by the
5690 dependency scanner. Note: directory names in $F95PATH will be
5691 looked-up relative to the SConscript directory when they are
5692 used in a command. To force scons to look-up a directory rela‐
5693 tive to the root of the source tree use #: You only need to set
5694 $F95PATH if you need to define a specific include path for For‐
5695 tran 95 files. You should normally set the $FORTRANPATH vari‐
5696 able, which specifies the include path for the default Fortran
5697 compiler for all Fortran versions.
5698 env = Environment(F95PATH='#/include')
5700 The directory look-up can also be forced using the Dir() func‐
5702 tion:
5703 include = Dir('include')
5705 env = Environment(F95PATH=include)
5706 The directory list will be added to command lines through the
5708 automatically-generated $_F95INCFLAGS construction variable,
5709 which is constructed by appending the values of the $INCPREFIX
5710 and $INCSUFFIX construction variables to the beginning and end
5711 of each directory in $F95PATH. Any command lines you define
5712 that need the F95PATH directory list should include
5713 $_F95INCFLAGS:
5714 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5716 F95PPCOM
5719 The command line used to compile a Fortran 95 source file to an
5720 object file after first running the file through the C pre‐
5721 processor. Any options specified in the $F95FLAGS and $CPPFLAGS
5722 construction variables are included on this command line. You
5723 only need to set $F95PPCOM if you need to use a specific C-pre‐
5724 processor command line for Fortran 95 files. You should nor‐
5725 mally set the $FORTRANPPCOM variable, which specifies the
5726 default C-preprocessor command line for all Fortran versions.
5727 F95PPCOMSTR
5730 The string displayed when a Fortran 95 source file is compiled
5731 to an object file after first running the file through the C
5732 preprocessor. If this is not set, then $F95PPCOM or $FORTRANPP‐
5733 COM (the command line) is displayed.
5734 F95PPFILESUFFIXES
5737 The list of file extensions for which the compilation + pre‐
5738 processor pass for F95 dialect will be used. By default, this is
5739 empty
5740 File A function that converts a string into a File instance relative
5743 to the target being built.
5744 FORTRAN
5747 The default Fortran compiler for all versions of Fortran.
5748 FORTRANCOM
5751 The command line used to compile a Fortran source file to an
5752 object file. By default, any options specified in the $FORTRAN‐
5753 FLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FOR‐
5754 TRANINCFLAGS construction variables are included on this command
5755 line.
5756 FORTRANCOMSTR
5759 The string displayed when a Fortran source file is compiled to
5760 an object file. If this is not set, then $FORTRANCOM (the com‐
5761 mand line) is displayed.
5762 FORTRANFILESUFFIXES
5765 The list of file extensions for which the FORTRAN dialect will
5766 be used. By default, this is ['.f', '.for', '.ftn']
5767 FORTRANFLAGS
5770 General user-specified options that are passed to the Fortran
5771 compiler. Note that this variable does not contain -I (or simi‐
5772 lar) include or module search path options that scons generates
5773 automatically from $FORTRANPATH. See $_FORTRANINCFLAGS and
5774 $_FORTRANMODFLAG, below, for the variables that expand those
5775 options.
5776 _FORTRANINCFLAGS
5779 An automatically-generated construction variable containing the
5780 Fortran compiler command-line options for specifying directories
5781 to be searched for include files and module files. The value of
5782 $_FORTRANINCFLAGS is created by prepending/appending $INCPREFIX
5783 and $INCSUFFIX to the beginning and end of each directory in
5784 $FORTRANPATH.
5785 FORTRANMODDIR
5788 Directory location where the Fortran compiler should place any
5789 module files it generates. This variable is empty, by default.
5790 Some Fortran compilers will internally append this directory in
5791 the search path for module files, as well.
5792 FORTRANMODDIRPREFIX
5795 The prefix used to specify a module directory on the Fortran
5796 compiler command line. This will be appended to the beginning
5797 of the directory in the $FORTRANMODDIR construction variables
5798 when the $_FORTRANMODFLAG variables is automatically generated.
5799 FORTRANMODDIRSUFFIX
5802 The suffix used to specify a module directory on the Fortran
5803 compiler command line. This will be appended to the beginning
5804 of the directory in the $FORTRANMODDIR construction variables
5805 when the $_FORTRANMODFLAG variables is automatically generated.
5806 _FORTRANMODFLAG
5809 An automatically-generated construction variable containing the
5810 Fortran compiler command-line option for specifying the direc‐
5811 tory location where the Fortran compiler should place any module
5812 files that happen to get generated during compilation. The
5813 value of $_FORTRANMODFLAG is created by prepending/appending
5814 $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the beginning
5815 and end of the directory in $FORTRANMODDIR.
5816 FORTRANMODPREFIX
5819 The module file prefix used by the Fortran compiler. SCons
5820 assumes that the Fortran compiler follows the quasi-standard
5821 naming convention for module files of module_name.mod. As a
5822 result, this variable is left empty, by default. For situations
5823 in which the compiler does not necessarily follow the normal
5824 convention, the user may use this variable. Its value will be
5825 appended to every module file name as scons attempts to resolve
5826 dependencies.
5827 FORTRANMODSUFFIX
5830 The module file suffix used by the Fortran compiler. SCons
5831 assumes that the Fortran compiler follows the quasi-standard
5832 naming convention for module files of module_name.mod. As a
5833 result, this variable is set to ".mod", by default. For situa‐
5834 tions in which the compiler does not necessarily follow the nor‐
5835 mal convention, the user may use this variable. Its value will
5836 be appended to every module file name as scons attempts to
5837 resolve dependencies.
5838 FORTRANPATH
5841 The list of directories that the Fortran compiler will search
5842 for include files and (for some compilers) module files. The
5843 Fortran implicit dependency scanner will search these directo‐
5844 ries for include files (but not module files since they are
5845 autogenerated and, as such, may not actually exist at the time
5846 the scan takes place). Don't explicitly put include directory
5847 arguments in FORTRANFLAGS because the result will be non-porta‐
5848 ble and the directories will not be searched by the dependency
5849 scanner. Note: directory names in FORTRANPATH will be looked-up
5850 relative to the SConscript directory when they are used in a
5851 command. To force scons to look-up a directory relative to the
5852 root of the source tree use #:
5853 env = Environment(FORTRANPATH='#/include')
5855 The directory look-up can also be forced using the Dir() func‐
5857 tion:
5858 include = Dir('include')
5860 env = Environment(FORTRANPATH=include)
5861 The directory list will be added to command lines through the
5863 automatically-generated $_FORTRANINCFLAGS construction variable,
5864 which is constructed by appending the values of the $INCPREFIX
5865 and $INCSUFFIX construction variables to the beginning and end
5866 of each directory in $FORTRANPATH. Any command lines you define
5867 that need the FORTRANPATH directory list should include $_FOR‐
5868 TRANINCFLAGS:
5869 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5871 FORTRANPPCOM
5874 The command line used to compile a Fortran source file to an
5875 object file after first running the file through the C pre‐
5876 processor. By default, any options specified in the $FORTRAN‐
5877 FLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FOR‐
5878 TRANINCFLAGS construction variables are included on this command
5879 line.
5880 FORTRANPPCOMSTR
5883 The string displayed when a Fortran source file is compiled to
5884 an object file after first running the file through the C pre‐
5885 processor. If this is not set, then $FORTRANPPCOM (the command
5886 line) is displayed.
5887 FORTRANPPFILESUFFIXES
5890 The list of file extensions for which the compilation + pre‐
5891 processor pass for FORTRAN dialect will be used. By default,
5892 this is ['.fpp', '.FPP']
5893 FORTRANSUFFIXES
5896 The list of suffixes of files that will be scanned for Fortran
5897 implicit dependencies (INCLUDE lines and USE statements). The
5898 default list is:
5899 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5901 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5902 FRAMEWORKPATH
5905 On Mac OS X with gcc, a list containing the paths to search for
5906 frameworks. Used by the compiler to find framework-style
5907 includes like #include <Fmwk/Header.h>. Used by the linker to
5908 find user-specified frameworks when linking (see $FRAMEWORKS).
5909 For example:
5910 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
5912 will add
5914 ... -Fmyframeworkdir
5916 to the compiler and linker command lines.
5918 _FRAMEWORKPATH
5921 On Mac OS X with gcc, an automatically-generated construction
5922 variable containing the linker command-line options correspond‐
5923 ing to $FRAMEWORKPATH.
5924 FRAMEWORKPATHPREFIX
5927 On Mac OS X with gcc, the prefix to be used for the FRAMEWORK‐
5928 PATH entries. (see $FRAMEWORKPATH). The default value is -F.
5929 FRAMEWORKPREFIX
5932 On Mac OS X with gcc, the prefix to be used for linking in
5933 frameworks (see $FRAMEWORKS). The default value is -framework.
5934 _FRAMEWORKS
5937 On Mac OS X with gcc, an automatically-generated construction
5938 variable containing the linker command-line options for linking
5939 with FRAMEWORKS.
5940 FRAMEWORKS
5943 On Mac OS X with gcc, a list of the framework names to be linked
5944 into a program or shared library or bundle. The default value
5945 is the empty list. For example:
5946 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
5948 FRAMEWORKSFLAGS
5950 On Mac OS X with gcc, general user-supplied frameworks options
5951 to be added at the end of a command line building a loadable
5952 module. (This has been largely superseded by the $FRAMEWORK‐
5953 PATH, $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS
5954 variables described above.)
5955 GS The Ghostscript program used to convert PostScript to PDF files.
5958 GSCOM The Ghostscript command line used to convert PostScript to PDF
5961 files.
5962 GSCOMSTR
5965 The string displayed when Ghostscript is used to convert a Post‐
5966 Script file to a PDF file. If this is not set, then $GSCOM (the
5967 command line) is displayed.
5968 GSFLAGS
5971 General options passed to the Ghostscript program when convert‐
5972 ing PostScript to PDF files.
5973 HOST_ARCH
5976 Sets the host architecture for Visual Studio compiler. If not
5977 set, default to the detected host architecture: note that this
5978 may depend on the python you are using. This variable must be
5979 passed as an argument to the Environment() constructor; setting
5980 it later has no effect.
5981 Valid values are the same as for $TARGET_ARCH.
5983 This is currently only used on Windows, but in the future it
5985 will be used on other OSes as well.
5986 HOST_OS
5989 The name of the host operating system used to create the
5990 Environment.
5991 If a platform is specified when creating the Environ‐
5992 ment, then
5993 that Platform's logic will handle setting this value.
5994 This value is immutable, and should not be changed by
5995 the user after
5996 the Environment is initialized.
5997 Currently only set for Win32.
5998 IDLSUFFIXES
6001 The list of suffixes of files that will be scanned for IDL
6002 implicit dependencies (#include or import lines). The default
6003 list is:
6004 [".idl", ".IDL"]
6006 IMPLICIT_COMMAND_DEPENDENCIES
6009 Controls whether or not SCons will add implicit dependencies for
6010 the commands executed to build targets.
6011 By default, SCons will add to each target an implicit dependency
6013 on the command represented by the first argument on any command
6014 line it executes. The specific file for the dependency is found
6015 by searching the PATH variable in the ENV environment used to
6016 execute the command.
6017 If the construction variable $IMPLICIT_COMMAND_DEPENDENCIES is
6019 set to a false value (None, False, 0, etc.), then the implicit
6020 dependency will not be added to the targets built with that con‐
6021 struction environment.
6022 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
6024 INCPREFIX
6027 The prefix used to specify an include directory on the C com‐
6028 piler command line. This will be appended to the beginning of
6029 each directory in the $CPPPATH and $FORTRANPATH construction
6030 variables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables
6031 are automatically generated.
6032 INCSUFFIX
6035 The suffix used to specify an include directory on the C com‐
6036 piler command line. This will be appended to the end of each
6037 directory in the $CPPPATH and $FORTRANPATH construction vari‐
6038 ables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are
6039 automatically generated.
6040 INSTALL
6043 A function to be called to install a file into a destination
6044 file name. The default function copies the file into the desti‐
6045 nation (and sets the destination file's mode and permission bits
6046 to match the source file's). The function takes the following
6047 arguments:
6048 def install(dest, source, env):
6050 dest is the path name of the destination file. source is the
6052 path name of the source file. env is the construction environ‐
6053 ment (a dictionary of construction values) in force for this
6054 file installation.
6055 INSTALLSTR
6058 The string displayed when a file is installed into a destination
6059 file name. The default is:
6060 Install file: "$SOURCE" as "$TARGET"
6061 INTEL_C_COMPILER_VERSION
6064 Set by the "intelc" Tool to the major version number of the
6065 Intel C compiler selected for use.
6066 JAR The Java archive tool.
6069 JARCHDIR
6072 The directory to which the Java archive tool should change
6073 (using the -C option).
6074 JARCOM The command line used to call the Java archive tool.
6077 JARCOMSTR
6080 The string displayed when the Java archive tool is called If
6081 this is not set, then $JARCOM (the command line) is displayed.
6082 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
6084 JARFLAGS
6087 General options passed to the Java archive tool. By default
6088 this is set to cf to create the necessary jar file.
6089 JARSUFFIX
6092 The suffix for Java archives: .jar by default.
6093 JAVABOOTCLASSPATH
6096 Specifies the list of directories that will be added to the
6097 &javac; command line via the -bootclasspath option. The indi‐
6098 vidual directory names will be separated by the operating sys‐
6099 tem's path separate character (: on UNIX/Linux/POSIX, ; on Win‐
6100 dows).
6101 JAVAC The Java compiler.
6104 JAVACCOM
6107 The command line used to compile a directory tree containing
6108 Java source files to corresponding Java class files. Any
6109 options specified in the $JAVACFLAGS construction variable are
6110 included on this command line.
6111 JAVACCOMSTR
6114 The string displayed when compiling a directory tree of Java
6115 source files to corresponding Java class files. If this is not
6116 set, then $JAVACCOM (the command line) is displayed.
6117 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
6119 JAVACFLAGS
6122 General options that are passed to the Java compiler.
6123 JAVACLASSDIR
6126 The directory in which Java class files may be found. This is
6127 stripped from the beginning of any Java .class file names sup‐
6128 plied to the JavaH builder.
6129 JAVACLASSPATH
6132 Specifies the list of directories that will be searched for Java
6133 .class file. The directories in this list will be added to the
6134 &javac; and &javah; command lines via the -classpath option.
6135 The individual directory names will be separated by the operat‐
6136 ing system's path separate character (: on UNIX/Linux/POSIX, ;
6137 on Windows).
6138 Note that this currently just adds the specified directory via
6140 the -classpath option. &SCons; does not currently search the
6141 $JAVACLASSPATH directories for dependency .class files.
6142 JAVACLASSSUFFIX
6145 The suffix for Java class files; .class by default.
6146 JAVAH The Java generator for C header and stub files.
6149 JAVAHCOM
6152 The command line used to generate C header and stub files from
6153 Java classes. Any options specified in the $JAVAHFLAGS con‐
6154 struction variable are included on this command line.
6155 JAVAHCOMSTR
6158 The string displayed when C header and stub files are generated
6159 from Java classes. If this is not set, then $JAVAHCOM (the com‐
6160 mand line) is displayed.
6161 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
6163 JAVAHFLAGS
6166 General options passed to the C header and stub file generator
6167 for Java classes.
6168 JAVASOURCEPATH
6171 Specifies the list of directories that will be searched for
6172 input .java file. The directories in this list will be added to
6173 the &javac; command line via the -sourcepath option. The indi‐
6174 vidual directory names will be separated by the operating sys‐
6175 tem's path separate character (: on UNIX/Linux/POSIX, ; on Win‐
6176 dows).
6177 Note that this currently just adds the specified directory via
6179 the -sourcepath option. &SCons; does not currently search the
6180 $JAVASOURCEPATH directories for dependency .java files.
6181 JAVASUFFIX
6184 The suffix for Java files; .java by default.
6185 JAVAVERSION
6188 Specifies the Java version being used by the Java() builder.
6189 This is not currently used to select one version of the Java
6190 compiler vs. another. Instead, you should set this to specify
6191 the version of Java supported by your &javac; compiler. The
6192 default is 1.4.
6193 This is sometimes necessary because Java 1.5 changed the file
6195 names that are created for nested anonymous inner classes, which
6196 can cause a mismatch with the files that &SCons; expects will be
6197 generated by the &javac; compiler. Setting $JAVAVERSION to 1.5
6198 (or 1.6, as appropriate) can make &SCons; realize that a Java
6199 1.5 or 1.6 build is actually up to date.
6200 LATEX The LaTeX structured formatter and typesetter.
6203 LATEXCOM
6206 The command line used to call the LaTeX structured formatter and
6207 typesetter.
6208 LATEXCOMSTR
6211 The string displayed when calling the LaTeX structured formatter
6212 and typesetter. If this is not set, then $LATEXCOM (the command
6213 line) is displayed.
6214 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
6216 LATEXFLAGS
6219 General options passed to the LaTeX structured formatter and
6220 typesetter.
6221 LATEXRETRIES
6224 The maximum number of times that LaTeX will be re-run if the
6225 .log generated by the $LATEXCOM command indicates that there are
6226 undefined references. The default is to try to resolve unde‐
6227 fined references by re-running LaTeX up to three times.
6228 LATEXSUFFIXES
6231 The list of suffixes of files that will be scanned for LaTeX
6232 implicit dependencies (\include or \import files). The default
6233 list is:
6234 [".tex", ".ltx", ".latex"]
6236 LDMODULE
6239 The linker for building loadable modules. By default, this is
6240 the same as $SHLINK.
6241 LDMODULECOM
6244 The command line for building loadable modules. On Mac OS X,
6245 this uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS
6246 variables. On other systems, this is the same as $SHLINK.
6247 LDMODULECOMSTR
6250 The string displayed when building loadable modules. If this is
6251 not set, then $LDMODULECOM (the command line) is displayed.
6252 LDMODULEFLAGS
6255 General user options passed to the linker for building loadable
6256 modules.
6257 LDMODULEPREFIX
6260 The prefix used for loadable module file names. On Mac OS X,
6261 this is null; on other systems, this is the same as $SHLIBPRE‐
6262 FIX.
6263 LDMODULESUFFIX
6266 The suffix used for loadable module file names. On Mac OS X,
6267 this is null; on other systems, this is the same as $SHLIBSUF‐
6268 FIX.
6269 LEX The lexical analyzer generator.
6272 LEXCOM The command line used to call the lexical analyzer generator to
6275 generate a source file.
6276 LEXCOMSTR
6279 The string displayed when generating a source file using the
6280 lexical analyzer generator. If this is not set, then $LEXCOM
6281 (the command line) is displayed.
6282 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
6284 LEXFLAGS
6287 General options passed to the lexical analyzer generator.
6288 _LIBDIRFLAGS
6291 An automatically-generated construction variable containing the
6292 linker command-line options for specifying directories to be
6293 searched for library. The value of $_LIBDIRFLAGS is created by
6294 appending $LIBDIRPREFIX and $LIBDIRSUFFIX to the beginning and
6295 end of each directory in $LIBPATH.
6296 LIBDIRPREFIX
6299 The prefix used to specify a library directory on the linker
6300 command line. This will be appended to the beginning of each
6301 directory in the $LIBPATH construction variable when the $_LIB‐
6302 DIRFLAGS variable is automatically generated.
6303 LIBDIRSUFFIX
6306 The suffix used to specify a library directory on the linker
6307 command line. This will be appended to the end of each direc‐
6308 tory in the $LIBPATH construction variable when the $_LIB‐
6309 DIRFLAGS variable is automatically generated.
6310 _LIBFLAGS
6313 An automatically-generated construction variable containing the
6314 linker command-line options for specifying libraries to be
6315 linked with the resulting target. The value of $_LIBFLAGS is
6316 created by appending $LIBLINKPREFIX and $LIBLINKSUFFIX to the
6317 beginning and end of each filename in $LIBS.
6318 LIBLINKPREFIX
6321 The prefix used to specify a library to link on the linker com‐
6322 mand line. This will be appended to the beginning of each
6323 library in the $LIBS construction variable when the $_LIBFLAGS
6324 variable is automatically generated.
6325 LIBLINKSUFFIX
6328 The suffix used to specify a library to link on the linker com‐
6329 mand line. This will be appended to the end of each library in
6330 the $LIBS construction variable when the $_LIBFLAGS variable is
6331 automatically generated.
6332 LIBPATH
6335 The list of directories that will be searched for libraries.
6336 The implicit dependency scanner will search these directories
6337 for include files. Don't explicitly put include directory argu‐
6338 ments in $LINKFLAGS or $SHLINKFLAGS because the result will be
6339 non-portable and the directories will not be searched by the
6340 dependency scanner. Note: directory names in LIBPATH will be
6341 looked-up relative to the SConscript directory when they are
6342 used in a command. To force scons to look-up a directory rela‐
6343 tive to the root of the source tree use #:
6344 env = Environment(LIBPATH='#/libs')
6346 The directory look-up can also be forced using the Dir() func‐
6348 tion:
6349 libs = Dir('libs')
6351 env = Environment(LIBPATH=libs)
6352 The directory list will be added to command lines through the
6354 automatically-generated $_LIBDIRFLAGS construction variable,
6355 which is constructed by appending the values of the $LIBDIRPRE‐
6356 FIX and $LIBDIRSUFFIX construction variables to the beginning
6357 and end of each directory in $LIBPATH. Any command lines you
6358 define that need the LIBPATH directory list should include
6359 $_LIBDIRFLAGS:
6360 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6362 LIBPREFIX
6365 The prefix used for (static) library file names. A default
6366 value is set for each platform (posix, win32, os2, etc.), but
6367 the value is overridden by individual tools (ar, mslib, sgiar,
6368 sunar, tlib, etc.) to reflect the names of the libraries they
6369 create.
6370 LIBPREFIXES
6373 A list of all legal prefixes for library file names. When
6374 searching for library dependencies, SCons will look for files
6375 with these prefixes, the base library name, and suffixes in the
6376 $LIBSUFFIXES list.
6377 LIBS A list of one or more libraries that will be linked with any
6380 executable programs created by this environment.
6381 The library list will be added to command lines through the
6383 automatically-generated $_LIBFLAGS construction variable, which
6384 is constructed by appending the values of the $LIBLINKPREFIX and
6385 $LIBLINKSUFFIX construction variables to the beginning and end
6386 of each filename in $LIBS. Any command lines you define that
6387 need the LIBS library list should include $_LIBFLAGS:
6388 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6390 If you add a File object to the $LIBS list, the name of that
6392 file will be added to $_LIBFLAGS, and thus the link line, as is,
6393 without $LIBLINKPREFIX or $LIBLINKSUFFIX. For example:
6394 env.Append(LIBS=File('/tmp/mylib.so'))
6396 In all cases, scons will add dependencies from the executable
6398 program to all the libraries in this list.
6399 LIBSUFFIX
6402 The suffix used for (static) library file names. A default
6403 value is set for each platform (posix, win32, os2, etc.), but
6404 the value is overridden by individual tools (ar, mslib, sgiar,
6405 sunar, tlib, etc.) to reflect the names of the libraries they
6406 create.
6407 LIBSUFFIXES
6410 A list of all legal suffixes for library file names. When
6411 searching for library dependencies, SCons will look for files
6412 with prefixes, in the $LIBPREFIXES list, the base library name,
6413 and these suffixes.
6414 LICENSE
6417 The abbreviated name of the license under which this project is
6418 released (gpl, lpgl, bsd etc.). See http://www.open‐
6419 source.org/licenses/alphabetical for a list of license names.
6420 LINESEPARATOR
6423 The separator used by the Substfile() and Textfile() builders.
6424 This value is used between sources when constructing the target.
6425 It defaults to the current system line separator.
6426 LINK The linker.
6429 LINKCOM
6432 The command line used to link object files into an executable.
6433 LINKCOMSTR
6436 The string displayed when object files are linked into an exe‐
6437 cutable. If this is not set, then $LINKCOM (the command line)
6438 is displayed.
6439 env = Environment(LINKCOMSTR = "Linking $TARGET")
6441 LINKFLAGS
6444 General user options passed to the linker. Note that this vari‐
6445 able should not contain -l (or similar) options for linking with
6446 the libraries listed in $LIBS, nor -L (or similar) library
6447 search path options that scons generates automatically from
6448 $LIBPATH. See $_LIBFLAGS above, for the variable that expands
6449 to library-link options, and $_LIBDIRFLAGS above, for the vari‐
6450 able that expands to library search path options.
6451 M4 The M4 macro preprocessor.
6454 M4COM The command line used to pass files through the M4 macro pre‐
6457 processor.
6458 M4COMSTR
6461 The string displayed when a file is passed through the M4 macro
6462 preprocessor. If this is not set, then $M4COM (the command
6463 line) is displayed.
6464 M4FLAGS
6467 General options passed to the M4 macro preprocessor.
6468 MAKEINDEX
6471 The makeindex generator for the TeX formatter and typesetter and
6472 the LaTeX structured formatter and typesetter.
6473 MAKEINDEXCOM
6476 The command line used to call the makeindex generator for the
6477 TeX formatter and typesetter and the LaTeX structured formatter
6478 and typesetter.
6479 MAKEINDEXCOMSTR
6482 The string displayed when calling the makeindex generator for
6483 the TeX formatter and typesetter and the LaTeX structured for‐
6484 matter and typesetter. If this is not set, then $MAKEINDEXCOM
6485 (the command line) is displayed.
6486 MAKEINDEXFLAGS
6489 General options passed to the makeindex generator for the TeX
6490 formatter and typesetter and the LaTeX structured formatter and
6491 typesetter.
6492 MAXLINELENGTH
6495 The maximum number of characters allowed on an external command
6496 line. On Win32 systems, link lines longer than this many char‐
6497 acters are linked via a temporary file name.
6498 MIDL The Microsoft IDL compiler.
6501 MIDLCOM
6504 The command line used to pass files to the Microsoft IDL com‐
6505 piler.
6506 MIDLCOMSTR
6509 The string displayed when the Microsoft IDL copmiler is called.
6510 If this is not set, then $MIDLCOM (the command line) is dis‐
6511 played.
6512 MIDLFLAGS
6515 General options passed to the Microsoft IDL compiler.
6516 MSSDK_DIR
6519 The directory containing the Microsoft SDK (either Platform SDK
6520 or Windows SDK) to be used for compilation.
6521 MSSDK_VERSION
6524 The version string of the Microsoft SDK (either Platform SDK or
6525 Windows SDK) to be used for compilation. Supported versions
6526 include 6.1, 6.0A, 6.0, 2003R2 and 2003R1.
6527 MSVC_BATCH
6530 When set to any true value, specifies that SCons should batch
6531 compilation of object files when calling the Microsoft Visual
6532 C/C++ compiler. All compilations of source files from the same
6533 source directory that generate target files in a same output
6534 directory and were configured in SCons using the same construc‐
6535 tion environment will be built in a single call to the compiler.
6536 Only source files that have changed since their object files
6537 were built will be passed to each compiler invocation (via the
6538 $CHANGED_SOURCES construction variable). Any compilations where
6539 the object (target) file base name (minus the .obj) does not
6540 match the source file base name will be compiled separately.
6541 MSVC_USE_SCRIPT
6544 Use a batch script to set up Microsoft Visual Studio compiler
6545 $MSVC_USE_SCRIPT overrides $MSVC_VERSION and $TARGET_ARCH. If
6547 set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
6548 SCons will run that bat file and extract the relevant variables
6549 from the result (typically %INCLUDE%, %LIB%, and %PATH%). Set‐
6550 ting MSVC_USE_SCRIPT to None bypasses the Visual Studio autode‐
6551 tection entirely; use this if you are running SCons in a Visual
6552 Studio cmd window and importing the shell's environment vari‐
6553 ables.
6554 MSVC_VERSION
6557 Sets the preferred version of Microsoft Visual C/C++ to use.
6558 If $MSVC_VERSION is not set, SCons will (by default) select the
6560 latest version of Visual C/C++ installed on your system. If the
6561 specified version isn't installed, tool initialization will
6562 fail. This variable must be passed as an argument to the Envi‐
6563 ronment() constructor; setting it later has no effect. Set it
6564 to an unexpected value (e.g. "XXX") to see the valid values on
6565 your system.
6566 MSVS When the Microsoft Visual Studio tools are initialized, they set
6569 up this dictionary with the following keys:
6570 VERSION: the version of MSVS being used (can be set via
6572 $MSVS_VERSION)
6573 VERSIONS: the available versions of MSVS installed
6575 VCINSTALLDIR: installed directory of Visual C++
6577 VSINSTALLDIR: installed directory of Visual Studio
6579 FRAMEWORKDIR: installed directory of the .NET framework
6581 FRAMEWORKVERSIONS: list of installed versions of the .NET frame‐
6583 work, sorted latest to oldest.
6584 FRAMEWORKVERSION: latest installed version of the .NET framework
6586 FRAMEWORKSDKDIR: installed location of the .NET SDK.
6588 PLATFORMSDKDIR: installed location of the Platform SDK.
6590 PLATFORMSDK_MODULES: dictionary of installed Platform SDK mod‐
6592 ules, where the dictionary keys are keywords for the various
6593 modules, and the values are 2-tuples where the first is the
6594 release date, and the second is the version number.
6595 If a value isn't set, it wasn't available in the registry.
6597 MSVS_ARCH
6600 Sets the architecture for which the generated project(s) should
6601 build.
6602 The default value is x86. amd64 is also supported by &SCons;
6604 for some Visual Studio versions. Trying to set $MSVS_ARCH to an
6605 architecture that's not supported for a given Visual Studio ver‐
6606 sion will generate an error.
6607 MSVS_PROJECT_BASE_PATH
6610 The string placed in a generated Microsoft Visual Studio solu‐
6611 tion file as the value of the SccProjectFilePathRelativizedFrom‐
6612 Connection0 and SccProjectFilePathRelativizedFromConnection1
6613 attributes of the GlobalSection(SourceCodeControl) section.
6614 There is no default value.
6615 MSVS_PROJECT_GUID
6618 The string placed in a generated Microsoft Visual Studio project
6619 file as the value of the ProjectGUID attribute. The string is
6620 also placed in the SolutionUniqueID attribute of the GlobalSec‐
6621 tion(SourceCodeControl) section of the Microsoft Visual Studio
6622 solution file. There is no default value.
6623 MSVS_SCC_AUX_PATH
6626 The path name placed in a generated Microsoft Visual Studio
6627 project file as the value of the SccAuxPath attribute if the
6628 MSVS_SCC_PROVIDER construction variable is also set. There is
6629 no default value.
6630 MSVS_SCC_LOCAL_PATH
6633 The path name placed in a generated Microsoft Visual Studio
6634 project file as the value of the SccLocalPath attribute if the
6635 MSVS_SCC_PROVIDER construction variable is also set. The path
6636 name is also placed in the SccLocalPath0 and SccLocalPath1
6637 attributes of the GlobalSection(SourceCodeControl) section of
6638 the Microsoft Visual Studio solution file. There is no default
6639 value.
6640 MSVS_SCC_PROJECT_NAME
6643 The project name placed in a generated Microsoft Visual Studio
6644 project file as the value of the SccProjectName attribute.
6645 There is no default value.
6646 MSVS_SCC_PROVIDER
6649 The string placed in a generated Microsoft Visual Studio project
6650 file as the value of the SccProvider attribute. The string is
6651 also placed in the SccProvider1 attribute of the GlobalSec‐
6652 tion(SourceCodeControl) section of the Microsoft Visual Studio
6653 solution file. There is no default value.
6654 MSVS_VERSION
6657 Sets the preferred version of Microsoft Visual Studio to use.
6658 If $MSVS_VERSION is not set, &SCons; will (by default) select
6660 the latest version of Visual Studio installed on your system.
6661 So, if you have version 6 and version 7 (MSVS .NET) installed,
6662 it will prefer version 7. You can override this by specifying
6663 the MSVS_VERSION variable in the Environment initialization,
6664 setting it to the appropriate version ('6.0' or '7.0', for exam‐
6665 ple). If the specified version isn't installed, tool initial‐
6666 ization will fail.
6667 This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is
6669 set and $MSVC_VERSION is not, $MSVC_VERSION will be set automat‐
6670 ically to $MSVS_VERSION. If both are set to different values,
6671 scons will raise an error.
6672 MSVSBUILDCOM
6675 The build command line placed in a generated Microsoft Visual
6676 Studio project file. The default is to have Visual Studio
6677 invoke SCons with any specified build targets.
6678 MSVSCLEANCOM
6681 The clean command line placed in a generated Microsoft Visual
6682 Studio project file. The default is to have Visual Studio
6683 invoke SCons with the -c option to remove any specified targets.
6684 MSVSENCODING
6687 The encoding string placed in a generated Microsoft Visual Stu‐
6688 dio project file. The default is encoding Windows-1252.
6689 MSVSPROJECTCOM
6692 The action used to generate Microsoft Visual Studio project
6693 files.
6694 MSVSPROJECTSUFFIX
6697 The suffix used for Microsoft Visual Studio project (DSP) files.
6698 The default value is .vcproj when using Visual Studio version
6699 7.x (.NET) or later version, and .dsp when using earlier ver‐
6700 sions of Visual Studio.
6701 MSVSREBUILDCOM
6704 The rebuild command line placed in a generated Microsoft Visual
6705 Studio project file. The default is to have Visual Studio
6706 invoke SCons with any specified rebuild targets.
6707 MSVSSCONS
6710 The SCons used in generated Microsoft Visual Studio project
6711 files. The default is the version of SCons being used to gener‐
6712 ate the project file.
6713 MSVSSCONSCOM
6716 The default SCons command used in generated Microsoft Visual
6717 Studio project files.
6718 MSVSSCONSCRIPT
6721 The sconscript file (that is, SConstruct or SConscript file)
6722 that will be invoked by Visual Studio project files (through the
6723 $MSVSSCONSCOM variable). The default is the same sconscript
6724 file that contains the call to MSVSProject() to build the
6725 project file.
6726 MSVSSCONSFLAGS
6729 The SCons flags used in generated Microsoft Visual Studio
6730 project files.
6731 MSVSSOLUTIONCOM
6734 The action used to generate Microsoft Visual Studio solution
6735 files.
6736 MSVSSOLUTIONSUFFIX
6739 The suffix used for Microsoft Visual Studio solution (DSW)
6740 files. The default value is .sln when using Visual Studio ver‐
6741 sion 7.x (.NET), and .dsw when using earlier versions of Visual
6742 Studio.
6743 MWCW_VERSION
6746 The version number of the MetroWerks CodeWarrior C compiler to
6747 be used.
6748 MWCW_VERSIONS
6751 A list of installed versions of the MetroWerks CodeWarrior C
6752 compiler on this system.
6753 NAME Specfies the name of the project to package.
6756 no_import_lib
6759 When set to non-zero, suppresses creation of a corresponding
6760 Windows static import lib by the SharedLibrary builder when used
6761 with MinGW, Microsoft Visual Studio or Metrowerks. This also
6762 suppresses creation of an export (.exp) file when using Micro‐
6763 soft Visual Studio.
6764 OBJPREFIX
6767 The prefix used for (static) object file names.
6768 OBJSUFFIX
6771 The suffix used for (static) object file names.
6772 P4 The Perforce executable.
6775 P4COM The command line used to fetch source files from Perforce.
6778 P4COMSTR
6781 The string displayed when fetching a source file from Perforce.
6782 If this is not set, then $P4COM (the command line) is displayed.
6783 P4FLAGS
6786 General options that are passed to Perforce.
6787 PACKAGEROOT
6790 Specifies the directory where all files in resulting archive
6791 will be placed if applicable. The default value is "$NAME-$VER‐
6792 SION".
6793 PACKAGETYPE
6796 Selects the package type to build. Currently these are avail‐
6797 able:
6798 * msi - Microsoft Installer
6800 * rpm - Redhat Package Manger
6801 * ipkg - Itsy Package Management System
6802 * tarbz2 - compressed tar
6803 * targz - compressed tar
6804 * zip - zip file
6805 * src_tarbz2 - compressed tar source
6806 * src_targz - compressed tar source
6807 * src_zip - zip file source
6808 This may be overridden with the "package_type" command line
6810 option.
6811 PACKAGEVERSION
6814 The version of the package (not the underlying project). This
6815 is currently only used by the rpm packager and should reflect
6816 changes in the packaging, not the underlying project code
6817 itself.
6818 PCH The Microsoft Visual C++ precompiled header that will be used
6821 when compiling object files. This variable is ignored by tools
6822 other than Microsoft Visual C++. When this variable is defined
6823 SCons will add options to the compiler command line to cause it
6824 to use the precompiled header, and will also set up the depen‐
6825 dencies for the PCH file. Example:
6826 env['PCH'] = 'StdAfx.pch'
6828 PCHCOM The command line used by the PCH() builder to generated a pre‐
6831 compiled header.
6832 PCHCOMSTR
6835 The string displayed when generating a precompiled header. If
6836 this is not set, then $PCHCOM (the command line) is displayed.
6837 PCHPDBFLAGS
6840 A construction variable that, when expanded, adds the /yD flag
6841 to the command line only if the $PDB construction variable is
6842 set.
6843 PCHSTOP
6846 This variable specifies how much of a source file is precom‐
6847 piled. This variable is ignored by tools other than Microsoft
6848 Visual C++, or when the PCH variable is not being used. When
6849 this variable is define it must be a string that is the name of
6850 the header that is included at the end of the precompiled por‐
6851 tion of the source files, or the empty string if the "#pragma
6852 hrdstop" construct is being used:
6853 env['PCHSTOP'] = 'StdAfx.h'
6855 PDB The Microsoft Visual C++ PDB file that will store debugging
6858 information for object files, shared libraries, and programs.
6859 This variable is ignored by tools other than Microsoft Visual
6860 C++. When this variable is defined SCons will add options to
6861 the compiler and linker command line to cause them to generate
6862 external debugging information, and will also set up the depen‐
6863 dencies for the PDB file. Example:
6864 env['PDB'] = 'hello.pdb'
6866 The Visual C++ compiler switch that SCons uses by default to
6868 generate PDB information is /Z7. This works correctly with par‐
6869 allel (-j) builds because it embeds the debug information in the
6870 intermediate object files, as opposed to sharing a single PDB
6871 file between multiple object files. This is also the only way
6872 to get debug information embedded into a static library. Using
6873 the /Zi instead may yield improved link-time performance,
6874 although parallel builds will no longer work. You can generate
6875 PDB files with the /Zi switch by overriding the default
6876 $CCPDBFLAGS variable; see the entry for that variable for spe‐
6877 cific examples.
6878 PDFCOM A deprecated synonym for $DVIPDFCOM.
6881 PDFLATEX
6884 The &pdflatex; utility.
6885 PDFLATEXCOM
6888 The command line used to call the &pdflatex; utility.
6889 PDFLATEXCOMSTR
6892 The string displayed when calling the &pdflatex; utility. If
6893 this is not set, then $PDFLATEXCOM (the command line) is dis‐
6894 played.
6895 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
6897 PDFLATEXFLAGS
6900 General options passed to the &pdflatex; utility.
6901 PDFPREFIX
6904 The prefix used for PDF file names.
6905 PDFSUFFIX
6908 The suffix used for PDF file names.
6909 PDFTEX The &pdftex; utility.
6912 PDFTEXCOM
6915 The command line used to call the &pdftex; utility.
6916 PDFTEXCOMSTR
6919 The string displayed when calling the &pdftex; utility. If this
6920 is not set, then $PDFTEXCOM (the command line) is displayed.
6921 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
6923 PDFTEXFLAGS
6926 General options passed to the &pdftex; utility.
6927 PKGCHK On Solaris systems, the package-checking program that will be
6930 used (along with $PKGINFO) to look for installed versions of the
6931 Sun PRO C++ compiler. The default is /usr/sbin/pgkchk.
6932 PKGINFO
6935 On Solaris systems, the package information program that will be
6936 used (along with $PKGCHK) to look for installed versions of the
6937 Sun PRO C++ compiler. The default is pkginfo.
6938 PLATFORM
6941 The name of the platform used to create the Environment. If no
6942 platform is specified when the Environment is created, scons
6943 autodetects the platform.
6944 env = Environment(tools = [])
6946 if env['PLATFORM'] == 'cygwin':
6947 Tool('mingw')(env)
6948 else:
6949 Tool('msvc')(env)
6950 PRINT_CMD_LINE_FUNC
6953 A Python function used to print the command lines as they are
6954 executed (assuming command printing is not disabled by the -q or
6955 -s options or their equivalents). The function should take four
6956 arguments: s, the command being executed (a string), target, the
6957 target being built (file node, list, or string name(s)), source,
6958 the source(s) used (file node, list, or string name(s)), and
6959 env, the environment being used.
6960 The function must do the printing itself. The default implemen‐
6962 tation, used if this variable is not set or is None, is:
6963 def print_cmd_line(s, target, source, env):
6964 sys.stdout.write(s + "\n")
6965 Here's an example of a more interesting function:
6967 def print_cmd_line(s, target, source, env):
6969 sys.stdout.write("Building %s -> %s...\n" %
6970 (' and '.join([str(x) for x in source]),
6971 ' and '.join([str(x) for x in target])))
6972 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
6973 env.Program('foo', 'foo.c')
6974 This just prints "Building targetname from sourcename..."
6976 instead of the actual commands. Such a function could also log
6977 the actual commands to a log file, for example.
6978 PROGPREFIX
6981 The prefix used for executable file names.
6982 PROGSUFFIX
6985 The suffix used for executable file names.
6986 PSCOM The command line used to convert TeX DVI files into a PostScript
6989 file.
6990 PSCOMSTR
6993 The string displayed when a TeX DVI file is converted into a
6994 PostScript file. If this is not set, then $PSCOM (the command
6995 line) is displayed.
6996 PSPREFIX
6999 The prefix used for PostScript file names.
7000 PSSUFFIX
7003 The prefix used for PostScript file names.
7004 QT_AUTOSCAN
7007 Turn off scanning for mocable files. Use the Moc Builder to
7008 explicitly specify files to run moc on.
7009 QT_BINPATH
7012 The path where the qt binaries are installed. The default value
7013 is '$QTDIR/bin'.
7014 QT_CPPPATH
7017 The path where the qt header files are installed. The default
7018 value is '$QTDIR/include'. Note: If you set this variable to
7019 None, the tool won't change the $CPPPATH construction variable.
7020 QT_DEBUG
7023 Prints lots of debugging information while scanning for moc
7024 files.
7025 QT_LIB Default value is 'qt'. You may want to set this to 'qt-mt'.
7028 Note: If you set this variable to None, the tool won't change
7029 the $LIBS variable.
7030 QT_LIBPATH
7033 The path where the qt libraries are installed. The default
7034 value is '$QTDIR/lib'. Note: If you set this variable to None,
7035 the tool won't change the $LIBPATH construction variable.
7036 QT_MOC Default value is '$QT_BINPATH/moc'.
7039 QT_MOCCXXPREFIX
7042 Default value is ''. Prefix for moc output files, when source is
7043 a cxx file.
7044 QT_MOCCXXSUFFIX
7047 Default value is '.moc'. Suffix for moc output files, when
7048 source is a cxx file.
7049 QT_MOCFROMCXXCOM
7052 Command to generate a moc file from a cpp file.
7053 QT_MOCFROMCXXCOMSTR
7056 The string displayed when generating a moc file from a cpp file.
7057 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is
7058 displayed.
7059 QT_MOCFROMCXXFLAGS
7062 Default value is '-i'. These flags are passed to moc, when mocc‐
7063 ing a C++ file.
7064 QT_MOCFROMHCOM
7067 Command to generate a moc file from a header.
7068 QT_MOCFROMHCOMSTR
7071 The string displayed when generating a moc file from a cpp file.
7072 If this is not set, then $QT_MOCFROMHCOM (the command line) is
7073 displayed.
7074 QT_MOCFROMHFLAGS
7077 Default value is ''. These flags are passed to moc, when moccing
7078 a header file.
7079 QT_MOCHPREFIX
7082 Default value is 'moc_'. Prefix for moc output files, when
7083 source is a header.
7084 QT_MOCHSUFFIX
7087 Default value is '$CXXFILESUFFIX'. Suffix for moc output files,
7088 when source is a header.
7089 QT_UIC Default value is '$QT_BINPATH/uic'.
7092 QT_UICCOM
7095 Command to generate header files from .ui files.
7096 QT_UICCOMSTR
7099 The string displayed when generating header files from .ui
7100 files. If this is not set, then $QT_UICCOM (the command line)
7101 is displayed.
7102 QT_UICDECLFLAGS
7105 Default value is ''. These flags are passed to uic, when creat‐
7106 ing a a h file from a .ui file.
7107 QT_UICDECLPREFIX
7110 Default value is ''. Prefix for uic generated header files.
7111 QT_UICDECLSUFFIX
7114 Default value is '.h'. Suffix for uic generated header files.
7115 QT_UICIMPLFLAGS
7118 Default value is ''. These flags are passed to uic, when creat‐
7119 ing a cxx file from a .ui file.
7120 QT_UICIMPLPREFIX
7123 Default value is 'uic_'. Prefix for uic generated implementation
7124 files.
7125 QT_UICIMPLSUFFIX
7128 Default value is '$CXXFILESUFFIX'. Suffix for uic generated
7129 implementation files.
7130 QT_UISUFFIX
7133 Default value is '.ui'. Suffix of designer input files.
7134 QTDIR The qt tool tries to take this from os.environ. It also ini‐
7137 tializes all QT_* construction variables listed below. (Note
7138 that all paths are constructed with python's os.path.join()
7139 method, but are listed here with the '/' separator for easier
7140 reading.) In addition, the construction environment variables
7141 $CPPPATH, $LIBPATH and $LIBS may be modified and the variables
7142 PROGEMITTER, SHLIBEMITTER and LIBEMITTER are modified. Because
7143 the build-performance is affected when using this tool, you have
7144 to explicitly specify it at Environment creation:
7145 Environment(tools=['default','qt'])
7147 The qt tool supports the following operations:
7149 Automatic moc file generation from header files. You do not
7151 have to specify moc files explicitly, the tool does it for you.
7152 However, there are a few preconditions to do so: Your header
7153 file must have the same filebase as your implementation file and
7154 must stay in the same directory. It must have one of the suf‐
7155 fixes .h, .hpp, .H, .hxx, .hh. You can turn off automatic moc
7156 file generation by setting QT_AUTOSCAN to 0. See also the cor‐
7157 responding builder method Moc()
7158 Automatic moc file generation from cxx files. As stated in the
7160 qt documentation, include the moc file at the end of the cxx
7161 file. Note that you have to include the file, which is generated
7162 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOC‐
7163 CXXSUFFIX}, by default <basename>.moc. A warning is generated
7164 after building the moc file, if you do not include the correct
7165 file. If you are using VariantDir, you may need to specify
7166 duplicate=1. You can turn off automatic moc file generation by
7167 setting QT_AUTOSCAN to 0. See also the corresponding Moc()
7168 builder method.
7169 Automatic handling of .ui files. The implementation files gen‐
7171 erated from .ui files are handled much the same as yacc or lex
7172 files. Each .ui file given as a source of Program, Library or
7173 SharedLibrary will generate three files, the declaration file,
7174 the implementation file and a moc file. Because there are also
7175 generated headers, you may need to specify duplicate=1 in calls
7176 to VariantDir. See also the corresponding Uic() builder method.
7177 RANLIB The archive indexer.
7180 RANLIBCOM
7183 The command line used to index a static library archive.
7184 RANLIBCOMSTR
7187 The string displayed when a static library archive is indexed.
7188 If this is not set, then $RANLIBCOM (the command line) is dis‐
7189 played.
7190 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
7192 RANLIBFLAGS
7195 General options passed to the archive indexer.
7196 RC The resource compiler used to build a Microsoft Visual C++
7199 resource file.
7200 RCCOM The command line used to build a Microsoft Visual C++ resource
7203 file.
7204 RCCOMSTR
7207 The string displayed when invoking the resource compiler to
7208 build a Microsoft Visual C++ resource file. If this is not set,
7209 then $RCCOM (the command line) is displayed.
7210 RCFLAGS
7213 The flags passed to the resource compiler by the RES builder.
7214 RCINCFLAGS
7217 An automatically-generated construction variable containing the
7218 command-line options for specifying directories to be searched
7219 by the resource compiler. The value of $RCINCFLAGS is created
7220 by appending $RCINCPREFIX and $RCINCSUFFIX to the beginning and
7221 end of each directory in $CPPPATH.
7222 RCINCPREFIX
7225 The prefix (flag) used to specify an include directory on the
7226 resource compiler command line. This will be appended to the
7227 beginning of each directory in the $CPPPATH construction vari‐
7228 able when the $RCINCFLAGS variable is expanded.
7229 RCINCSUFFIX
7232 The suffix used to specify an include directory on the resource
7233 compiler command line. This will be appended to the end of each
7234 directory in the $CPPPATH construction variable when the
7235 $RCINCFLAGS variable is expanded.
7236 RCS The RCS executable. Note that this variable is not actually
7239 used for the command to fetch source files from RCS; see the
7240 $RCS_CO construction variable, below.
7241 RCS_CO The RCS "checkout" executable, used to fetch source files from
7244 RCS.
7245 RCS_COCOM
7248 The command line used to fetch (checkout) source files from RCS.
7249 RCS_COCOMSTR
7252 The string displayed when fetching a source file from RCS. If
7253 this is not set, then $RCS_COCOM (the command line) is dis‐
7254 played.
7255 RCS_COFLAGS
7258 Options that are passed to the $RCS_CO command.
7259 RDirs A function that converts a string into a list of Dir instances
7262 by searching the repositories.
7263 REGSVR The program used on Windows systems to register a newly-built
7266 DLL library whenever the SharedLibrary() builder is passed a
7267 keyword argument of register=1.
7268 REGSVRCOM
7271 The command line used on Windows systems to register a newly-
7272 built DLL library whenever the SharedLibrary() builder is passed
7273 a keyword argument of register=1.
7274 REGSVRCOMSTR
7277 The string displayed when registering a newly-built DLL file.
7278 If this is not set, then $REGSVRCOM (the command line) is dis‐
7279 played.
7280 REGSVRFLAGS
7283 Flags passed to the DLL registration program on Windows systems
7284 when a newly-built DLL library is registered. By default, this
7285 includes the /s that prevents dialog boxes from popping up and
7286 requiring user attention.
7287 RMIC The Java RMI stub compiler.
7290 RMICCOM
7293 The command line used to compile stub and skeleton class files
7294 from Java classes that contain RMI implementations. Any options
7295 specified in the $RMICFLAGS construction variable are included
7296 on this command line.
7297 RMICCOMSTR
7300 The string displayed when compiling stub and skeleton class
7301 files from Java classes that contain RMI implementations. If
7302 this is not set, then $RMICCOM (the command line) is displayed.
7303 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
7305 RMICFLAGS
7308 General options passed to the Java RMI stub compiler.
7309 _RPATH An automatically-generated construction variable containing the
7312 rpath flags to be used when linking a program with shared
7313 libraries. The value of $_RPATH is created by appending $RPATH‐
7314 PREFIX and $RPATHSUFFIX to the beginning and end of each direc‐
7315 tory in $RPATH.
7316 RPATH A list of paths to search for shared libraries when running pro‐
7319 grams. Currently only used in the GNU (gnulink), IRIX (sgilink)
7320 and Sun (sunlink) linkers. Ignored on platforms and toolchains
7321 that don't support it. Note that the paths added to RPATH are
7322 not transformed by scons in any way: if you want an absolute
7323 path, you must make it absolute yourself.
7324 RPATHPREFIX
7327 The prefix used to specify a directory to be searched for shared
7328 libraries when running programs. This will be appended to the
7329 beginning of each directory in the $RPATH construction variable
7330 when the $_RPATH variable is automatically generated.
7331 RPATHSUFFIX
7334 The suffix used to specify a directory to be searched for shared
7335 libraries when running programs. This will be appended to the
7336 end of each directory in the $RPATH construction variable when
7337 the $_RPATH variable is automatically generated.
7338 RPCGEN The RPC protocol compiler.
7341 RPCGENCLIENTFLAGS
7344 Options passed to the RPC protocol compiler when generating
7345 client side stubs. These are in addition to any flags specified
7346 in the $RPCGENFLAGS construction variable.
7347 RPCGENFLAGS
7350 General options passed to the RPC protocol compiler.
7351 RPCGENHEADERFLAGS
7354 Options passed to the RPC protocol compiler when generating a
7355 header file. These are in addition to any flags specified in
7356 the $RPCGENFLAGS construction variable.
7357 RPCGENSERVICEFLAGS
7360 Options passed to the RPC protocol compiler when generating
7361 server side stubs. These are in addition to any flags specified
7362 in the $RPCGENFLAGS construction variable.
7363 RPCGENXDRFLAGS
7366 Options passed to the RPC protocol compiler when generating XDR
7367 routines. These are in addition to any flags specified in the
7368 $RPCGENFLAGS construction variable.
7369 SCANNERS
7372 A list of the available implicit dependency scanners. New file
7373 scanners may be added by appending to this list, although the
7374 more flexible approach is to associate scanners with a specific
7375 Builder. See the sections "Builder Objects" and "Scanner
7376 Objects," below, for more information.
7377 SCCS The SCCS executable.
7380 SCCSCOM
7383 The command line used to fetch source files from SCCS.
7384 SCCSCOMSTR
7387 The string displayed when fetching a source file from a CVS
7388 repository. If this is not set, then $SCCSCOM (the command
7389 line) is displayed.
7390 SCCSFLAGS
7393 General options that are passed to SCCS.
7394 SCCSGETFLAGS
7397 Options that are passed specifically to the SCCS "get" subcom‐
7398 mand. This can be set, for example, to -e to check out editable
7399 files from SCCS.
7400 SCONS_HOME
7403 The (optional) path to the SCons library directory, initialized
7404 from the external environment. If set, this is used to con‐
7405 struct a shorter and more efficient search path in the $MSVSS‐
7406 CONS command line executed from Microsoft Visual Studio project
7407 files.
7408 SHCC The C compiler used for generating shared-library objects.
7411 SHCCCOM
7414 The command line used to compile a C source file to a shared-
7415 library object file. Any options specified in the $SHCFLAGS,
7416 $SHCCFLAGS and $CPPFLAGS construction variables are included on
7417 this command line.
7418 SHCCCOMSTR
7421 The string displayed when a C source file is compiled to a
7422 shared object file. If this is not set, then $SHCCCOM (the com‐
7423 mand line) is displayed.
7424 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
7426 SHCCFLAGS
7429 Options that are passed to the C and C++ compilers to generate
7430 shared-library objects.
7431 SHCFLAGS
7434 Options that are passed to the C compiler (only; not C++) to
7435 generate shared-library objects.
7436 SHCXX The C++ compiler used for generating shared-library objects.
7439 SHCXXCOM
7442 The command line used to compile a C++ source file to a shared-
7443 library object file. Any options specified in the $SHCXXFLAGS
7444 and $CPPFLAGS construction variables are included on this com‐
7445 mand line.
7446 SHCXXCOMSTR
7449 The string displayed when a C++ source file is compiled to a
7450 shared object file. If this is not set, then $SHCXXCOM (the
7451 command line) is displayed.
7452 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
7454 SHCXXFLAGS
7457 Options that are passed to the C++ compiler to generate shared-
7458 library objects.
7459 SHELL A string naming the shell program that will be passed to the
7462 $SPAWN function. See the $SPAWN construction variable for more
7463 information.
7464 SHF77 The Fortran 77 compiler used for generating shared-library
7467 objects. You should normally set the $SHFORTRAN variable, which
7468 specifies the default Fortran compiler for all Fortran versions.
7469 You only need to set $SHF77 if you need to use a specific com‐
7470 piler or compiler version for Fortran 77 files.
7471 SHF77COM
7474 The command line used to compile a Fortran 77 source file to a
7475 shared-library object file. You only need to set $SHF77COM if
7476 you need to use a specific command line for Fortran 77 files.
7477 You should normally set the $SHFORTRANCOM variable, which speci‐
7478 fies the default command line for all Fortran versions.
7479 SHF77COMSTR
7482 The string displayed when a Fortran 77 source file is compiled
7483 to a shared-library object file. If this is not set, then
7484 $SHF77COM or $SHFORTRANCOM (the command line) is displayed.
7485 SHF77FLAGS
7488 Options that are passed to the Fortran 77 compiler to generated
7489 shared-library objects. You only need to set $SHF77FLAGS if you
7490 need to define specific user options for Fortran 77 files. You
7491 should normally set the $SHFORTRANFLAGS variable, which speci‐
7492 fies the user-specified options passed to the default Fortran
7493 compiler for all Fortran versions.
7494 SHF77PPCOM
7497 The command line used to compile a Fortran 77 source file to a
7498 shared-library object file after first running the file through
7499 the C preprocessor. Any options specified in the $SHF77FLAGS
7500 and $CPPFLAGS construction variables are included on this com‐
7501 mand line. You only need to set $SHF77PPCOM if you need to use
7502 a specific C-preprocessor command line for Fortran 77 files.
7503 You should normally set the $SHFORTRANPPCOM variable, which
7504 specifies the default C-preprocessor command line for all For‐
7505 tran versions.
7506 SHF77PPCOMSTR
7509 The string displayed when a Fortran 77 source file is compiled
7510 to a shared-library object file after first running the file
7511 through the C preprocessor. If this is not set, then
7512 $SHF77PPCOM or $SHFORTRANPPCOM (the command line) is displayed.
7513 SHF90 The Fortran 90 compiler used for generating shared-library
7516 objects. You should normally set the $SHFORTRAN variable, which
7517 specifies the default Fortran compiler for all Fortran versions.
7518 You only need to set $SHF90 if you need to use a specific com‐
7519 piler or compiler version for Fortran 90 files.
7520 SHF90COM
7523 The command line used to compile a Fortran 90 source file to a
7524 shared-library object file. You only need to set $SHF90COM if
7525 you need to use a specific command line for Fortran 90 files.
7526 You should normally set the $SHFORTRANCOM variable, which speci‐
7527 fies the default command line for all Fortran versions.
7528 SHF90COMSTR
7531 The string displayed when a Fortran 90 source file is compiled
7532 to a shared-library object file. If this is not set, then
7533 $SHF90COM or $SHFORTRANCOM (the command line) is displayed.
7534 SHF90FLAGS
7537 Options that are passed to the Fortran 90 compiler to generated
7538 shared-library objects. You only need to set $SHF90FLAGS if you
7539 need to define specific user options for Fortran 90 files. You
7540 should normally set the $SHFORTRANFLAGS variable, which speci‐
7541 fies the user-specified options passed to the default Fortran
7542 compiler for all Fortran versions.
7543 SHF90PPCOM
7546 The command line used to compile a Fortran 90 source file to a
7547 shared-library object file after first running the file through
7548 the C preprocessor. Any options specified in the $SHF90FLAGS
7549 and $CPPFLAGS construction variables are included on this com‐
7550 mand line. You only need to set $SHF90PPCOM if you need to use
7551 a specific C-preprocessor command line for Fortran 90 files.
7552 You should normally set the $SHFORTRANPPCOM variable, which
7553 specifies the default C-preprocessor command line for all For‐
7554 tran versions.
7555 SHF90PPCOMSTR
7558 The string displayed when a Fortran 90 source file is compiled
7559 to a shared-library object file after first running the file
7560 through the C preprocessor. If this is not set, then
7561 $SHF90PPCOM or $SHFORTRANPPCOM (the command line) is displayed.
7562 SHF95 The Fortran 95 compiler used for generating shared-library
7565 objects. You should normally set the $SHFORTRAN variable, which
7566 specifies the default Fortran compiler for all Fortran versions.
7567 You only need to set $SHF95 if you need to use a specific com‐
7568 piler or compiler version for Fortran 95 files.
7569 SHF95COM
7572 The command line used to compile a Fortran 95 source file to a
7573 shared-library object file. You only need to set $SHF95COM if
7574 you need to use a specific command line for Fortran 95 files.
7575 You should normally set the $SHFORTRANCOM variable, which speci‐
7576 fies the default command line for all Fortran versions.
7577 SHF95COMSTR
7580 The string displayed when a Fortran 95 source file is compiled
7581 to a shared-library object file. If this is not set, then
7582 $SHF95COM or $SHFORTRANCOM (the command line) is displayed.
7583 SHF95FLAGS
7586 Options that are passed to the Fortran 95 compiler to generated
7587 shared-library objects. You only need to set $SHF95FLAGS if you
7588 need to define specific user options for Fortran 95 files. You
7589 should normally set the $SHFORTRANFLAGS variable, which speci‐
7590 fies the user-specified options passed to the default Fortran
7591 compiler for all Fortran versions.
7592 SHF95PPCOM
7595 The command line used to compile a Fortran 95 source file to a
7596 shared-library object file after first running the file through
7597 the C preprocessor. Any options specified in the $SHF95FLAGS
7598 and $CPPFLAGS construction variables are included on this com‐
7599 mand line. You only need to set $SHF95PPCOM if you need to use
7600 a specific C-preprocessor command line for Fortran 95 files.
7601 You should normally set the $SHFORTRANPPCOM variable, which
7602 specifies the default C-preprocessor command line for all For‐
7603 tran versions.
7604 SHF95PPCOMSTR
7607 The string displayed when a Fortran 95 source file is compiled
7608 to a shared-library object file after first running the file
7609 through the C preprocessor. If this is not set, then
7610 $SHF95PPCOM or $SHFORTRANPPCOM (the command line) is displayed.
7611 SHFORTRAN
7614 The default Fortran compiler used for generating shared-library
7615 objects.
7616 SHFORTRANCOM
7619 The command line used to compile a Fortran source file to a
7620 shared-library object file.
7621 SHFORTRANCOMSTR
7624 The string displayed when a Fortran source file is compiled to a
7625 shared-library object file. If this is not set, then $SHFOR‐
7626 TRANCOM (the command line) is displayed.
7627 SHFORTRANFLAGS
7630 Options that are passed to the Fortran compiler to generate
7631 shared-library objects.
7632 SHFORTRANPPCOM
7635 The command line used to compile a Fortran source file to a
7636 shared-library object file after first running the file through
7637 the C preprocessor. Any options specified in the $SHFORTRAN‐
7638 FLAGS and $CPPFLAGS construction variables are included on this
7639 command line.
7640 SHFORTRANPPCOMSTR
7643 The string displayed when a Fortran source file is compiled to a
7644 shared-library object file after first running the file through
7645 the C preprocessor. If this is not set, then $SHFORTRANPPCOM
7646 (the command line) is displayed.
7647 SHLIBPREFIX
7650 The prefix used for shared library file names.
7651 SHLIBSUFFIX
7654 The suffix used for shared library file names.
7655 SHLINK The linker for programs that use shared libraries.
7658 SHLINKCOM
7661 The command line used to link programs using shared libraries.
7662 SHLINKCOMSTR
7665 The string displayed when programs using shared libraries are
7666 linked. If this is not set, then $SHLINKCOM (the command line)
7667 is displayed.
7668 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
7670 SHLINKFLAGS
7673 General user options passed to the linker for programs using
7674 shared libraries. Note that this variable should not contain -l
7675 (or similar) options for linking with the libraries listed in
7676 $LIBS, nor -L (or similar) include search path options that
7677 scons generates automatically from $LIBPATH. See $_LIBFLAGS
7678 above, for the variable that expands to library-link options,
7679 and $_LIBDIRFLAGS above, for the variable that expands to
7680 library search path options.
7681 SHOBJPREFIX
7684 The prefix used for shared object file names.
7685 SHOBJSUFFIX
7688 The suffix used for shared object file names.
7689 SOURCE A reserved variable name that may not be set or used in a con‐
7692 struction environment. (See "Variable Substitution," below.)
7693 SOURCE_URL
7696 The URL (web address) of the location from which the project was
7697 retrieved. This is used to fill in the Source: field in the
7698 controlling information for Ipkg and RPM packages.
7699 SOURCES
7702 A reserved variable name that may not be set or used in a con‐
7703 struction environment. (See "Variable Substitution," below.)
7704 SPAWN A command interpreter function that will be called to execute
7707 command line strings. The function must expect the following
7708 arguments:
7709 def spawn(shell, escape, cmd, args, env):
7711 sh is a string naming the shell program to use. escape is a
7713 function that can be called to escape shell special characters
7714 in the command line. cmd is the path to the command to be exe‐
7715 cuted. args is the arguments to the command. env is a dictio‐
7716 nary of the environment variables in which the command should be
7717 executed.
7718 SUBST_DICT
7721 The dictionary used by the Substfile() or Textfile() builders
7722 for substitution values. It can be anything acceptable to the
7723 dict() constructor, so in addition to a dictionary, lists of
7724 tuples are also acceptable.
7725 SUBSTFILEPREFIX
7728 The prefix used for Substfile() file names, the null string by
7729 default.
7730 SUBSTFILESUFFIX
7733 The suffix used for Substfile() file names, the null string by
7734 default.
7735 SUMMARY
7738 A short summary of what the project is about. This is used to
7739 fill in the Summary: field in the controlling information for
7740 Ipkg and RPM packages, and as the Description: field in MSI
7741 packages.
7742 SWIG The scripting language wrapper and interface generator.
7745 SWIGCFILESUFFIX
7748 The suffix that will be used for intermediate C source files
7749 generated by the scripting language wrapper and interface gener‐
7750 ator. The default value is _wrap$CFILESUFFIX. By default, this
7751 value is used whenever the -c++ option is not specified as part
7752 of the $SWIGFLAGS construction variable.
7753 SWIGCOM
7756 The command line used to call the scripting language wrapper and
7757 interface generator.
7758 SWIGCOMSTR
7761 The string displayed when calling the scripting language wrapper
7762 and interface generator. If this is not set, then $SWIGCOM (the
7763 command line) is displayed.
7764 SWIGCXXFILESUFFIX
7767 The suffix that will be used for intermediate C++ source files
7768 generated by the scripting language wrapper and interface gener‐
7769 ator. The default value is _wrap$CFILESUFFIX. By default, this
7770 value is used whenever the -c++ option is specified as part of
7771 the $SWIGFLAGS construction variable.
7772 SWIGDIRECTORSUFFIX
7775 The suffix that will be used for intermediate C++ header files
7776 generated by the scripting language wrapper and interface gener‐
7777 ator. These are only generated for C++ code when the SWIG
7778 'directors' feature is turned on. The default value is _wrap.h.
7779 SWIGFLAGS
7782 General options passed to the scripting language wrapper and
7783 interface generator. This is where you should set -python,
7784 -perl5, -tcl, or whatever other options you want to specify to
7785 SWIG. If you set the -c++ option in this variable, scons will,
7786 by default, generate a C++ intermediate source file with the
7787 extension that is specified as the $CXXFILESUFFIX variable.
7788 _SWIGINCFLAGS
7791 An automatically-generated construction variable containing the
7792 SWIG command-line options for specifying directories to be
7793 searched for included files. The value of $_SWIGINCFLAGS is
7794 created by appending $SWIGINCPREFIX and $SWIGINCSUFFIX to the
7795 beginning and end of each directory in $SWIGPATH.
7796 SWIGINCPREFIX
7799 The prefix used to specify an include directory on the SWIG com‐
7800 mand line. This will be appended to the beginning of each
7801 directory in the $SWIGPATH construction variable when the
7802 $_SWIGINCFLAGS variable is automatically generated.
7803 SWIGINCSUFFIX
7806 The suffix used to specify an include directory on the SWIG com‐
7807 mand line. This will be appended to the end of each directory
7808 in the $SWIGPATH construction variable when the $_SWIGINCFLAGS
7809 variable is automatically generated.
7810 SWIGOUTDIR
7813 Specifies the output directory in which the scripting language
7814 wrapper and interface generator should place generated language-
7815 specific files. This will be used by SCons to identify the
7816 files that will be generated by the &swig; call, and translated
7817 into the swig -outdir option on the command line.
7818 SWIGPATH
7821 The list of directories that the scripting language wrapper and
7822 interface generate will search for included files. The SWIG
7823 implicit dependency scanner will search these directories for
7824 include files. The default is to use the same path specified as
7825 $CPPPATH.
7826 Don't explicitly put include directory arguments in SWIGFLAGS;
7828 the result will be non-portable and the directories will not be
7829 searched by the dependency scanner. Note: directory names in
7830 SWIGPATH will be looked-up relative to the SConscript directory
7831 when they are used in a command. To force scons to look-up a
7832 directory relative to the root of the source tree use #:
7833 env = Environment(SWIGPATH='#/include')
7835 The directory look-up can also be forced using the Dir() func‐
7837 tion:
7838 include = Dir('include')
7840 env = Environment(SWIGPATH=include)
7841 The directory list will be added to command lines through the
7843 automatically-generated $_SWIGINCFLAGS construction variable,
7844 which is constructed by appending the values of the $SWIGINCPRE‐
7845 FIX and $SWIGINCSUFFIX construction variables to the beginning
7846 and end of each directory in $SWIGPATH. Any command lines you
7847 define that need the SWIGPATH directory list should include
7848 $_SWIGINCFLAGS:
7849 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")
7851 SWIGVERSION
7854 The version number of the SWIG tool.
7855 TAR The tar archiver.
7858 TARCOM The command line used to call the tar archiver.
7861 TARCOMSTR
7864 The string displayed when archiving files using the tar
7865 archiver. If this is not set, then $TARCOM (the command line)
7866 is displayed.
7867 env = Environment(TARCOMSTR = "Archiving $TARGET")
7869 TARFLAGS
7872 General options passed to the tar archiver.
7873 TARGET A reserved variable name that may not be set or used in a con‐
7876 struction environment. (See "Variable Substitution," below.)
7877 TARGET_ARCH
7880 Sets the target architecture for Visual Studio compiler (i.e.
7881 the arch of the binaries generated by the compiler). If not set,
7882 default to $HOST_ARCH, or, if that is unset, to the architecture
7883 of the running machine's OS (note that the python build or
7884 architecture has no effect). This variable must be passed as an
7885 argument to the Environment() constructor; setting it later has
7886 no effect. This is currently only used on Windows, but in the
7887 future it will be used on other OSes as well.
7888 Valid values for Windows are x86, i386 (for 32 bits); amd64,
7890 emt64, x86_64 (for 64 bits); and ia64 (Itanium). For example,
7891 if you want to compile 64-bit binaries, you would set TAR‐
7892 GET_ARCH='x86_64' in your SCons environment.
7893 TARGET_OS
7896 The name of the target operating system for the compiled
7897 objects
7898 created by this Environment.
7899 This defaults to the value of HOST_OS, and the user can
7900 override it.
7901 Currently only set for Win32.
7902 TARGETS
7905 A reserved variable name that may not be set or used in a con‐
7906 struction environment. (See "Variable Substitution," below.)
7907 TARSUFFIX
7910 The suffix used for tar file names.
7911 TEMPFILEPREFIX
7914 The prefix for a temporary file used to execute lines longer
7915 than $MAXLINELENGTH. The default is '@'. This may be set for
7916 toolchains that use other values, such as '-@' for the diab com‐
7917 piler or '-via' for ARM toolchain.
7918 TEX The TeX formatter and typesetter.
7921 TEXCOM The command line used to call the TeX formatter and typesetter.
7924 TEXCOMSTR
7927 The string displayed when calling the TeX formatter and typeset‐
7928 ter. If this is not set, then $TEXCOM (the command line) is
7929 displayed.
7930 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7932 TEXFLAGS
7935 General options passed to the TeX formatter and typesetter.
7936 TEXINPUTS
7939 List of directories that the LaTeX program will search for
7940 include directories. The LaTeX implicit dependency scanner will
7941 search these directories for \include and \import files.
7942 TEXTFILEPREFIX
7945 The prefix used for Textfile() file names, the null string by
7946 default.
7947 TEXTFILESUFFIX
7950 The suffix used for Textfile() file names; .txt by default.
7951 TOOLS A list of the names of the Tool specifications that are part of
7954 this construction environment.
7955 UNCHANGED_SOURCES
7958 A reserved variable name that may not be set or used in a con‐
7959 struction environment. (See "Variable Substitution," below.)
7960 UNCHANGED_TARGETS
7963 A reserved variable name that may not be set or used in a con‐
7964 struction environment. (See "Variable Substitution," below.)
7965 VENDOR The person or organization who supply the packaged software.
7968 This is used to fill in the Vendor: field in the controlling
7969 information for RPM packages, and the Manufacturer: field in the
7970 controlling information for MSI packages.
7971 VERSION
7974 The version of the project, specified as a string.
7975 WIN32_INSERT_DEF
7978 A deprecated synonym for $WINDOWS_INSERT_DEF.
7979 WIN32DEFPREFIX
7982 A deprecated synonym for $WINDOWSDEFPREFIX.
7983 WIN32DEFSUFFIX
7986 A deprecated synonym for $WINDOWSDEFSUFFIX.
7987 WIN32EXPPREFIX
7990 A deprecated synonym for $WINDOWSEXPSUFFIX.
7991 WIN32EXPSUFFIX
7994 A deprecated synonym for $WINDOWSEXPSUFFIX.
7995 WINDOWS_INSERT_DEF
7998 When this is set to true, a library build of a Windows shared
7999 library (.dllfile) will also build a corresponding .def file at
8000 the same time, if a .def file is not already listed as a build
8001 target. The default is 0 (do not build a .def file).
8002 WINDOWS_INSERT_MANIFEST
8005 When this is set to true, scons will be aware of the .manifest
8006 files generated by Microsoft Visua C/C++ 8.
8007 WINDOWSDEFPREFIX
8010 The prefix used for Windows .deffile names.
8011 WINDOWSDEFSUFFIX
8014 The suffix used for Windows .def file names.
8015 WINDOWSEXPPREFIX
8018 The prefix used for Windows .exp file names.
8019 WINDOWSEXPSUFFIX
8022 The suffix used for Windows .exp file names.
8023 WINDOWSPROGMANIFESTPREFIX
8026 The prefix used for executable program .manifest files generated
8027 by Microsoft Visual C/C++.
8028 WINDOWSPROGMANIFESTSUFFIX
8031 The suffix used for executable program .manifest files generated
8032 by Microsoft Visual C/C++.
8033 WINDOWSSHLIBMANIFESTPREFIX
8036 The prefix used for shared library .manifest files generated by
8037 Microsoft Visual C/C++.
8038 WINDOWSSHLIBMANIFESTSUFFIX
8041 The suffix used for shared library .manifest files generated by
8042 Microsoft Visual C/C++.
8043 X_IPK_DEPENDS
8046 This is used to fill in the Depends: field in the controlling
8047 information for Ipkg packages.
8048 X_IPK_DESCRIPTION
8051 This is used to fill in the Description: field in the control‐
8052 ling information for Ipkg packages. The default value is $SUM‐
8053 MARY\$SUMMARY
8054 X_IPK_MAINTAINER
8056 This is used to fill in the Maintainer: field in the controlling
8057 information for Ipkg packages.
8058 X_IPK_PRIORITY
8061 This is used to fill in the Priority: field in the controlling
8062 information for Ipkg packages.
8063 X_IPK_SECTION
8066 This is used to fill in the Section: field in the controlling
8067 information for Ipkg packages.
8068 X_MSI_LANGUAGE
8071 This is used to fill in the Language: attribute in the control‐
8072 ling information for MSI packages.
8073 X_MSI_LICENSE_TEXT
8076 The text of the software license in RTF format. Carriage return
8077 characters will be replaced with the RTF equivalent \ar.
8078 X_MSI_UPGRADE_CODE
8081 TODO
8082 X_RPM_AUTOREQPROV
8085 This is used to fill in the AutoReqProv: field in the RPM .spec
8086 file.
8087 X_RPM_BUILD
8090 internal, but overridable
8091 X_RPM_BUILDREQUIRES
8094 This is used to fill in the BuildRequires: field in the RPM
8095 .spec file.
8096 X_RPM_BUILDROOT
8099 internal, but overridable
8100 X_RPM_CLEAN
8103 internal, but overridable
8104 X_RPM_CONFLICTS
8107 This is used to fill in the Conflicts: field in the RPM .spec
8108 file.
8109 X_RPM_DEFATTR
8112 This value is used as the default attributes for the files in
8113 the RPM package. The default value is (-,root,root).
8114 X_RPM_DISTRIBUTION
8117 This is used to fill in the Distribution: field in the RPM .spec
8118 file.
8119 X_RPM_EPOCH
8122 This is used to fill in the Epoch: field in the controlling
8123 information for RPM packages.
8124 X_RPM_EXCLUDEARCH
8127 This is used to fill in the ExcludeArch: field in the RPM .spec
8128 file.
8129 X_RPM_EXLUSIVEARCH
8132 This is used to fill in the ExclusiveArch: field in the RPM
8133 .spec file.
8134 X_RPM_GROUP
8137 This is used to fill in the Group: field in the RPM .spec file.
8138 X_RPM_GROUP_lang
8141 This is used to fill in the Group(lang): field in the RPM .spec
8142 file. Note that lang is not literal and should be replaced by
8143 the appropriate language code.
8144 X_RPM_ICON
8147 This is used to fill in the Icon: field in the RPM .spec file.
8148 X_RPM_INSTALL
8151 internal, but overridable
8152 X_RPM_PACKAGER
8155 This is used to fill in the Packager: field in the RPM .spec
8156 file.
8157 X_RPM_POSTINSTALL
8160 This is used to fill in the %post: section in the RPM .spec
8161 file.
8162 X_RPM_POSTUNINSTALL
8165 This is used to fill in the %postun: section in the RPM .spec
8166 file.
8167 X_RPM_PREFIX
8170 This is used to fill in the Prefix: field in the RPM .spec file.
8171 X_RPM_PREINSTALL
8174 This is used to fill in the %pre: section in the RPM .spec file.
8175 X_RPM_PREP
8178 internal, but overridable
8179 X_RPM_PREUNINSTALL
8182 This is used to fill in the %preun: section in the RPM .spec
8183 file.
8184 X_RPM_PROVIDES
8187 This is used to fill in the Provides: field in the RPM .spec
8188 file.
8189 X_RPM_REQUIRES
8192 This is used to fill in the Requires: field in the RPM .spec
8193 file.
8194 X_RPM_SERIAL
8197 This is used to fill in the Serial: field in the RPM .spec file.
8198 X_RPM_URL
8201 This is used to fill in the Url: field in the RPM .spec file.
8202 YACC The parser generator.
8205 YACCCOM
8208 The command line used to call the parser generator to generate a
8209 source file.
8210 YACCCOMSTR
8213 The string displayed when generating a source file using the
8214 parser generator. If this is not set, then $YACCCOM (the com‐
8215 mand line) is displayed.
8216 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
8218 YACCFLAGS
8221 General options passed to the parser generator. If $YACCFLAGS
8222 contains a -d option, SCons assumes that the call will also cre‐
8223 ate a .h file (if the yacc source file ends in a .y suffix) or a
8224 .hpp file (if the yacc source file ends in a .yy suffix)
8225 YACCHFILESUFFIX
8228 The suffix of the C header file generated by the parser genera‐
8229 tor when the -d option is used. Note that setting this variable
8230 does not cause the parser generator to generate a header file
8231 with the specified suffix, it exists to allow you to specify
8232 what suffix the parser generator will use of its own accord.
8233 The default value is .h.
8234 YACCHXXFILESUFFIX
8237 The suffix of the C++ header file generated by the parser gener‐
8238 ator when the -d option is used. Note that setting this vari‐
8239 able does not cause the parser generator to generate a header
8240 file with the specified suffix, it exists to allow you to spec‐
8241 ify what suffix the parser generator will use of its own accord.
8242 The default value is .hpp, except on Mac OS X, where the default
8243 is ${TARGET.suffix}.h. because the default &bison; parser gen‐
8244 erator just appends .h to the name of the generated C++ file.
8245 YACCVCGFILESUFFIX
8248 The suffix of the file containing the VCG grammar automaton def‐
8249 inition when the --graph= option is used. Note that setting
8250 this variable does not cause the parser generator to generate a
8251 VCG file with the specified suffix, it exists to allow you to
8252 specify what suffix the parser generator will use of its own
8253 accord. The default value is .vcg.
8254 ZIP The zip compression and file packaging utility.
8257 ZIPCOM The command line used to call the zip utility, or the internal
8260 Python function used to create a zip archive.
8261 ZIPCOMPRESSION
8264 The compression flag from the Python zipfile module used by the
8265 internal Python function to control whether the zip archive is
8266 compressed or not. The default value is zipfile.ZIP_DEFLATED,
8267 which creates a compressed zip archive. This value has no
8268 effect if the zipfile module is unavailable.
8269 ZIPCOMSTR
8272 The string displayed when archiving files using the zip utility.
8273 If this is not set, then $ZIPCOM (the command line or internal
8274 Python function) is displayed.
8275 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
8277 ZIPFLAGS
8280 General options passed to the zip utility.
8281 ZIPSUFFIX
8284 The suffix used for zip file names.
8285 Construction variables can be retrieved and set using the Dictionary
8288 method of the construction environment:
8289 dict = env.Dictionary()
8291 dict["CC"] = "cc"
8292 or using the [] operator:
8294 env["CC"] = "cc"
8296 Construction variables can also be passed to the construction environ‐
8298 ment constructor:
8299 env = Environment(CC="cc")
8301 or when copying a construction environment using the Clone method:
8303 env2 = env.Clone(CC="cl.exe")
8305 Configure Contexts
8308 scons supports configure contexts, an integrated mechanism similar to
8309 the various AC_CHECK macros in GNU autoconf for testing for the exis‐
8310 tence of C header files, libraries, etc. In contrast to autoconf,
8311 scons does not maintain an explicit cache of the tested values, but
8312 uses its normal dependency tracking to keep the checked values up to
8313 date. However, users may override this behaviour with the --config com‐
8314 mand line option.
8315 The following methods can be used to perform checks:
8317 Configure(env, [custom_tests, conf_dir, log_file, config_h, clean,
8320 help])
8321 env.Configure([custom_tests, conf_dir, log_file, config_h, clean,
8323 help])
8324 This creates a configure context, which can be used to perform
8325 checks. env specifies the environment for building the tests.
8326 This environment may be modified when performing checks. cus‐
8327 tom_tests is a dictionary containing custom tests. See also the
8328 section about custom tests below. By default, no custom tests
8329 are added to the configure context. conf_dir specifies a direc‐
8330 tory where the test cases are built. Note that this directory
8331 is not used for building normal targets. The default value is
8332 the directory #/.sconf_temp. log_file specifies a file which
8333 collects the output from commands that are executed to check for
8334 the existence of header files, libraries, etc. The default is
8335 the file #/config.log. If you are using the VariantDir()
8336 method, you may want to specify a subdirectory under your vari‐
8337 ant directory. config_h specifies a C header file where the
8338 results of tests will be written, e.g. #define HAVE_STDIO_H,
8339 #define HAVE_LIBM, etc. The default is to not write a config.h
8340 file. You can specify the same config.h file in multiple calls
8341 to Configure, in which case scons will concatenate all results
8342 in the specified file. Note that SCons uses its normal depen‐
8343 dency checking to decide if it's necessary to rebuild the speci‐
8344 fied config_h file. This means that the file is not necessarily
8345 re-built each time scons is run, but is only rebuilt if its con‐
8346 tents will have changed and some target that depends on the con‐
8347 fig_h file is being built.
8348 The optional clean and help arguments can be used to suppress
8350 execution of the configuration tests when the -c/--clean or
8351 -H/-h/--help options are used, respectively. The default behav‐
8352 ior is always to execute configure context tests, since the
8353 results of the tests may affect the list of targets to be
8354 cleaned or the help text. If the configure tests do not affect
8355 these, then you may add the clean=False or help=False arguments
8356 (or both) to avoid unnecessary test execution.
8357 A created Configure instance has the following associated methods:
8359 SConf.Finish(context)
8362 sconf.Finish()
8364 This method should be called after configuration is done. It
8365 returns the environment as modified by the configuration checks
8366 performed. After this method is called, no further checks can
8367 be performed with this configuration context. However, you can
8368 create a new Configure context to perform additional checks.
8369 Only one context should be active at a time.
8370 The following Checks are predefined. (This list will likely
8372 grow larger as time goes by and developers contribute new useful
8373 tests.)
8374 SConf.CheckHeader(context, header, [include_quotes, language])
8377 sconf.CheckHeader(header, [include_quotes, language])
8379 Checks if header is usable in the specified language. header
8380 may be a list, in which case the last item in the list is the
8381 header file to be checked, and the previous list items are
8382 header files whose #include lines should precede the header line
8383 being checked for. The optional argument include_quotes must be
8384 a two character string, where the first character denotes the
8385 opening quote and the second character denotes the closing
8386 quote. By default, both characters are " (double quote). The
8387 optional argument language should be either C or C++ and selects
8388 the compiler to be used for the check. Returns 1 on success and
8389 0 on failure.
8390 SConf.CheckCHeader(context, header, [include_quotes])
8393 sconf.CheckCHeader(header, [include_quotes])
8395 This is a wrapper around SConf.CheckHeader which checks if
8396 header is usable in the C language. header may be a list, in
8397 which case the last item in the list is the header file to be
8398 checked, and the previous list items are header files whose
8399 #include lines should precede the header line being checked for.
8400 The optional argument include_quotes must be a two character
8401 string, where the first character denotes the opening quote and
8402 the second character denotes the closing quote (both default to
8403 "). Returns 1 on success and 0 on failure.
8404 SConf.CheckCXXHeader(context, header, [include_quotes])
8407 sconf.CheckCXXHeader(header, [include_quotes])
8409 This is a wrapper around SConf.CheckHeader which checks if
8410 header is usable in the C++ language. header may be a list, in
8411 which case the last item in the list is the header file to be
8412 checked, and the previous list items are header files whose
8413 #include lines should precede the header line being checked for.
8414 The optional argument include_quotes must be a two character
8415 string, where the first character denotes the opening quote and
8416 the second character denotes the closing quote (both default to
8417 "). Returns 1 on success and 0 on failure.
8418 SConf.CheckFunc(context,, function_name, [header, language])
8421 sconf.CheckFunc(function_name, [header, language])
8423 Checks if the specified C or C++ function is available. func‐
8424 tion_name is the name of the function to check for. The
8425 optional header argument is a string that will be placed at the
8426 top of the test file that will be compiled to check if the func‐
8427 tion exists; the default is:
8428 #ifdef __cplusplus
8429 extern "C"
8430 #endif
8431 char function_name();
8432 The optional language argument should be C or C++ and selects the com‐
8433 piler to be used for the check; the default is "C".
8434 SConf.CheckLib(context, [library, symbol, header, language, autoadd=1])
8437 sconf.CheckLib([library, symbol, header, language, autoadd=1])
8439 Checks if library provides symbol. If the value of autoadd is 1
8440 and the library provides the specified symbol, appends the
8441 library to the LIBS construction environment variable. library
8442 may also be None (the default), in which case symbol is checked
8443 with the current LIBS variable, or a list of library names, in
8444 which case each library in the list will be checked for symbol.
8445 If symbol is not set or is None, then SConf.CheckLib() just
8446 checks if you can link against the specified library. The
8447 optional language argument should be C or C++ and selects the
8448 compiler to be used for the check; the default is "C". The
8449 default value for autoadd is 1. This method returns 1 on suc‐
8450 cess and 0 on error.
8451 SConf.CheckLibWithHeader(context, library, header, language, [call,
8454 autoadd])
8455 sconf.CheckLibWithHeader(library, header, language, [call, autoadd])
8457 In contrast to the SConf.CheckLib call, this call provides a
8459 more sophisticated way to check against libraries. Again,
8460 library specifies the library or a list of libraries to check.
8461 header specifies a header to check for. header may be a list,
8462 in which case the last item in the list is the header file to be
8463 checked, and the previous list items are header files whose
8464 #include lines should precede the header line being checked for.
8465 language may be one of 'C','c','CXX','cxx','C++' and 'c++'.
8466 call can be any valid expression (with a trailing ';'). If call
8467 is not set, the default simply checks that you can link against
8468 the specified library. autoadd specifies whether to add the
8469 library to the environment (only if the check succeeds). This
8470 method returns 1 on success and 0 on error.
8471 SConf.CheckType(context, type_name, [includes, language])
8474 sconf.CheckType(type_name, [includes, language])
8476 Checks for the existence of a type defined by typedef.
8477 type_name specifies the typedef name to check for. includes is
8478 a string containing one or more #include lines that will be
8479 inserted into the program that will be run to test for the exis‐
8480 tence of the type. The optional language argument should be C
8481 or C++ and selects the compiler to be used for the check; the
8482 default is "C". Example:
8483 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
8484 Configure.CheckCC(self)
8487 Checks whether the C compiler (as defined by the CC construction
8488 variable) works by trying to compile a small source file.
8489 By default, SCons only detects if there is a program with the
8491 correct name, not if it is a functioning compiler.
8492 This uses the exact same command than the one used by the object
8494 builder for C source file, so it can be used to detect if a par‐
8495 ticular compiler flag works or not.
8496 Configure.CheckCXX(self)
8499 Checks whether the C++ compiler (as defined by the CXX construc‐
8500 tion variable) works by trying to compile a small source file.
8501 By default, SCons only detects if there is a program with the
8502 correct name, not if it is a functioning compiler.
8503 This uses the exact same command than the one used by the object
8505 builder for CXX source files, so it can be used to detect if a
8506 particular compiler flag works or not.
8507 Configure.CheckSHCC(self)
8510 Checks whether the C compiler (as defined by the SHCC construc‐
8511 tion variable) works by trying to compile a small source file.
8512 By default, SCons only detects if there is a program with the
8513 correct name, not if it is a functioning compiler.
8514 This uses the exact same command than the one used by the object
8516 builder for C source file, so it can be used to detect if a par‐
8517 ticular compiler flag works or not. This does not check whether
8518 the object code can be used to build a shared library, only that
8519 the compilation (not link) succeeds.
8520 Configure.CheckSHCXX(self)
8523 Checks whether the C++ compiler (as defined by the SHCXX con‐
8524 struction variable) works by trying to compile a small source
8525 file. By default, SCons only detects if there is a program with
8526 the correct name, not if it is a functioning compiler.
8527 This uses the exact same command than the one used by the object
8529 builder for CXX source files, so it can be used to detect if a
8530 particular compiler flag works or not. This does not check
8531 whether the object code can be used to build a shared library,
8532 only that the compilation (not link) succeeds.
8533 Example of a typical Configure usage:
8535 env = Environment()
8537 conf = Configure( env )
8538 if not conf.CheckCHeader( 'math.h' ):
8539 print 'We really need math.h!'
8540 Exit(1)
8541 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
8542 'QApplication qapp(0,0);' ):
8543 # do stuff for qt - usage, e.g.
8544 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
8545 env = conf.Finish()
8546 SConf.CheckTypeSize(context, type_name, [header, language, expect])
8549 sconf.CheckTypeSize(type_name, [header, language, expect])
8551 Checks for the size of a type defined by typedef. type_name
8552 specifies the typedef name to check for. The optional header
8553 argument is a string that will be placed at the top of the test
8554 file that will be compiled to check if the function exists; the
8555 default is empty. The optional language argument should be C or
8556 C++ and selects the compiler to be used for the check; the
8557 default is "C". The optional expect argument should be an inte‐
8558 ger. If this argument is used, the function will only check
8559 whether the type given in type_name has the expected size (in
8560 bytes). For example, CheckTypeSize('short', expect = 2) will
8561 return success only if short is two bytes.
8562 SConf.CheckDeclaration(context, symbol, [includes, language])
8566 sconf.CheckDeclaration(symbol, [includes, language])
8568 Checks if the specified symbol is declared. includes is a
8569 string containing one or more #include lines that will be
8570 inserted into the program that will be run to test for the exis‐
8571 tence of the type. The optional language argument should be C
8572 or C++ and selects the compiler to be used for the check; the
8573 default is "C".
8574 SConf.Define(context, symbol, [value, comment])
8577 sconf.Define(symbol, [value, comment])
8579 This function does not check for anything, but defines a pre‐
8580 processor symbol that will be added to the configuration header
8581 file. It is the equivalent of AC_DEFINE, and defines the symbol
8582 name with the optional value and the optional comment comment.
8583 Examples:
8586 env = Environment()
8588 conf = Configure( env )
8589 # Puts the following line in the config header file:
8591 # #define A_SYMBOL
8592 conf.Define('A_SYMBOL')
8593 # Puts the following line in the config header file:
8595 # #define A_SYMBOL 1
8596 conf.Define('A_SYMBOL', 1)
8597 Be careful about quoting string values, though:
8600 env = Environment()
8602 conf = Configure( env )
8603 # Puts the following line in the config header file:
8605 # #define A_SYMBOL YA
8606 conf.Define('A_SYMBOL', "YA")
8607 # Puts the following line in the config header file:
8609 # #define A_SYMBOL "YA"
8610 conf.Define('A_SYMBOL', '"YA"')
8611 For comment:
8614 env = Environment()
8616 conf = Configure( env )
8617 # Puts the following lines in the config header file:
8619 # /* Set to 1 if you have a symbol */
8620 # #define A_SYMBOL 1
8621 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
8622 You can define your own custom checks. in addition to the predefined
8624 checks. These are passed in a dictionary to the Configure function.
8625 This dictionary maps the names of the checks to user defined Python
8626 callables (either Python functions or class instances implementing the
8627 __call__ method). The first argument of the call is always a CheckCon‐
8628 text instance followed by the arguments, which must be supplied by the
8629 user of the check. These CheckContext instances define the following
8630 methods:
8631 CheckContext.Message(self, text)
8634 Usually called before the check is started. text will be dis‐
8636 played to the user, e.g. 'Checking for library X...'
8637 CheckContext.Result(self,, res)
8640 Usually called after the check is done. res can be either an
8642 integer or a string. In the former case, 'yes' (res != 0) or
8643 'no' (res == 0) is displayed to the user, in the latter case the
8644 given string is displayed.
8645 CheckContext.TryCompile(self, text, extension)
8648 Checks if a file with the specified extension (e.g. '.c') con‐
8649 taining text can be compiled using the environment's Object
8650 builder. Returns 1 on success and 0 on failure.
8651 CheckContext.TryLink(self, text, extension)
8654 Checks, if a file with the specified extension (e.g. '.c') con‐
8655 taining text can be compiled using the environment's Program
8656 builder. Returns 1 on success and 0 on failure.
8657 CheckContext.TryRun(self, text, extension)
8660 Checks, if a file with the specified extension (e.g. '.c') con‐
8661 taining text can be compiled using the environment's Program
8662 builder. On success, the program is run. If the program executes
8663 successfully (that is, its return status is 0), a tuple (1, out‐
8664 putStr) is returned, where outputStr is the standard output of
8665 the program. If the program fails execution (its return status
8666 is non-zero), then (0, '') is returned.
8667 CheckContext.TryAction(self, action, [text, extension])
8670 Checks if the specified action with an optional source file
8671 (contents text , extension extension = '' ) can be executed.
8672 action may be anything which can be converted to a scons Action.
8673 On success, (1, outputStr) is returned, where outputStr is the
8674 content of the target file. On failure (0, '') is returned.
8675 CheckContext.TryBuild(self, builder, [text, extension])
8678 Low level implementation for testing specific builds; the meth‐
8679 ods above are based on this method. Given the Builder instance
8680 builder and the optional text of a source file with optional
8681 extension, this method returns 1 on success and 0 on failure. In
8682 addition, self.lastTarget is set to the build target node, if
8683 the build was successful.
8684 Example for implementing and using custom tests:
8686 def CheckQt(context, qtdir):
8688 context.Message( 'Checking for qt ...' )
8689 lastLIBS = context.env['LIBS']
8690 lastLIBPATH = context.env['LIBPATH']
8691 lastCPPPATH= context.env['CPPPATH']
8692 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
8693 ret = context.TryLink("""
8694 #include <qapp.h>
8695 int main(int argc, char **argv) {
8696 QApplication qapp(argc, argv);
8697 return 0;
8698 }
8699 """)
8700 if not ret:
8701 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
8702 context.Result( ret )
8703 return ret
8704 env = Environment()
8706 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
8707 if not conf.CheckQt('/usr/lib/qt'):
8708 print 'We really need qt!'
8709 Exit(1)
8710 env = conf.Finish()
8711 Command-Line Construction Variables
8714 Often when building software, some variables must be specified at build
8715 time. For example, libraries needed for the build may be in non-stan‐
8716 dard locations, or site-specific compiler options may need to be passed
8717 to the compiler. scons provides a Variables object to support overrid‐
8718 ing construction variables on the command line:
8719 $ scons VARIABLE=foo
8720 The variable values can also be specified in a text-based SConscript
8721 file. To create a Variables object, call the Variables() function:
8722 Variables([files], [args])
8725 This creates a Variables object that will read construction
8726 variables from the file or list of filenames specified in files.
8727 If no files are specified, or the files argument is None, then
8728 no files will be read. The optional argument args is a dictio‐
8729 nary of values that will override anything read from the speci‐
8730 fied files; it is primarily intended to be passed the ARGUMENTS
8731 dictionary that holds variables specified on the command line.
8732 Example:
8733 vars = Variables('custom.py')
8735 vars = Variables('overrides.py', ARGUMENTS)
8736 vars = Variables(None, {FOO:'expansion', BAR:7})
8737 Variables objects have the following methods:
8739 Add(key, [help, default, validator, converter])
8742 This adds a customizable construction variable to the Variables
8743 object. key is the name of the variable. help is the help text
8744 for the variable. default is the default value of the variable;
8745 if the default value is None and there is no explicit value
8746 specified, the construction variable will not be added to the
8747 construction environment. validator is called to validate the
8748 value of the variable, and should take three arguments: key,
8749 value, and environment. The recommended way to handle an
8750 invalid value is to raise an exception (see example below).
8751 converter is called to convert the value before putting it in
8752 the environment, and should take either a value, or the value
8753 and environment, as parameters. The converter must return a
8754 value, which will be converted into a string before being vali‐
8755 dated by the validator (if any) and then added to the environ‐
8756 ment.
8757 Examples:
8759 vars.Add('CC', 'The C compiler')
8761 def validate_color(key, val, env):
8763 if not val in ['red', 'blue', 'yellow']:
8764 raise Exception("Invalid color value '%s'" % val)
8765 vars.Add('COLOR', validator=valid_color)
8766 AddVariables(list)
8769 A wrapper script that adds multiple customizable construction
8770 variables to a Variables object. list is a list of tuple or
8771 list objects that contain the arguments for an individual call
8772 to the Add method.
8773 opt.AddVariables(
8775 ('debug', '', 0),
8776 ('CC', 'The C compiler'),
8777 ('VALIDATE', 'An option for testing validation',
8778 'notset', validator, None),
8779 )
8780 Update(env, [args])
8783 This updates a construction environment env with the customized
8784 construction variables. Any specified variables that are not
8785 configured for the Variables object will be saved and may be
8786 retrieved with the UnknownVariables() method, below.
8787 Normally this method is not called directly, but is called indi‐
8789 rectly by passing the Variables object to the Environment()
8790 function:
8791 env = Environment(variables=vars)
8793 The text file(s) that were specified when the Variables object
8796 was created are executed as Python scripts, and the values of
8797 (global) Python variables set in the file are added to the con‐
8798 struction environment.
8799 Example:
8801 CC = 'my_cc'
8803 UnknownVariables()
8806 Returns a dictionary containing any variables that were speci‐
8807 fied either in the files or the dictionary with which the Vari‐
8808 ables object was initialized, but for which the Variables object
8809 was not configured.
8810 env = Environment(variables=vars)
8812 for key, value in vars.UnknownVariables():
8813 print "unknown variable: %s=%s" % (key, value)
8814 Save(filename, env)
8817 This saves the currently set variables into a script file named
8818 filename that can be used on the next invocation to automati‐
8819 cally load the current settings. This method combined with the
8820 Variables method can be used to support caching of variables
8821 between runs.
8822 env = Environment()
8824 vars = Variables(['variables.cache', 'custom.py'])
8825 vars.Add(...)
8826 vars.Update(env)
8827 vars.Save('variables.cache', env)
8828 GenerateHelpText(env, [sort])
8831 This generates help text documenting the customizable construc‐
8832 tion variables suitable to passing in to the Help() function.
8833 env is the construction environment that will be used to get the
8834 actual values of customizable variables. Calling with an
8835 optional sort function will cause the output to be sorted by the
8836 specified argument. The specific sort function should take two
8837 arguments and return -1, 0 or 1 (like the standard Python cmp
8838 function).
8839 Help(vars.GenerateHelpText(env))
8841 Help(vars.GenerateHelpText(env, sort=cmp))
8842 FormatVariableHelpText(env, opt, help, default, actual)
8845 This method returns a formatted string containing the printable
8846 help text for one option. It is normally not called directly,
8847 but is called by the GenerateHelpText() method to create the
8848 returned help text. It may be overridden with your own function
8849 that takes the arguments specified above and returns a string of
8850 help text formatted to your liking. Note that the GenerateHelp‐
8851 Text() will not put any blank lines or extra characters in
8852 between the entries, so you must add those characters to the
8853 returned string if you want the entries separated.
8854 def my_format(env, opt, help, default, actual):
8856 fmt = "106s: default=%s actual=%s (%s)0
8857 return fmt % (opt, default. actual, help)
8858 vars.FormatVariableHelpText = my_format
8859 To make it more convenient to work with customizable Variables, scons
8861 provides a number of functions that make it easy to set up various
8862 types of Variables:
8863 BoolVariable(key, help, default)
8866 Return a tuple of arguments to set up a Boolean option. The
8867 option will use the specified name key, have a default value of
8868 default, and display the specified help text. The option will
8869 interpret the values y, yes, t, true, 1, on and all as true, and
8870 the values n, no, f, false, 0, off and none as false.
8871 EnumVariable(key, help, default, allowed_values, [map, ignorecase])
8874 Return a tuple of arguments to set up an option whose value may
8875 be one of a specified list of legal enumerated values. The
8876 option will use the specified name key, have a default value of
8877 default, and display the specified help text. The option will
8878 only support those values in the allowed_values list. The
8879 optional map argument is a dictionary that can be used to con‐
8880 vert input values into specific legal values in the allowed_val‐
8881 ues list. If the value of ignore_case is 0 (the default), then
8882 the values are case-sensitive. If the value of ignore_case is
8883 1, then values will be matched case-insensitive. If the value
8884 of ignore_case is 1, then values will be matched case-insensi‐
8885 tive, and all input values will be converted to lower case.
8886 ListVariable(key, help, default, names, [,map])
8889 Return a tuple of arguments to set up an option whose value may
8890 be one or more of a specified list of legal enumerated values.
8891 The option will use the specified name key, have a default value
8892 of default, and display the specified help text. The option
8893 will only support the values all, none, or the values in the
8894 names list. More than one value may be specified, with all val‐
8895 ues separated by commas. The default may be a string of comma-
8896 separated default values, or a list of the default values. The
8897 optional map argument is a dictionary that can be used to con‐
8898 vert input values into specific legal values in the names list.
8899 PackageVariable(key, help, default)
8902 Return a tuple of arguments to set up an option whose value is a
8903 path name of a package that may be enabled, disabled or given an
8904 explicit path name. The option will use the specified name key,
8905 have a default value of default, and display the specified help
8906 text. The option will support the values yes, true, on, enable
8907 or search, in which case the specified default will be used, or
8908 the option may be set to an arbitrary string (typically the path
8909 name to a package that is being enabled). The option will also
8910 support the values no, false, off or disable to disable use of
8911 the specified option.
8912 PathVariable(key, help, default, [validator])
8915 Return a tuple of arguments to set up an option whose value is
8916 expected to be a path name. The option will use the specified
8917 name key, have a default value of default, and display the spec‐
8918 ified help text. An additional validator may be specified that
8919 will be called to verify that the specified path is acceptable.
8920 SCons supplies the following ready-made validators: PathVari‐
8921 able.PathExists (the default), which verifies that the specified
8922 path exists; PathVariable.PathIsFile, which verifies that the
8923 specified path is an existing file; PathVariable.PathIsDir,
8924 which verifies that the specified path is an existing directory;
8925 PathVariable.PathIsDirCreate, which verifies that the specified
8926 path is a directory and will create the specified directory if
8927 the path does not exist; and PathVariable.PathAccept, which sim‐
8928 ply accepts the specific path name argument without validation,
8929 and which is suitable if you want your users to be able to spec‐
8930 ify a directory path that will be created as part of the build
8931 process, for example. You may supply your own validator func‐
8932 tion, which must take three arguments (key, the name of the
8933 variable to be set; val, the specified value being checked; and
8934 env, the construction environment) and should raise an exception
8935 if the specified value is not acceptable.
8936 These functions make it convenient to create a number of variables with
8938 consistent behavior in a single call to the AddVariables method:
8939 vars.AddVariables(
8941 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
8942 EnumVariable('debug', 'debug output and symbols', 'no'
8943 allowed_values=('yes', 'no', 'full'),
8944 map={}, ignorecase=0), # case sensitive
8945 ListVariable('shared',
8946 'libraries to build as shared libraries',
8947 'all',
8948 names = list_of_libs),
8949 PackageVariable('x11',
8950 'use X11 installed here (yes = search some places)',
8951 'yes'),
8952 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
8953 PathVariable('foopath', 'where the foo library is installed', foopath,
8954 PathVariable.PathIsDir),
8955 )
8957 File and Directory Nodes
8960 The File() and Dir() functions return File and Dir Nodes, respectively.
8961 python objects, respectively. Those objects have several user-visible
8962 attributes and methods that are often useful:
8963 path The build path of the given file or directory. This path is
8966 relative to the top-level directory (where the SConstruct file
8967 is found). The build path is the same as the source path if
8968 variant_dir is not being used.
8969 abspath
8972 The absolute build path of the given file or directory.
8973 srcnode()
8976 The srcnode() method returns another File or Dir object repre‐
8977 senting the source path of the given File or Dir. The
8978 # Get the current build dir's path, relative to top.
8980 Dir('.').path
8981 # Current dir's absolute path
8982 Dir('.').abspath
8983 # Next line is always '.', because it is the top dir's path relative to itself.
8984 Dir('#.').path
8985 File('foo.c').srcnode().path # source path of the given source file.
8986 # Builders also return File objects:
8988 foo = env.Program('foo.c')
8989 print "foo will be built in %s"%foo.path
8990 A Dir Node or File Node can also be used to create file and subdirec‐
8992 tory Nodes relative to the generating Node. A Dir Node will place the
8993 new Nodes within the directory it represents. A File node will place
8994 the new Nodes within its parent directory (that is, "beside" the file
8995 in question). If d is a Dir (directory) Node and f is a File (file)
8996 Node, then these methods are available:
8997 d.Dir(name)
9000 Returns a directory Node for a subdirectory of d named name.
9001 d.File(name)
9004 Returns a file Node for a file within d named name.
9005 d.Entry(name)
9008 Returns an unresolved Node within d named name.
9009 f.Dir(name)
9012 Returns a directory named name within the parent directory of f.
9013 f.File(name)
9016 Returns a file named name within the parent directory of f.
9017 f.Entry(name)
9020 Returns an unresolved Node named name within the parent direc‐
9021 tory of f.
9022 For example:
9024 # Get a Node for a file within a directory
9026 incl = Dir('include')
9027 f = incl.File('header.h')
9028 # Get a Node for a subdirectory within a directory
9030 dist = Dir('project-3.2.1)
9031 src = dist.Dir('src')
9032 # Get a Node for a file in the same directory
9034 cfile = File('sample.c')
9035 hfile = cfile.File('sample.h')
9036 # Combined example
9038 docs = Dir('docs')
9039 html = docs.Dir('html')
9040 index = html.File('index.html')
9041 css = index.File('app.css')
9042
9045 Builder Objects
9046 scons can be extended to build different types of targets by adding new
9047 Builder objects to a construction environment. In general, you should
9048 only need to add a new Builder object when you want to build a new type
9049 of file or other external target. If you just want to invoke a differ‐
9050 ent compiler or other tool to build a Program, Object, Library, or any
9051 other type of output file for which scons already has an existing
9052 Builder, it is generally much easier to use those existing Builders in
9053 a construction environment that sets the appropriate construction vari‐
9054 ables (CC, LINK, etc.).
9055 Builder objects are created using the Builder function. The Builder
9057 function accepts the following arguments:
9058 action The command line string used to build the target from the
9061 source. action can also be: a list of strings representing the
9062 command to be executed and its arguments (suitable for enclosing
9063 white space in an argument), a dictionary mapping source file
9064 name suffixes to any combination of command line strings (if the
9065 builder should accept multiple source file extensions), a Python
9066 function; an Action object (see the next section); or a list of
9067 any of the above.
9068 An action function takes three arguments: source - a list of
9070 source nodes, target - a list of target nodes, env - the con‐
9071 struction environment.
9072 prefix The prefix that will be prepended to the target file name. This
9075 may be specified as a:
9076 * string,
9079 * callable object - a function or other callable that takes
9082 two arguments (a construction environment and a list of
9083 sources) and returns a prefix,
9084 * dictionary - specifies a mapping from a specific source
9087 suffix (of the first source specified) to a correspond‐
9088 ing target prefix. Both the source suffix and target
9089 prefix specifications may use environment variable sub‐
9090 stitution, and the target prefix (the 'value' entries
9091 in the dictionary) may also be a callable object. The
9092 default target prefix may be indicated by a dictionary
9093 entry with a key value of None.
9094 b = Builder("build_it < $SOURCE > $TARGET",
9096 prefix = "file-")
9097 def gen_prefix(env, sources):
9099 return "file-" + env['PLATFORM'] + '-'
9100 b = Builder("build_it < $SOURCE > $TARGET",
9101 prefix = gen_prefix)
9102 b = Builder("build_it < $SOURCE > $TARGET",
9104 suffix = { None: "file-",
9105 "$SRC_SFX_A": gen_prefix })
9106 suffix The suffix that will be appended to the target file name. This
9109 may be specified in the same manner as the prefix above. If the
9110 suffix is a string, then scons will append a '.' to the begin‐
9111 ning of the suffix if it's not already there. The string
9112 returned by callable object (or obtained from the dictionary) is
9113 untouched and must append its own '.' to the beginning if one
9114 is desired.
9115 b = Builder("build_it < $SOURCE > $TARGET"
9117 suffix = "-file")
9118 def gen_suffix(env, sources):
9120 return "." + env['PLATFORM'] + "-file"
9121 b = Builder("build_it < $SOURCE > $TARGET",
9122 suffix = gen_suffix)
9123 b = Builder("build_it < $SOURCE > $TARGET",
9125 suffix = { None: ".sfx1",
9126 "$SRC_SFX_A": gen_suffix })
9127 ensure_suffix
9130 When set to any true value, causes scons to add the target suf‐
9131 fix specified by the suffix keyword to any target strings that
9132 have a different suffix. (The default behavior is to leave
9133 untouched any target file name that looks like it already has
9134 any suffix.)
9135 b1 = Builder("build_it < $SOURCE > $TARGET"
9137 suffix = ".out")
9138 b2 = Builder("build_it < $SOURCE > $TARGET"
9139 suffix = ".out",
9140 ensure_suffix)
9141 env = Environment()
9142 env['BUILDERS']['B1'] = b1
9143 env['BUILDERS']['B2'] = b2
9144 # Builds "foo.txt" because ensure_suffix is not set.
9146 env.B1('foo.txt', 'foo.in')
9147 # Builds "bar.txt.out" because ensure_suffix is set.
9149 env.B2('bar.txt', 'bar.in')
9150 src_suffix
9153 The expected source file name suffix. This may be a string or a
9154 list of strings.
9155 target_scanner
9158 A Scanner object that will be invoked to find implicit dependen‐
9159 cies for this target file. This keyword argument should be used
9160 for Scanner objects that find implicit dependencies based only
9161 on the target file and the construction environment, not for
9162 implicit (See the section "Scanner Objects," below, for informa‐
9163 tion about creating Scanner objects.)
9164 source_scanner
9167 A Scanner object that will be invoked to find implicit depen‐
9168 dences in any source files used to build this target file. This
9169 is where you would specify a scanner to find things like
9170 #include lines in source files. The pre-built DirScanner Scan‐
9171 ner object may be used to indicate that this Builder should scan
9172 directory trees for on-disk changes to files that scons does not
9173 know about from other Builder or function calls. (See the sec‐
9174 tion "Scanner Objects," below, for information about creating
9175 your own Scanner objects.)
9176 target_factory
9179 A factory function that the Builder will use to turn any targets
9180 specified as strings into SCons Nodes. By default, SCons
9181 assumes that all targets are files. Other useful target_factory
9182 values include Dir, for when a Builder creates a directory tar‐
9183 get, and Entry, for when a Builder can create either a file or
9184 directory target.
9185 Example:
9187 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
9189 env = Environment()
9190 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
9191 env.MakeDirectory('new_directory', [])
9192 Note that the call to the MakeDirectory Builder needs to specify
9195 an empty source list to make the string represent the builder's
9196 target; without that, it would assume the argument is the
9197 source, and would try to deduce the target name from it, which
9198 in the absence of an automatically-added prefix or suffix would
9199 lead to a matching target and source name and a circular depen‐
9200 dency.
9201 source_factory
9204 A factory function that the Builder will use to turn any sources
9205 specified as strings into SCons Nodes. By default, SCons
9206 assumes that all source are files. Other useful source_factory
9207 values include Dir, for when a Builder uses a directory as a
9208 source, and Entry, for when a Builder can use files or directo‐
9209 ries (or both) as sources.
9210 Example:
9212 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
9214 env = Environment()
9215 env.Append(BUILDERS = {'Collect':CollectBuilder})
9216 env.Collect('archive', ['directory_name', 'file_name'])
9217 emitter
9220 A function or list of functions to manipulate the target and
9221 source lists before dependencies are established and the tar‐
9222 get(s) are actually built. emitter can also be a string con‐
9223 taining a construction variable to expand to an emitter function
9224 or list of functions, or a dictionary mapping source file suf‐
9225 fixes to emitter functions. (Only the suffix of the first
9226 source file is used to select the actual emitter function from
9227 an emitter dictionary.)
9228 An emitter function takes three arguments: source - a list of
9230 source nodes, target - a list of target nodes, env - the con‐
9231 struction environment. An emitter must return a tuple contain‐
9232 ing two lists, the list of targets to be built by this builder,
9233 and the list of sources for this builder.
9234 Example:
9236 def e(target, source, env):
9238 return (target + ['foo.foo'], source + ['foo.src'])
9239 # Simple association of an emitter function with a Builder.
9241 b = Builder("my_build < $TARGET > $SOURCE",
9242 emitter = e)
9243 def e2(target, source, env):
9245 return (target + ['bar.foo'], source + ['bar.src'])
9246 # Simple association of a list of emitter functions with a Builder.
9248 b = Builder("my_build < $TARGET > $SOURCE",
9249 emitter = [e, e2])
9250 # Calling an emitter function through a construction variable.
9252 env = Environment(MY_EMITTER = e)
9253 b = Builder("my_build < $TARGET > $SOURCE",
9254 emitter = '$MY_EMITTER')
9255 # Calling a list of emitter functions through a construction variable.
9257 env = Environment(EMITTER_LIST = [e, e2])
9258 b = Builder("my_build < $TARGET > $SOURCE",
9259 emitter = '$EMITTER_LIST')
9260 # Associating multiple emitters with different file
9262 # suffixes using a dictionary.
9263 def e_suf1(target, source, env):
9264 return (target + ['another_target_file'], source)
9265 def e_suf2(target, source, env):
9266 return (target, source + ['another_source_file'])
9267 b = Builder("my_build < $TARGET > $SOURCE",
9268 emitter = {'.suf1' : e_suf1,
9269 '.suf2' : e_suf2})
9270 multi Specifies whether this builder is allowed to be called multiple
9273 times for the same target file(s). The default is 0, which means
9274 the builder can not be called multiple times for the same target
9275 file(s). Calling a builder multiple times for the same target
9276 simply adds additional source files to the target; it is not
9277 allowed to change the environment associated with the target,
9278 specify addition environment overrides, or associate a different
9279 builder with the target.
9280 env A construction environment that can be used to fetch source code
9283 using this Builder. (Note that this environment is not used for
9284 normal builds of normal target files, which use the environment
9285 that was used to call the Builder for the target file.)
9286 generator
9289 A function that returns a list of actions that will be executed
9290 to build the target(s) from the source(s). The returned
9291 action(s) may be an Action object, or anything that can be con‐
9292 verted into an Action object (see the next section).
9293 The generator function takes four arguments: source - a list of
9295 source nodes, target - a list of target nodes, env - the con‐
9296 struction environment, for_signature - a Boolean value that
9297 specifies whether the generator is being called for generating a
9298 build signature (as opposed to actually executing the command).
9299 Example:
9300 def g(source, target, env, for_signature):
9302 return [["gcc", "-c", "-o"] + target + source]
9303 b = Builder(generator=g)
9305 The generator and action arguments must not both be used for the
9308 same Builder.
9309 src_builder
9312 Specifies a builder to use when a source file name suffix does
9313 not match any of the suffixes of the builder. Using this argu‐
9314 ment produces a multi-stage builder.
9315 single_source
9318 Specifies that this builder expects exactly one source file per
9319 call. Giving more than one source file without target files
9320 results in implicitely calling the builder multiple times (once
9321 for each source given). Giving multiple source files together
9322 with target files results in a UserError exception.
9323 The generator and action arguments must not both be used for the
9326 same Builder.
9327 source_ext_match
9330 When the specified action argument is a dictionary, the default
9331 behavior when a builder is passed multiple source files is to
9332 make sure that the extensions of all the source files match. If
9333 it is legal for this builder to be called with a list of source
9334 files with different extensions, this check can be suppressed by
9335 setting source_ext_match to None or some other non-true value.
9336 When source_ext_match is disable, scons will use the suffix of
9337 the first specified source file to select the appropriate action
9338 from the action dictionary.
9339 In the following example, the setting of source_ext_match pre‐
9341 vents scons from exiting with an error due to the mismatched
9342 suffixes of foo.in and foo.extra.
9343 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
9345 source_ext_match = None)
9346 env = Environment(BUILDERS = {'MyBuild':b})
9348 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
9349 env A construction environment that can be used to fetch source code
9352 using this Builder. (Note that this environment is not used for
9353 normal builds of normal target files, which use the environment
9354 that was used to call the Builder for the target file.)
9355 b = Builder(action="build < $SOURCE > $TARGET")
9357 env = Environment(BUILDERS = {'MyBuild' : b})
9358 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
9359 chdir A directory from which scons will execute the action(s) speci‐
9362 fied for this Builder. If the chdir argument is a string or a
9363 directory Node, scons will change to the specified directory.
9364 If the chdir is not a string or Node and is non-zero, then scons
9365 will change to the target file's directory.
9366 Note that scons will not automatically modify its expansion of
9368 construction variables like $TARGET and $SOURCE when using the
9369 chdir keyword argument--that is, the expanded file names will
9370 still be relative to the top-level SConstruct directory, and
9371 consequently incorrect relative to the chdir directory.
9372 Builders created using chdir keyword argument, will need to use
9373 construction variable expansions like ${TARGET.file} and
9374 ${SOURCE.file} to use just the filename portion of the targets
9375 and source.
9376 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
9378 chdir=1)
9379 env = Environment(BUILDERS = {'MyBuild' : b})
9380 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
9381 WARNING: Python only keeps one current directory location for all of
9383 the threads. This means that use of the chdir argument will not work
9384 with the SCons -j option, because individual worker threads spawned by
9385 SCons interfere with each other when they start changing directory.
9386 Any additional keyword arguments supplied when a Builder object is cre‐
9388 ated (that is, when the Builder() function is called) will be set in
9389 the executing construction environment when the Builder object is
9390 called. The canonical example here would be to set a construction
9391 variable to the repository of a source code system.
9392 Any additional keyword arguments supplied when a Builder object is
9394 called will only be associated with the target created by that particu‐
9395 lar Builder call (and any other files built as a result of the call).
9396 These extra keyword arguments are passed to the following functions:
9398 command generator functions, function Actions, and emitter functions.
9399 Action Objects
9402 The Builder() function will turn its action keyword argument into an
9403 appropriate internal Action object. You can also explicity create
9404 Action objects using the Action() global function, which can then be
9405 passed to the Builder() function. This can be used to configure an
9406 Action object more flexibly, or it may simply be more efficient than
9407 letting each separate Builder object create a separate Action when mul‐
9408 tiple Builder objects need to do the same thing.
9409 The Action() global function returns an appropriate object for the
9411 action represented by the type of the first argument:
9412 Action If the first argument is already an Action object, the object is
9415 simply returned.
9416 String If the first argument is a string, a command-line Action is
9419 returned. Note that the command-line string may be preceded by
9420 an @ (at-sign) to suppress printing of the specified command
9421 line, or by a - (hyphen) to ignore the exit status from the
9422 specified command:
9423 Action('$CC -c -o $TARGET $SOURCES')
9425 # Doesn't print the line being executed.
9427 Action('@build $TARGET $SOURCES')
9428 # Ignores return value
9430 Action('-build $TARGET $SOURCES')
9431 List If the first argument is a list, then a list of Action objects
9434 is returned. An Action object is created as necessary for each
9435 element in the list. If an element within the list is itself a
9436 list, the internal list is the command and arguments to be exe‐
9437 cuted via the command line. This allows white space to be
9438 enclosed in an argument by defining a command in a list within a
9439 list:
9440 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
9442 Function
9445 If the first argument is a Python function, a function Action is
9446 returned. The Python function must take three keyword argu‐
9447 ments, target (a Node object representing the target file),
9448 source (a Node object representing the source file) and env (the
9449 construction environment used for building the target file).
9450 The target and source arguments may be lists of Node objects if
9451 there is more than one target file or source file. The actual
9452 target and source file name(s) may be retrieved from their Node
9453 objects via the built-in Python str() function:
9454 target_file_name = str(target)
9456 source_file_names = map(lambda x: str(x), source)
9457 The function should return 0 or None to indicate a successful
9459 build of the target file(s). The function may raise an excep‐
9460 tion or return a non-zero exit status to indicate an unsuccess‐
9461 ful build.
9462 def build_it(target = None, source = None, env = None):
9464 # build the target from the source
9465 return 0
9466 a = Action(build_it)
9468 If the action argument is not one of the above, None is returned.
9470 The second argument is optional and is used to define the output which
9472 is printed when the Action is actually performed. In the absence of
9473 this parameter, or if it's an empty string, a default output depending
9474 on the type of the action is used. For example, a command-line action
9475 will print the executed command. The argument must be either a Python
9476 function or a string.
9477 In the first case, it's a function that returns a string to be printed
9479 to describe the action being executed. The function may also be speci‐
9480 fied by the strfunction= keyword argument. Like a function to build a
9481 file, this function must take three keyword arguments: target (a Node
9482 object representing the target file), source (a Node object represent‐
9483 ing the source file) and env (a construction environment). The target
9484 and source arguments may be lists of Node objects if there is more than
9485 one target file or source file.
9486 In the second case, you provide the string itself. The string may also
9488 be specified by the cmdstr= keyword argument. The string typically
9489 contains variables, notably $TARGET(S) and $SOURCE(S), or consists of
9490 just a single variable, which is optionally defined somewhere else.
9491 SCons itself heavily uses the latter variant.
9492 Examples:
9494 def build_it(target, source, env):
9496 # build the target from the source
9497 return 0
9498 def string_it(target, source, env):
9500 return "building '%s' from '%s'" % (target[0], source[0])
9501 # Use a positional argument.
9503 f = Action(build_it, string_it)
9504 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
9505 # Alternatively, use a keyword argument.
9507 f = Action(build_it, strfunction=string_it)
9508 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
9509 # You can provide a configurable variable.
9511 l = Action(build_it, '$STRINGIT')
9512 The third and succeeding arguments, if present, may either be a con‐
9514 struction variable or a list of construction variables whose values
9515 will be included in the signature of the Action when deciding whether a
9516 target should be rebuilt because the action changed. The variables may
9517 also be specified by a varlist= keyword parameter; if both are present,
9518 they are combined. This is necessary whenever you want a target to be
9519 rebuilt when a specific construction variable changes. This is not
9520 often needed for a string action, as the expanded variables will nor‐
9521 mally be part of the command line, but may be needed if a Python func‐
9522 tion action uses the value of a construction variable when generating
9523 the command line.
9524 def build_it(target, source, env):
9526 # build the target from the 'XXX' construction variable
9527 open(target[0], 'w').write(env['XXX'])
9528 return 0
9529 # Use positional arguments.
9531 a = Action(build_it, '$STRINGIT', ['XXX'])
9532 # Alternatively, use a keyword argument.
9534 a = Action(build_it, varlist=['XXX'])
9535 The Action() global function can be passed the following optional key‐
9537 word arguments to modify the Action object's behavior:
9538 chdir The chdir keyword argument specifies that scons will exe‐
9541 cute the action after changing to the specified directory. If
9542 the chdir argument is a string or a directory Node, scons will
9543 change to the specified directory. If the chdir argument is not
9544 a string or Node and is non-zero, then scons will change to the
9545 target file's directory.
9546 Note that scons will not automatically modify its expansion of
9548 construction variables like $TARGET and $SOURCE when using the
9549 chdir keyword argument--that is, the expanded file names will
9550 still be relative to the top-level SConstruct directory, and
9551 consequently incorrect relative to the chdir directory.
9552 Builders created using chdir keyword argument, will need to use
9553 construction variable expansions like ${TARGET.file} and
9554 ${SOURCE.file} to use just the filename portion of the targets
9555 and source.
9556 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9558 chdir=1)
9559 exitstatfunc The Action() global function also takes an exit‐
9562 statfunc keyword argument which specifies a function that is
9563 passed the exit status (or return value) from the specified
9564 action and can return an arbitrary or modified value. This can
9565 be used, for example, to specify that an Action object's return
9566 value should be ignored under special conditions and SCons
9567 should, therefore, consider that the action always suceeds:
9568 def always_succeed(s):
9570 # Always return 0, which indicates success.
9571 return 0
9572 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9573 exitstatfunc=always_succeed)
9574 batch_key The batch_key keyword argument can be used to specify
9577 that the Action can create multiple target files by processing
9578 multiple independent source files simultaneously. (The canoni‐
9579 cal example is "batch compilation" of multiple object files by
9580 passing multiple source files to a single invocation of a com‐
9581 piler such as Microsoft's Visual C / C++ compiler.) If the
9582 batch_key argument is any non-False, non-callable Python value,
9583 the configured Action object will cause scons to collect all
9584 targets built with the Action object and configured with the
9585 same construction environment into single invocations of the
9586 Action object's command line or function. Command lines will
9587 typically want to use the CHANGED_SOURCES construction variable
9588 (and possibly CHANGED_TARGETS as well) to only pass to the com‐
9589 mand line those sources that have actually changed since their
9590 targets were built.
9591 Example:
9593 a = Action('build $CHANGED_SOURCES', batch_key=True)
9595 The batch_key argument may also be a callable function that returns a
9597 key that will be used to identify different "batches" of target files
9598 to be collected for batch building. A batch_key function must take the
9599 following arguments:
9600 action The action object.
9603 env The construction environment configured for the target.
9606 target The list of targets for a particular configured action.
9609 source The list of source for a particular configured action.
9612 The returned key should typically be a tuple of values derived
9614 from the arguments, using any appropriate logic to decide how
9615 multiple invocations should be batched. For example, a
9616 batch_key function may decide to return the value of a specific
9617 construction variable from the env argument which will cause
9618 scons to batch-build targets with matching values of that vari‐
9619 able, or perhaps return the id() of the entire construction
9620 environment, in which case scons will batch-build all targets
9621 configured with the same construction environment. Returning
9622 None indicates that the particular target should not be part of
9623 any batched build, but instead will be built by a separate invo‐
9624 cation of action's command or function. Example:
9625 def batch_key(action, env, target, source):
9627 tdir = target[0].dir
9628 if tdir.name == 'special':
9629 # Don't batch-build any target
9630 # in the special/ subdirectory.
9631 return None
9632 return (id(action), id(env), tdir)
9633 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
9634 Miscellaneous Action Functions
9637 scons supplies a number of functions that arrange for various common
9638 file and directory manipulations to be performed. These are similar in
9639 concept to "tasks" in the Ant build tool, although the implementation
9640 is slightly different. These functions do not actually perform the
9641 specified action at the time the function is called, but instead return
9642 an Action object that can be executed at the appropriate time. (In
9643 Object-Oriented terminology, these are actually Action Factory func‐
9644 tions that return Action objects.)
9645 In practice, there are two natural ways that these Action Functions are
9647 intended to be used.
9648 First, if you need to perform the action at the time the SConscript
9650 file is being read, you can use the Execute global function to do so:
9651 Execute(Touch('file'))
9652 Second, you can use these functions to supply Actions in a list for use
9654 by the Command method. This can allow you to perform more complicated
9655 sequences of file manipulation without relying on platform-specific
9656 external commands: that
9657 env = Environment(TMPBUILD = '/tmp/builddir')
9658 env.Command('foo.out', 'foo.in',
9659 [Mkdir('$TMPBUILD'),
9660 Copy('$TMPBUILD', '${SOURCE.dir}'),
9661 "cd $TMPBUILD && make",
9662 Delete('$TMPBUILD')])
9663 Chmod(dest, mode)
9666 Returns an Action object that changes the permissions on the
9667 specified dest file or directory to the specified mode. Exam‐
9668 ples:
9669 Execute(Chmod('file', 0755))
9671 env.Command('foo.out', 'foo.in',
9673 [Copy('$TARGET', '$SOURCE'),
9674 Chmod('$TARGET', 0755)])
9675 Copy(dest, src)
9678 Returns an Action object that will copy the src source file or
9679 directory to the dest destination file or directory. Examples:
9680 Execute(Copy('foo.output', 'foo.input'))
9682 env.Command('bar.out', 'bar.in',
9684 Copy('$TARGET', '$SOURCE'))
9685 Delete(entry, [must_exist])
9688 Returns an Action that deletes the specified entry, which may be
9689 a file or a directory tree. If a directory is specified, the
9690 entire directory tree will be removed. If the must_exist flag
9691 is set, then a Python error will be thrown if the specified
9692 entry does not exist; the default is must_exist=0, that is, the
9693 Action will silently do nothing if the entry does not exist.
9694 Examples:
9695 Execute(Delete('/tmp/buildroot'))
9697 env.Command('foo.out', 'foo.in',
9699 [Delete('${TARGET.dir}'),
9700 MyBuildAction])
9701 Execute(Delete('file_that_must_exist', must_exist=1))
9703 Mkdir(dir)
9706 Returns an Action that creates the specified directory dir .
9707 Examples:
9708 Execute(Mkdir('/tmp/outputdir'))
9710 env.Command('foo.out', 'foo.in',
9712 [Mkdir('/tmp/builddir'),
9713 Copy('/tmp/builddir/foo.in', '$SOURCE'),
9714 "cd /tmp/builddir && make",
9715 Copy('$TARGET', '/tmp/builddir/foo.out')])
9716 Move(dest, src)
9719 Returns an Action that moves the specified src file or directory
9720 to the specified dest file or directory. Examples:
9721 Execute(Move('file.destination', 'file.source'))
9723 env.Command('output_file', 'input_file',
9725 [MyBuildAction,
9726 Move('$TARGET', 'file_created_by_MyBuildAction')])
9727 Touch(file)
9730 Returns an Action that updates the modification time on the
9731 specified file. Examples:
9732 Execute(Touch('file_to_be_touched'))
9734 env.Command('marker', 'input_file',
9736 [MyBuildAction,
9737 Touch('$TARGET')])
9738 Variable Substitution
9741 Before executing a command, scons performs construction variable inter‐
9742 polation on the strings that make up the command line of builders.
9743 Variables are introduced by a $ prefix. Besides construction vari‐
9744 ables, scons provides the following variables for each command execu‐
9745 tion:
9746 CHANGED_SOURCES
9749 The file names of all sources of the build command that have
9750 changed since the target was last built.
9751 CHANGED_TARGETS
9754 The file names of all targets that would be built from sources
9755 that have changed since the target was last built.
9756 SOURCE The file name of the source of the build command, or the file
9759 name of the first source if multiple sources are being built.
9760 SOURCES
9763 The file names of the sources of the build command.
9764 TARGET The file name of the target being built, or the file name of the
9767 first target if multiple targets are being built.
9768 TARGETS
9771 The file names of all targets being built.
9772 UNCHANGED_SOURCES
9775 The file names of all sources of the build command that have not
9776 changed since the target was last built.
9777 UNCHANGED_TARGETS
9780 The file names of all targets that would be built from sources
9781 that have not changed since the target was last built.
9782 (Note that the above variables are reserved and may not be set
9784 in a construction environment.)
9785 For example, given the construction variable CC='cc', targets=['foo'],
9788 and sources=['foo.c', 'bar.c']:
9789 action='$CC -c -o $TARGET $SOURCES'
9791 would produce the command line:
9793 cc -c -o foo foo.c bar.c
9795 Variable names may be surrounded by curly braces ({}) to separate the
9797 name from the trailing characters. Within the curly braces, a variable
9798 name may have a Python slice subscript appended to select one or more
9799 items from a list. In the previous example, the string:
9800 ${SOURCES[1]}
9802 would produce:
9804 bar.c
9806 Additionally, a variable name may have the following special modifiers
9808 appended within the enclosing curly braces to modify the interpolated
9809 string:
9810 base The base path of the file name, including the directory path but
9813 excluding any suffix.
9814 dir The name of the directory in which the file exists.
9817 file The file name, minus any directory portion.
9820 filebase
9823 Just the basename of the file, minus any suffix and minus the
9824 directory.
9825 suffix Just the file suffix.
9828 abspath
9831 The absolute path name of the file.
9832 posix The POSIX form of the path, with directories separated by /
9835 (forward slashes) not backslashes. This is sometimes necessary
9836 on Windows systems when a path references a file on other
9837 (POSIX) systems.
9838 srcpath
9841 The directory and file name to the source file linked to this
9842 file through VariantDir(). If this file isn't linked, it just
9843 returns the directory and filename unchanged.
9844 srcdir The directory containing the source file linked to this file
9847 through VariantDir(). If this file isn't linked, it just
9848 returns the directory part of the filename.
9849 rsrcpath
9852 The directory and file name to the source file linked to this
9853 file through VariantDir(). If the file does not exist locally
9854 but exists in a Repository, the path in the Repository is
9855 returned. If this file isn't linked, it just returns the direc‐
9856 tory and filename unchanged.
9857 rsrcdir
9860 The Repository directory containing the source file linked to
9861 this file through VariantDir(). If this file isn't linked, it
9862 just returns the directory part of the filename.
9863 For example, the specified target will expand as follows for the corre‐
9866 sponding modifiers:
9867 $TARGET => sub/dir/file.x
9869 ${TARGET.base} => sub/dir/file
9870 ${TARGET.dir} => sub/dir
9871 ${TARGET.file} => file.x
9872 ${TARGET.filebase} => file
9873 ${TARGET.suffix} => .x
9874 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9875 SConscript('src/SConscript', variant_dir='sub/dir')
9877 $SOURCE => sub/dir/file.x
9878 ${SOURCE.srcpath} => src/file.x
9879 ${SOURCE.srcdir} => src
9880 Repository('/usr/repository')
9882 $SOURCE => sub/dir/file.x
9883 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9884 ${SOURCE.rsrcdir} => /usr/repository/src
9885 Note that curly braces braces may also be used to enclose arbitrary
9887 Python code to be evaluated. (In fact, this is how the above modifiers
9888 are substituted, they are simply attributes of the Python objects that
9889 represent TARGET, SOURCES, etc.) See the section "Python Code Substi‐
9890 tution," below, for more thorough examples of how this can be used.
9891 Lastly, a variable name may be a callable Python function associated
9893 with a construction variable in the environment. The function should
9894 take four arguments: target - a list of target nodes, source - a list
9895 of source nodes, env - the construction environment, for_signature - a
9896 Boolean value that specifies whether the function is being called for
9897 generating a build signature. SCons will insert whatever the called
9898 function returns into the expanded string:
9899 def foo(target, source, env, for_signature):
9901 return "bar"
9902 # Will expand $BAR to "bar baz"
9904 env=Environment(FOO=foo, BAR="$FOO baz")
9905 You can use this feature to pass arguments to a Python function by cre‐
9907 ating a callable class that stores one or more arguments in an object,
9908 and then uses them when the __call__() method is called. Note that in
9909 this case, the entire variable expansion must be enclosed by curly
9910 braces so that the arguments will be associated with the instantiation
9911 of the class:
9912 class foo(object):
9914 def __init__(self, arg):
9915 self.arg = arg
9916 def __call__(self, target, source, env, for_signature):
9918 return self.arg + " bar"
9919 # Will expand $BAR to "my argument bar baz"
9921 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9922 The special pseudo-variables $( and $) may be used to surround parts of
9925 a command line that may change without causing a rebuild--that is,
9926 which are not included in the signature of target files built with this
9927 command. All text between $( and $) will be removed from the command
9928 line before it is added to file signatures, and the $( and $) will be
9929 removed before the command is executed. For example, the command line:
9930 echo Last build occurred $( $TODAY $). > $TARGET
9932 would execute the command:
9935 echo Last build occurred $TODAY. > $TARGET
9937 but the command signature added to any target files would be:
9940 echo Last build occurred . > $TARGET
9942 Python Code Substitution
9945 Any python code within ${-} pairs gets evaluated by python 'eval', with
9946 the python globals set to the current environment's set of construction
9947 variables. So in the following case:
9948 env['COND'] = 0
9949 env.Command('foo.out', 'foo.in',
9950 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9951 the command executed will be either
9952 echo FOO > foo.out
9953 or
9954 echo BAR > foo.out
9955 according to the current value of env['COND'] when the command is exe‐
9956 cuted. The evaluation occurs when the target is being built, not when
9957 the SConscript is being read. So if env['COND'] is changed later in
9958 the SConscript, the final value will be used.
9959 Here's a more interesting example. Note that all of COND, FOO, and BAR
9961 are environment variables, and their values are substituted into the
9962 final command. FOO is a list, so its elements are interpolated sepa‐
9963 rated by spaces.
9964 env=Environment()
9966 env['COND'] = 0
9967 env['FOO'] = ['foo1', 'foo2']
9968 env['BAR'] = 'barbar'
9969 env.Command('foo.out', 'foo.in',
9970 'echo ${COND==1 and FOO or BAR} > $TARGET')
9971 # Will execute this:
9973 # echo foo1 foo2 > foo.out
9974 SCons uses the following rules when converting construction variables
9976 into command lines:
9977 String When the value is a string it is interpreted as a space delim‐
9980 ited list of command line arguments.
9981 List When the value is a list it is interpreted as a list of command
9984 line arguments. Each element of the list is converted to a
9985 string.
9986 Other Anything that is not a list or string is converted to a string
9989 and interpreted as a single command line argument.
9990 Newline
9993 Newline characters (\n) delimit lines. The newline parsing is
9994 done after all other parsing, so it is not possible for argu‐
9995 ments (e.g. file names) to contain embedded newline characters.
9996 This limitation will likely go away in a future version of
9997 SCons.
9998 Scanner Objects
10001 You can use the Scanner function to define objects to scan new file
10002 types for implicit dependencies. The Scanner function accepts the fol‐
10003 lowing arguments:
10004 function
10007 This can be either: 1) a Python function that will process the
10008 Node (file) and return a list of strings (file names) represent‐
10009 ing the implicit dependencies found in the contents; or: 2) a
10010 dictionary that maps keys (typically the file suffix, but see
10011 below for more discussion) to other Scanners that should be
10012 called.
10013 If the argument is actually a Python function, the function must
10015 take three or four arguments:
10016 def scanner_function(node, env, path):
10018 def scanner_function(node, env, path, arg=None):
10020 The node argument is the internal SCons node representing the
10022 file. Use str(node) to fetch the name of the file, and
10023 node.get_contents() to fetch contents of the file. Note that
10024 the file is not guaranteed to exist before the scanner is
10025 called, so the scanner function should check that if there's any
10026 chance that the scanned file might not exist (for example, if
10027 it's built from other files).
10028 The env argument is the construction environment for the scan.
10030 Fetch values from it using the env.Dictionary() method.
10031 The path argument is a tuple (or list) of directories that can
10033 be searched for files. This will usually be the tuple returned
10034 by the path_function argument (see below).
10035 The arg argument is the argument supplied when the scanner was
10037 created, if any.
10038 name The name of the Scanner. This is mainly used to identify the
10041 Scanner internally.
10042 argument
10045 An optional argument that, if specified, will be passed to the
10046 scanner function (described above) and the path function (speci‐
10047 fied below).
10048 skeys An optional list that can be used to determine which scanner
10051 should be used for a given Node. In the usual case of scanning
10052 for file names, this argument will be a list of suffixes for the
10053 different file types that this Scanner knows how to scan. If
10054 the argument is a string, then it will be expanded into a list
10055 by the current environment.
10056 path_function
10059 A Python function that takes four or five arguments: a construc‐
10060 tion environment, a Node for the directory containing the SCon‐
10061 script file in which the first target was defined, a list of
10062 target nodes, a list of source nodes, and an optional argument
10063 supplied when the scanner was created. The path_function
10064 returns a tuple of directories that can be searched for files to
10065 be returned by this Scanner object. (Note that the Find‐
10066 PathDirs() function can be used to return a ready-made
10067 path_function for a given construction variable name, instead of
10068 having to write your own function from scratch.)
10069 node_class
10072 The class of Node that should be returned by this Scanner
10073 object. Any strings or other objects returned by the scanner
10074 function that are not of this class will be run through the
10075 node_factory function.
10076 node_factory
10079 A Python function that will take a string or other object and
10080 turn it into the appropriate class of Node to be returned by
10081 this Scanner object.
10082 scan_check
10085 An optional Python function that takes two arguments, a Node
10086 (file) and a construction environment, and returns whether the
10087 Node should, in fact, be scanned for dependencies. This check
10088 can be used to eliminate unnecessary calls to the scanner func‐
10089 tion when, for example, the underlying file represented by a
10090 Node does not yet exist.
10091 recursive
10094 An optional flag that specifies whether this scanner should be
10095 re-invoked on the dependency files returned by the scanner.
10096 When this flag is not set, the Node subsystem will only invoke
10097 the scanner on the file being scanned, and not (for example)
10098 also on the files specified by the #include lines in the file
10099 being scanned. recursive may be a callable function, in which
10100 case it will be called with a list of Nodes found and should
10101 return a list of Nodes that should be scanned recursively; this
10102 can be used to select a specific subset of Nodes for additional
10103 scanning.
10104 Note that scons has a global SourceFileScanner object that is used by
10106 the Object(), SharedObject(), and StaticObject() builders to decide
10107 which scanner should be used for different file extensions. You can
10108 using the SourceFileScanner.add_scanner() method to add your own Scan‐
10109 ner object to the scons infrastructure that builds target programs or
10110 libraries from a list of source files of different types:
10111 def xyz_scan(node, env, path):
10113 contents = node.get_text_contents()
10114 # Scan the contents and return the included files.
10115 XYZScanner = Scanner(xyz_scan)
10117 SourceFileScanner.add_scanner('.xyx', XYZScanner)
10119 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
10121
10124 SCons and its configuration files are very portable, due largely to its
10125 implementation in Python. There are, however, a few portability issues
10126 waiting to trap the unwary.
10127 .C file suffix
10129 SCons handles the upper-case .C file suffix differently, depending on
10130 the capabilities of the underlying system. On a case-sensitive system
10131 such as Linux or UNIX, SCons treats a file with a .C suffix as a C++
10132 source file. On a case-insensitive system such as Windows, SCons
10133 treats a file with a .C suffix as a C source file.
10134 .F file suffix
10136 SCons handles the upper-case .F file suffix differently, depending on
10137 the capabilities of the underlying system. On a case-sensitive system
10138 such as Linux or UNIX, SCons treats a file with a .F suffix as a For‐
10139 tran source file that is to be first run through the standard C pre‐
10140 processor. On a case-insensitive system such as Windows, SCons treats
10141 a file with a .F suffix as a Fortran source file that should not be run
10142 through the C preprocessor.
10143 Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
10145 Cygwin supplies a set of tools and utilities that let users work on a
10146 Windows system using a more POSIX-like environment. The Cygwin tools,
10147 including Cygwin Python, do this, in part, by sharing an ability to
10148 interpret UNIX-like path names. For example, the Cygwin tools will
10149 internally translate a Cygwin path name like /cygdrive/c/mydir to an
10150 equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
10151 Versions of Python that are built for native Windows execution, such as
10153 the python.org and ActiveState versions, do not have the Cygwin path
10154 name semantics. This means that using a native Windows version of
10155 Python to build compiled programs using Cygwin tools (such as gcc,
10156 bison, and flex) may yield unpredictable results. "Mixing and match‐
10157 ing" in this way can be made to work, but it requires careful attention
10158 to the use of path names in your SConscript files.
10159 In practice, users can sidestep the issue by adopting the following
10161 rules: When using gcc, use the Cygwin-supplied Python interpreter to
10162 run SCons; when using Microsoft Visual C/C++ (or some other Windows
10163 compiler) use the python.org or ActiveState version of Python to run
10164 SCons.
10165 Windows: scons.bat file
10167 On Windows systems, SCons is executed via a wrapper scons.bat file.
10168 This has (at least) two ramifications:
10169 First, Windows command-line users that want to use variable assignment
10171 on the command line may have to put double quotes around the assign‐
10172 ments:
10173 scons "FOO=BAR" "BAZ=BLEH"
10175 Second, the Cygwin shell does not recognize this file as being the same
10177 as an scons command issued at the command-line prompt. You can work
10178 around this either by executing scons.bat from the Cygwin command line,
10179 or by creating a wrapper shell script named scons .
10180 MinGW
10183 The MinGW bin directory must be in your PATH environment variable or
10184 the PATH variable under the ENV construction variable for SCons to
10185 detect and use the MinGW tools. When running under the native Windows
10186 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
10187 tools, if they are both installed, regardless of the order of the bin
10188 directories in the PATH variable. If you have both MSVC and MinGW
10189 installed and you want to use MinGW instead of MSVC, then you must
10190 explictly tell SCons to use MinGW by passing
10191 tools=['mingw']
10193 to the Environment() function, because SCons will prefer the MSVC tools
10195 over the MinGW tools.
10196
10199 To help you get started using SCons, this section contains a brief
10200 overview of some common tasks.
10201 Basic Compilation From a Single Source File
10204 env = Environment()
10205 env.Program(target = 'foo', source = 'foo.c')
10206 Note: Build the file by specifying the target as an argument ("scons
10208 foo" or "scons foo.exe"). or by specifying a dot ("scons .").
10209 Basic Compilation From Multiple Source Files
10212 env = Environment()
10213 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
10214 Setting a Compilation Flag
10217 env = Environment(CCFLAGS = '-g')
10218 env.Program(target = 'foo', source = 'foo.c')
10219 Search The Local Directory For .h Files
10222 Note: You do not need to set CCFLAGS to specify -I options by hand.
10223 SCons will construct the right -I options from CPPPATH.
10224 env = Environment(CPPPATH = ['.'])
10226 env.Program(target = 'foo', source = 'foo.c')
10227 Search Multiple Directories For .h Files
10230 env = Environment(CPPPATH = ['include1', 'include2'])
10231 env.Program(target = 'foo', source = 'foo.c')
10232 Building a Static Library
10235 env = Environment()
10236 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
10237 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
10238 Building a Shared Library
10241 env = Environment()
10242 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
10243 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
10244 Linking a Local Library Into a Program
10247 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
10248 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
10249 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
10250 Defining Your Own Builder Object
10253 Notice that when you invoke the Builder, you can leave off the target
10254 file suffix, and SCons will add it automatically.
10255 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10257 suffix = '.pdf',
10258 src_suffix = '.tex')
10259 env = Environment(BUILDERS = {'PDFBuilder' : bld})
10260 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10261 # The following creates "bar.pdf" from "bar.tex"
10263 env.PDFBuilder(target = 'bar', source = 'bar')
10264 Note also that the above initialization overwrites the default Builder
10266 objects, so the Environment created above can not be used call Builders
10267 like env.Program(), env.Object(), env.StaticLibrary(), etc.
10268 Adding Your Own Builder Object to an Environment
10271 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10272 suffix = '.pdf',
10273 src_suffix = '.tex')
10274 env = Environment()
10275 env.Append(BUILDERS = {'PDFBuilder' : bld})
10276 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10277 env.Program(target = 'bar', source = 'bar.c')
10278 You also can use other Pythonic techniques to add to the BUILDERS con‐
10280 struction variable, such as:
10281 env = Environment()
10283 env['BUILDERS]['PDFBuilder'] = bld
10284 Defining Your Own Scanner Object
10287 The following example shows an extremely simple scanner (the
10288 kfile_scan() function) that doesn't use a search path at all and simply
10289 returns the file names present on any include lines in the scanned
10290 file. This would implicitly assume that all included files live in the
10291 top-level directory:
10292 import re
10294 include_re = re.compile(r'^include\s+(\S+)$', re.M)
10296 def kfile_scan(node, env, path, arg):
10298 contents = node.get_text_contents()
10299 includes = include_re.findall(contents)
10300 return includes
10301 kscan = Scanner(name = 'kfile',
10303 function = kfile_scan,
10304 argument = None,
10305 skeys = ['.k'])
10306 scanners = Environment().Dictionary('SCANNERS')
10307 env = Environment(SCANNERS = scanners + [kscan])
10308 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
10310 bar_in = File('bar.in')
10312 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
10313 bar_in.target_scanner = kscan
10314 Here is a similar but more complete example that searches a path of
10316 directories (specified as the MYPATH construction variable) for files
10317 that actually exist:
10318 include_re = re.compile(r'^include\s+(\S+)$', re.M)
10320 def my_scan(node, env, path, arg):
10322 contents = node.get_text_contents()
10323 includes = include_re.findall(contents)
10324 if includes == []:
10325 return []
10326 results = []
10327 for inc in includes:
10328 for dir in path:
10329 file = dir + os.sep + inc
10330 if os.path.exists(file):
10331 results.append(file)
10332 break
10333 return results
10334 scanner = Scanner(name = 'myscanner',
10336 function = my_scan,
10337 argument = None,
10338 skeys = ['.x'],
10339 path_function = FindPathDirs('MYPATH'),
10340 )
10341 scanners = Environment().Dictionary('SCANNERS')
10342 env = Environment(SCANNERS = scanners + [scanner])
10343 The FindPathDirs() function used in the previous example returns a
10345 function (actually a callable Python object) that will return a list of
10346 directories specified in the $MYPATH construction variable. If you
10347 need to customize how the search path is derived, you would provide
10348 your own path_function argument when creating the Scanner object, as
10349 follows:
10350 # MYPATH is a list of directories to search for files in
10352 def pf(env, dir, target, source, arg):
10353 top_dir = Dir('#').abspath
10354 results = []
10355 if 'MYPATH' in env:
10356 for p in env['MYPATH']:
10357 results.append(top_dir + os.sep + p)
10358 return results
10359 scanner = Scanner(name = 'myscanner',
10361 function = my_scan,
10362 argument = None,
10363 skeys = ['.x'],
10364 path_function = pf,
10365 )
10366 Creating a Hierarchical Build
10369 Notice that the file names specified in a subdirectory's SConscript
10370 file are relative to that subdirectory.
10371 SConstruct:
10373 env = Environment()
10375 env.Program(target = 'foo', source = 'foo.c')
10376 SConscript('sub/SConscript')
10378 sub/SConscript:
10380 env = Environment()
10382 # Builds sub/foo from sub/foo.c
10383 env.Program(target = 'foo', source = 'foo.c')
10384 SConscript('dir/SConscript')
10386 sub/dir/SConscript:
10388 env = Environment()
10390 # Builds sub/dir/foo from sub/dir/foo.c
10391 env.Program(target = 'foo', source = 'foo.c')
10392 Sharing Variables Between SConscript Files
10395 You must explicitly Export() and Import() variables that you want to
10396 share between SConscript files.
10397 SConstruct:
10399 env = Environment()
10401 env.Program(target = 'foo', source = 'foo.c')
10402 Export("env")
10404 SConscript('subdirectory/SConscript')
10405 subdirectory/SConscript:
10407 Import("env")
10409 env.Program(target = 'foo', source = 'foo.c')
10410 Building Multiple Variants From the Same Source
10413 Use the variant_dir keyword argument to the SConscript function to
10414 establish one or more separate variant build directory trees for a
10415 given source directory:
10416 SConstruct:
10418 cppdefines = ['FOO']
10420 Export("cppdefines")
10421 SConscript('src/SConscript', variant_dir='foo')
10422 cppdefines = ['BAR']
10424 Export("cppdefines")
10425 SConscript('src/SConscript', variant_dir='bar')
10426 src/SConscript:
10428 Import("cppdefines")
10430 env = Environment(CPPDEFINES = cppdefines)
10431 env.Program(target = 'src', source = 'src.c')
10432 Note the use of the Export() method to set the "cppdefines" variable to
10434 a different value each time we call the SConscript function.
10435 Hierarchical Build of Two Libraries Linked With a Program
10438 SConstruct:
10439 env = Environment(LIBPATH = ['#libA', '#libB'])
10441 Export('env')
10442 SConscript('libA/SConscript')
10443 SConscript('libB/SConscript')
10444 SConscript('Main/SConscript')
10445 libA/SConscript:
10447 Import('env')
10449 env.Library('a', Split('a1.c a2.c a3.c'))
10450 libB/SConscript:
10452 Import('env')
10454 env.Library('b', Split('b1.c b2.c b3.c'))
10455 Main/SConscript:
10457 Import('env')
10459 e = env.Copy(LIBS = ['a', 'b'])
10460 e.Program('foo', Split('m1.c m2.c m3.c'))
10461 The '#' in the LIBPATH directories specify that they're relative to the
10463 top-level directory, so they don't turn into "Main/libA" when they're
10464 used in Main/SConscript.
10465 Specifying only 'a' and 'b' for the library names allows SCons to
10467 append the appropriate library prefix and suffix for the current plat‐
10468 form (for example, 'liba.a' on POSIX systems, 'a.lib' on Windows).
10469 Customizing construction variables from the command line.
10472 The following would allow the C compiler to be specified on the command
10473 line or in the file custom.py.
10474 vars = Variables('custom.py')
10476 vars.Add('CC', 'The C compiler.')
10477 env = Environment(variables=vars)
10478 Help(vars.GenerateHelpText(env))
10479 The user could specify the C compiler on the command line:
10481 scons "CC=my_cc"
10483 or in the custom.py file:
10485 CC = 'my_cc'
10487 or get documentation on the options:
10489 $ scons -h
10491 CC: The C compiler.
10493 default: None
10494 actual: cc
10495 Using Microsoft Visual C++ precompiled headers
10499 Since windows.h includes everything and the kitchen sink, it can take
10500 quite some time to compile it over and over again for a bunch of object
10501 files, so Microsoft provides a mechanism to compile a set of headers
10502 once and then include the previously compiled headers in any object
10503 file. This technology is called precompiled headers. The general recipe
10504 is to create a file named "StdAfx.cpp" that includes a single header
10505 named "StdAfx.h", and then include every header you want to precompile
10506 in "StdAfx.h", and finally include "StdAfx.h" as the first header in
10507 all the source files you are compiling to object files. For example:
10508 StdAfx.h:
10510 #include <windows.h>
10511 #include <my_big_header.h>
10512 StdAfx.cpp:
10514 #include <StdAfx.h>
10515 Foo.cpp:
10517 #include <StdAfx.h>
10518 /* do some stuff */
10520 Bar.cpp:
10522 #include <StdAfx.h>
10523 /* do some other stuff */
10525 SConstruct:
10527 env=Environment()
10528 env['PCHSTOP'] = 'StdAfx.h'
10529 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10530 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10531 For more information see the document for the PCH builder, and the PCH
10533 and PCHSTOP construction variables. To learn about the details of pre‐
10534 compiled headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10535 Using Microsoft Visual C++ external debugging information
10538 Since including debugging information in programs and shared libraries
10539 can cause their size to increase significantly, Microsoft provides a
10540 mechanism for including the debugging information in an external file
10541 called a PDB file. SCons supports PDB files through the PDB construc‐
10542 tion variable.
10543 SConstruct:
10545 env=Environment()
10546 env['PDB'] = 'MyApp.pdb'
10547 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10548 For more information see the document for the PDB construction vari‐
10550 able.
10551
10554 SCONS_LIB_DIR
10555 Specifies the directory that contains the SCons Python module
10556 directory (e.g. /home/aroach/scons-src-0.01/src/engine).
10557 SCONSFLAGS
10560 A string of options that will be used by scons in addition to
10561 those passed on the command line.
10562
10565 scons User Manual, scons Design Document, scons source code.
10566
10569 Steven Knight <knight@baldmt.com>
10570 Anthony Roach <aroach@electriceyeball.com>
10571 August 2010 SCONS(1)