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 various system directories (see below) and the directory
36 containing the SConstruct file; for each of those dirs which exists,
37 site_scons is prepended to sys.path, the file site_scons/site_init.py,
38 is evaluated if it exists, and the directory site_scons/site_tools is
39 prepended to the default toolpath if it exists. See the --no-site-dir
40 and --site-dir options for more details.
41 scons reads and executes the SConscript files as Python scripts, so you
43 may use normal Python scripting capabilities (such as flow control,
44 data manipulation, and imported Python libraries) to handle complicated
45 build situations. scons, however, reads and executes all of the SCon‐
46 script files before it begins building any targets. To make this obvi‐
47 ous, scons prints the following messages about what it is doing:
48 $ scons foo.out
50 scons: Reading SConscript files ...
51 scons: done reading SConscript files.
52 scons: Building targets ...
53 cp foo.in foo.out
54 scons: done building targets.
55 $
56 The status messages (everything except the line that reads "cp foo.in
58 foo.out") may be suppressed using the -Q option.
59 scons does not automatically propagate the external environment used to
61 execute scons to the commands used to build target files. This is so
62 that builds will be guaranteed repeatable regardless of the environment
63 variables set at the time scons is invoked. This also means that if
64 the compiler or other commands that you want to use to build your tar‐
65 get files are not in standard system locations, scons will not find
66 them unless you explicitly set the PATH to include those locations.
67 Whenever you create an scons construction environment, you can propa‐
68 gate the value of PATH from your external environment as follows:
69 import os
71 env = Environment(ENV = {'PATH' : os.environ['PATH']})
72 Similarly, if the commands use external environment variables like
74 $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables
75 can also be explicitly propagated:
76 import os
78 env = Environment(ENV = {'PATH' : os.environ['PATH'],
79 'HOME' : os.environ['HOME']})
80 Or you may explicitly propagate the invoking user's complete external
82 environment:
83 import os
85 env = Environment(ENV = os.environ)
86 This comes at the expense of making your build dependent on the user's
88 environment being set correctly, but it may be more convenient for many
89 configurations.
90 scons can scan known input files automatically for dependency informa‐
92 tion (for example, #include statements in C or C++ files) and will
93 rebuild dependent files appropriately whenever any "included" input
94 file changes. scons supports the ability to define new scanners for
95 unknown input file types.
96 scons knows how to fetch files automatically from SCCS or RCS subdirec‐
98 tories using SCCS, RCS or BitKeeper.
99 scons is normally executed in a top-level directory containing a SCon‐
101 struct file, optionally specifying as command-line arguments the target
102 file or files to be built.
103 By default, the command
105 scons
107 will build all target files in or below the current directory.
109 Explicit default targets (to be built when no targets are specified on
110 the command line) may be defined the SConscript file(s) using the
111 Default() function, described below.
112 Even when Default() targets are specified in the SConscript file(s),
114 all target files in or below the current directory may be built by
115 explicitly specifying the current directory (.) as a command-line tar‐
116 get:
117 scons .
119 Building all target files, including any files outside of the current
121 directory, may be specified by supplying a command-line target of the
122 root directory (on POSIX systems):
123 scons /
125 or the path name(s) of the volume(s) in which all the targets should be
127 built (on Windows systems):
128 scons C:\ D:\
130 To build only specific targets, supply them as command-line arguments:
132 scons foo bar
134 in which case only the specified targets will be built (along with any
136 derived files on which they depend).
137 Specifying "cleanup" targets in SConscript files is not usually neces‐
139 sary. The -c flag removes all files necessary to build the specified
140 target:
141 scons -c .
143 to remove all target files, or:
145 scons -c build export
147 to remove target files under build and export. Additional files or
149 directories to remove can be specified using the Clean() function.
150 Conversely, targets that would normally be removed by the -c invocation
151 can be prevented from being removed by using the NoClean() function.
152 A subset of a hierarchical tree may be built by remaining at the top-
154 level directory (where the SConstruct file lives) and specifying the
155 subdirectory as the target to be built:
156 scons src/subdir
158 or by changing directory and invoking scons with the -u option, which
160 traverses up the directory hierarchy until it finds the SConstruct
161 file, and then builds targets relatively to the current subdirectory:
162 cd src/subdir
164 scons -u .
165 scons supports building multiple targets in parallel via a -j option
167 that takes, as its argument, the number of simultaneous tasks that may
168 be spawned:
169 scons -j 4
171 builds four targets in parallel, for example.
173 scons can maintain a cache of target (derived) files that can be shared
175 between multiple builds. When caching is enabled in a SConscript file,
176 any target files built by scons will be copied to the cache. If an up-
177 to-date target file is found in the cache, it will be retrieved from
178 the cache instead of being rebuilt locally. Caching behavior may be
179 disabled and controlled in other ways by the --cache-force, --cache-
180 disable, and --cache-show command-line options. The --random option is
181 useful to prevent multiple builds from trying to update the cache
182 simultaneously.
183 Values of variables to be passed to the SConscript file(s) may be spec‐
185 ified on the command line:
186 scons debug=1 .
188 These variables are available in SConscript files through the ARGUMENTS
190 dictionary, and can be used in the SConscript file(s) to modify the
191 build in any way:
192 if ARGUMENTS.get('debug', 0):
194 env = Environment(CCFLAGS = '-g')
195 else:
196 env = Environment()
197 The command-line variable arguments are also available in the ARGLIST
199 list, indexed by their order on the command line. This allows you to
200 process them in order rather than by name, if necessary. ARGLIST[0]
201 returns a tuple containing (argname, argvalue). A Python exception is
202 thrown if you try to access a list member that does not exist.
203 scons requires Python version 2.4 or later. There should be no other
205 dependencies or requirements to run scons.
206 By default, scons knows how to search for available programming tools
208 on various systems. On Windows systems, scons searches in order for
209 the Microsoft Visual C++ tools, the MinGW tool chain, the Intel com‐
210 piler tools, and the PharLap ETS compiler. On OS/2 systems, scons
211 searches in order for the OS/2 compiler, the GCC tool chain, and the
212 Microsoft Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-
213 UX, and Sun Solaris systems, scons searches for the native compiler
214 tools (MIPSpro, Visual Age, aCC, and Forte tools respectively) and the
215 GCC tool chain. On all other platforms, including POSIX (Linux and
216 UNIX) platforms, scons searches in order for the GCC tool chain, the
217 Microsoft Visual C++ tools, and the Intel compiler tools. You may, of
218 course, override these default values by appropriate configuration of
219 Environment construction variables.
220
223 In general, scons supports the same command-line options as GNU make,
224 and many of those supported by cons.
225 -b Ignored for compatibility with non-GNU versions of make.
228 -c, --clean, --remove
231 Clean up by removing all target files for which a construction
232 command is specified. Also remove any files or directories
233 associated to the construction command using the Clean() func‐
234 tion. Will not remove any targets specified by the NoClean()
235 function.
236 --cache-debug=file
239 Print debug information about the CacheDir() derived-file
240 caching to the specified file. If file is - (a hyphen), the
241 debug information are printed to the standard output. The
242 printed messages describe what signature file names are being
243 looked for in, retrieved from, or written to the CacheDir()
244 directory tree.
245 --cache-disable, --no-cache
248 Disable the derived-file caching specified by CacheDir(). scons
249 will neither retrieve files from the cache nor copy files to the
250 cache.
251 --cache-force, --cache-populate
254 When using CacheDir(), populate a cache by copying any already-
255 existing, up-to-date derived files to the cache, in addition to
256 files built by this invocation. This is useful to populate a
257 new cache with all the current derived files, or to add to the
258 cache any derived files recently built with caching disabled via
259 the --cache-disable option.
260 --cache-show
263 When using CacheDir() and retrieving a derived file from the
264 cache, show the command that would have been executed to build
265 the file, instead of the usual report, "Retrieved `file' from
266 cache." This will produce consistent output for build logs,
267 regardless of whether a target file was rebuilt or retrieved
268 from the cache.
269 --config=mode
272 This specifies how the Configure call should use or generate the
273 results of configuration tests. The option should be specified
274 from among the following choices:
275 --config=auto
278 scons will use its normal dependency mechanisms to decide if a
279 test must be rebuilt or not. This saves time by not running the
280 same configuration tests every time you invoke scons, but will
281 overlook changes in system header files or external commands
282 (such as compilers) if you don't specify those dependecies
283 explicitly. This is the default behavior.
284 --config=force
287 If this option is specified, all configuration tests will be re-
288 run regardless of whether the cached results are out of date.
289 This can be used to explicitly force the configuration tests to
290 be updated in response to an otherwise unconfigured change in a
291 system header file or compiler.
292 --config=cache
295 If this option is specified, no configuration tests will be
296 rerun and all results will be taken from cache. Note that scons
297 will still consider it an error if --config=cache is specified
298 and a necessary test does not yet have any results in the cache.
299 -C directory, --directory=directory
302 Change to the specified directory before searching for the SCon‐
303 struct, Sconstruct, or sconstruct file, or doing anything else.
304 Multiple -C options are interpreted relative to the previous
305 one, and the right-most -C option wins. (This option is nearly
306 equivalent to -f directory/SConstruct, except that it will
307 search for SConstruct, Sconstruct, or sconstruct in the speci‐
308 fied directory.)
309 -D Works exactly the same way as the -u option except for the way
313 default targets are handled. When this option is used and no
314 targets are specified on the command line, all default targets
315 are built, whether or not they are below the current directory.
316 --debug=type
319 Debug the build process. type specifies what type of debugging:
320 --debug=count
323 Print how many objects are created of the various classes used
324 internally by SCons before and after reading the SConscript
325 files and before and after building targets. This is not sup‐
326 ported when SCons is executed with the Python -O (optimized)
327 option or when the SCons modules have been compiled with opti‐
328 mization (that is, when executing from *.pyo files).
329 --debug=duplicate
332 Print a line for each unlink/relink (or copy) of a variant file
333 from its source file. Includes debugging info for unlinking
334 stale variant files, as well as unlinking old targets before
335 building them.
336 --debug=dtree
339 A synonym for the newer --tree=derived option. This will be
340 deprecated in some future release and ultimately removed.
341 --debug=explain
344 Print an explanation of precisely why scons is deciding to
345 (re-)build any targets. (Note: this does not print anything
346 for targets that are not rebuilt.)
347 --debug=findlibs
350 Instruct the scanner that searches for libraries to print a mes‐
351 sage about each potential library name it is searching for, and
352 about the actual libraries it finds.
353 --debug=includes
356 Print the include tree after each top-level target is built.
357 This is generally used to find out what files are included by
358 the sources of a given derived file:
359 $ scons --debug=includes foo.o
361 --debug=memoizer
364 Prints a summary of hits and misses using the Memoizer, an
365 internal subsystem that counts how often SCons uses cached val‐
366 ues in memory instead of recomputing them each time they're
367 needed.
368 --debug=memory
371 Prints how much memory SCons uses before and after reading the
372 SConscript files and before and after building targets.
373 --debug=nomemoizer
376 A deprecated option preserved for backwards compatibility.
377 --debug=objects
380 Prints a list of the various objects of the various classes used
381 internally by SCons.
382 --debug=pdb
385 Re-run SCons under the control of the pdb Python debugger.
386 --debug=prepare
389 Print a line each time any target (internal or external) is pre‐
390 pared for building. scons prints this for each target it con‐
391 siders, even if that target is up to date (see also
392 --debug=explain). This can help debug problems with targets
393 that aren't being built; it shows whether scons is at least con‐
394 sidering them or not.
395 --debug=presub
398 Print the raw command line used to build each target before the
399 construction environment variables are substituted. Also shows
400 which targets are being built by this command. Output looks
401 something like this:
402 $ scons --debug=presub
403 Building myprog.o with action(s):
404 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
405 ...
406 --debug=stacktrace
409 Prints an internal Python stack trace when encountering an oth‐
410 erwise unexplained error.
411 --debug=stree
414 A synonym for the newer --tree=all,status option. This will be
415 deprecated in some future release and ultimately removed.
416 --debug=time
419 Prints various time profiling information: the time spent exe‐
420 cuting each individual build command; the total build time (time
421 SCons ran from beginning to end); the total time spent reading
422 and executing SConscript files; the total time spent SCons
423 itself spend running (that is, not counting reading and execut‐
424 ing SConscript files); and both the total time spent executing
425 all build commands and the elapsed wall-clock time spent execut‐
426 ing those build commands. (When scons is executed without the
427 -j option, the elapsed wall-clock time will typically be
428 slightly longer than the total time spent executing all the
429 build commands, due to the SCons processing that takes place in
430 between executing each command. When scons is executed with the
431 -j option, and your build configuration allows good paralleliza‐
432 tion, the elapsed wall-clock time should be significantly
433 smaller than the total time spent executing all the build com‐
434 mands, since multiple build commands and intervening SCons pro‐
435 cessing should take place in parallel.)
436 --debug=tree
439 A synonym for the newer --tree=all option. This will be depre‐
440 cated in some future release and ultimately removed.
441 --diskcheck=types
444 Enable specific checks for whether or not there is a file on
445 disk where the SCons configuration expects a directory (or vice
446 versa), and whether or not RCS or SCCS sources exist when
447 searching for source and include files. The types argument can
448 be set to: all, to enable all checks explicitly (the default
449 behavior); none, to disable all such checks; match, to check
450 that files and directories on disk match SCons' expected config‐
451 uration; rcs, to check for the existence of an RCS source for
452 any missing source or include files; sccs, to check for the
453 existence of an SCCS source for any missing source or include
454 files. Multiple checks can be specified separated by commas;
455 for example, --diskcheck=sccs,rcs would still check for SCCS and
456 RCS sources, but disable the check for on-disk matches of files
457 and directories. Disabling some or all of these checks can pro‐
458 vide a performance boost for large configurations, or when the
459 configuration will check for files and/or directories across
460 networked or shared file systems, at the slight increased risk
461 of an incorrect build or of not handling errors gracefully (if
462 include files really should be found in SCCS or RCS, for exam‐
463 ple, or if a file really does exist where the SCons configura‐
464 tion expects a directory).
465 --duplicate=ORDER
468 There are three ways to duplicate files in a build tree: hard
469 links, soft (symbolic) links and copies. The default behaviour
470 of SCons is to prefer hard links to soft links to copies. You
471 can specify different behaviours with this option. ORDER must
472 be one of hard-soft-copy (the default), soft-hard-copy, hard-
473 copy, soft-copy or copy. SCons will attempt to duplicate files
474 using the mechanisms in the specified order.
475 -f file, --file=file, --makefile=file, --sconstruct=file
479 Use file as the initial SConscript file. Multiple -f options
480 may be specified, in which case scons will read all of the spec‐
481 ified files.
482 -h, --help
485 Print a local help message for this build, if one is defined in
486 the SConscript file(s), plus a line that describes the -H option
487 for command-line option help. If no local help message is
488 defined, prints the standard help message about command-line
489 options. Exits after displaying the appropriate message.
490 -H, --help-options
493 Print the standard help message about command-line options and
494 exit.
495 -i, --ignore-errors
498 Ignore all errors from commands executed to rebuild files.
499 -I directory, --include-dir=directory
502 Specifies a directory to search for imported Python modules. If
503 several -I options are used, the directories are searched in the
504 order specified.
505 --implicit-cache
508 Cache implicit dependencies. This causes scons to use the
509 implicit (scanned) dependencies from the last time it was run
510 instead of scanning the files for implicit dependencies. This
511 can significantly speed up SCons, but with the following limita‐
512 tions:
513 scons will not detect changes to implicit dependency search
515 paths (e.g. CPPPATH, LIBPATH) that would ordinarily cause dif‐
516 ferent versions of same-named files to be used.
517 scons will miss changes in the implicit dependencies in cases
519 where a new implicit dependency is added earlier in the implicit
520 dependency search path (e.g. CPPPATH, LIBPATH) than a current
521 implicit dependency with the same name.
522 --implicit-deps-changed
525 Forces SCons to ignore the cached implicit dependencies. This
526 causes the implicit dependencies to be rescanned and recached.
527 This implies --implicit-cache.
528 --implicit-deps-unchanged
531 Force SCons to ignore changes in the implicit dependencies.
532 This causes cached implicit dependencies to always be used.
533 This implies --implicit-cache.
534 --interactive
537 Starts SCons in interactive mode. The SConscript files are read
538 once and a scons>>> prompt is printed. Targets may now be
539 rebuilt by typing commands at interactive prompt without having
540 to re-read the SConscript files and re-initialize the dependency
541 graph from scratch.
542 SCons interactive mode supports the following commands:
544 build[OPTIONS] [TARGETS] ...
547 Builds the specified TARGETS (and their dependencies)
548 with the specified SCons command-line OPTIONS. b and
549 scons are synonyms.
550 The following SCons command-line options affect the
552 build command:
553 --cache-debug=FILE
555 --cache-disable, --no-cache
556 --cache-force, --cache-populate
557 --cache-show
558 --debug=TYPE
559 -i, --ignore-errors
560 -j N, --jobs=N
561 -k, --keep-going
562 -n, --no-exec, --just-print, --dry-run, --recon
563 -Q
564 -s, --silent, --quiet
565 --taskmastertrace=FILE
566 --tree=OPTIONS
567 Any other SCons command-line options that are specified
570 do not cause errors but have no effect on the build
571 command (mainly because they affect how the SConscript
572 files are read, which only happens once at the begin‐
573 ning of interactive mode).
574 clean[OPTIONS] [TARGETS] ...
577 Cleans the specified TARGETS (and their dependencies)
578 with the specified options. c is a synonym. This com‐
579 mand is itself a synonym for build --clean
580 exit Exits SCons interactive mode. You can also exit by
583 terminating input (CTRL+D on UNIX or Linux systems,
584 CTRL+Z on Windows systems).
585 help[COMMAND]
588 Provides a help message about the commands available in
589 SCons interactive mode. If COMMAND is specified, h and
590 ? are synonyms.
591 shell[COMMANDLINE]
594 Executes the specified COMMANDLINE in a subshell. If
595 no COMMANDLINE is specified, executes the interactive
596 command interpreter specified in the SHELL environment
597 variable (on UNIX and Linux systems) or the COMSPEC
598 environment variable (on Windows systems). sh and !
599 are synonyms.
600 version
603 Prints SCons version information.
604 An empty line repeats the last typed command. Command-line
607 editing can be used if the readline module is available.
608 $ scons --interactive
610 scons: Reading SConscript files ...
611 scons: done reading SConscript files.
612 scons>>> build -n prog
613 scons>>> exit
614 -j N, --jobs=N
617 Specifies the number of jobs (commands) to run simultaneously.
618 If there is more than one -j option, the last one is effective.
619 -k, --keep-going
622 Continue as much as possible after an error. The target that
623 failed and those that depend on it will not be remade, but other
624 targets specified on the command line will still be processed.
625 -m Ignored for compatibility with non-GNU versions of make.
630 --max-drift=SECONDS
633 Set the maximum expected drift in the modification time of files
634 to SECONDS. This value determines how long a file must be
635 unmodified before its cached content signature will be used
636 instead of calculating a new content signature (MD5 checksum) of
637 the file's contents. The default value is 2 days, which means a
638 file must have a modification time of at least two days ago in
639 order to have its cached content signature used. A negative
640 value means to never cache the content signature and to ignore
641 the cached value if there already is one. A value of 0 means to
642 always use the cached signature, no matter how old the file is.
643 --md5-chunksize=KILOBYTES
646 Set the block size used to compute MD5 signatures to KILOBYTES.
647 This value determines the size of the chunks which are read in
648 at once when computing MD5 signatures. Files below that size
649 are fully stored in memory before performing the signature com‐
650 putation while bigger files are read in block-by-block. A huge
651 block-size leads to high memory consumption while a very small
652 block-size slows down the build considerably.
653 The default value is to use a chunk size of 64 kilobytes, which
655 should be appropriate for most uses.
656 -n, --just-print, --dry-run, --recon
659 No execute. Print the commands that would be executed to build
660 any out-of-date target files, but do not execute the commands.
661 --no-site-dir
664 Prevents the automatic addition of the standard site_scons dirs
665 to sys.path. Also prevents loading the site_scons/site_init.py
666 modules if they exist, and prevents adding their
667 site_scons/site_tools dirs to the toolpath.
668 --profile=file
672 Run SCons under the Python profiler and save the results in the
673 specified file. The results may be analyzed using the Python
674 pstats module.
675 -q, --question
678 Do not run any commands, or print anything. Just return an exit
679 status that is zero if the specified targets are already up to
680 date, non-zero otherwise.
681 -Q Quiets SCons status messages about reading SConscript files,
683 building targets and entering directories. Commands that are
684 executed to rebuild target files are still printed.
685 --random
689 Build dependencies in a random order. This is useful when
690 building multiple trees simultaneously with caching enabled, to
691 prevent multiple builds from simultaneously trying to build or
692 retrieve the same target files.
693 -s, --silent, --quiet
696 Silent. Do not print commands that are executed to rebuild tar‐
697 get files. Also suppresses SCons status messages.
698 -S, --no-keep-going, --stop
701 Ignored for compatibility with GNU make.
702 --site-dir=dir
705 Uses the named dir as the site dir rather than the default
706 site_scons dirs. This dir will get prepended to sys.path, the
707 module dir/site_init.py will get loaded if it exists, and
708 dir/site_tools will get added to the default toolpath.
709 The default set of site_scons dirs used when --site-dir is not
711 specified depends on the system platform, as follows. Note that
712 the directories are examined in the order given, from most
713 generic to most specific, so the last-executed site_init.py file
714 is the most specific one (which gives it the chance to override
715 everything else), and the dirs are prepended to the paths, again
716 so the last dir examined comes first in the resulting path.
717 Windows:
720 %ALLUSERSPROFILE/Application Data/scons/site_scons
721 %USERPROFILE%/Local Settings/Application Data/scons/site_scons
722 %APPDATA%/scons/site_scons
723 %HOME%/.scons/site_scons
724 ./site_scons
725 Mac OS X:
727 /Library/Application Support/SCons/site_scons
728 /opt/local/share/scons/site_scons (for MacPorts)
729 /sw/share/scons/site_scons (for Fink)
730 $HOME/Library/Application Support/SCons/site_scons
731 $HOME/.scons/site_scons
732 ./site_scons
733 Solaris:
735 /opt/sfw/scons/site_scons
736 /usr/share/scons/site_scons
737 $HOME/.scons/site_scons
738 ./site_scons
739 Linux, HPUX, and other Posix-like systems:
741 /usr/share/scons/site_scons
742 $HOME/.scons/site_scons
743 ./site_scons
744 --stack-size=KILOBYTES
747 Set the size stack used to run threads to KILOBYTES. This value
748 determines the stack size of the threads used to run jobs.
749 These are the threads that execute the actions of the builders
750 for the nodes that are out-of-date. Note that this option has
751 no effect unless the num_jobs option, which corresponds to -j
752 and --jobs, is larger than one. Using a stack size that is too
753 small may cause stack overflow errors. This usually shows up as
754 segmentation faults that cause scons to abort before building
755 anything. Using a stack size that is too large will cause scons
756 to use more memory than required and may slow down the entire
757 build process.
758 The default value is to use a stack size of 256 kilobytes, which
760 should be appropriate for most uses. You should not need to
761 increase this value unless you encounter stack overflow errors.
762 -t, --touch
765 Ignored for compatibility with GNU make. (Touching a file to
766 make it appear up-to-date is unnecessary when using scons.)
767 --taskmastertrace=file
770 Prints trace information to the specified file about how the
771 internal Taskmaster object evaluates and controls the order in
772 which Nodes are built. A file name of - may be used to specify
773 the standard output.
774 -tree=options
777 Prints a tree of the dependencies after each top-level target is
778 built. This prints out some or all of the tree, in various for‐
779 mats, depending on the options specified:
780 --tree=all
783 Print the entire dependency tree after each top-level target is
784 built. This prints out the complete dependency tree, including
785 implicit dependencies and ignored dependencies.
786 --tree=derived
789 Restricts the tree output to only derived (target) files, not
790 source files.
791 --tree=status
794 Prints status information for each displayed node.
795 --tree=prune
798 Prunes the tree to avoid repeating dependency information for
799 nodes that have already been displayed. Any node that has
800 already been displayed will have its name printed in [square
801 brackets], as an indication that the dependencies for that node
802 can be found by searching for the relevant output higher up in
803 the tree.
804 Multiple options may be specified, separated by commas:
807 # Prints only derived files, with status information:
809 scons --tree=derived,status
810 # Prints all dependencies of target, with status information
812 # and pruning dependencies of already-visited Nodes:
813 scons --tree=all,prune,status target
814 -u, --up, --search-up
817 Walks up the directory structure until an SConstruct , Scon‐
818 struct or sconstruct file is found, and uses that as the top of
819 the directory tree. If no targets are specified on the command
820 line, only targets at or below the current directory will be
821 built.
822 -U Works exactly the same way as the -u option except for the way
825 default targets are handled. When this option is used and no
826 targets are specified on the command line, all default targets
827 that are defined in the SConscript(s) in the current directory
828 are built, regardless of what directory the resultant targets
829 end up in.
830 -v, --version
833 Print the scons version, copyright information, list of authors,
834 and any other relevant information. Then exit.
835 -w, --print-directory
838 Print a message containing the working directory before and
839 after other processing.
840 --no-print-directory
843 Turn off -w, even if it was turned on implicitly.
844 --warn=type, --warn=no-type
847 Enable or disable warnings. type specifies the type of warnings
848 to be enabled or disabled:
849 --warn=all, --warn=no-all
852 Enables or disables all warnings.
853 --warn=cache-write-error, --warn=no-cache-write-error
856 Enables or disables warnings about errors trying to write a copy
857 of a built file to a specified CacheDir(). These warnings are
858 disabled by default.
859 --warn=corrupt-sconsign, --warn=no-corrupt-sconsign
862 Enables or disables warnings about unfamiliar signature data in
863 .sconsign files. These warnings are enabled by default.
864 --warn=dependency, --warn=no-dependency
867 Enables or disables warnings about dependencies. These warnings
868 are disabled by default.
869 --warn=deprecated, --warn=no-deprecated
872 Enables or disables all warnings about use of currently depre‐
873 cated features. These warnings are enabled by default. Note
874 that the --warn=no-deprecated option does not disable warnings
875 about absolutely all deprecated features. Warnings for some
876 deprecated features that have already been through several
877 releases with deprecation warnings may be mandatory for a
878 release or two before they are officially no longer supported by
879 SCons. Warnings for some specific deprecated features may be
880 enabled or disabled individually; see below.
881 --warn=deprecated-copy, --warn=no-deprecated-copy
884 Enables or disables warnings about use of the deprecated
885 env.Copy() method.
886 --warn=deprecated-source-signatures, --warn=no-deprecated-
889 source-signatures
890 Enables or disables warnings about use of the deprecated
891 SourceSignatures() function or env.SourceSignatures()
892 method.
893 --warn=deprecated-target-signatures, --warn=no-deprecated-tar‐
896 get-signatures
897 Enables or disables warnings about use of the deprecated
898 TargetSignatures() function or env.TargetSignatures()
899 method.
900 --warn=duplicate-environment, --warn=no-duplicate-environment
903 Enables or disables warnings about attempts to specify a build
904 of a target with two different construction environments that
905 use the same action. These warnings are enabled by default.
906 --warn=fortran-cxx-mix, --warn=no-fortran-cxx-mix
909 Enables or disables the specific warning about linking Fortran
910 and C++ object files in a single executable, which can yield
911 unpredictable behavior with some compilers.
912 --warn=future-deprecated, --warn=no-future-deprecated
915 Enables or disables warnings about features that will be depre‐
916 cated in the future. These warnings are disabled by default.
917 Enabling this warning is especially recommended for projects
918 that redistribute SCons configurations for other users to build,
919 so that the project can be warned as soon as possible about to-
920 be-deprecated features that may require changes to the configu‐
921 ration.
922 --warn=link, --warn=no-link
925 Enables or disables warnings about link steps.
926 --warn=misleading-keywords, --warn=no-misleading-keywords
929 Enables or disables warnings about use of the misspelled key‐
930 words targets and sources when calling Builders. (Note the last
931 s characters, the correct spellings are target and source.)
932 These warnings are enabled by default.
933 --warn=missing-sconscript, --warn=no-missing-sconscript
936 Enables or disables warnings about missing SConscript files.
937 These warnings are enabled by default.
938 --warn=no-md5-module, --warn=no-no-md5-module
941 Enables or disables warnings about the version of Python not
942 having an MD5 checksum module available. These warnings are
943 enabled by default.
944 --warn=no-metaclass-support, --warn=no-no-metaclass-support
947 Enables or disables warnings about the version of Python not
948 supporting metaclasses when the --debug=memoizer option is used.
949 These warnings are enabled by default.
950 --warn=no-object-count, --warn=no-no-object-count
953 Enables or disables warnings about the --debug=object feature
954 not working when scons is run with the python -O option or from
955 optimized Python (.pyo) modules.
956 --warn=no-parallel-support, --warn=no-no-parallel-support
959 Enables or disables warnings about the version of Python not
960 being able to support parallel builds when the -j option is
961 used. These warnings are enabled by default.
962 --warn=python-version, --warn=no-python-version
965 Enables or disables the warning about running SCons with a dep‐
966 recated version of Python. These warnings are enabled by
967 default.
968 --warn=reserved-variable, --warn=no-reserved-variable
971 Enables or disables warnings about attempts to set the reserved
972 construction variable names CHANGED_SOURCES, CHANGED_TARGETS,
973 TARGET, TARGETS, SOURCE, SOURCES, UNCHANGED_SOURCES or
974 UNCHANGED_TARGETS. These warnings are disabled by default.
975 --warn=stack-size, --warn=no-stack-size
978 Enables or disables warnings about requests to set the stack
979 size that could not be honored. These warnings are enabled by
980 default.
981 -Y repository, --repository=repository, --srcdir=repository
985 Search the specified repository for any input and target files
986 not found in the local directory hierarchy. Multiple -Y options
987 may be specified, in which case the repositories are searched in
988 the order specified.
989
992 Construction Environments
993 A construction environment is the basic means by which the SConscript
994 files communicate build information to scons. A new construction envi‐
995 ronment is created using the Environment function:
996 env = Environment()
998 Variables, called construction variables, may be set in a construction
1000 environment either by specifying them as keywords when the object is
1001 created or by assigning them a value after the object is created:
1002 env = Environment(FOO = 'foo')
1004 env['BAR'] = 'bar'
1005 As a convenience, construction variables may also be set or modified by
1007 the parse_flags keyword argument, which applies the ParseFlags method
1008 (described below) to the argument value after all other processing is
1009 completed. This is useful either if the exact content of the flags is
1010 unknown (for example, read from a control file) or if the flags are
1011 distributed to a number of construction variables.
1012 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1014 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
1016 to LIBS.
1017 By default, a new construction environment is initialized with a set of
1019 builder methods and construction variables that are appropriate for the
1020 current platform. An optional platform keyword argument may be used to
1021 specify that an environment should be initialized for a different plat‐
1022 form:
1023 env = Environment(platform = 'cygwin')
1025 env = Environment(platform = 'os2')
1026 env = Environment(platform = 'posix')
1027 env = Environment(platform = 'win32')
1028 Specifying a platform initializes the appropriate construction vari‐
1030 ables in the environment to use and generate file names with prefixes
1031 and suffixes appropriate for the platform.
1032 Note that the win32 platform adds the SystemDrive and SystemRoot vari‐
1034 ables from the user's external environment to the construction environ‐
1035 ment's ENV dictionary. This is so that any executed commands that use
1036 sockets to connect with other systems (such as fetching source files
1037 from external CVS repository specifications like :pserver:anony‐
1038 mous@cvs.sourceforge.net:/cvsroot/scons) will work on Windows systems.
1039 The platform argument may be function or callable object, in which case
1041 the Environment() method will call the specified argument to update the
1042 new construction environment:
1043 def my_platform(env):
1045 env['VAR'] = 'xyzzy'
1046 env = Environment(platform = my_platform)
1048 Additionally, a specific set of tools with which to initialize the
1050 environment may be specified as an optional keyword argument:
1051 env = Environment(tools = ['msvc', 'lex'])
1053 Non-built-in tools may be specified using the toolpath argument:
1055 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1057 This looks for a tool specification in tools/foo.py (as well as using
1059 the ordinary default tools for the platform). foo.py should have two
1060 functions: generate(env, **kw) and exists(env). The generate() func‐
1061 tion modifies the passed-in environment to set up variables so that the
1062 tool can be executed; it may use any keyword arguments that the user
1063 supplies (see below) to vary its initialization. The exists() function
1064 should return a true value if the tool is available. Tools in the
1065 toolpath are used before any of the built-in ones. For example, adding
1066 gcc.py to the toolpath would override the built-in gcc tool. Also note
1067 that the toolpath is stored in the environment for use by later calls
1068 to Clone() and Tool() methods:
1069 base = Environment(toolpath=['custom_path'])
1071 derived = base.Clone(tools=['custom_tool'])
1072 derived.CustomBuilder()
1073 The elements of the tools list may also be functions or callable
1075 objects, in which case the Environment() method will call the specified
1076 elements to update the new construction environment:
1077 def my_tool(env):
1079 env['XYZZY'] = 'xyzzy'
1080 env = Environment(tools = [my_tool])
1082 The individual elements of the tools list may also themselves be two-
1084 element lists of the form (toolname, kw_dict). SCons searches for the
1085 toolname specification file as described above, and passes kw_dict,
1086 which must be a dictionary, as keyword arguments to the tool's generate
1087 function. The generate function can use the arguments to modify the
1088 tool's behavior by setting up the environment in different ways or oth‐
1089 erwise changing its initialization.
1090 # in tools/my_tool.py:
1092 def generate(env, **kw):
1093 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1094 env['MY_TOOL'] = kw.get('arg1', '1')
1095 def exists(env):
1096 return 1
1097 # in SConstruct:
1099 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1100 toolpath=['tools'])
1101 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1103 the environment it receives to customize the tool for different plat‐
1104 forms.
1105 If no tool list is specified, then SCons will auto-detect the installed
1107 tools using the PATH variable in the ENV construction variable and the
1108 platform name when the Environment is constructed. Changing the PATH
1109 variable after the Environment is constructed will not cause the tools
1110 to be redetected.
1111 SCons supports the following tool specifications out of the box:
1113 386asm
1115 aixc++
1116 aixcc
1117 aixf77
1118 aixlink
1119 ar
1120 as
1121 bcc32
1122 c++
1123 cc
1124 cvf
1125 dmd
1126 dvipdf
1127 dvips
1128 f77
1129 f90
1130 f95
1131 fortran
1132 g++
1133 g77
1134 gas
1135 gcc
1136 gfortran
1137 gnulink
1138 gs
1139 hpc++
1140 hpcc
1141 hplink
1142 icc
1143 icl
1144 ifl
1145 ifort
1146 ilink
1147 ilink32
1148 intelc
1149 jar
1150 javac
1151 javah
1152 latex
1153 lex
1154 link
1155 linkloc
1156 m4
1157 masm
1158 midl
1159 mingw
1160 mslib
1161 mslink
1162 mssdk
1163 msvc
1164 msvs
1165 mwcc
1166 mwld
1167 nasm
1168 pdflatex
1169 pdftex
1170 qt
1171 rmic
1172 rpcgen
1173 sgiar
1174 sgic++
1175 sgicc
1176 sgilink
1177 sunar
1178 sunc++
1179 suncc
1180 sunf77
1181 sunf90
1182 sunf95
1183 sunlink
1184 swig
1185 tar
1186 tex
1187 textfile
1188 tlib
1189 yacc
1190 zip
1191 Additionally, there is a "tool" named default which configures the
1193 environment with a default set of tools for the current platform.
1194 On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by
1196 SCons, on Windows the Microsoft tools (e.g. msvc) followed by MinGW are
1197 preferred by SCons, and in OS/2 the IBM tools (e.g. icc) are preferred
1198 by SCons.
1199 Builder Methods
1202 Build rules are specified by calling a construction environment's
1203 builder methods. The arguments to the builder methods are target (a
1204 list of targets to be built, usually file names) and source (a list of
1205 sources to be built, usually file names).
1206 Because long lists of file names can lead to a lot of quoting, scons
1208 supplies a Split() global function and a same-named environment method
1209 that split a single string into a list, separated on strings of white-
1210 space characters. (These are similar to the split() member function of
1211 Python strings but work even if the input isn't a string.)
1212 Like all Python arguments, the target and source arguments to a builder
1214 method can be specified either with or without the "target" and
1215 "source" keywords. When the keywords are omitted, the target is first,
1216 followed by the source. The following are equivalent examples of call‐
1217 ing the Program builder method:
1218 env.Program('bar', ['bar.c', 'foo.c'])
1220 env.Program('bar', Split('bar.c foo.c'))
1221 env.Program('bar', env.Split('bar.c foo.c'))
1222 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
1223 env.Program(target = 'bar', Split('bar.c foo.c'))
1224 env.Program(target = 'bar', env.Split('bar.c foo.c'))
1225 env.Program('bar', source = 'bar.c foo.c'.split())
1226 Target and source file names that are not absolute path names (that is,
1228 do not begin with / on POSIX systems or on Windows systems, with or
1229 without an optional drive letter) are interpreted relative to the
1230 directory containing the SConscript file being read. An initial #
1231 (hash mark) on a path name means that the rest of the file name is
1232 interpreted relative to the directory containing the top-level SCon‐
1233 struct file, even if the # is followed by a directory separator charac‐
1234 ter (slash or backslash).
1235 Examples:
1237 # The comments describing the targets that will be built
1239 # assume these calls are in a SConscript file in the
1240 # a subdirectory named "subdir".
1241 # Builds the program "subdir/foo" from "subdir/foo.c":
1243 env.Program('foo', 'foo.c')
1244 # Builds the program "/tmp/bar" from "subdir/bar.c":
1246 env.Program('/tmp/bar', 'bar.c')
1247 # An initial '#' or '#/' are equivalent; the following
1249 # calls build the programs "foo" and "bar" (in the
1250 # top-level SConstruct directory) from "subdir/foo.c" and
1251 # "subdir/bar.c", respectively:
1252 env.Program('#foo', 'foo.c')
1253 env.Program('#/bar', 'bar.c')
1254 # Builds the program "other/foo" (relative to the top-level
1256 # SConstruct directory) from "subdir/foo.c":
1257 env.Program('#other/foo', 'foo.c')
1258 When the target shares the same base name as the source and only the
1260 suffix varies, and if the builder method has a suffix defined for the
1261 target file type, then the target argument may be omitted completely,
1262 and scons will deduce the target file name from the source file name.
1263 The following examples all build the executable program bar (on POSIX
1264 systems) or bar.exe (on Windows systems) from the bar.c source file:
1265 env.Program(target = 'bar', source = 'bar.c')
1267 env.Program('bar', source = 'bar.c')
1268 env.Program(source = 'bar.c')
1269 env.Program('bar.c')
1270 As a convenience, a srcdir keyword argument may be specified when call‐
1272 ing a Builder. When specified, all source file strings that are not
1273 absolute paths will be interpreted relative to the specified srcdir.
1274 The following example will build the build/prog (or build/prog.exe on
1275 Windows) program from the files src/f1.c and src/f2.c:
1276 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
1278 It is possible to override or add construction variables when calling a
1280 builder method by passing additional keyword arguments. These overrid‐
1281 den or added variables will only be in effect when building the target,
1282 so they will not affect other parts of the build. For example, if you
1283 want to add additional libraries for just one program:
1284 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
1286 or generate a shared library with a non-standard suffix:
1288 env.SharedLibrary('word', 'word.cpp',
1290 SHLIBSUFFIX='.ocx',
1291 LIBSUFFIXES=['.ocx'])
1292 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
1294 if you want SCons to search automatically for dependencies on the non-
1295 standard library names; see the descriptions of these variables, below,
1296 for more information.)
1297 It is also possible to use the parse_flags keyword argument in an over‐
1299 ride:
1300 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
1302 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
1304 to LIBS.
1305 Although the builder methods defined by scons are, in fact, methods of
1307 a construction environment object, they may also be called without an
1308 explicit environment:
1309 Program('hello', 'hello.c')
1311 SharedLibrary('word', 'word.cpp')
1312 In this case, the methods are called internally using a default con‐
1314 struction environment that consists of the tools and values that scons
1315 has determined are appropriate for the local system.
1316 Builder methods that can be called without an explicit environment may
1318 be called from custom Python modules that you import into an SConscript
1319 file by adding the following to the Python module:
1320 from SCons.Script import *
1322 All builder methods return a list-like object containing Nodes that
1324 represent the target or targets that will be built. A Node is an
1325 internal SCons object which represents build targets or sources.
1326 The returned Node-list object can be passed to other builder methods as
1328 source(s) or passed to any SCons function or method where a filename
1329 would normally be accepted. For example, if it were necessary to add a
1330 specific -D flag when compiling one specific object file:
1331 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1333 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
1334 Using a Node in this way makes for a more portable build by avoiding
1336 having to specify a platform-specific object suffix when calling the
1337 Program() builder method.
1338 Note that Builder calls will automatically "flatten" the source and
1340 target file lists, so it's all right to have the bar_obj list return by
1341 the StaticObject() call in the middle of the source file list. If you
1342 need to manipulate a list of lists returned by Builders directly using
1343 Python, you can either build the list by hand:
1344 foo = Object('foo.c')
1346 bar = Object('bar.c')
1347 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
1348 for object in objects:
1349 print str(object)
1350 Or you can use the Flatten() function supplied by scons to create a
1352 list containing just the Nodes, which may be more convenient:
1353 foo = Object('foo.c')
1355 bar = Object('bar.c')
1356 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
1357 for object in objects:
1358 print str(object)
1359 Note also that because Builder calls return a list-like object, not an
1361 actual Python list, you should not use the Python += operator to append
1362 Builder results to a Python list. Because the list and the object are
1363 different types, Python will not update the original list in place, but
1364 will instead create a new Node-list object containing the concatenation
1365 of the list elements and the Builder results. This will cause problems
1366 for any other Python variables in your SCons configuration that still
1367 hold on to a reference to the original list. Instead, use the Python
1368 .extend() method to make sure the list is updated in-place. Example:
1369 object_files = []
1371 # Do NOT use += as follows:
1373 #
1374 # object_files += Object('bar.c')
1375 #
1376 # It will not update the object_files list in place.
1377 #
1378 # Instead, use the .extend() method:
1379 object_files.extend(Object('bar.c'))
1380 The path name for a Node's file may be used by passing the Node to the
1383 Python-builtin str() function:
1384 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
1386 print "The path to bar_obj is:", str(bar_obj_list[0])
1387 Note again that because the Builder call returns a list, we have to
1389 access the first element in the list (bar_obj_list[0]) to get at the
1390 Node that actually represents the object file.
1391 Builder calls support a chdir keyword argument that specifies that the
1393 Builder's action(s) should be executed after changing directory. If
1394 the chdir argument is a string or a directory Node, scons will change
1395 to the specified directory. If the chdir is not a string or Node and
1396 is non-zero, then scons will change to the target file's directory.
1397 # scons will change to the "sub" subdirectory
1399 # before executing the "cp" command.
1400 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1401 "cp dir/foo.in dir/foo.out",
1402 chdir='sub')
1403 # Because chdir is not a string, scons will change to the
1405 # target's directory ("sub/dir") before executing the
1406 # "cp" command.
1407 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
1408 "cp foo.in foo.out",
1409 chdir=1)
1410 Note that scons will not automatically modify its expansion of con‐
1412 struction variables like $TARGET and $SOURCE when using the chdir key‐
1413 word argument--that is, the expanded file names will still be relative
1414 to the top-level SConstruct directory, and consequently incorrect rela‐
1415 tive to the chdir directory. If you use the chdir keyword argument,
1416 you will typically need to supply a different command line using expan‐
1417 sions like ${TARGET.file} and ${SOURCE.file} to use just the filename
1418 portion of the targets and source.
1419 scons provides the following builder methods:
1421 CFile()
1425 env.CFile()
1427 Builds a C source file given a lex (.l) or yacc (.y) input file.
1428 The suffix specified by the $CFILESUFFIX construction variable
1429 (.c by default) is automatically added to the target if it is
1430 not already present. Example:
1431 # builds foo.c
1433 env.CFile(target = 'foo.c', source = 'foo.l')
1434 # builds bar.c
1435 env.CFile(target = 'bar', source = 'bar.y')
1436 Command()
1439 env.Command()
1441 The Command() "Builder" is actually implemented as a function
1442 that looks like a Builder, but actually takes an additional
1443 argument of the action from which the Builder should be made.
1444 See the Command() function description for the calling syntax
1445 and details.
1446 CXXFile()
1449 env.CXXFile()
1451 Builds a C++ source file given a lex (.ll) or yacc (.yy) input
1452 file. The suffix specified by the $CXXFILESUFFIX construction
1453 variable (.cc by default) is automatically added to the target
1454 if it is not already present. Example:
1455 # builds foo.cc
1457 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1458 # builds bar.cc
1459 env.CXXFile(target = 'bar', source = 'bar.yy')
1460 DVI()
1463 env.DVI()
1465 Builds a .dvi file from a .tex, .ltx or .latex input file. If
1466 the source file suffix is .tex, scons will examine the contents
1467 of the file; if the string ocumentclass or ocumentstyle is
1468 found, the file is assumed to be a LaTeX file and the target is
1469 built by invoking the $LATEXCOM command line; otherwise, the
1470 $TEXCOM command line is used. If the file is a LaTeX file, the
1471 DVI() builder method will also examine the contents of the .aux
1472 file and invoke the $BIBTEX command line if the string bibdata
1473 is found, start $MAKEINDEX to generate an index if a .ind file
1474 is found and will examine the contents .log file and re-run the
1475 $LATEXCOM command if the log file says it is necessary.
1476 The suffix .dvi (hard-coded within TeX itself) is automatically
1478 added to the target if it is not already present. Examples:
1479 # builds from aaa.tex
1481 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1482 # builds bbb.dvi
1483 env.DVI(target = 'bbb', source = 'bbb.ltx')
1484 # builds from ccc.latex
1485 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1486 Install()
1489 env.Install()
1491 Installs one or more source files or directories in the speci‐
1492 fied target, which must be a directory. The names of the speci‐
1493 fied source files or directories remain the same within the des‐
1494 tination directory.
1495 env.Install('/usr/local/bin', source = ['foo', 'bar'])
1497 InstallAs()
1500 env.InstallAs()
1502 Installs one or more source files or directories to specific
1503 names, allowing changing a file or directory name as part of the
1504 installation. It is an error if the target and source arguments
1505 list different numbers of files or directories.
1506 env.InstallAs(target = '/usr/local/bin/foo',
1508 source = 'foo_debug')
1509 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
1510 source = ['libFOO.a', 'libBAR.a'])
1511 Jar()
1514 env.Jar()
1516 Builds a Java archive (.jar) file from the specified list of
1517 sources. Any directories in the source list will be searched
1518 for .class files). Any .java files in the source list will be
1519 compiled to .class files by calling the Java() Builder.
1520 If the $JARCHDIR value is set, the jar command will change to
1522 the specified directory using the -C option. If $JARCHDIR is
1523 not set explicitly, &SCons; will use the top of any subdirectory
1524 tree in which Java .class were built by the Java() Builder.
1525 If the contents any of the source files begin with the string
1527 Manifest-Version, the file is assumed to be a manifest and is
1528 passed to the jar command with the m option set.
1529 env.Jar(target = 'foo.jar', source = 'classes')
1531 env.Jar(target = 'bar.jar',
1533 source = ['bar1.java', 'bar2.java'])
1534 Java()
1537 env.Java()
1539 Builds one or more Java class files. The sources may be any
1540 combination of explicit .java files, or directory trees which
1541 will be scanned for .java files.
1542 SCons will parse each source .java file to find the classes
1544 (including inner classes) defined within that file, and from
1545 that figure out the target .class files that will be created.
1546 The class files will be placed underneath the specified target
1547 directory.
1548 SCons will also search each Java file for the Java package name,
1550 which it assumes can be found on a line beginning with the
1551 string package in the first column; the resulting .class files
1552 will be placed in a directory reflecting the specified package
1553 name. For example, the file Foo.java defining a single public
1554 Foo class and containing a package name of sub.dir will generate
1555 a corresponding sub/dir/Foo.class class file.
1556 Examples:
1558 env.Java(target = 'classes', source = 'src')
1560 env.Java(target = 'classes', source = ['src1', 'src2'])
1561 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
1562 Java source files can use the native encoding for the underlying
1564 OS. Since SCons compiles in simple ASCII mode by default, the
1565 compiler will generate warnings about unmappable characters,
1566 which may lead to errors as the file is processed further. In
1567 this case, the user must specify the LANG environment variable
1568 to tell the compiler what encoding is used. For portibility,
1569 it's best if the encoding is hard-coded so that the compile will
1570 work if it is done on a system with a different encoding.
1571 env = Environment()
1573 env['ENV']['LANG'] = 'en_GB.UTF-8'
1574 JavaH()
1577 env.JavaH()
1579 Builds C header and source files for implementing Java native
1580 methods. The target can be either a directory in which the
1581 header files will be written, or a header file name which will
1582 contain all of the definitions. The source can be the names of
1583 .class files, the names of .java files to be compiled into
1584 .class files by calling the Java() builder method, or the
1585 objects returned from the Java() builder method.
1586 If the construction variable $JAVACLASSDIR is set, either in the
1588 environment or in the call to the JavaH() builder method itself,
1589 then the value of the variable will be stripped from the begin‐
1590 ning of any .class file names.
1591 Examples:
1593 # builds java_native.h
1595 classes = env.Java(target = 'classdir', source = 'src')
1596 env.JavaH(target = 'java_native.h', source = classes)
1597 # builds include/package_foo.h and include/package_bar.h
1599 env.JavaH(target = 'include',
1600 source = ['package/foo.class', 'package/bar.class'])
1601 # builds export/foo.h and export/bar.h
1603 env.JavaH(target = 'export',
1604 source = ['classes/foo.class', 'classes/bar.class'],
1605 JAVACLASSDIR = 'classes')
1606 Library()
1609 env.Library()
1611 A synonym for the StaticLibrary() builder method.
1612 LoadableModule()
1615 env.LoadableModule()
1617 On most systems, this is the same as SharedLibrary(). On Mac OS
1618 X (Darwin) platforms, this creates a loadable module bundle.
1619 M4()
1622 env.M4()
1624 Builds an output file from an M4 input file. This uses a
1625 default $M4FLAGS value of -E, which considers all warnings to be
1626 fatal and stops on the first warning when using the GNU version
1627 of m4. Example:
1628 env.M4(target = 'foo.c', source = 'foo.c.m4')
1630 Moc()
1633 env.Moc()
1635 Builds an output file from a moc input file. Moc input files are
1636 either header files or cxx files. This builder is only available
1637 after using the tool 'qt'. See the $QTDIR variable for more
1638 information. Example:
1639 env.Moc('foo.h') # generates moc_foo.cc
1641 env.Moc('foo.cpp') # generates foo.moc
1642 MSVSProject()
1645 env.MSVSProject()
1647 Builds a Microsoft Visual Studio project file, and by default
1648 builds a solution file as well.
1649 This builds a Visual Studio project file, based on the version
1651 of Visual Studio that is configured (either the latest installed
1652 version, or the version specified by $MSVS_VERSION in the Envi‐
1653 ronment constructor). For Visual Studio 6, it will generate a
1654 .dsp file. For Visual Studio 7 (.NET) and later versions, it
1655 will generate a .vcproj file.
1656 By default, this also generates a solution file for the speci‐
1658 fied project, a .dsw file for Visual Studio 6 or a .sln file for
1659 Visual Studio 7 (.NET). This behavior may be disabled by speci‐
1660 fying auto_build_solution=0 when you call MSVSProject(), in
1661 which case you presumably want to build the solution file(s) by
1662 calling the MSVSSolution() Builder (see below).
1663 The MSVSProject() builder takes several lists of filenames to be
1665 placed into the project file. These are currently limited to
1666 srcs, incs, localincs, resources, and misc. These are pretty
1667 self-explanatory, but it should be noted that these lists are
1668 added to the $SOURCES construction variable as strings, NOT as
1669 SCons File Nodes. This is because they represent file names to
1670 be added to the project file, not the source files used to build
1671 the project file.
1672 The above filename lists are all optional, although at least one
1674 must be specified for the resulting project file to be non-
1675 empty.
1676 In addition to the above lists of values, the following values
1678 may be specified:
1679 target: The name of the target .dsp or .vcproj file. The cor‐
1681 rect suffix for the version of Visual Studio must be used, but
1682 the $MSVSPROJECTSUFFIX construction variable will be defined to
1683 the correct value (see example below).
1684 variant: The name of this particular variant. For Visual Studio
1686 7 projects, this can also be a list of variant names. These are
1687 typically things like "Debug" or "Release", but really can be
1688 anything you want. For Visual Studio 7 projects, they may also
1689 specify a target platform separated from the variant name by a |
1690 (vertical pipe) character: Debug|Xbox. The default target plat‐
1691 form is Win32. Multiple calls to MSVSProject() with different
1692 variants are allowed; all variants will be added to the project
1693 file with their appropriate build targets and sources.
1694 buildtarget: An optional string, node, or list of strings or
1696 nodes (one per build variant), to tell the Visual Studio debug‐
1697 ger what output target to use in what build variant. The number
1698 of buildtarget entries must match the number of variant entries.
1699 runfile: The name of the file that Visual Studio 7 and later
1701 will run and debug. This appears as the value of the Output
1702 field in the resutling Visual Studio project file. If this is
1703 not specified, the default is the same as the specified build‐
1704 target value.
1705 Note that because &SCons; always executes its build commands
1707 from the directory in which the SConstruct file is located, if
1708 you generate a project file in a different directory than the
1709 SConstruct directory, users will not be able to double-click on
1710 the file name in compilation error messages displayed in the
1711 Visual Studio console output window. This can be remedied by
1712 adding the Visual C/C++ /FC compiler option to the $CCFLAGS
1713 variable so that the compiler will print the full path name of
1714 any files that cause compilation errors.
1715 Example usage:
1717 barsrcs = ['bar.cpp'],
1719 barincs = ['bar.h'],
1720 barlocalincs = ['StdAfx.h']
1721 barresources = ['bar.rc','resource.h']
1722 barmisc = ['bar_readme.txt']
1723 dll = env.SharedLibrary(target = 'bar.dll',
1725 source = barsrcs)
1726 env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
1728 srcs = barsrcs,
1729 incs = barincs,
1730 localincs = barlocalincs,
1731 resources = barresources,
1732 misc = barmisc,
1733 buildtarget = dll,
1734 variant = 'Release')
1735 MSVSSolution()
1738 env.MSVSSolution()
1740 Builds a Microsoft Visual Studio solution file.
1741 This builds a Visual Studio solution file, based on the version
1743 of Visual Studio that is configured (either the latest installed
1744 version, or the version specified by $MSVS_VERSION in the con‐
1745 struction environment). For Visual Studio 6, it will generate a
1746 .dsw file. For Visual Studio 7 (.NET), it will generate a .sln
1747 file.
1748 The following values must be specified:
1750 target: The name of the target .dsw or .sln file. The correct
1752 suffix for the version of Visual Studio must be used, but the
1753 value $MSVSSOLUTIONSUFFIX will be defined to the correct value
1754 (see example below).
1755 variant: The name of this particular variant, or a list of vari‐
1757 ant names (the latter is only supported for MSVS 7 solutions).
1758 These are typically things like "Debug" or "Release", but really
1759 can be anything you want. For MSVS 7 they may also specify tar‐
1760 get platform, like this "Debug|Xbox". Default platform is Win32.
1761 projects: A list of project file names, or Project nodes
1763 returned by calls to the MSVSProject() Builder, to be placed
1764 into the solution file. It should be noted that these file
1765 names are NOT added to the $SOURCES environment variable in form
1766 of files, but rather as strings. This is because they repre‐
1767 sent file names to be added to the solution file, not the source
1768 files used to build the solution file.
1769 Example Usage:
1771 env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'],
1773 projects = ['bar' + env['MSVSPROJECTSUFFIX']],
1774 variant = 'Release')
1775 Object()
1778 env.Object()
1780 A synonym for the StaticObject() builder method.
1781 Package()
1784 env.Package()
1786 Builds software distribution packages. Packages consist of
1787 files to install and packaging information. The former may be
1788 specified with the source parameter and may be left out, in
1789 which case the &FindInstalledFiles; function will collect all
1790 files that have an Install() or InstallAs() Builder attached.
1791 If the target is not specified it will be deduced from addi‐
1792 tional information given to this Builder.
1793 The packaging information is specified with the help of con‐
1795 struction variables documented below. This information is
1796 called a tag to stress that some of them can also be attached to
1797 files with the &Tag; function. The mandatory ones will complain
1798 if they were not specified. They vary depending on chosen tar‐
1799 get packager.
1800 The target packager may be selected with the "PACKAGETYPE" com‐
1802 mand line option or with the $PACKAGETYPE construction variable.
1803 Currently the following packagers available:
1804 * msi - Microsoft Installer
1806 * rpm - Redhat Package Manger
1807 * ipkg - Itsy Package Management System
1808 * tarbz2 - compressed tar
1809 * targz - compressed tar
1810 * zip - zip file
1811 * src_tarbz2 - compressed tar source
1812 * src_targz - compressed tar source
1813 * src_zip - zip file source
1814 An updated list is always available under the "package_type"
1816 option when running "scons --help" on a project that has packag‐
1817 ing activated.
1818 env = Environment(tools=['default', 'packaging'])
1819 env.Install('/bin/', 'my_program')
1820 env.Package( NAME = 'foo',
1821 VERSION = '1.2.3',
1822 PACKAGEVERSION = 0,
1823 PACKAGETYPE = 'rpm',
1824 LICENSE = 'gpl',
1825 SUMMARY = 'balalalalal',
1826 DESCRIPTION = 'this should be really really long',
1827 X_RPM_GROUP = 'Application/fu',
1828 SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
1829 )
1830 PCH()
1833 env.PCH()
1835 Builds a Microsoft Visual C++ precompiled header. Calling this
1836 builder method returns a list of two targets: the PCH as the
1837 first element, and the object file as the second element. Nor‐
1838 mally the object file is ignored. This builder method is only
1839 provided when Microsoft Visual C++ is being used as the com‐
1840 piler. The PCH builder method is generally used in conjuction
1841 with the PCH construction variable to force object files to use
1842 the precompiled header:
1843 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1845 PDF()
1848 env.PDF()
1850 Builds a .pdf file from a .dvi input file (or, by extension, a
1851 .tex, .ltx, or .latex input file). The suffix specified by the
1852 $PDFSUFFIX construction variable (.pdf by default) is added
1853 automatically to the target if it is not already present. Exam‐
1854 ple:
1855 # builds from aaa.tex
1857 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1858 # builds bbb.pdf from bbb.dvi
1859 env.PDF(target = 'bbb', source = 'bbb.dvi')
1860 PostScript()
1863 env.PostScript()
1865 Builds a .ps file from a .dvi input file (or, by extension, a
1866 .tex, .ltx, or .latex input file). The suffix specified by the
1867 $PSSUFFIX construction variable (.ps by default) is added auto‐
1868 matically to the target if it is not already present. Example:
1869 # builds from aaa.tex
1871 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1872 # builds bbb.ps from bbb.dvi
1873 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1874 Program()
1877 env.Program()
1879 Builds an executable given one or more object files or C, C++,
1880 D, or Fortran source files. If any C, C++, D or Fortran source
1881 files are specified, then they will be automatically compiled to
1882 object files using the Object() builder method; see that builder
1883 method's description for a list of legal source file suffixes
1884 and how they are interpreted. The target executable file prefix
1885 (specified by the $PROGPREFIX construction variable; nothing by
1886 default) and suffix (specified by the $PROGSUFFIX construction
1887 variable; by default, .exe on Windows systems, nothing on POSIX
1888 systems) are automatically added to the target if not already
1889 present. Example:
1890 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1892 RES()
1895 env.RES()
1897 Builds a Microsoft Visual C++ resource file. This builder
1898 method is only provided when Microsoft Visual C++ or MinGW is
1899 being used as the compiler. The .res (or .o for MinGW) suffix is
1900 added to the target name if no other suffix is given. The
1901 source file is scanned for implicit dependencies as though it
1902 were a C file. Example:
1903 env.RES('resource.rc')
1905 RMIC()
1908 env.RMIC()
1910 Builds stub and skeleton class files for remote objects from
1911 Java .class files. The target is a directory relative to which
1912 the stub and skeleton class files will be written. The source
1913 can be the names of .class files, or the objects return from the
1914 Java() builder method.
1915 If the construction variable $JAVACLASSDIR is set, either in the
1917 environment or in the call to the RMIC() builder method itself,
1918 then the value of the variable will be stripped from the begin‐
1919 ning of any .class file names.
1920 classes = env.Java(target = 'classdir', source = 'src')
1922 env.RMIC(target = 'outdir1', source = classes)
1923 env.RMIC(target = 'outdir2',
1925 source = ['package/foo.class', 'package/bar.class'])
1926 env.RMIC(target = 'outdir3',
1928 source = ['classes/foo.class', 'classes/bar.class'],
1929 JAVACLASSDIR = 'classes')
1930 RPCGenClient()
1933 env.RPCGenClient()
1935 Generates an RPC client stub (_clnt.c) file from a specified RPC
1936 (.x) source file. Because rpcgen only builds output files in
1937 the local directory, the command will be executed in the source
1938 file's directory by default.
1939 # Builds src/rpcif_clnt.c
1941 env.RPCGenClient('src/rpcif.x')
1942 RPCGenHeader()
1945 env.RPCGenHeader()
1947 Generates an RPC header (.h) file from a specified RPC (.x)
1948 source file. Because rpcgen only builds output files in the
1949 local directory, the command will be executed in the source
1950 file's directory by default.
1951 # Builds src/rpcif.h
1953 env.RPCGenHeader('src/rpcif.x')
1954 RPCGenService()
1957 env.RPCGenService()
1959 Generates an RPC server-skeleton (_svc.c) file from a specified
1960 RPC (.x) source file. Because rpcgen only builds output files
1961 in the local directory, the command will be executed in the
1962 source file's directory by default.
1963 # Builds src/rpcif_svc.c
1965 env.RPCGenClient('src/rpcif.x')
1966 RPCGenXDR()
1969 env.RPCGenXDR()
1971 Generates an RPC XDR routine (_xdr.c) file from a specified RPC
1972 (.x) source file. Because rpcgen only builds output files in
1973 the local directory, the command will be executed in the source
1974 file's directory by default.
1975 # Builds src/rpcif_xdr.c
1977 env.RPCGenClient('src/rpcif.x')
1978 SharedLibrary()
1981 env.SharedLibrary()
1983 Builds a shared library (.so on a POSIX system, .dll on Windows)
1984 given one or more object files or C, C++, D or Fortran source
1985 files. If any source files are given, then they will be auto‐
1986 matically compiled to object files. The static library prefix
1987 and suffix (if any) are automatically added to the target. The
1988 target library file prefix (specified by the $SHLIBPREFIX con‐
1989 struction variable; by default, lib on POSIX systems, nothing on
1990 Windows systems) and suffix (specified by the $SHLIBSUFFIX con‐
1991 struction variable; by default, .dll on Windows systems, .so on
1992 POSIX systems) are automatically added to the target if not
1993 already present. Example:
1994 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1996 On Windows systems, the SharedLibrary() builder method will
1998 always build an import (.lib) library in addition to the shared
1999 (.dll) library, adding a .lib library with the same basename if
2000 there is not already a .lib file explicitly listed in the tar‐
2001 gets.
2002 Any object files listed in the source must have been built for a
2004 shared library (that is, using the SharedObject() builder
2005 method). scons will raise an error if there is any mismatch.
2006 On some platforms, there is a distinction between a shared
2008 library (loaded automatically by the system to resolve external
2009 references) and a loadable module (explicitly loaded by user
2010 action). For maximum portability, use the LoadableModule()
2011 builder for the latter.
2012 On Windows systems, specifying register=1 will cause the .dll to
2014 be registered after it is built using REGSVR32. The command
2015 that is run ("regsvr32" by default) is determined by $REGSVR
2016 construction variable, and the flags passed are determined by
2017 $REGSVRFLAGS. By default, $REGSVRFLAGS includes the /s option,
2018 to prevent dialogs from popping up and requiring user attention
2019 when it is run. If you change $REGSVRFLAGS, be sure to include
2020 the /s option. For example,
2021 env.SharedLibrary(target = 'bar',
2023 source = ['bar.cxx', 'foo.obj'],
2024 register=1)
2025 will register bar.dll as a COM object when it is done linking
2027 it.
2028 SharedObject()
2031 env.SharedObject()
2033 Builds an object file for inclusion in a shared library. Source
2034 files must have one of the same set of extensions specified
2035 above for the StaticObject() builder method. On some platforms
2036 building a shared object requires additional compiler option
2037 (e.g. -fPIC for gcc) in addition to those needed to build a nor‐
2038 mal (static) object, but on some platforms there is no differ‐
2039 ence between a shared object and a normal (static) one. When
2040 there is a difference, SCons will only allow shared objects to
2041 be linked into a shared library, and will use a different suffix
2042 for shared objects. On platforms where there is no difference,
2043 SCons will allow both normal (static) and shared objects to be
2044 linked into a shared library, and will use the same suffix for
2045 shared and normal (static) objects. The target object file pre‐
2046 fix (specified by the $SHOBJPREFIX construction variable; by
2047 default, the same as $OBJPREFIX) and suffix (specified by the
2048 $SHOBJSUFFIX construction variable) are automatically added to
2049 the target if not already present. Examples:
2050 env.SharedObject(target = 'ddd', source = 'ddd.c')
2052 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
2053 env.SharedObject(target = 'fff.obj', source = 'fff.for')
2054 Note that the source files will be scanned according to the suf‐
2056 fix mappings in the SourceFileScanner object. See the section
2057 "Scanner Objects," below, for more information.
2058 StaticLibrary()
2061 env.StaticLibrary()
2063 Builds a static library given one or more object files or C,
2064 C++, D or Fortran source files. If any source files are given,
2065 then they will be automatically compiled to object files. The
2066 static library prefix and suffix (if any) are automatically
2067 added to the target. The target library file prefix (specified
2068 by the $LIBPREFIX construction variable; by default, lib on
2069 POSIX systems, nothing on Windows systems) and suffix (specified
2070 by the $LIBSUFFIX construction variable; by default, .lib on
2071 Windows systems, .a on POSIX systems) are automatically added to
2072 the target if not already present. Example:
2073 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
2075 Any object files listed in the source must have been built for a
2077 static library (that is, using the StaticObject() builder
2078 method). scons will raise an error if there is any mismatch.
2079 StaticObject()
2082 env.StaticObject()
2084 Builds a static object file from one or more C, C++, D, or For‐
2085 tran source files. Source files must have one of the following
2086 extensions:
2087 .asm assembly language file
2089 .ASM assembly language file
2090 .c C file
2091 .C Windows: C file
2092 POSIX: C++ file
2093 .cc C++ file
2094 .cpp C++ file
2095 .cxx C++ file
2096 .cxx C++ file
2097 .c++ C++ file
2098 .C++ C++ file
2099 .d D file
2100 .f Fortran file
2101 .F Windows: Fortran file
2102 POSIX: Fortran file + C pre-processor
2103 .for Fortran file
2104 .FOR Fortran file
2105 .fpp Fortran file + C pre-processor
2106 .FPP Fortran file + C pre-processor
2107 .m Object C file
2108 .mm Object C++ file
2109 .s assembly language file
2110 .S Windows: assembly language file
2111 ARM: CodeSourcery Sourcery Lite
2112 .sx assembly language file + C pre-processor
2113 POSIX: assembly language file + C pre-processor
2114 .spp assembly language file + C pre-processor
2115 .SPP assembly language file + C pre-processor
2116 The target object file prefix (specified by the $OBJPREFIX con‐
2118 struction variable; nothing by default) and suffix (specified by
2119 the $OBJSUFFIX construction variable; .obj on Windows systems,
2120 .o on POSIX systems) are automatically added to the target if
2121 not already present. Examples:
2122 env.StaticObject(target = 'aaa', source = 'aaa.c')
2124 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
2125 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
2126 Note that the source files will be scanned according to the suf‐
2128 fix mappings in SourceFileScanner object. See the section
2129 "Scanner Objects," below, for more information.
2130 Substfile()
2133 env.Substfile()
2135 The Substfile() builder generates a single text file by concate‐
2136 nating the source files. Nested lists of sources are flattened.
2137 $LINESEPARATOR is used to separate the source files; see the
2138 description of Textfile() for details.
2139 If a single source file is present with an .in suffix, the suf‐
2141 fix is stripped and the remainder is used as the default target
2142 name.
2143 The prefix and suffix specified by the $SUBSTFILEPREFIX and
2145 $SUBSTFILESUFFIX construction variables (the null string by
2146 default in both cases) are automatically added to the target if
2147 they are not already present.
2148 If a construction variable named $SUBST_DICT is present, it may
2150 be either a Python dictionary or a sequence of (key,value)
2151 tuples. If the former, the dictionary is converted into a list
2152 of tuples in an arbitrary order, so if one key is a prefix of
2153 another key or if one substitution could be further expanded by
2154 another subsitition, it is unpredictible whether the expansion
2155 will occur.
2156 Any occurences in the source of a key are replaced by the corre‐
2158 sponding value, which may be a Python callable function or a
2159 string. If a value is a function, it is first called (with no
2160 arguments) to produce a string. The string is subst-expanded
2161 and the result replaces the key.
2162 env = Environment(tools = ['default', 'textfile'])
2164 env['prefix'] = '/usr/bin'
2166 script_dict = {'@prefix@': '/bin', @exec_prefix@: '$prefix'}
2167 env.Substfile('script.in', SUBST_DICT = script_dict)
2168 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
2170 env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
2171 # UNPREDICTABLE - one key is a prefix of another
2173 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
2174 env.Substfile('foo.in', SUBST_DICT = bad_foo)
2175 # PREDICTABLE - keys are applied longest first
2177 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
2178 env.Substfile('foo.in', SUBST_DICT = good_foo)
2179 # UNPREDICTABLE - one substitution could be futher expanded
2181 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
2182 env.Substfile('bar.in', SUBST_DICT = bad_bar)
2183 # PREDICTABLE - substitutions are expanded in order
2185 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
2186 env.Substfile('bar.in', SUBST_DICT = good_bar)
2187 # the SUBST_DICT may be in common (and not an override)
2189 substutions = {}
2190 subst = Environment(tools = ['textfile', SUBST_DICT = substitutions)
2191 substitutions['@foo@'] = 'foo'
2192 subst['SUBST_DICT']['@bar@'] = 'bar'
2193 subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
2194 Value('#include "@bar@.h"'),
2195 "common.in",
2196 "pgm1.in"
2197 ])
2198 subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
2199 Value('#include "@bar@.h"'),
2200 "common.in",
2201 "pgm2.in"
2202 ])
2203 Tar()
2207 env.Tar()
2209 Builds a tar archive of the specified files and/or directories.
2210 Unlike most builder methods, the Tar() builder method may be
2211 called multiple times for a given target; each additional call
2212 adds to the list of entries that will be built into the archive.
2213 Any source directories will be scanned for changes to any on-
2214 disk files, regardless of whether or not scons knows about them
2215 from other Builder or function calls.
2216 env.Tar('src.tar', 'src')
2218 # Create the stuff.tar file.
2220 env.Tar('stuff', ['subdir1', 'subdir2'])
2221 # Also add "another" to the stuff.tar file.
2222 env.Tar('stuff', 'another')
2223 # Set TARFLAGS to create a gzip-filtered archive.
2225 env = Environment(TARFLAGS = '-c -z')
2226 env.Tar('foo.tar.gz', 'foo')
2227 # Also set the suffix to .tgz.
2229 env = Environment(TARFLAGS = '-c -z',
2230 TARSUFFIX = '.tgz')
2231 env.Tar('foo')
2232 Textfile()
2235 env.Textfile()
2237 The Textfile() builder generates a single text file. The source
2238 strings constitute the lines; nested lists of sources are flat‐
2239 tened. $LINESEPARATOR is used to separate the strings.
2240 If present, the $SUBST_DICT construction variable is used to
2242 modify the strings before they are written; see the Substfile()
2243 description for details.
2244 The prefix and suffix specified by the $TEXTFILEPREFIX and
2246 $TEXTFILESUFFIX construction variables (the null string and .txt
2247 by default, respectively) are automatically added to the target
2248 if they are not already present. Examples:
2249 # builds/writes foo.txt
2251 env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
2252 # builds/writes bar.txt
2254 env.Textfile(target = 'bar',
2255 source = ['lalala', 'tanteratei'],
2256 LINESEPARATOR='|*')
2257 # nested lists are flattened automatically
2259 env.Textfile(target = 'blob',
2260 source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
2261 # files may be used as input by wraping them in File()
2263 env.Textfile(target = 'concat', # concatenate files with a marker between
2264 source = [File('concat1'), File('concat2')],
2265 LINESEPARATOR = '====================\n')
2266 Results are:
2268 foo.txt
2269 ....8<----
2270 Goethe
2271 42
2272 Schiller
2273 ....8<---- (no linefeed at the end)
2274 bar.txt:
2276 ....8<----
2277 lalala|*tanteratei
2278 ....8<---- (no linefeed at the end)
2279 blob.txt
2281 ....8<----
2282 lalala
2283 Goethe
2284 42
2285 Schiller
2286 tanteratei
2287 ....8<---- (no linefeed at the end)
2288 TypeLibrary()
2291 env.TypeLibrary()
2293 Builds a Windows type library (.tlb) file from an input IDL file
2294 (.idl). In addition, it will build the associated inteface stub
2295 and proxy source files, naming them according to the base name
2296 of the .idl file. For example,
2297 env.TypeLibrary(source="foo.idl")
2299 Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c
2301 files.
2302 Uic()
2305 env.Uic()
2307 Builds a header file, an implementation file and a moc file from
2308 an ui file. and returns the corresponding nodes in the above
2309 order. This builder is only available after using the tool
2310 'qt'. Note: you can specify .ui files directly as source files
2311 to the Program(), Library() and SharedLibrary() builders without
2312 using this builder. Using this builder lets you override the
2313 standard naming conventions (be careful: prefixes are always
2314 prepended to names of built files; if you don't want prefixes,
2315 you may set them to ``). See the $QTDIR variable for more
2316 information. Example:
2317 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
2319 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
2320 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
2321 Zip()
2324 env.Zip()
2326 Builds a zip archive of the specified files and/or directories.
2327 Unlike most builder methods, the Zip() builder method may be
2328 called multiple times for a given target; each additional call
2329 adds to the list of entries that will be built into the archive.
2330 Any source directories will be scanned for changes to any on-
2331 disk files, regardless of whether or not scons knows about them
2332 from other Builder or function calls.
2333 env.Zip('src.zip', 'src')
2335 # Create the stuff.zip file.
2337 env.Zip('stuff', ['subdir1', 'subdir2'])
2338 # Also add "another" to the stuff.tar file.
2339 env.Zip('stuff', 'another')
2340 All targets of builder methods automatically depend on their sources.
2343 An explicit dependency can be specified using the Depends method of a
2344 construction environment (see below).
2345 In addition, scons automatically scans source files for various pro‐
2347 gramming languages, so the dependencies do not need to be specified
2348 explicitly. By default, SCons can C source files, C++ source files,
2349 Fortran source files with .F (POSIX systems only), .fpp, or .FPP file
2350 extensions, and assembly language files with .S (POSIX systems only),
2351 .spp, or .SPP files extensions for C preprocessor dependencies. SCons
2352 also has default support for scanning D source files, You can also
2353 write your own Scanners to add support for additional source file
2354 types. These can be added to the default Scanner object used by the
2355 Object(), StaticObject(), and SharedObject() Builders by adding them to
2356 the SourceFileScanner object. See the section "Scanner Objects" below,
2357 for more information about defining your own Scanner objects and using
2358 the SourceFileScanner object.
2359 Methods and Functions to Do Things
2362 In addition to Builder methods, scons provides a number of other con‐
2363 struction environment methods and global functions to manipulate the
2364 build configuration.
2365 Usually, a construction environment method and global function with the
2367 same name both exist so that you don't have to remember whether to a
2368 specific bit of functionality must be called with or without a con‐
2369 struction environment. In the following list, if you call something as
2370 a global function it looks like:
2371 Function(arguments)
2372 and if you call something through a construction environment it looks
2373 like:
2374 env.Function(arguments)
2375 If you can call the functionality in both ways, then both forms are
2376 listed.
2377 Global functions may be called from custom Python modules that you
2379 import into an SConscript file by adding the following to the Python
2380 module:
2381 from SCons.Script import *
2383 Except where otherwise noted, the same-named construction environment
2385 method and global function provide the exact same functionality. The
2386 only difference is that, where appropriate, calling the functionality
2387 through a construction environment will substitute construction vari‐
2388 ables into any supplied strings. For example:
2389 env = Environment(FOO = 'foo')
2391 Default('$FOO')
2392 env.Default('$FOO')
2393 In the above example, the first call to the global Default() function
2395 will actually add a target named $FOO to the list of default targets,
2396 while the second call to the env.Default() construction environment
2397 method will expand the value and add a target named foo to the list of
2398 default targets. For more on construction variable expansion, see the
2399 next section on construction variables.
2400 Construction environment methods and global functions supported by
2402 scons include:
2403 Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])
2407 env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])
2409 Creates an Action object for the specified action. See the sec‐
2410 tion "Action Objects," below, for a complete explanation of the
2411 arguments and behavior.
2412 Note that the env.Action() form of the invocation will expand
2414 construction variables in any argument strings, including the
2415 action argument, at the time it is called using the construction
2416 variables in the env construction environment through which
2417 env.Action() was called. The Action() form delays all variable
2418 expansion until the Action object is actually used.
2419 AddMethod(object, function, [name])
2422 env.AddMethod(function, [name])
2424 When called with the AddMethod() form, adds the specified func‐
2425 tion to the specified object as the specified method name. When
2426 called with the env.AddMethod() form, adds the specified func‐
2427 tion to the construction environment env as the specified method
2428 name. In both cases, if name is omitted or None, the name of
2429 the specified function itself is used for the method name.
2430 Examples:
2432 # Note that the first argument to the function to
2434 # be attached as a method must be the object through
2435 # which the method will be called; the Python
2436 # convention is to call it 'self'.
2437 def my_method(self, arg):
2438 print "my_method() got", arg
2439 # Use the global AddMethod() function to add a method
2441 # to the Environment class. This
2442 AddMethod(Environment, my_method)
2443 env = Environment()
2444 env.my_method('arg')
2445 # Add the function as a method, using the function
2447 # name for the method call.
2448 env = Environment()
2449 env.AddMethod(my_method, 'other_method_name')
2450 env.other_method_name('another arg')
2451 AddOption(arguments)
2454 This function adds a new command-line option to be recognized.
2455 The specified arguments are the same as supported by the stan‐
2456 dard Python optparse.add_option() method (with a few additional
2457 capabilities noted below); see the documentation for optparse
2458 for a thorough discussion of its option-processing capabities.
2459 In addition to the arguments and values supported by the opt‐
2461 parse.add_option() method, the SCons AddOption() function allows
2462 you to set the nargs keyword value to '?' (a string with just
2463 the question mark) to indicate that the specified long option(s)
2464 take(s) an optional argument. When nargs = '?' is passed to
2465 the AddOption() function, the const keyword argument may be used
2466 to supply the "default" value that should be used when the
2467 option is specified on the command line without an explicit
2468 argument.
2469 If no default= keyword argument is supplied when calling AddOp‐
2471 tion(), the option will have a default value of None.
2472 Once a new command-line option has been added with AddOption(),
2474 the option value may be accessed using GetOption() or env.GetOp‐
2475 tion(). The value may also be set, using SetOption() or
2476 env.SetOption(), if conditions in a SConscript require overrid‐
2477 ing any default value. Note, however, that a value specified on
2478 the command line will always override a value set by any SCon‐
2479 script file.
2480 Any specified help= strings for the new option(s) will be dis‐
2482 played by the -H or -h options (the latter only if no other help
2483 text is specified in the SConscript files). The help text for
2484 the local options specified by AddOption() will appear below the
2485 SCons options themselves, under a separate Local Options head‐
2486 ing. The options will appear in the help text in the order in
2487 which the AddOption() calls occur.
2488 Example:
2490 AddOption('--prefix',
2492 dest='prefix',
2493 nargs=1, type='string',
2494 action='store',
2495 metavar='DIR',
2496 help='installation prefix')
2497 env = Environment(PREFIX = GetOption('prefix'))
2498 AddPostAction(target, action)
2501 env.AddPostAction(target, action)
2503 Arranges for the specified action to be performed after the
2504 specified target has been built. The specified action(s) may be
2505 an Action object, or anything that can be converted into an
2506 Action object (see below).
2507 When multiple targets are supplied, the action may be called
2509 multiple times, once after each action that generates one or
2510 more targets in the list.
2511 AddPreAction(target, action)
2514 env.AddPreAction(target, action)
2516 Arranges for the specified action to be performed before the
2517 specified target is built. The specified action(s) may be an
2518 Action object, or anything that can be converted into an Action
2519 object (see below).
2520 When multiple targets are specified, the action(s) may be called
2522 multiple times, once before each action that generates one or
2523 more targets in the list.
2524 Note that if any of the targets are built in multiple steps, the
2526 action will be invoked just before the "final" action that
2527 specifically generates the specified target(s). For example,
2528 when building an executable program from a specified source .c
2529 file via an intermediate object file:
2530 foo = Program('foo.c')
2532 AddPreAction(foo, 'pre_action')
2533 The specified pre_action would be executed before scons calls
2535 the link command that actually generates the executable program
2536 binary foo, not before compiling the foo.c file into an object
2537 file.
2538 Alias(alias, [targets, [action]])
2541 env.Alias(alias, [targets, [action]])
2543 Creates one or more phony targets that expand to one or more
2544 other targets. An optional action (command) or list of actions
2545 can be specified that will be executed whenever the any of the
2546 alias targets are out-of-date. Returns the Node object repre‐
2547 senting the alias, which exists outside of any file system.
2548 This Node object, or the alias name, may be used as a dependency
2549 of any other target, including another alias. Alias() can be
2550 called multiple times for the same alias to add additional tar‐
2551 gets to the alias, or additional actions to the list for this
2552 alias.
2553 Examples:
2555 Alias('install')
2557 Alias('install', '/usr/bin')
2558 Alias(['install', 'install-lib'], '/usr/local/lib')
2559 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
2561 env.Alias('install', ['/usr/local/man'])
2562 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
2564 AllowSubstExceptions([exception, ...])
2567 Specifies the exceptions that will be allowed when expanding
2568 construction variables. By default, any construction variable
2569 expansions that generate a NameError or IndexError exception
2570 will expand to a '' (a null string) and not cause scons to fail.
2571 All exceptions not in the specified list will generate an error
2572 message and terminate processing.
2573 If AllowSubstExceptions() is called multiple times, each call
2575 completely overwrites the previous list of allowed exceptions.
2576 Example:
2578 # Requires that all construction variable names exist.
2580 # (You may wish to do this if you want to enforce strictly
2581 # that all construction variables must be defined before use.)
2582 AllowSubstExceptions()
2583 # Also allow a string containing a zero-division expansion
2585 # like '${1 / 0}' to evalute to ''.
2586 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
2587 AlwaysBuild(target, ...)
2590 env.AlwaysBuild(target, ...)
2592 Marks each given target so that it is always assumed to be out
2593 of date, and will always be rebuilt if needed. Note, however,
2594 that AlwaysBuild() does not add its target(s) to the default
2595 target list, so the targets will only be built if they are spec‐
2596 ified on the command line, or are a dependent of a target speci‐
2597 fied on the command line--but they will always be built if so
2598 specified. Multiple targets can be passed in to a single call
2599 to AlwaysBuild().
2600 env.Append(key=val, [...])
2603 Appends the specified keyword arguments to the end of construc‐
2604 tion variables in the environment. If the Environment does not
2605 have the specified construction variable, it is simply added to
2606 the environment. If the values of the construction variable and
2607 the keyword argument are the same type, then the two values will
2608 be simply added together. Otherwise, the construction variable
2609 and the value of the keyword argument are both coerced to lists,
2610 and the lists are added together. (See also the Prepend method,
2611 below.)
2612 Example:
2614 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
2616 env.AppendENVPath(name, newpath, [envname, sep, delete_existing])
2619 This appends new path elements to the given path in the speci‐
2620 fied external environment (ENV by default). This will only add
2621 any particular path once (leaving the last one it encounters and
2622 ignoring the rest, to preserve path order), and to help assure
2623 this, will normalize all paths (using os.path.normpath and
2624 os.path.normcase). This can also handle the case where the
2625 given old path variable is a list instead of a string, in which
2626 case a list will be returned instead of a string.
2627 If delete_existing is 0, then adding a path that already exists
2629 will not move it to the end; it will stay where it is in the
2630 list.
2631 Example:
2633 print 'before:',env['ENV']['INCLUDE']
2635 include_path = '/foo/bar:/foo'
2636 env.AppendENVPath('INCLUDE', include_path)
2637 print 'after:',env['ENV']['INCLUDE']
2638 yields:
2640 before: /foo:/biz
2641 after: /biz:/foo/bar:/foo
2642 env.AppendUnique(key=val, [...], delete_existing=0)
2645 Appends the specified keyword arguments to the end of construc‐
2646 tion variables in the environment. If the Environment does not
2647 have the specified construction variable, it is simply added to
2648 the environment. If the construction variable being appended to
2649 is a list, then any value(s) that already exist in the construc‐
2650 tion variable will not be added again to the list. However, if
2651 delete_existing is 1, existing matching values are removed
2652 first, so existing values in the arg list move to the end of the
2653 list.
2654 Example:
2656 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
2658 env.BitKeeper()
2661 A factory function that returns a Builder object to be used to
2662 fetch source files using BitKeeper. The returned Builder is
2663 intended to be passed to the SourceCode() function.
2664 This function is deprecated. For details, see the entry for the
2666 SourceCode() function.
2667 Example:
2669 env.SourceCode('.', env.BitKeeper())
2671 BuildDir(build_dir, src_dir, [duplicate])
2674 env.BuildDir(build_dir, src_dir, [duplicate])
2676 Deprecated synonyms for VariantDir() and env.VariantDir(). The
2677 build_dir argument becomes the variant_dir argument of Variant‐
2678 Dir() or env.VariantDir().
2679 Builder(action, [arguments])
2682 env.Builder(action, [arguments])
2684 Creates a Builder object for the specified action. See the sec‐
2685 tion "Builder Objects," below, for a complete explanation of the
2686 arguments and behavior.
2687 Note that the env.Builder() form of the invocation will expand
2689 construction variables in any arguments strings, including the
2690 action argument, at the time it is called using the construction
2691 variables in the env construction environment through which
2692 env.Builder() was called. The Builder() form delays all vari‐
2693 able expansion until after the Builder object is actually
2694 called.
2695 CacheDir(cache_dir)
2698 env.CacheDir(cache_dir)
2700 Specifies that scons will maintain a cache of derived files in
2701 cache_dir. The derived files in the cache will be shared among
2702 all the builds using the same CacheDir() call. Specifying a
2703 cache_dir of None disables derived file caching.
2704 Calling env.CacheDir() will only affect targets built through
2706 the specified construction environment. Calling CacheDir() sets
2707 a global default that will be used by all targets built through
2708 construction environments that do not have an env.CacheDir()
2709 specified.
2710 When a CacheDir() is being used and scons finds a derived file
2712 that needs to be rebuilt, it will first look in the cache to see
2713 if a derived file has already been built from identical input
2714 files and an identical build action (as incorporated into the
2715 MD5 build signature). If so, scons will retrieve the file from
2716 the cache. If the derived file is not present in the cache,
2717 scons will rebuild it and then place a copy of the built file in
2718 the cache (identified by its MD5 build signature), so that it
2719 may be retrieved by other builds that need to build the same
2720 derived file from identical inputs.
2721 Use of a specified CacheDir() may be disabled for any invocation
2723 by using the --cache-disable option.
2724 If the --cache-force option is used, scons will place a copy of
2726 all derived files in the cache, even if they already existed and
2727 were not built by this invocation. This is useful to populate a
2728 cache the first time CacheDir() is added to a build, or after
2729 using the --cache-disable option.
2730 When using CacheDir(), scons will report, "Retrieved `file' from
2732 cache," unless the --cache-show option is being used. When the
2733 --cache-show option is used, scons will print the action that
2734 would have been used to build the file, without any indication
2735 that the file was actually retrieved from the cache. This is
2736 useful to generate build logs that are equivalent regardless of
2737 whether a given derived file has been built in-place or
2738 retrieved from the cache.
2739 The NoCache() method can be used to disable caching of specific
2741 files. This can be useful if inputs and/or outputs of some tool
2742 are impossible to predict or prohibitively large.
2743 Clean(targets, files_or_dirs)
2746 env.Clean(targets, files_or_dirs)
2748 This specifies a list of files or directories which should be
2749 removed whenever the targets are specified with the -c command
2750 line option. The specified targets may be a list or an individ‐
2751 ual target. Multiple calls to Clean() are legal, and create new
2752 targets or add files and directories to the clean list for the
2753 specified targets.
2754 Multiple files or directories should be specified either as sep‐
2756 arate arguments to the Clean() method, or as a list. Clean()
2757 will also accept the return value of any of the construction
2758 environment Builder methods. Examples:
2759 The related NoClean() function overrides calling Clean() for the
2761 same target, and any targets passed to both functions will not
2762 be removed by the -c option.
2763 Examples:
2765 Clean('foo', ['bar', 'baz'])
2767 Clean('dist', env.Program('hello', 'hello.c'))
2768 Clean(['foo', 'bar'], 'something_else_to_clean')
2769 In this example, installing the project creates a subdirectory
2771 for the documentation. This statement causes the subdirectory
2772 to be removed if the project is deinstalled.
2773 Clean(docdir, os.path.join(docdir, projectname))
2774 env.Clone([key=val, ...])
2777 Returns a separate copy of a construction environment. If there
2778 are any keyword arguments specified, they are added to the
2779 returned copy, overwriting any existing values for the keywords.
2780 Example:
2782 env2 = env.Clone()
2784 env3 = env.Clone(CCFLAGS = '-g')
2785 Additionally, a list of tools and a toolpath may be specified,
2787 as in the Environment constructor:
2788 def MyTool(env): env['FOO'] = 'bar'
2790 env4 = env.Clone(tools = ['msvc', MyTool])
2791 The parse_flags keyword argument is also recognized:
2793 # create an environment for compiling programs that use wxWidgets
2795 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
2796 Command(target, source, action, [key=val, ...])
2799 env.Command(target, source, action, [key=val, ...])
2801 Executes a specific action (or list of actions) to build a tar‐
2802 get file or files. This is more convenient than defining a sep‐
2803 arate Builder object for a single special-case build.
2804 As a special case, the source_scanner keyword argument can be
2806 used to specify a Scanner object that will be used to scan the
2807 sources. (The global DirScanner object can be used if any of
2808 the sources will be directories that must be scanned on-disk for
2809 changes to files that aren't already specified in other Builder
2810 of function calls.)
2811 Any other keyword arguments specified override any same-named
2813 existing construction variables.
2814 An action can be an external command, specified as a string, or
2816 a callable Python object; see "Action Objects," below, for more
2817 complete information. Also note that a string specifying an
2818 external command may be preceded by an @ (at-sign) to suppress
2819 printing the command in question, or by a - (hyphen) to ignore
2820 the exit status of the external command.
2821 Examples:
2823 env.Command('foo.out', 'foo.in',
2825 "$FOO_BUILD < $SOURCES > $TARGET")
2826 env.Command('bar.out', 'bar.in',
2828 ["rm -f $TARGET",
2829 "$BAR_BUILD < $SOURCES > $TARGET"],
2830 ENV = {'PATH' : '/usr/local/bin/'})
2831 def rename(env, target, source):
2833 import os
2834 os.rename('.tmp', str(target[0]))
2835 env.Command('baz.out', 'baz.in',
2837 ["$BAZ_BUILD < $SOURCES > .tmp",
2838 rename ])
2839 Note that the Command() function will usually assume, by
2841 default, that the specified targets and/or sources are Files, if
2842 no other part of the configuration identifies what type of entry
2843 it is. If necessary, you can explicitly specify that targets or
2844 source nodes should be treated as directoriese by using the
2845 Dir() or env.Dir() functions.
2846 Examples:
2848 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
2850 env['DISTDIR'] = 'destination/directory'
2852 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
2853 (Also note that SCons will usually automatically create any
2855 directory necessary to hold a target file, so you normally don't
2856 need to create directories by hand.)
2857 Configure(env, [custom_tests, conf_dir, log_file, config_h])
2860 env.Configure([custom_tests, conf_dir, log_file, config_h])
2862 Creates a Configure object for integrated functionality similar
2863 to GNU autoconf. See the section "Configure Contexts," below,
2864 for a complete explanation of the arguments and behavior.
2865 env.Copy([key=val, ...])
2868 A now-deprecated synonym for env.Clone().
2869 env.CVS(repository, module)
2872 A factory function that returns a Builder object to be used to
2873 fetch source files from the specified CVS repository. The
2874 returned Builder is intended to be passed to the SourceCode()
2875 function.
2876 This function is deprecated. For details, see the entry for the
2878 SourceCode() function.
2879 The optional specified module will be added to the beginning of
2881 all repository path names; this can be used, in essence, to
2882 strip initial directory names from the repository path names, so
2883 that you only have to replicate part of the repository directory
2884 hierarchy in your local build directory.
2885 Examples:
2887 # Will fetch foo/bar/src.c
2889 # from /usr/local/CVSROOT/foo/bar/src.c.
2890 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
2891 # Will fetch bar/src.c
2893 # from /usr/local/CVSROOT/foo/bar/src.c.
2894 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
2895 # Will fetch src.c
2897 # from /usr/local/CVSROOT/foo/bar/src.c.
2898 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
2899 Decider(function)
2902 env.Decider(function)
2904 Specifies that all up-to-date decisions for targets built
2905 through this construction environment will be handled by the
2906 specified function. The function can be one of the following
2907 strings that specify the type of decision function to be per‐
2908 formed:
2909 timestamp-newer
2912 Specifies that a target shall be considered out of date
2913 and rebuilt if the dependency's timestamp is newer than
2914 the target file's timestamp. This is the behavior of
2915 the classic Make utility, and make can be used a syn‐
2916 onym for timestamp-newer.
2917 timestamp-match
2919 Specifies that a target shall be considered out of date
2920 and rebuilt if the dependency's timestamp is different
2921 than the timestamp recorded the last time the target
2922 was built. This provides behavior very similar to the
2923 classic Make utility (in particular, files are not
2924 opened up so that their contents can be checksummed)
2925 except that the target will also be rebuilt if a depen‐
2926 dency file has been restored to a version with an ear‐
2927 lier timestamp, such as can happen when restoring files
2928 from backup archives.
2929 MD5 Specifies that a target shall be considered out of date
2931 and rebuilt if the dependency's content has changed
2932 sine the last time the target was built, as determined
2933 be performing an MD5 checksum on the dependency's con‐
2934 tents and comparing it to the checksum recorded the
2935 last time the target was built. content can be used as
2936 a synonym for MD5.
2937 MD5-timestamp
2939 Specifies that a target shall be considered out of date
2940 and rebuilt if the dependency's content has changed
2941 sine the last time the target was built, except that
2942 dependencies with a timestamp that matches the last
2943 time the target was rebuilt will be assumed to be up-
2944 to-date and not rebuilt. This provides behavior very
2945 similar to the MD5 behavior of always checksumming file
2946 contents, with an optimization of not checking the con‐
2947 tents of files whose timestamps haven't changed. The
2948 drawback is that SCons will not detect if a file's con‐
2949 tent has changed but its timestamp is the same, as
2950 might happen in an automated script that runs a build,
2951 updates a file, and runs the build again, all within a
2952 single second.
2953 Examples:
2955 # Use exact timestamp matches by default.
2957 Decider('timestamp-match')
2958 # Use MD5 content signatures for any targets built
2960 # with the attached construction environment.
2961 env.Decider('content')
2962 In addition to the above already-available functions, the func‐
2964 tion argument may be an actual Python function that takes the
2965 following three arguments:
2966 dependency
2969 The Node (file) which should cause the target to be
2970 rebuilt if it has "changed" since the last tme target
2971 was built.
2972 target The Node (file) being built. In the normal case, this
2974 is what should get rebuilt if the dependency has
2975 "changed."
2976 prev_ni
2978 Stored information about the state of the dependency
2979 the last time the target was built. This can be con‐
2980 sulted to match various file characteristics such as
2981 the timestamp, size, or content signature.
2982 The function should return a True (non-zero) value if the dependency
2984 has "changed" since the last time the target was built (indicating that
2985 the target should be rebuilt), and False (zero) otherwise (indicating
2986 that the target should not be rebuilt). Note that the decision can be
2987 made using whatever criteria are appopriate. Ignoring some or all of
2988 the function arguments is perfectly normal.
2989 Example:
2991 def my_decider(dependency, target, prev_ni):
2993 return not os.path.exists(str(target))
2994 env.Decider(my_decider)
2996 Default(targets)
2999 env.Default(targets)
3001 This specifies a list of default targets, which will be built by
3002 scons if no explicit targets are given on the command line.
3003 Multiple calls to Default() are legal, and add to the list of
3004 default targets.
3005 Multiple targets should be specified as separate arguments to
3007 the Default() method, or as a list. Default() will also accept
3008 the Node returned by any of a construction environment's builder
3009 methods.
3010 Examples:
3012 Default('foo', 'bar', 'baz')
3014 env.Default(['a', 'b', 'c'])
3015 hello = env.Program('hello', 'hello.c')
3016 env.Default(hello)
3017 An argument to Default() of None will clear all default targets.
3019 Later calls to Default() will add to the (now empty) default-
3020 target list like normal.
3021 The current list of targets added using the Default() function
3023 or method is available in the DEFAULT_TARGETS list; see below.
3024 DefaultEnvironment([args])
3027 Creates and returns a default construction environment object.
3028 This construction environment is used internally by SCons in
3029 order to execute many of the global functions in this list, and
3030 to fetch source files transparently from source code management
3031 systems.
3032 Depends(target, dependency)
3035 env.Depends(target, dependency)
3037 Specifies an explicit dependency; the target will be rebuilt
3038 whenever the dependency has changed. Both the specified target
3039 and dependency can be a string (usually the path name of a file
3040 or directory) or Node objects, or a list of strings or Node
3041 objects (such as returned by a Builder call). This should only
3042 be necessary for cases where the dependency is not caught by a
3043 Scanner for the file.
3044 Example:
3046 env.Depends('foo', 'other-input-file-for-foo')
3048 mylib = env.Library('mylib.c')
3050 installed_lib = env.Install('lib', mylib)
3051 bar = env.Program('bar.c')
3052 # Arrange for the library to be copied into the installation
3054 # directory before trying to build the "bar" program.
3055 # (Note that this is for example only. A "real" library
3056 # dependency would normally be configured through the $LIBS
3057 # and $LIBPATH variables, not using an env.Depends() call.)
3058 env.Depends(bar, installed_lib)
3060 env.Dictionary([vars])
3063 Returns a dictionary object containing copies of all of the con‐
3064 struction variables in the environment. If there are any vari‐
3065 able names specified, only the specified construction variables
3066 are returned in the dictionary.
3067 Example:
3069 dict = env.Dictionary()
3071 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
3072 Dir(name, [directory])
3075 env.Dir(name, [directory])
3077 This returns a Directory Node, an object that represents the
3078 specified directory name. name can be a relative or absolute
3079 path. directory is an optional directory that will be used as
3080 the parent directory. If no directory is specified, the current
3081 script's directory is used as the parent.
3082 If name is a list, SCons returns a list of Dir nodes. Construc‐
3084 tion variables are expanded in name.
3085 Directory Nodes can be used anywhere you would supply a string
3087 as a directory name to a Builder method or function. Directory
3088 Nodes have attributes and methods that are useful in many situa‐
3089 tions; see "File and Directory Nodes," below.
3090 env.Dump([key])
3093 Returns a pretty printable representation of the environment.
3094 key, if not None, should be a string containing the name of the
3095 variable of interest.
3096 This SConstruct:
3098 env=Environment()
3100 print env.Dump('CCCOM')
3101 will print:
3103 While this SConstruct:
3106 env=Environment()
3108 print env.Dump()
3109 will print:
3111 { 'AR': 'ar',
3112 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
3113 'ARFLAGS': ['r'],
3114 'AS': 'as',
3115 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
3116 'ASFLAGS': [],
3117 ...
3118 EnsurePythonVersion(major, minor)
3121 env.EnsurePythonVersion(major, minor)
3123 Ensure that the Python version is at least major.minor. This
3124 function will print out an error message and exit SCons with a
3125 non-zero exit code if the actual Python version is not late
3126 enough.
3127 Example:
3129 EnsurePythonVersion(2,2)
3131 EnsureSConsVersion(major, minor, [revision])
3134 env.EnsureSConsVersion(major, minor, [revision])
3136 Ensure that the SCons version is at least major.minor, or
3137 major.minor.revision. if revision is specified. This function
3138 will print out an error message and exit SCons with a non-zero
3139 exit code if the actual SCons version is not late enough.
3140 Examples:
3142 EnsureSConsVersion(0,14)
3144 EnsureSConsVersion(0,96,90)
3146 Environment([key=value, ...])
3149 env.Environment([key=value, ...])
3151 Return a new construction environment initialized with the spec‐
3152 ified key=value pairs.
3153 Execute(action, [strfunction, varlist])
3156 env.Execute(action, [strfunction, varlist])
3158 Executes an Action object. The specified action may be an
3159 Action object (see the section "Action Objects," below, for a
3160 complete explanation of the arguments and behavior), or it may
3161 be a command-line string, list of commands, or executable Python
3162 function, each of which will be converted into an Action object
3163 and then executed. The exit value of the command or return
3164 value of the Python function will be returned.
3165 Note that scons will print an error message if the executed
3167 action fails--that is, exits with or returns a non-zero value.
3168 scons will not, however, automatically terminate the build if
3169 the specified action fails. If you want the build to stop in
3170 response to a failed Execute() call, you must explicitly check
3171 for a non-zero return value:
3172 Execute(Copy('file.out', 'file.in'))
3174 if Execute("mkdir sub/dir/ectory"):
3176 # The mkdir failed, don't try to build.
3177 Exit(1)
3178 Exit([value])
3181 env.Exit([value])
3183 This tells scons to exit immediately with the specified value.
3184 A default exit value of 0 (zero) is used if no value is speci‐
3185 fied.
3186 Export(vars)
3189 env.Export(vars)
3191 This tells scons to export a list of variables from the current
3192 SConscript file to all other SConscript files. The exported
3193 variables are kept in a global collection, so subsequent calls
3194 to Export() will over-write previous exports that have the same
3195 name. Multiple variable names can be passed to Export() as sep‐
3196 arate arguments or as a list. Keyword arguments can be used to
3197 provide names and their values. A dictionary can be used to map
3198 variables to a different name when exported. Both local vari‐
3199 ables and global variables can be exported.
3200 Examples:
3202 env = Environment()
3204 # Make env available for all SConscript files to Import().
3205 Export("env")
3206 package = 'my_name'
3208 # Make env and package available for all SConscript files:.
3209 Export("env", "package")
3210 # Make env and package available for all SConscript files:
3212 Export(["env", "package"])
3213 # Make env available using the name debug:
3215 Export(debug = env)
3216 # Make env available using the name debug:
3218 Export({"debug":env})
3219 Note that the SConscript() function supports an exports argument
3221 that makes it easier to to export a variable or set of variables
3222 to a single SConscript file. See the description of the SCon‐
3223 script() function, below.
3224 File(name, [directory])
3227 env.File(name, [directory])
3229 This returns a File Node, an object that represents the speci‐
3230 fied file name. name can be a relative or absolute path.
3231 directory is an optional directory that will be used as the par‐
3232 ent directory.
3233 If name is a list, SCons returns a list of File nodes. Con‐
3235 struction variables are expanded in name.
3236 File Nodes can be used anywhere you would supply a string as a
3238 file name to a Builder method or function. File Nodes have
3239 attributes and methods that are useful in many situations; see
3240 "File and Directory Nodes," below.
3241 FindFile(file, dirs)
3244 env.FindFile(file, dirs)
3246 Search for file in the path specified by dirs. dirs may be a
3247 list of directory names or a single directory name. In addition
3248 to searching for files that exist in the filesystem, this func‐
3249 tion also searches for derived files that have not yet been
3250 built.
3251 Example:
3253 foo = env.FindFile('foo', ['dir1', 'dir2'])
3255 FindInstalledFiles()
3258 env.FindInstalledFiles()
3260 Returns the list of targets set up by the Install() or Instal‐
3261 lAs() builders.
3262 This function serves as a convenient method to select the con‐
3264 tents of a binary package.
3265 Example:
3267 Install( '/bin', [ 'executable_a', 'executable_b' ] )
3269 # will return the file node list
3271 # [ '/bin/executable_a', '/bin/executable_b' ]
3272 FindInstalledFiles()
3273 Install( '/lib', [ 'some_library' ] )
3275 # will return the file node list
3277 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
3278 FindInstalledFiles()
3279 FindPathDirs(variable)
3282 Returns a function (actually a callable Python object) intended
3283 to be used as the path_function of a Scanner object. The
3284 returned object will look up the specified variable in a con‐
3285 struction environment and treat the construction variable's
3286 value as a list of directory paths that should be searched (like
3287 $CPPPATH, $LIBPATH, etc.).
3288 Note that use of FindPathDirs() is generally preferable to writ‐
3290 ing your own path_function for the following reasons: 1) The
3291 returned list will contain all appropriate directories found in
3292 source trees (when VariantDir() is used) or in code repositories
3293 (when Repository() or the -Y option are used). 2) scons will
3294 identify expansions of variable that evaluate to the same list
3295 of directories as, in fact, the same list, and avoid re-scanning
3296 the directories for files, when possible.
3297 Example:
3299 def my_scan(node, env, path, arg):
3301 # Code to scan file contents goes here...
3302 return include_files
3303 scanner = Scanner(name = 'myscanner',
3305 function = my_scan,
3306 path_function = FindPathDirs('MYPATH'))
3307 FindSourceFiles(node='"."')
3310 env.FindSourceFiles(node='"."')
3312 Returns the list of nodes which serve as the source of the built
3313 files. It does so by inspecting the dependency tree starting at
3314 the optional argument node which defaults to the '"."'-node. It
3315 will then return all leaves of node. These are all children
3316 which have no further children.
3317 This function is a convenient method to select the contents of a
3319 Source Package.
3320 Example:
3322 Program( 'src/main_a.c' )
3324 Program( 'src/main_b.c' )
3325 Program( 'main_c.c' )
3326 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
3328 FindSourceFiles()
3329 # returns ['src/main_b.c', 'src/main_a.c' ]
3331 FindSourceFiles( 'src' )
3332 As you can see build support files (SConstruct in the above
3334 example) will also be returned by this function.
3335 Flatten(sequence)
3338 env.Flatten(sequence)
3340 Takes a sequence (that is, a Python list or tuple) that may con‐
3341 tain nested sequences and returns a flattened list containing
3342 all of the individual elements in any sequence. This can be
3343 helpful for collecting the lists returned by calls to Builders;
3344 other Builders will automatically flatten lists specified as
3345 input, but direct Python manipulation of these lists does not.
3346 Examples:
3348 foo = Object('foo.c')
3350 bar = Object('bar.c')
3351 # Because `foo' and `bar' are lists returned by the Object() Builder,
3353 # `objects' will be a list containing nested lists:
3354 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
3355 # Passing such a list to another Builder is all right because
3357 # the Builder will flatten the list automatically:
3358 Program(source = objects)
3359 # If you need to manipulate the list directly using Python, you need to
3361 # call Flatten() yourself, or otherwise handle nested lists:
3362 for object in Flatten(objects):
3363 print str(object)
3364 GetBuildFailures()
3367 Returns a list of exceptions for the actions that failed while
3368 attempting to build targets. Each element in the returned list
3369 is a BuildError object with the following attributes that record
3370 various aspects of the build failure:
3371 .node The node that was being built when the build failure
3373 occurred.
3374 .status The numeric exit status returned by the command or
3376 Python function that failed when trying to build the specified
3377 Node.
3378 .errstr The SCons error string describing the build failure.
3380 (This is often a generic message like "Error 2" to indicate that
3381 an executed command exited with a status of 2.)
3382 .filename The name of the file or directory that actually caused
3384 the failure. This may be different from the .node attribute.
3385 For example, if an attempt to build a target named sub/dir/tar‐
3386 get fails because the sub/dir directory could not be created,
3387 then the .node attribute will be sub/dir/target but the .file‐
3388 name attribute will be sub/dir.
3389 .executor The SCons Executor object for the target Node being
3391 built. This can be used to retrieve the construction environ‐
3392 ment used for the failed action.
3393 .action The actual SCons Action object that failed. This will
3395 be one specific action out of the possible list of actions that
3396 would have been executed to build the target.
3397 .command The actual expanded command that was executed and
3399 failed, after expansion of $TARGET, $SOURCE, and other construc‐
3400 tion variables.
3401 Note that the GetBuildFailures() function will always return an
3403 empty list until any build failure has occurred, which means
3404 that GetBuildFailures() will always return an empty list while
3405 the SConscript files are being read. Its primary intended use
3406 is for functions that will be executed before SCons exits by
3407 passing them to the standard Python atexit.register() function.
3408 Example:
3409 import atexit
3411 def print_build_failures():
3413 from SCons.Script import GetBuildFailures
3414 for bf in GetBuildFailures():
3415 print "%s failed: %s" % (bf.node, bf.errstr)
3416 atexit.register(print_build_failures)
3418 GetBuildPath(file, [...])
3421 env.GetBuildPath(file, [...])
3423 Returns the scons path name (or names) for the specified file
3424 (or files). The specified file or files may be scons Nodes or
3425 strings representing path names.
3426 GetLaunchDir()
3429 env.GetLaunchDir()
3431 Returns the absolute path name of the directory from which scons
3432 was initially invoked. This can be useful when using the -u, -U
3433 or -D options, which internally change to the directory in which
3434 the SConstruct file is found.
3435 GetOption(name)
3438 env.GetOption(name)
3440 This function provides a way to query the value of SCons options
3441 set on scons command line (or set using the SetOption() func‐
3442 tion). The options supported are:
3443 cache_debug
3446 which corresponds to --cache-debug;
3447 cache_disable
3449 which corresponds to --cache-disable;
3450 cache_force
3452 which corresponds to --cache-force;
3453 cache_show
3455 which corresponds to --cache-show;
3456 clean which corresponds to -c, --clean and --remove;
3458 config
3460 which corresponds to --config;
3461 directory
3463 which corresponds to -C and --directory;
3464 diskcheck
3466 which corresponds to --diskcheck
3467 duplicate
3469 which corresponds to --duplicate;
3470 file which corresponds to -f, --file, --makefile and --scon‐
3472 struct;
3473 help which corresponds to -h and --help;
3475 ignore_errors
3477 which corresponds to --ignore-errors;
3478 implicit_cache
3480 which corresponds to --implicit-cache;
3481 implicit_deps_changed
3483 which corresponds to --implicit-deps-changed;
3484 implicit_deps_unchanged
3486 which corresponds to --implicit-deps-unchanged;
3487 interactive
3489 which corresponds to --interact and --interactive;
3490 keep_going
3492 which corresponds to -k and --keep-going;
3493 max_drift
3495 which corresponds to --max-drift;
3496 no_exec
3498 which corresponds to -n, --no-exec, --just-print,
3499 --dry-run and --recon;
3500 no_site_dir
3502 which corresponds to --no-site-dir;
3503 num_jobs
3505 which corresponds to -j and --jobs;
3506 profile_file
3508 which corresponds to --profile;
3509 question
3511 which corresponds to -q and --question;
3512 random
3514 which corresponds to --random;
3515 repository
3517 which corresponds to -Y, --repository and --srcdir;
3518 silent
3520 which corresponds to -s, --silent and --quiet;
3521 site_dir
3523 which corresponds to --site-dir;
3524 stack_size
3526 which corresponds to --stack-size;
3527 taskmastertrace_file
3529 which corresponds to --taskmastertrace; and
3530 warn which corresponds to --warn and --warning.
3532 See the documentation for the corresponding command line object for
3534 information about each specific option.
3535 Glob(pattern, [ondisk, source, strings])
3538 env.Glob(pattern, [ondisk, source, strings])
3540 Returns Nodes (or strings) that match the specified pattern,
3541 relative to the directory of the current SConscript file. The
3542 env.Glob() form performs string substition on pattern and
3543 returns whatever matches the resulting expanded pattern.
3544 The specified pattern uses Unix shell style metacharacters for
3546 matching:
3547 * matches everything
3549 ? matches any single character
3550 [seq] matches any character in seq
3551 [!seq] matches any char not in seq
3552 If the first character of a filename is a dot, it must be
3554 matched explicitly. Character matches do not span directory
3555 separators.
3556 The Glob() knows about repositories (see the Repository() func‐
3558 tion) and source directories (see the VariantDir() function) and
3559 returns a Node (or string, if so configured) in the local (SCon‐
3560 script) directory if matching Node is found anywhere in a corre‐
3561 sponding repository or source directory.
3562 The ondisk argument may be set to False (or any other non-true
3564 value) to disable the search for matches on disk, thereby only
3565 returning matches among already-configured File or Dir Nodes.
3566 The default behavior is to return corresponding Nodes for any
3567 on-disk matches found.
3568 The source argument may be set to True (or any equivalent value)
3570 to specify that, when the local directory is a VariantDir(), the
3571 returned Nodes should be from the corresponding source direc‐
3572 tory, not the local directory.
3573 The strings argument may be set to True (or any equivalent
3575 value) to have the Glob() function return strings, not Nodes,
3576 that represent the matched files or directories. The returned
3577 strings will be relative to the local (SConscript) directory.
3578 (Note that This may make it easier to perform arbitrary manipu‐
3579 lation of file names, but if the returned strings are passed to
3580 a different SConscript file, any Node translation will be rela‐
3581 tive to the other SConscript directory, not the original SCon‐
3582 script directory.)
3583 Examples:
3585 Program('foo', Glob('*.c'))
3587 Zip('/tmp/everything', Glob('.??*') + Glob('*'))
3588 Help(text)
3591 env.Help(text)
3593 This specifies help text to be printed if the -h argument is
3594 given to scons. If Help() is called multiple times, the text is
3595 appended together in the order that Help() is called.
3596 Ignore(target, dependency)
3599 env.Ignore(target, dependency)
3601 The specified dependency file(s) will be ignored when deciding
3602 if the target file(s) need to be rebuilt.
3603 You can also use Ignore() to remove a target from the default
3605 build. In order to do this you must specify the directory the
3606 target will be built in as the target, and the file you want to
3607 skip building as the dependency.
3608 Note that this will only remove the dependencies listed from the
3610 files built by default. It will still be built if that depen‐
3611 dency is needed by another object being built. See the third
3612 and forth examples below.
3613 Examples:
3615 env.Ignore('foo', 'foo.c')
3617 env.Ignore('bar', ['bar1.h', 'bar2.h'])
3618 env.Ignore('.','foobar.obj')
3619 env.Ignore('bar','bar/foobar.obj')
3620 Import(vars)
3623 env.Import(vars)
3625 This tells scons to import a list of variables into the current
3626 SConscript file. This will import variables that were exported
3627 with Export() or in the exports argument to SConscript(). Vari‐
3628 ables exported by SConscript() have precedence. Multiple vari‐
3629 able names can be passed to Import() as separate arguments or as
3630 a list. The variable "*" can be used to import all variables.
3631 Examples:
3633 Import("env")
3635 Import("env", "variable")
3636 Import(["env", "variable"])
3637 Import("*")
3638 Literal(string)
3641 env.Literal(string)
3643 The specified string will be preserved as-is and not have con‐
3644 struction variables expanded.
3645 Local(targets)
3648 env.Local(targets)
3650 The specified targets will have copies made in the local tree,
3651 even if an already up-to-date copy exists in a repository.
3652 Returns a list of the target Node or Nodes.
3653 env.MergeFlags(arg, [unique])
3656 Merges the specified arg values to the construction environ‐
3657 ment's construction variables. If the arg argument is not a
3658 dictionary, it is converted to one by calling env.ParseFlags()
3659 on the argument before the values are merged. Note that arg
3660 must be a single value, so multiple strings must be passed in as
3661 a list, not as separate arguments to env.MergeFlags().
3662 By default, duplicate values are eliminated; you can, however,
3664 specify unique=0 to allow duplicate values to be added. When
3665 eliminating duplicate values, any construction variables that
3666 end with the string PATH keep the left-most unique value. All
3667 other construction variables keep the right-most unique value.
3668 Examples:
3670 # Add an optimization flag to $CCFLAGS.
3672 env.MergeFlags('-O3')
3673 # Combine the flags returned from running pkg-config with an optimization
3675 # flag and merge the result into the construction variables.
3676 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
3677 # Combine an optimization flag with the flags returned from running pkg-config
3679 # twice and merge the result into the construction variables.
3680 env.MergeFlags(['-O3',
3681 '!pkg-config gtk+-2.0 --cflags --libs',
3682 '!pkg-config libpng12 --cflags --libs'])
3683 NoCache(target, ...)
3686 env.NoCache(target, ...)
3688 Specifies a list of files which should not be cached whenever
3689 the CacheDir() method has been activated. The specified targets
3690 may be a list or an individual target.
3691 Multiple files should be specified either as separate arguments
3693 to the NoCache() method, or as a list. NoCache() will also
3694 accept the return value of any of the construction environment
3695 Builder methods.
3696 Calling NoCache() on directories and other non-File Node types
3698 has no effect because only File Nodes are cached.
3699 Examples:
3701 NoCache('foo.elf')
3703 NoCache(env.Program('hello', 'hello.c'))
3704 NoClean(target, ...)
3707 env.NoClean(target, ...)
3709 Specifies a list of files or directories which should not be
3710 removed whenever the targets (or their dependencies) are speci‐
3711 fied with the -c command line option. The specified targets may
3712 be a list or an individual target. Multiple calls to NoClean()
3713 are legal, and prevent each specified target from being removed
3714 by calls to the -c option.
3715 Multiple files or directories should be specified either as sep‐
3717 arate arguments to the NoClean() method, or as a list.
3718 NoClean() will also accept the return value of any of the con‐
3719 struction environment Builder methods.
3720 Calling NoClean() for a target overrides calling Clean() for the
3722 same target, and any targets passed to both functions will not
3723 be removed by the -c option.
3724 Examples:
3726 NoClean('foo.elf')
3728 NoClean(env.Program('hello', 'hello.c'))
3729 env.ParseConfig(command, [function, unique])
3732 Calls the specified function to modify the environment as speci‐
3733 fied by the output of command. The default function is
3734 env.MergeFlags(), which expects the output of a typical *-config
3735 command (for example, gtk-config) and adds the options to the
3736 appropriate construction variables. By default, duplicate val‐
3737 ues are not added to any construction variables; you can specify
3738 unique=0 to allow duplicate values to be added.
3739 Interpreted options and the construction variables they affect
3741 are as specified for the env.ParseFlags() method (which this
3742 method calls). See that method's description, below, for a ta‐
3743 ble of options and construction variables.
3744 ParseDepends(filename, [must_exist, only_one])
3747 env.ParseDepends(filename, [must_exist, only_one])
3749 Parses the contents of the specified filename as a list of
3750 dependencies in the style of Make or mkdep, and explicitly
3751 establishes all of the listed dependencies.
3752 By default, it is not an error if the specified filename does
3754 not exist. The optional must_exist argument may be set to a
3755 non-zero value to have scons throw an exception and generate an
3756 error if the file does not exist, or is otherwise inaccessible.
3757 The optional only_one argument may be set to a non-zero value to
3759 have scons thrown an exception and generate an error if the file
3760 contains dependency information for more than one target. This
3761 can provide a small sanity check for files intended to be gener‐
3762 ated by, for example, the gcc -M flag, which should typically
3763 only write dependency information for one output file into a
3764 corresponding .d file.
3765 The filename and all of the files listed therein will be inter‐
3767 preted relative to the directory of the SConscript file which
3768 calls the ParseDepends() function.
3769 env.ParseFlags(flags, ...)
3772 Parses one or more strings containing typical command-line flags
3773 for GCC tool chains and returns a dictionary with the flag val‐
3774 ues separated into the appropriate SCons construction variables.
3775 This is intended as a companion to the env.MergeFlags() method,
3776 but allows for the values in the returned dictionary to be modi‐
3777 fied, if necessary, before merging them into the construction
3778 environment. (Note that env.MergeFlags() will call this method
3779 if its argument is not a dictionary, so it is usually not neces‐
3780 sary to call env.ParseFlags() directly unless you want to manip‐
3781 ulate the values.)
3782 If the first character in any string is an exclamation mark (!),
3784 the rest of the string is executed as a command, and the output
3785 from the command is parsed as GCC tool chain command-line flags
3786 and added to the resulting dictionary.
3787 Flag values are translated accordig to the prefix found, and
3789 added to the following construction variables:
3790 -arch CCFLAGS, LINKFLAGS
3792 -D CPPDEFINES
3793 -framework FRAMEWORKS
3794 -frameworkdir= FRAMEWORKPATH
3795 -include CCFLAGS
3796 -isysroot CCFLAGS, LINKFLAGS
3797 -I CPPPATH
3798 -l LIBS
3799 -L LIBPATH
3800 -mno-cygwin CCFLAGS, LINKFLAGS
3801 -mwindows LINKFLAGS
3802 -pthread CCFLAGS, LINKFLAGS
3803 -std= CFLAGS
3804 -Wa, ASFLAGS, CCFLAGS
3805 -Wl,-rpath= RPATH
3806 -Wl,-R, RPATH
3807 -Wl,-R RPATH
3808 -Wl, LINKFLAGS
3809 -Wp, CPPFLAGS
3810 - CCFLAGS
3811 + CCFLAGS, LINKFLAGS
3812 Any other strings not associated with options are assumed to be
3814 the names of libraries and added to the $LIBS construction vari‐
3815 able.
3816 Examples (all of which produce the same result):
3818 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
3820 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
3821 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
3822 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
3823 env.Perforce()
3826 A factory function that returns a Builder object to be used to
3827 fetch source files from the Perforce source code management sys‐
3828 tem. The returned Builder is intended to be passed to the
3829 SourceCode() function.
3830 This function is deprecated. For details, see the entry for the
3832 SourceCode() function.
3833 Example:
3835 env.SourceCode('.', env.Perforce())
3837 Perforce uses a number of external environment variables for its
3839 operation. Consequently, this function adds the following vari‐
3840 ables from the user's external environment to the construction
3841 environment's ENV dictionary: P4CHARSET, P4CLIENT, P4LANGUAGE,
3842 P4PASSWD, P4PORT, P4USER, SystemRoot, USER, and USERNAME.
3843 Platform(string)
3846 The Platform() form returns a callable object that can be used
3847 to initialize a construction environment using the platform key‐
3848 word of the Environment() function.
3849 Example:
3851 env = Environment(platform = Platform('win32'))
3853 The env.Platform() form applies the callable object for the
3855 specified platform string to the environment through which the
3856 method was called.
3857 env.Platform('posix')
3859 Note that the win32 platform adds the SystemDrive and SystemRoot
3861 variables from the user's external environment to the construc‐
3862 tion environment's $ENV dictionary. This is so that any exe‐
3863 cuted commands that use sockets to connect with other systems
3864 (such as fetching source files from external CVS repository
3865 specifications like :pserver:anonymous@cvs.sourceforge.net:/cvs‐
3866 root/scons) will work on Windows systems.
3867 Precious(target, ...)
3870 env.Precious(target, ...)
3872 Marks each given target as precious so it is not deleted before
3873 it is rebuilt. Normally scons deletes a target before building
3874 it. Multiple targets can be passed in to a single call to Pre‐
3875 cious().
3876 env.Prepend(key=val, [...])
3879 Appends the specified keyword arguments to the beginning of con‐
3880 struction variables in the environment. If the Environment does
3881 not have the specified construction variable, it is simply added
3882 to the environment. If the values of the construction variable
3883 and the keyword argument are the same type, then the two values
3884 will be simply added together. Otherwise, the construction
3885 variable and the value of the keyword argument are both coerced
3886 to lists, and the lists are added together. (See also the
3887 Append method, above.)
3888 Example:
3890 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
3892 env.PrependENVPath(name, newpath, [envname, sep, delete_existing])
3895 This appends new path elements to the given path in the speci‐
3896 fied external environment ($ENV by default). This will only add
3897 any particular path once (leaving the first one it encounters
3898 and ignoring the rest, to preserve path order), and to help
3899 assure this, will normalize all paths (using os.path.normpath
3900 and os.path.normcase). This can also handle the case where the
3901 given old path variable is a list instead of a string, in which
3902 case a list will be returned instead of a string.
3903 If delete_existing is 0, then adding a path that already exists
3905 will not move it to the beginning; it will stay where it is in
3906 the list.
3907 Example:
3909 print 'before:',env['ENV']['INCLUDE']
3911 include_path = '/foo/bar:/foo'
3912 env.PrependENVPath('INCLUDE', include_path)
3913 print 'after:',env['ENV']['INCLUDE']
3914 The above example will print:
3916 before: /biz:/foo
3918 after: /foo/bar:/foo:/biz
3919 env.PrependUnique(key=val, delete_existing=0, [...])
3922 Appends the specified keyword arguments to the beginning of con‐
3923 struction variables in the environment. If the Environment does
3924 not have the specified construction variable, it is simply added
3925 to the environment. If the construction variable being appended
3926 to is a list, then any value(s) that already exist in the con‐
3927 struction variable will not be added again to the list. How‐
3928 ever, if delete_existing is 1, existing matching values are
3929 removed first, so existing values in the arg list move to the
3930 front of the list.
3931 Example:
3933 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
3935 Progress(callable, [interval])
3938 Progress(string, [interval, file, overwrite])
3940 Progress(list_of_strings, [interval, file, overwrite])
3942 Allows SCons to show progress made during the build by display‐
3943 ing a string or calling a function while evaluating Nodes (e.g.
3944 files).
3945 If the first specified argument is a Python callable (a function
3947 or an object that has a __call__() method), the function will be
3948 called once every interval times a Node is evaluated. The
3949 callable will be passed the evaluated Node as its only argument.
3950 (For future compatibility, it's a good idea to also add *args
3951 and **kw as arguments to your function or method. This will
3952 prevent the code from breaking if SCons ever changes the inter‐
3953 face to call the function with additional arguments in the
3954 future.)
3955 An example of a simple custom progress function that prints a
3957 string containing the Node name every 10 Nodes:
3958 def my_progress_function(node, *args, **kw):
3960 print 'Evaluating node %s!' % node
3961 Progress(my_progress_function, interval=10)
3962 A more complicated example of a custom progress display object
3964 that prints a string contai(naincgarraiagceournetturenv)erayt t1h0e0enedvaslouattheadt
3965 Nodes. Note the use of
3966 the string will overwrite itself on a display:
3967 import sys
3969 class ProgressCounter(object):
3970 count = 0
3971 def __call__(self, node, *args, **kw):
3972 self.count += 100
3973 sys.stderr.write('Evaluated %s nodes\r' % self.count)
3974 Progress(ProgressCounter(), interval=100)
3975 If the first argument Progress() is a string, the string will be
3977 displayed every interval evaluated Nodes. The default is to
3978 print the string on standard output; an alternate output stream
3979 may be specified with the file= argument. The following will
3980 print a series of dots on the error output, one dot for every
3981 100 evaluated Nodes:
3982 import sys
3984 Progress('.', interval=100, file=sys.stderr)
3985 If the string contains the verbatim substring $TARGET, it will
3987 be replaced with the Node. Note that, for performance reasons,
3988 this is not a regular SCons variable substition, so you can not
3989 use other variables or use curly braces. The following(ceaxrarmipalgee
3990 will print the name of every evaluated Node, using a
3991 return) to cause each line to overwritten by the next line, and
3992 the overwrite= keyword argument to make sure the previously-
3993 printed file name is overwritten with blank spaces:
3994 import sys
3996 Progress('$TARGET\r', overwrite=True)
3997 If the first argument to Progress() is a list of strings, then
3999 each string in the list will be displayed in rotating fashion
4000 every interval evaluated Nodes. This can be used to implement a
4001 "spinner" on the user's screen as follows:
4002 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
4004 env.RCS()
4007 A factory function that returns a Builder object to be used to
4008 fetch source files from RCS. The returned Builder is intended
4009 to be passed to the SourceCode() function:
4010 This function is deprecated. For details, see the entry for the
4012 SourceCode() function.
4013 Examples:
4015 env.SourceCode('.', env.RCS())
4017 Note that scons will fetch source files from RCS subdirectories
4019 automatically, so configuring RCS as demonstrated in the above
4020 example should only be necessary if you are fetching from RCS,v
4021 files in the same directory as the source files, or if you need
4022 to explicitly specify RCS for a specific subdirectory.
4023 env.Replace(key=val, [...])
4026 Replaces construction variables in the Environment with the
4027 specified keyword arguments.
4028 Example:
4030 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
4032 Repository(directory)
4035 env.Repository(directory)
4037 Specifies that directory is a repository to be searched for
4038 files. Multiple calls to Repository() are legal, and each one
4039 adds to the list of repositories that will be searched.
4040 To scons, a repository is a copy of the source tree, from the
4042 top-level directory on down, which may contain both source files
4043 and derived files that can be used to build targets in the local
4044 source tree. The canonical example would be an official source
4045 tree maintained by an integrator. If the repository contains
4046 derived files, then the derived files should have been built
4047 using scons, so that the repository contains the necessary sig‐
4048 nature information to allow scons to figure out when it is
4049 appropriate to use the repository copy of a derived file,
4050 instead of building one locally.
4051 Note that if an up-to-date derived file already exists in a
4053 repository, scons will not make a copy in the local directory
4054 tree. In order to guarantee that a local copy will be made, use
4055 the Local() method.
4056 Requires(target, prerequisite)
4059 env.Requires(target, prerequisite)
4061 Specifies an order-only relationship between the specified tar‐
4062 get file(s) and the specified prerequisite file(s). The prereq‐
4063 uisite file(s) will be (re)built, if necessary, before the tar‐
4064 get file(s), but the target file(s) do not actually depend on
4065 the prerequisites and will not be rebuilt simply because the
4066 prerequisite file(s) change.
4067 Example:
4069 env.Requires('foo', 'file-that-must-be-built-before-foo')
4071 Return([vars..., stop=])
4074 By default, this stops processing the current SConscript file
4075 and returns to the calling SConscript file the values of the
4076 variables named in the vars string arguments. Multiple strings
4077 contaning variable names may be passed to Return(). Any strings
4078 that contain white space
4079 The optional stop= keyword argument may be set to a false value
4081 to continue processing the rest of the SConscript file after the
4082 Return() call. This was the default behavior prior to SCons
4083 0.98. However, the values returned are still the values of the
4084 variables in the named vars at the point Return() is called.
4085 Examples:
4087 # Returns without returning a value.
4089 Return()
4090 # Returns the value of the 'foo' Python variable.
4092 Return("foo")
4093 # Returns the values of the Python variables 'foo' and 'bar'.
4095 Return("foo", "bar")
4096 # Returns the values of Python variables 'val1' and 'val2'.
4098 Return('val1 val2')
4099 Scanner(function, [argument, keys, path_function, node_class, node_fac‐
4102 tory, scan_check, recursive])
4103 env.Scanner(function, [argument, keys, path_function, node_class,
4105 node_factory, scan_check, recursive])
4106 Creates a Scanner object for the specified function. See the
4107 section "Scanner Objects," below, for a complete explanation of
4108 the arguments and behavior.
4109 env.SCCS()
4112 A factory function that returns a Builder object to be used to
4113 fetch source files from SCCS. The returned Builder is intended
4114 to be passed to the SourceCode() function.
4115 Example:
4117 env.SourceCode('.', env.SCCS())
4119 Note that scons will fetch source files from SCCS subdirectories
4121 automatically, so configuring SCCS as demonstrated in the above
4122 example should only be necessary if you are fetching from s.SCCS
4123 files in the same directory as the source files, or if you need
4124 to explicitly specify SCCS for a specific subdirectory.
4125 SConscript(scripts, [exports, variant_dir, duplicate])
4128 env.SConscript(scripts, [exports, variant_dir, duplicate])
4130 SConscript(dirs=subdirs, [name=script, exports, variant_dir, dupli‐
4132 cate])
4133 env.SConscript(dirs=subdirs, [name=script, exports, variant_dir, dupli‐
4135 cate])
4136 This tells scons to execute one or more subsidiary SConscript
4137 (configuration) files. Any variables returned by a called
4138 script using Return() will be returned by the call to SCon‐
4139 script(). There are two ways to call the SConscript() function.
4140 The first way you can call SConscript() is to explicitly specify
4142 one or more scripts as the first argument. A single script may
4143 be specified as a string; multiple scripts must be specified as
4144 a list (either explicitly or as created by a function like
4145 Split()). Examples:
4146 SConscript('SConscript') # run SConscript in the current directory
4147 SConscript('src/SConscript') # run SConscript in the src directory
4148 SConscript(['src/SConscript', 'doc/SConscript'])
4149 config = SConscript('MyConfig.py')
4150 The second way you can call SConscript() is to specify a list of
4152 (sub)directory names as a dirs=subdirs keyword argument. In
4153 this case, scons will, by default, execute a subsidiary configu‐
4154 ration file named SConscript in each of the specified directo‐
4155 ries. You may specify a name other than SConscript by supplying
4156 an optional name=script keyword argument. The first three exam‐
4157 ples below have the same effect as the first three examples
4158 above:
4159 SConscript(dirs='.') # run SConscript in the current directory
4160 SConscript(dirs='src') # run SConscript in the src directory
4161 SConscript(dirs=['src', 'doc'])
4162 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
4163 The optional exports argument provides a list of variable names
4165 or a dictionary of named values to export to the script(s).
4166 These variables are locally exported only to the specified
4167 script(s), and do not affect the global pool of variables used
4168 by the Export() function. The subsidiary script(s) must use the
4169 Import() function to import the variables. Examples:
4170 foo = SConscript('sub/SConscript', exports='env')
4171 SConscript('dir/SConscript', exports=['env', 'variable'])
4172 SConscript(dirs='subdir', exports='env variable')
4173 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
4174 If the optional variant_dir argument is present, it causes an
4176 effect equivalent to the VariantDir() method described below.
4177 (If variant_dir is not present, the duplicate argument is
4178 ignored.) The variant_dir argument is interpreted relative to
4179 the directory of the calling SConscript file. See the descrip‐
4180 tion of the VariantDir() function below for additional details
4181 and restrictions.
4182 If variant_dir is present, the source directory is the directory
4184 in which the SConscript file resides and the SConscript file is
4185 evaluated as if it were in the variant_dir directory:
4186 SConscript('src/SConscript', variant_dir = 'build')
4187 is equivalent to
4189 VariantDir('build', 'src')
4191 SConscript('build/SConscript')
4192 This later paradigm is often used when the sources are in the
4194 same directory as the SConstruct:
4195 SConscript('SConscript', variant_dir = 'build')
4197 is equivalent to
4199 VariantDir('build', '.')
4201 SConscript('build/SConscript')
4202 Here are some composite examples:
4204 # collect the configuration information and use it to build src and doc
4206 shared_info = SConscript('MyConfig.py')
4207 SConscript('src/SConscript', exports='shared_info')
4208 SConscript('doc/SConscript', exports='shared_info')
4209 # build debugging and production versions. SConscript
4211 # can use Dir('.').path to determine variant.
4212 SConscript('SConscript', variant_dir='debug', duplicate=0)
4213 SConscript('SConscript', variant_dir='prod', duplicate=0)
4214 # build debugging and production versions. SConscript
4216 # is passed flags to use.
4217 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
4218 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
4219 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
4220 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
4221 # build common documentation and compile for different architectures
4223 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
4224 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
4225 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
4226 SConscriptChdir(value)
4229 env.SConscriptChdir(value)
4231 By default, scons changes its working directory to the directory
4232 in which each subsidiary SConscript file lives. This behavior
4233 may be disabled by specifying either:
4234 SConscriptChdir(0)
4236 env.SConscriptChdir(0)
4237 in which case scons will stay in the top-level directory while
4239 reading all SConscript files. (This may be necessary when
4240 building from repositories, when all the directories in which
4241 SConscript files may be found don't necessarily exist locally.)
4242 You may enable and disable this ability by calling SCon‐
4243 scriptChdir() multiple times.
4244 Example:
4246 env = Environment()
4248 SConscriptChdir(0)
4249 SConscript('foo/SConscript') # will not chdir to foo
4250 env.SConscriptChdir(1)
4251 SConscript('bar/SConscript') # will chdir to bar
4252 SConsignFile([file, dbm_module])
4255 env.SConsignFile([file, dbm_module])
4257 This tells scons to store all file signatures in the specified
4258 database file. If the file name is omitted, .sconsign is used
4259 by default. (The actual file name(s) stored on disk may have an
4260 appropriated suffix appended by the dbm_module.) If file is not
4261 an absolute path name, the file is placed in the same directory
4262 as the top-level SConstruct file.
4263 If file is None, then scons will store file signatures in a sep‐
4265 arate .sconsign file in each directory, not in one global data‐
4266 base file. (This was the default behavior prior to SCons
4267 0.96.91 and 0.97.)
4268 The optional dbm_module argument can be used to specify which
4270 Python database module The default is to use a custom
4271 SCons.dblite module that uses pickled Python data structures,
4272 and which works on all Python versions.
4273 Examples:
4275 # Explicitly stores signatures in ".sconsign.dblite"
4277 # in the top-level SConstruct directory (the
4278 # default behavior).
4279 SConsignFile()
4280 # Stores signatures in the file "etc/scons-signatures"
4282 # relative to the top-level SConstruct directory.
4283 SConsignFile("etc/scons-signatures")
4284 # Stores signatures in the specified absolute file name.
4286 SConsignFile("/home/me/SCons/signatures")
4287 # Stores signatures in a separate .sconsign file
4289 # in each directory.
4290 SConsignFile(None)
4291 env.SetDefault(key=val, [...])
4294 Sets construction variables to default values specified with the
4295 keyword arguments if (and only if) the variables are not already
4296 set. The following statements are equivalent:
4297 env.SetDefault(FOO = 'foo')
4299 if 'FOO' not in env: env['FOO'] = 'foo'
4301 SetOption(name, value)
4304 env.SetOption(name, value)
4306 This function provides a way to set a select subset of the scons
4307 command line options from a SConscript file. The options sup‐
4308 ported are:
4309 clean which corresponds to -c, --clean and --remove;
4312 duplicate
4314 which corresponds to --duplicate;
4315 help which corresponds to -h and --help;
4317 implicit_cache
4319 which corresponds to --implicit-cache;
4320 max_drift
4322 which corresponds to --max-drift;
4323 no_exec
4325 which corresponds to -n, --no-exec, --just-print,
4326 --dry-run and --recon;
4327 num_jobs
4329 which corresponds to -j and --jobs;
4330 random
4332 which corresponds to --random; and
4333 stack_size
4335 which corresponds to --stack-size.
4336 See the documentation for the corresponding command line object for
4338 information about each specific option.
4339 Example:
4341 SetOption('max_drift', 1)
4343 SideEffect(side_effect, target)
4346 env.SideEffect(side_effect, target)
4348 Declares side_effect as a side effect of building target. Both
4349 side_effect and target can be a list, a file name, or a node. A
4350 side effect is a target file that is created or updated as a
4351 side effect of building other targets. For example, a Windows
4352 PDB file is created as a side effect of building the .obj files
4353 for a static library, and various log files are created updated
4354 as side effects of various TeX commands. If a target is a side
4355 effect of multiple build commands, scons will ensure that only
4356 one set of commands is executed at a time. Consequently, you
4357 only need to use this method for side-effect targets that are
4358 built as a result of multiple build commands.
4359 Because multiple build commands may update the same side effect
4361 file, by default the side_effect target is not automatically
4362 removed when the target is removed by the -c option. (Note,
4363 however, that the side_effect might be removed as part of clean‐
4364 ing the directory in which it lives.) If you want to make sure
4365 the side_effect is cleaned whenever a specific target is
4366 cleaned, you must specify this explicitly with the Clean() or
4367 env.Clean() function.
4368 SourceCode(entries, builder)
4371 env.SourceCode(entries, builder)
4373 This function and its associate factory functions are depre‐
4374 cated. There is no replacement. The intended use was to keep a
4375 local tree in sync with an archive, but in actuality the func‐
4376 tion only causes the archive to be fetched on the first run.
4377 Synchronizing with the archive is best done external to &SCons;.
4378 Arrange for non-existent source files to be fetched from a
4380 source code management system using the specified builder. The
4381 specified entries may be a Node, string or list of both, and may
4382 represent either individual source files or directories in which
4383 source files can be found.
4384 For any non-existent source files, scons will search up the
4386 directory tree and use the first SourceCode() builder it finds.
4387 The specified builder may be None, in which case scons will not
4388 use a builder to fetch source files for the specified entries,
4389 even if a SourceCode() builder has been specified for a direc‐
4390 tory higher up the tree.
4391 scons will, by default, fetch files from SCCS or RCS subdirecto‐
4393 ries without explicit configuration. This takes some extra pro‐
4394 cessing time to search for the necessary source code management
4395 files on disk. You can avoid these extra searches and speed up
4396 your build a little by disabling these searches as follows:
4397 env.SourceCode('.', None)
4399 Note that if the specified builder is one you create by hand, it
4401 must have an associated construction environment to use when
4402 fetching a source file.
4403 scons provides a set of canned factory functions that return
4405 appropriate Builders for various popular source code management
4406 systems. Canonical examples of invocation include:
4407 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
4409 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
4410 env.SourceCode('/', env.RCS())
4411 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
4412 env.SourceCode('no_source.c', None)
4413 SourceSignatures(type)
4416 env.SourceSignatures(type)
4418 Note: Although it is not yet officially deprecated, use of this
4419 function is discouraged. See the Decider() function for a more
4420 flexible and straightforward way to configure SCons' decision-
4421 making.
4422 The SourceSignatures() function tells scons how to decide if a
4424 source file (a file that is not built from any other files) has
4425 changed since the last time it was used to build a particular
4426 target file. Legal values are MD5 or timestamp.
4427 If the environment method is used, the specified type of source
4429 signature is only used when deciding whether targets built with
4430 that environment are up-to-date or must be rebuilt. If the
4431 global function is used, the specified type of source signature
4432 becomes the default used for all decisions about whether targets
4433 are up-to-date.
4434 MD5 means scons decides that a source file has changed if the
4436 MD5 checksum of its contents has changed since the last time it
4437 was used to rebuild a particular target file.
4438 timestamp means scons decides that a source file has changed if
4440 its timestamp (modification time) has changed since the last
4441 time it was used to rebuild a particular target file. (Note
4442 that although this is similar to the behavior of Make, by
4443 default it will also rebuild if the dependency is older than the
4444 last time it was used to rebuild the target file.)
4445 There is no different between the two behaviors for Python
4447 Value() node objects.
4448 MD5 signatures take longer to compute, but are more accurate
4450 than timestamp signatures. The default value is MD5.
4451 Note that the default TargetSignatures() setting (see below) is
4453 to use this SourceSignatures() setting for any target files that
4454 are used to build other target files. Consequently, changing
4455 the value of SourceSignatures() will, by default, affect the up-
4456 to-date decision for all files in the build (or all files built
4457 with a specific construction environment when env.SourceSigna‐
4458 tures() is used).
4459 Split(arg)
4462 env.Split(arg)
4464 Returns a list of file names or other objects. If arg is a
4465 string, it will be split on strings of white-space characters
4466 within the string, making it easier to write long lists of file
4467 names. If arg is already a list, the list will be returned
4468 untouched. If arg is any other type of object, it will be
4469 returned as a list containing just the object.
4470 Example:
4472 files = Split("f1.c f2.c f3.c")
4474 files = env.Split("f4.c f5.c f6.c")
4475 files = Split("""
4476 f7.c
4477 f8.c
4478 f9.c
4479 """)
4480 env.subst(input, [raw, target, source, conv])
4483 Performs construction variable interpolation on the specified
4484 string or sequence argument input.
4485 By default, leading or trailing white space will be removed from
4487 the result. and all sequences of white space will be compressed
4488 to a single space character. Additionally, any $( and $) char‐
4489 acter sequences will be stripped from the returned string, The
4490 optional raw argument may be set to 1 if you want to preserve
4491 white space and $(-$) sequences. The raw argument may be set to
4492 2 if you want to strip all characters between any $( and $)
4493 pairs (as is done for signature calculation).
4494 If the input is a sequence (list or tuple), the individual ele‐
4496 ments of the sequence will be expanded, and the results will be
4497 returned as a list.
4498 The optional target and source keyword arguments must be set to
4500 lists of target and source nodes, respectively, if you want the
4501 $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for
4502 expansion. This is usually necessary if you are calling
4503 env.subst() from within a Python function used as an SCons
4504 action.
4505 Returned string values or sequence elements are converted to
4507 their string representation by default. The optional conv argu‐
4508 ment may specify a conversion function that will be used in
4509 place of the default. For example, if you want Python objects
4510 (including SCons Nodes) to be returned as Python objects, you
4511 can use the Python lambda idiom to pass in an unnamed function
4512 that simply returns its unconverted argument.
4513 Example:
4515 print env.subst("The C compiler is: $CC")
4517 def compile(target, source, env):
4519 sourceDir = env.subst("${SOURCE.srcdir}",
4520 target=target,
4521 source=source)
4522 source_nodes = env.subst('$EXPAND_TO_NODELIST',
4524 conv=lambda x: x)
4525 Tag(node, tags)
4528 Annotates file or directory Nodes with information about how the
4529 Package() Builder should package those files or directories.
4530 All tags are optional.
4531 Examples:
4533 # makes sure the built library will be installed with 0644 file
4535 # access mode
4536 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
4537 # marks file2.txt to be a documentation file
4539 Tag( 'file2.txt', DOC )
4540 TargetSignatures(type)
4543 env.TargetSignatures(type)
4545 Note: Although it is not yet officially deprecated, use of this
4546 function is discouraged. See the Decider() function for a more
4547 flexible and straightforward way to configure SCons' decision-
4548 making.
4549 The TargetSignatures() function tells scons how to decide if a
4551 target file (a file that is built from any other files) has
4552 changed since the last time it was used to build some other tar‐
4553 get file. Legal values are build; content (or its synonym MD5);
4554 timestamp; or source.
4555 If the environment method is used, the specified type of target
4557 signature is only used for targets built with that environment.
4558 If the global function is used, the specified type of signature
4559 becomes the default used for all target files that don't have an
4560 explicit target signature type specified for their environments.
4561 content (or its synonym MD5) means scons decides that a target
4563 file has changed if the MD5 checksum of its contents has changed
4564 since the last time it was used to rebuild some other target
4565 file. This means scons will open up MD5 sum the contents of
4566 target files after they're built, and may decide that it does
4567 not need to rebuild "downstream" target files if a file was
4568 rebuilt with exactly the same contents as the last time.
4569 timestamp means scons decides that a target file has changed if
4571 its timestamp (modification time) has changed since the last
4572 time it was used to rebuild some other target file. (Note that
4573 although this is similar to the behavior of Make, by default it
4574 will also rebuild if the dependency is older than the last time
4575 it was used to rebuild the target file.)
4576 source means scons decides that a target file has changed as
4578 specified by the corresponding SourceSignatures() setting (MD5
4579 or timestamp). This means that scons will treat all input files
4580 to a target the same way, regardless of whether they are source
4581 files or have been built from other files.
4582 build means scons decides that a target file has changed if it
4584 has been rebuilt in this invocation or if its content or time‐
4585 stamp have changed as specified by the corresponding SourceSig‐
4586 natures() setting. This "propagates" the status of a rebuilt
4587 file so that other "downstream" target files will always be
4588 rebuilt, even if the contents or the timestamp have not changed.
4589 build signatures are fastest because content (or MD5) signatures
4591 take longer to compute, but are more accurate than timestamp
4592 signatures, and can prevent unnecessary "downstream" rebuilds
4593 when a target file is rebuilt to the exact same contents as the
4594 previous build. The source setting provides the most consistent
4595 behavior when other target files may be rebuilt from both source
4596 and target input files. The default value is source.
4597 Because the default setting is source, using SourceSignatures()
4599 is generally preferable to TargetSignatures(), so that the up-
4600 to-date decision will be consistent for all files (or all files
4601 built with a specific construction environment). Use of Tar‐
4602 getSignatures() provides specific control for how built target
4603 files affect their "downstream" dependencies.
4604 Tool(string, [toolpath, **kw])
4607 env.Tool(string, [toolpath, **kw])
4609 The Tool() form of the function returns a callable object that
4610 can be used to initialize a construction environment using the
4611 tools keyword of the Environment() method. The object may be
4612 called with a construction environment as an argument, in which
4613 case the object will add the necessary variables to the con‐
4614 struction environment and the name of the tool will be added to
4615 the $TOOLS construction variable.
4616 Additional keyword arguments are passed to the tool's generate()
4618 method.
4619 Examples:
4621 env = Environment(tools = [ Tool('msvc') ])
4623 env = Environment()
4625 t = Tool('msvc')
4626 t(env) # adds 'msvc' to the TOOLS variable
4627 u = Tool('opengl', toolpath = ['tools'])
4628 u(env) # adds 'opengl' to the TOOLS variable
4629 The env.Tool() form of the function applies the callable object
4631 for the specified tool string to the environment through which
4632 the method was called.
4633 Additional keyword arguments are passed to the tool's generate()
4635 method.
4636 env.Tool('gcc')
4638 env.Tool('opengl', toolpath = ['build/tools'])
4639 Value(value, [built_value])
4642 env.Value(value, [built_value])
4644 Returns a Node object representing the specified Python value.
4645 Value Nodes can be used as dependencies of targets. If the
4646 result of calling str(value) changes between SCons runs, any
4647 targets depending on Value(value) will be rebuilt. (This is
4648 true even when using timestamps to decide if files are up-to-
4649 date.) When using timestamp source signatures, Value Nodes'
4650 timestamps are equal to the system time when the Node is cre‐
4651 ated.
4652 The returned Value Node object has a write() method that can be
4654 used to "build" a Value Node by setting a new value. The
4655 optional built_value argument can be specified when the Value
4656 Node is created to indicate the Node should already be consid‐
4657 ered "built." There is a corresponding read() method that will
4658 return the built value of the Node.
4659 Examples:
4661 env = Environment()
4663 def create(target, source, env):
4665 # A function that will write a 'prefix=$SOURCE'
4666 # string into the file name specified as the
4667 # $TARGET.
4668 f = open(str(target[0]), 'wb')
4669 f.write('prefix=' + source[0].get_contents())
4670 # Fetch the prefix= argument, if any, from the command
4672 # line, and use /usr/local as the default.
4673 prefix = ARGUMENTS.get('prefix', '/usr/local')
4674 # Attach a .Config() builder for the above function action
4676 # to the construction environment.
4677 env['BUILDERS']['Config'] = Builder(action = create)
4678 env.Config(target = 'package-config', source = Value(prefix))
4679 def build_value(target, source, env):
4681 # A function that "builds" a Python Value by updating
4682 # the the Python value with the contents of the file
4683 # specified as the source of the Builder call ($SOURCE).
4684 target[0].write(source[0].get_contents())
4685 output = env.Value('before')
4687 input = env.Value('after')
4688 # Attach a .UpdateValue() builder for the above function
4690 # action to the construction environment.
4691 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
4692 env.UpdateValue(target = Value(output), source = Value(input))
4693 VariantDir(variant_dir, src_dir, [duplicate])
4696 env.VariantDir(variant_dir, src_dir, [duplicate])
4698 Use the VariantDir() function to create a copy of your sources
4699 in another location: if a name under variant_dir is not found
4700 but exists under src_dir, the file or directory is copied to
4701 variant_dir. Target files can be built in a different directory
4702 than the original sources by simply refering to the sources (and
4703 targets) within the variant tree.
4704 VariantDir() can be called multiple times with the same src_dir
4706 to set up multiple builds with different options (variants).
4707 The src_dir location must be in or underneath the SConstruct
4708 file's directory, and variant_dir may not be underneath src_dir.
4709 The default behavior is for scons to physically duplicate the
4711 source files in the variant tree. Thus, a build performed in
4712 the variant tree is guaranteed to be identical to a build per‐
4713 formed in the source tree even if intermediate source files are
4714 generated during the build, or preprocessors or other scanners
4715 search for included files relative to the source file, or indi‐
4716 vidual compilers or other invoked tools are hard-coded to put
4717 derived files in the same directory as source files.
4718 If possible on the platform, the duplication is performed by
4720 linking rather than copying; see also the --duplicate command-
4721 line option. Moreover, only the files needed for the build are
4722 duplicated; files and directories that are not used are not
4723 present in variant_dir.
4724 Duplicating the source tree may be disabled by setting the
4726 duplicate argument to 0 (zero). This will cause scons to invoke
4727 Builders using the path names of source files in src_dir and the
4728 path names of derived files within variant_dir. This is always
4729 more efficient than duplicate=1, and is usually safe for most
4730 builds (but see above for cases that may cause problems).
4731 Note that VariantDir() works most naturally with a subsidiary
4733 SConscript file. However, you would then call the subsidiary
4734 SConscript file not in the source directory, but in the vari‐
4735 ant_dir, regardless of the value of duplicate. This is how you
4736 tell scons which variant of a source tree to build:
4737 # run src/SConscript in two variant directories
4739 VariantDir('build/variant1', 'src')
4740 SConscript('build/variant1/SConscript')
4741 VariantDir('build/variant2', 'src')
4742 SConscript('build/variant2/SConscript')
4743 See also the SConscript() function, described above, for another
4745 way to specify a variant directory in conjunction with calling a
4746 subsidiary SConscript file.
4747 Examples:
4749 # use names in the build directory, not the source directory
4751 VariantDir('build', 'src', duplicate=0)
4752 Program('build/prog', 'build/source.c')
4753 # this builds both the source and docs in a separate subtree
4755 VariantDir('build', '.', duplicate=0)
4756 SConscript(dirs=['build/src','build/doc'])
4757 # same as previous example, but only uses SConscript
4759 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
4760 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
4761 WhereIs(program, [path, pathext, reject])
4764 env.WhereIs(program, [path, pathext, reject])
4766 Searches for the specified executable program, returning the
4767 full path name to the program if it is found, and returning None
4768 if not. Searches the specified path, the value of the calling
4769 environment's PATH (env['ENV']['PATH']), or the user's current
4770 external PATH (os.environ['PATH']) by default. On Windows sys‐
4771 tems, searches for executable programs with any of the file
4772 extensions listed in the specified pathext, the calling environ‐
4773 ment's PATHEXT (env['ENV']['PATHEXT']) or the user's current
4774 PATHEXT (os.environ['PATHEXT']) by default. Will not select any
4775 path name or names in the specified reject list, if any.
4776 SConscript Variables
4779 In addition to the global functions and methods, scons supports a num‐
4780 ber of Python variables that can be used in SConscript files to affect
4781 how you want the build to be performed. These variables may be
4782 accessed from custom Python modules that you import into an SConscript
4783 file by adding the following to the Python module:
4784 from SCons.Script import *
4786 ARGLIST
4789 A list keyword=value arguments specified on the command line.
4790 Each element in the list is a tuple containing the (key‐
4791 word,value) of the argument. The separate keyword and value
4792 elements of the tuple can be accessed by subscripting for ele‐
4793 ment [0] and [1] of the tuple, respectively.
4794 Example:
4796 print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1]
4798 print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1]
4799 third_tuple = ARGLIST[2]
4800 print "third keyword, value =", third_tuple[0], third_tuple[1]
4801 for key, value in ARGLIST:
4802 # process key and value
4803 ARGUMENTS
4806 A dictionary of all the keyword=value arguments specified on the
4807 command line. The dictionary is not in order, and if a given
4808 keyword has more than one value assigned to it on the command
4809 line, the last (right-most) value is the one in the ARGUMENTS
4810 dictionary.
4811 Example:
4813 if ARGUMENTS.get('debug', 0):
4815 env = Environment(CCFLAGS = '-g')
4816 else:
4817 env = Environment()
4818 BUILD_TARGETS
4821 A list of the targets which scons will actually try to build,
4822 regardless of whether they were specified on the command line or
4823 via the Default() function or method. The elements of this list
4824 may be strings or nodes, so you should run the list through the
4825 Python str function to make sure any Node path names are con‐
4826 verted to strings.
4827 Because this list may be taken from the list of targets speci‐
4829 fied using the Default() function or method, the contents of the
4830 list may change on each successive call to Default(). See the
4831 DEFAULT_TARGETS list, below, for additional information.
4832 Example:
4834 if 'foo' in BUILD_TARGETS:
4836 print "Don't forget to test the `foo' program!"
4837 if 'special/program' in BUILD_TARGETS:
4838 SConscript('special')
4839 Note that the BUILD_TARGETS list only contains targets expected
4841 listed on the command line or via calls to the Default() func‐
4842 tion or method. It does not contain all dependent targets that
4843 will be built as a result of making the sure the explicitly-
4844 specified targets are up to date.
4845 COMMAND_LINE_TARGETS
4848 A list of the targets explicitly specified on the command line.
4849 If there are no targets specified on the command line, the list
4850 is empty. This can be used, for example, to take specific
4851 actions only when a certain target or targets is explicitly
4852 being built.
4853 Example:
4855 if 'foo' in COMMAND_LINE_TARGETS:
4857 print "Don't forget to test the `foo' program!"
4858 if 'special/program' in COMMAND_LINE_TARGETS:
4859 SConscript('special')
4860 DEFAULT_TARGETS
4863 A list of the target nodes that have been specified using the
4864 Default() function or method. The elements of the list are
4865 nodes, so you need to run them through the Python str function
4866 to get at the path name for each Node.
4867 Example:
4869 print str(DEFAULT_TARGETS[0])
4871 if 'foo' in map(str, DEFAULT_TARGETS):
4872 print "Don't forget to test the `foo' program!"
4873 The contents of the DEFAULT_TARGETS list change on on each suc‐
4875 cessive call to the Default() function:
4876 print map(str, DEFAULT_TARGETS) # originally []
4878 Default('foo')
4879 print map(str, DEFAULT_TARGETS) # now a node ['foo']
4880 Default('bar')
4881 print map(str, DEFAULT_TARGETS) # now a node ['foo', 'bar']
4882 Default(None)
4883 print map(str, DEFAULT_TARGETS) # back to []
4884 Consequently, be sure to use DEFAULT_TARGETS only after you've
4886 made all of your Default() calls, or else simply be careful of
4887 the order of these statements in your SConscript files so that
4888 you don't look for a specific default target before it's actu‐
4889 ally been added to the list.
4890 Construction Variables
4893 A construction environment has an associated dictionary of construction
4894 variables that are used by built-in or user-supplied build rules. Con‐
4895 struction variables must follow the same rules for Python identifiers:
4896 the initial character must be an underscore or letter, followed by any
4897 number of underscores, letters, or digits.
4898 A number of useful construction variables are automatically defined by
4900 scons for each supported platform, and additional construction vari‐
4901 ables can be defined by the user. The following is a list of the auto‐
4902 matically defined construction variables:
4903 AR The static library archiver.
4907 ARCHITECTURE
4910 Specifies the system architecture for which the package is being
4911 built. The default is the system architecture of the machine on
4912 which SCons is running. This is used to fill in the Architec‐
4913 ture: field in an Ipkg control file, and as part of the name of
4914 a generated RPM file.
4915 ARCOM The command line used to generate a static library from object
4918 files.
4919 ARCOMSTR
4922 The string displayed when an object file is generated from an
4923 assembly-language source file. If this is not set, then $ARCOM
4924 (the command line) is displayed.
4925 env = Environment(ARCOMSTR = "Archiving $TARGET")
4927 ARFLAGS
4930 General options passed to the static library archiver.
4931 AS The assembler.
4934 ASCOM The command line used to generate an object file from an assem‐
4937 bly-language source file.
4938 ASCOMSTR
4941 The string displayed when an object file is generated from an
4942 assembly-language source file. If this is not set, then $ASCOM
4943 (the command line) is displayed.
4944 env = Environment(ASCOMSTR = "Assembling $TARGET")
4946 ASFLAGS
4949 General options passed to the assembler.
4950 ASPPCOM
4953 The command line used to assemble an assembly-language source
4954 file into an object file after first running the file through
4955 the C preprocessor. Any options specified in the $ASFLAGS and
4956 $CPPFLAGS construction variables are included on this command
4957 line.
4958 ASPPCOMSTR
4961 The string displayed when an object file is generated from an
4962 assembly-language source file after first running the file
4963 through the C preprocessor. If this is not set, then $ASPPCOM
4964 (the command line) is displayed.
4965 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
4967 ASPPFLAGS
4970 General options when an assembling an assembly-language source
4971 file into an object file after first running the file through
4972 the C preprocessor. The default is to use the value of
4973 $ASFLAGS.
4974 BIBTEX The bibliography generator for the TeX formatter and typesetter
4977 and the LaTeX structured formatter and typesetter.
4978 BIBTEXCOM
4981 The command line used to call the bibliography generator for the
4982 TeX formatter and typesetter and the LaTeX structured formatter
4983 and typesetter.
4984 BIBTEXCOMSTR
4987 The string displayed when generating a bibliography for TeX or
4988 LaTeX. If this is not set, then $BIBTEXCOM (the command line)
4989 is displayed.
4990 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
4992 BIBTEXFLAGS
4995 General options passed to the bibliography generator for the TeX
4996 formatter and typesetter and the LaTeX structured formatter and
4997 typesetter.
4998 BITKEEPER
5001 The BitKeeper executable.
5002 BITKEEPERCOM
5005 The command line for fetching source files using BitKeeper.
5006 BITKEEPERCOMSTR
5009 The string displayed when fetching a source file using Bit‐
5010 Keeper. If this is not set, then $BITKEEPERCOM (the command
5011 line) is displayed.
5012 BITKEEPERGET
5015 The command ($BITKEEPER) and subcommand for fetching source
5016 files using BitKeeper.
5017 BITKEEPERGETFLAGS
5020 Options that are passed to the BitKeeper get subcommand.
5021 BUILDERS
5024 A dictionary mapping the names of the builders available through
5025 this environment to underlying Builder objects. Builders named
5026 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript,
5027 and Program are available by default. If you initialize this
5028 variable when an Environment is created:
5029 env = Environment(BUILDERS = {'NewBuilder' : foo})
5031 the default Builders will no longer be available. To use a new
5033 Builder object in addition to the default Builders, add your new
5034 Builder object like this:
5035 env = Environment()
5037 env.Append(BUILDERS = {'NewBuilder' : foo})
5038 or this:
5040 env = Environment()
5042 env['BUILDERS]['NewBuilder'] = foo
5043 CC The C compiler.
5046 CCCOM The command line used to compile a C source file to a (static)
5049 object file. Any options specified in the $CFLAGS, $CCFLAGS and
5050 $CPPFLAGS construction variables are included on this command
5051 line.
5052 CCCOMSTR
5055 The string displayed when a C source file is compiled to a
5056 (static) object file. If this is not set, then $CCCOM (the com‐
5057 mand line) is displayed.
5058 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
5060 CCFLAGS
5063 General options that are passed to the C and C++ compilers.
5064 CCPCHFLAGS
5067 Options added to the compiler command line to support building
5068 with precompiled headers. The default value expands expands to
5069 the appropriate Microsoft Visual C++ command-line options when
5070 the $PCH construction variable is set.
5071 CCPDBFLAGS
5074 Options added to the compiler command line to support storing
5075 debugging information in a Microsoft Visual C++ PDB file. The
5076 default value expands expands to appropriate Microsoft Visual
5077 C++ command-line options when the $PDB construction variable is
5078 set.
5079 The Visual C++ compiler option that SCons uses by default to
5081 generate PDB information is /Z7. This works correctly with par‐
5082 allel (-j) builds because it embeds the debug information in the
5083 intermediate object files, as opposed to sharing a single PDB
5084 file between multiple object files. This is also the only way
5085 to get debug information embedded into a static library. Using
5086 the /Zi instead may yield improved link-time performance,
5087 although parallel builds will no longer work.
5088 You can generate PDB files with the /Zi switch by overriding the
5090 default $CCPDBFLAGS variable as follows:
5091 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
5093 An alternative would be to use the /Zi to put the debugging
5095 information in a separate .pdb file for each object file by
5096 overriding the $CCPDBFLAGS variable as follows:
5097 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
5099 CCVERSION
5102 The version number of the C compiler. This may or may not be
5103 set, depending on the specific C compiler being used.
5104 CFILESUFFIX
5107 The suffix for C source files. This is used by the internal
5108 CFile builder when generating C files from Lex (.l) or YACC (.y)
5109 input files. The default suffix, of course, is .c (lower case).
5110 On case-insensitive systems (like Windows), SCons also treats .C
5111 (upper case) files as C files.
5112 CFLAGS General options that are passed to the C compiler (C only; not
5115 C++).
5116 CHANGE_SPECFILE
5119 A hook for modifying the file that controls the packaging build
5120 (the .spec for RPM, the control for Ipkg, the .wxs for MSI). If
5121 set, the function will be called after the SCons template for
5122 the file has been written. XXX
5123 CHANGED_SOURCES
5126 A reserved variable name that may not be set or used in a con‐
5127 struction environment. (See "Variable Substitution," below.)
5128 CHANGED_TARGETS
5131 A reserved variable name that may not be set or used in a con‐
5132 struction environment. (See "Variable Substitution," below.)
5133 CHANGELOG
5136 The name of a file containing the change log text to be included
5137 in the package. This is included as the %changelog section of
5138 the RPM .spec file.
5139 _concat
5142 A function used to produce variables like $_CPPINCFLAGS. It
5143 takes four or five arguments: a prefix to concatenate onto each
5144 element, a list of elements, a suffix to concatenate onto each
5145 element, an environment for variable interpolation, and an
5146 optional function that will be called to transform the list
5147 before concatenation.
5148 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
5150 CONFIGUREDIR
5153 The name of the directory in which Configure context test files
5154 are written. The default is .sconf_temp in the top-level direc‐
5155 tory containing the SConstruct file.
5156 CONFIGURELOG
5159 The name of the Configure context log file. The default is con‐
5160 fig.log in the top-level directory containing the SConstruct
5161 file.
5162 _CPPDEFFLAGS
5165 An automatically-generated construction variable containing the
5166 C preprocessor command-line options to define values. The value
5167 of $_CPPDEFFLAGS is created by appending $CPPDEFPREFIX and
5168 $CPPDEFSUFFIX to the beginning and end of each definition in
5169 $CPPDEFINES.
5170 CPPDEFINES
5173 A platform independent specification of C preprocessor defini‐
5174 tions. The definitions will be added to command lines through
5175 the automatically-generated $_CPPDEFFLAGS construction variable
5176 (see above), which is constructed according to the type of value
5177 of $CPPDEFINES:
5178 If $CPPDEFINES is a string, the values of the $CPPDEFPRE‐
5180 FIXand$CPPDEFSUFFIX construction variables will be added to the
5181 beginning and end.
5182 # Will add -Dxyz to POSIX compiler command lines,
5184 # and /Dxyz to Microsoft Visual C++ command lines.
5185 env = Environment(CPPDEFINES='xyz')
5186 If $CPPDEFINES is a list, the values of the $CPPDEFPRE‐
5188 FIXand$CPPDEFSUFFIX construction variables will be appended to
5189 the beginning and end of each element in the list. If any ele‐
5190 ment is a list or tuple, then the first item is the name being
5191 defined and the second item is its value:
5192 # Will add -DB=2 -DA to POSIX compiler command lines,
5194 # and /DB=2 /DA to Microsoft Visual C++ command lines.
5195 env = Environment(CPPDEFINES=[('B', 2), 'A'])
5196 If $CPPDEFINES is a dictionary, the values of the $CPPDEFPRE‐
5198 FIXand$CPPDEFSUFFIX construction variables will be appended to
5199 the beginning and end of each item from the dictionary. The key
5200 of each dictionary item is a name being defined to the dictio‐
5201 nary item's corresponding value; if the value is None, then the
5202 name is defined without an explicit value. Note that the
5203 resulting flags are sorted by keyword to ensure that the order
5204 of the options on the command line is consistent each time scons
5205 is run.
5206 # Will add -DA -DB=2 to POSIX compiler command lines,
5208 # and /DA /DB=2 to Microsoft Visual C++ command lines.
5209 env = Environment(CPPDEFINES={'B':2, 'A':None})
5210 CPPDEFPREFIX
5213 The prefix used to specify preprocessor definitions on the C
5214 compiler command line. This will be appended to the beginning
5215 of each definition in the $CPPDEFINES construction variable when
5216 the $_CPPDEFFLAGS variable is automatically generated.
5217 CPPDEFSUFFIX
5220 The suffix used to specify preprocessor definitions on the C
5221 compiler command line. This will be appended to the end of each
5222 definition in the $CPPDEFINES construction variable when the
5223 $_CPPDEFFLAGS variable is automatically generated.
5224 CPPFLAGS
5227 User-specified C preprocessor options. These will be included
5228 in any command that uses the C preprocessor, including not just
5229 compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
5230 $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
5231 $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
5232 compile a Fortran source file, and the $ASPPCOM command line
5233 used to assemble an assembly language source file, after first
5234 running each file through the C preprocessor. Note that this
5235 variable does not contain -I (or similar) include search path
5236 options that scons generates automatically from $CPPPATH. See
5237 $_CPPINCFLAGS, below, for the variable that expands to those
5238 options.
5239 _CPPINCFLAGS
5242 An automatically-generated construction variable containing the
5243 C preprocessor command-line options for specifying directories
5244 to be searched for include files. The value of $_CPPINCFLAGS is
5245 created by appending $INCPREFIX and $INCSUFFIX to the beginning
5246 and end of each directory in $CPPPATH.
5247 CPPPATH
5250 The list of directories that the C preprocessor will search for
5251 include directories. The C/C++ implicit dependency scanner will
5252 search these directories for include files. Don't explicitly put
5253 include directory arguments in CCFLAGS or CXXFLAGS because the
5254 result will be non-portable and the directories will not be
5255 searched by the dependency scanner. Note: directory names in
5256 CPPPATH will be looked-up relative to the SConscript directory
5257 when they are used in a command. To force scons to look-up a
5258 directory relative to the root of the source tree use #:
5259 env = Environment(CPPPATH='#/include')
5261 The directory look-up can also be forced using the Dir() func‐
5263 tion:
5264 include = Dir('include')
5266 env = Environment(CPPPATH=include)
5267 The directory list will be added to command lines through the
5269 automatically-generated $_CPPINCFLAGS construction variable,
5270 which is constructed by appending the values of the $INCPRE‐
5271 FIXand$INCSUFFIX construction variables to the beginning and end
5272 of each directory in $CPPPATH. Any command lines you define
5273 that need the CPPPATH directory list should include
5274 $_CPPINCFLAGS:
5275 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
5277 CPPSUFFIXES
5280 The list of suffixes of files that will be scanned for C pre‐
5281 processor implicit dependencies (#include lines). The default
5282 list is:
5283 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
5285 ".h", ".H", ".hxx", ".hpp", ".hh",
5286 ".F", ".fpp", ".FPP",
5287 ".m", ".mm",
5288 ".S", ".spp", ".SPP"]
5289 CVS The CVS executable.
5292 CVSCOFLAGS
5295 Options that are passed to the CVS checkout subcommand.
5296 CVSCOM The command line used to fetch source files from a CVS reposi‐
5299 tory.
5300 CVSCOMSTR
5303 The string displayed when fetching a source file from a CVS
5304 repository. If this is not set, then $CVSCOM (the command line)
5305 is displayed.
5306 CVSFLAGS
5309 General options that are passed to CVS. By default, this is set
5310 to -d $CVSREPOSITORY to specify from where the files must be
5311 fetched.
5312 CVSREPOSITORY
5315 The path to the CVS repository. This is referenced in the
5316 default $CVSFLAGS value.
5317 CXX The C++ compiler.
5320 CXXCOM The command line used to compile a C++ source file to an object
5323 file. Any options specified in the $CXXFLAGS and $CPPFLAGS con‐
5324 struction variables are included on this command line.
5325 CXXCOMSTR
5328 The string displayed when a C++ source file is compiled to a
5329 (static) object file. If this is not set, then $CXXCOM (the
5330 command line) is displayed.
5331 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
5333 CXXFILESUFFIX
5336 The suffix for C++ source files. This is used by the internal
5337 CXXFile builder when generating C++ files from Lex (.ll) or YACC
5338 (.yy) input files. The default suffix is .cc. SCons also
5339 treats files with the suffixes .cpp, .cxx, .c++, and .C++ as C++
5340 files, and files with .mm suffixes as Objective C++ files. On
5341 case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
5342 SCons also treats .C (upper case) files as C++ files.
5343 CXXFLAGS
5346 General options that are passed to the C++ compiler. By
5347 default, this includes the value of $CCFLAGS, so that setting
5348 $CCFLAGS affects both C and C++ compilation. If you want to add
5349 C++-specific flags, you must set or override the value of
5350 $CXXFLAGS.
5351 CXXVERSION
5354 The version number of the C++ compiler. This may or may not be
5355 set, depending on the specific C++ compiler being used.
5356 DESCRIPTION
5359 A long description of the project being packaged. This is
5360 included in the relevant section of the file that controls the
5361 packaging build.
5362 DESCRIPTION_lang
5365 A language-specific long description for the specified lang.
5366 This is used to populate a %description -l section of an RPM
5367 .spec file.
5368 Dir A function that converts a string into a Dir instance relative
5371 to the target being built.
5372 Dirs A function that converts a list of strings into a list of Dir
5375 instances relative to the target being built.
5376 DSUFFIXES
5379 The list of suffixes of files that will be scanned for imported
5380 D package files. The default list is:
5381 ['.d']
5383 DVIPDF The TeX DVI file to PDF file converter.
5386 DVIPDFCOM
5389 The command line used to convert TeX DVI files into a PDF file.
5390 DVIPDFCOMSTR
5393 The string displayed when a TeX DVI file is converted into a PDF
5394 file. If this is not set, then $DVIPDFCOM (the command line) is
5395 displayed.
5396 DVIPDFFLAGS
5399 General options passed to the TeX DVI file to PDF file con‐
5400 verter.
5401 DVIPS The TeX DVI file to PostScript converter.
5404 DVIPSFLAGS
5407 General options passed to the TeX DVI file to PostScript con‐
5408 verter.
5409 ENV A dictionary of environment variables to use when invoking com‐
5412 mands. When $ENV is used in a command all list values will be
5413 joined using the path separator and any other non-string values
5414 will simply be coerced to a string. Note that, by default,
5415 scons does not propagate the environment in force when you exe‐
5416 cute scons to the commands used to build target files. This is
5417 so that builds will be guaranteed repeatable regardless of the
5418 environment variables set at the time scons is invoked.
5419 If you want to propagate your environment variables to the com‐
5421 mands executed to build target files, you must do so explicitly:
5422 import os
5424 env = Environment(ENV = os.environ)
5425 Note that you can choose only to propagate certain environment
5427 variables. A common example is the system PATH environment
5428 variable, so that scons uses the same utilities as the invoking
5429 shell (or other process):
5430 import os
5432 env = Environment(ENV = {'PATH' : os.environ['PATH']})
5433 ESCAPE A function that will be called to escape shell special charac‐
5436 ters in command lines. The function should take one argument:
5437 the command line string to escape; and should return the escaped
5438 command line.
5439 F77 The Fortran 77 compiler. You should normally set the $FORTRAN
5442 variable, which specifies the default Fortran compiler for all
5443 Fortran versions. You only need to set $F77 if you need to use
5444 a specific compiler or compiler version for Fortran 77 files.
5445 F77COM The command line used to compile a Fortran 77 source file to an
5448 object file. You only need to set $F77COM if you need to use a
5449 specific command line for Fortran 77 files. You should normally
5450 set the $FORTRANCOM variable, which specifies the default com‐
5451 mand line for all Fortran versions.
5452 F77COMSTR
5455 The string displayed when a Fortran 77 source file is compiled
5456 to an object file. If this is not set, then $F77COM or $FOR‐
5457 TRANCOM (the command line) is displayed.
5458 F77FILESUFFIXES
5461 The list of file extensions for which the F77 dialect will be
5462 used. By default, this is ['.f77']
5463 F77FLAGS
5466 General user-specified options that are passed to the Fortran 77
5467 compiler. Note that this variable does not contain -I (or simi‐
5468 lar) include search path options that scons generates automati‐
5469 cally from $F77PATH. See $_F77INCFLAGS below, for the variable
5470 that expands to those options. You only need to set $F77FLAGS
5471 if you need to define specific user options for Fortran 77
5472 files. You should normally set the $FORTRANFLAGS variable,
5473 which specifies the user-specified options passed to the default
5474 Fortran compiler for all Fortran versions.
5475 _F77INCFLAGS
5478 An automatically-generated construction variable containing the
5479 Fortran 77 compiler command-line options for specifying directo‐
5480 ries to be searched for include files. The value of
5481 $_F77INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
5482 to the beginning and end of each directory in $F77PATH.
5483 F77PATH
5486 The list of directories that the Fortran 77 compiler will search
5487 for include directories. The implicit dependency scanner will
5488 search these directories for include files. Don't explicitly put
5489 include directory arguments in $F77FLAGS because the result will
5490 be non-portable and the directories will not be searched by the
5491 dependency scanner. Note: directory names in $F77PATH will be
5492 looked-up relative to the SConscript directory when they are
5493 used in a command. To force scons to look-up a directory rela‐
5494 tive to the root of the source tree use #: You only need to set
5495 $F77PATH if you need to define a specific include path for For‐
5496 tran 77 files. You should normally set the $FORTRANPATH vari‐
5497 able, which specifies the include path for the default Fortran
5498 compiler for all Fortran versions.
5499 env = Environment(F77PATH='#/include')
5501 The directory look-up can also be forced using the Dir() func‐
5503 tion:
5504 include = Dir('include')
5506 env = Environment(F77PATH=include)
5507 The directory list will be added to command lines through the
5509 automatically-generated $_F77INCFLAGS construction variable,
5510 which is constructed by appending the values of the $INCPRE‐
5511 FIXand$INCSUFFIX construction variables to the beginning and end
5512 of each directory in $F77PATH. Any command lines you define
5513 that need the F77PATH directory list should include
5514 $_F77INCFLAGS:
5515 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
5517 F77PPCOM
5520 The command line used to compile a Fortran 77 source file to an
5521 object file after first running the file through the C pre‐
5522 processor. Any options specified in the $F77FLAGS and $CPPFLAGS
5523 construction variables are included on this command line. You
5524 only need to set $F77PPCOM if you need to use a specific C-pre‐
5525 processor command line for Fortran 77 files. You should nor‐
5526 mally set the $FORTRANPPCOM variable, which specifies the
5527 default C-preprocessor command line for all Fortran versions.
5528 F77PPCOMSTR
5531 The string displayed when a Fortran 77 source file is compiled
5532 to an object file after first running the file through the C
5533 preprocessor. If this is not set, then $F77PPCOM or $FORTRANPP‐
5534 COM (the command line) is displayed.
5535 F77PPFILESUFFIXES
5538 The list of file extensions for which the compilation + pre‐
5539 processor pass for F77 dialect will be used. By default, this is
5540 empty
5541 F90 The Fortran 90 compiler. You should normally set the $FORTRAN
5544 variable, which specifies the default Fortran compiler for all
5545 Fortran versions. You only need to set $F90 if you need to use
5546 a specific compiler or compiler version for Fortran 90 files.
5547 F90COM The command line used to compile a Fortran 90 source file to an
5550 object file. You only need to set $F90COM if you need to use a
5551 specific command line for Fortran 90 files. You should normally
5552 set the $FORTRANCOM variable, which specifies the default com‐
5553 mand line for all Fortran versions.
5554 F90COMSTR
5557 The string displayed when a Fortran 90 source file is compiled
5558 to an object file. If this is not set, then $F90COM or $FOR‐
5559 TRANCOM (the command line) is displayed.
5560 F90FILESUFFIXES
5563 The list of file extensions for which the F90 dialect will be
5564 used. By default, this is ['.f90']
5565 F90FLAGS
5568 General user-specified options that are passed to the Fortran 90
5569 compiler. Note that this variable does not contain -I (or simi‐
5570 lar) include search path options that scons generates automati‐
5571 cally from $F90PATH. See $_F90INCFLAGS below, for the variable
5572 that expands to those options. You only need to set $F90FLAGS
5573 if you need to define specific user options for Fortran 90
5574 files. You should normally set the $FORTRANFLAGS variable,
5575 which specifies the user-specified options passed to the default
5576 Fortran compiler for all Fortran versions.
5577 _F90INCFLAGS
5580 An automatically-generated construction variable containing the
5581 Fortran 90 compiler command-line options for specifying directo‐
5582 ries to be searched for include files. The value of
5583 $_F90INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
5584 to the beginning and end of each directory in $F90PATH.
5585 F90PATH
5588 The list of directories that the Fortran 90 compiler will search
5589 for include directories. The implicit dependency scanner will
5590 search these directories for include files. Don't explicitly put
5591 include directory arguments in $F90FLAGS because the result will
5592 be non-portable and the directories will not be searched by the
5593 dependency scanner. Note: directory names in $F90PATH will be
5594 looked-up relative to the SConscript directory when they are
5595 used in a command. To force scons to look-up a directory rela‐
5596 tive to the root of the source tree use #: You only need to set
5597 $F90PATH if you need to define a specific include path for For‐
5598 tran 90 files. You should normally set the $FORTRANPATH vari‐
5599 able, which specifies the include path for the default Fortran
5600 compiler for all Fortran versions.
5601 env = Environment(F90PATH='#/include')
5603 The directory look-up can also be forced using the Dir() func‐
5605 tion:
5606 include = Dir('include')
5608 env = Environment(F90PATH=include)
5609 The directory list will be added to command lines through the
5611 automatically-generated $_F90INCFLAGS construction variable,
5612 which is constructed by appending the values of the $INCPRE‐
5613 FIXand$INCSUFFIX construction variables to the beginning and end
5614 of each directory in $F90PATH. Any command lines you define
5615 that need the F90PATH directory list should include
5616 $_F90INCFLAGS:
5617 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
5619 F90PPCOM
5622 The command line used to compile a Fortran 90 source file to an
5623 object file after first running the file through the C pre‐
5624 processor. Any options specified in the $F90FLAGS and $CPPFLAGS
5625 construction variables are included on this command line. You
5626 only need to set $F90PPCOM if you need to use a specific C-pre‐
5627 processor command line for Fortran 90 files. You should nor‐
5628 mally set the $FORTRANPPCOM variable, which specifies the
5629 default C-preprocessor command line for all Fortran versions.
5630 F90PPCOMSTR
5633 The string displayed when a Fortran 90 source file is compiled
5634 after first running the file through the C preprocessor. If
5635 this is not set, then $F90PPCOM or $FORTRANPPCOM (the command
5636 line) is displayed.
5637 F90PPFILESUFFIXES
5640 The list of file extensions for which the compilation + pre‐
5641 processor pass for F90 dialect will be used. By default, this is
5642 empty
5643 F95 The Fortran 95 compiler. You should normally set the $FORTRAN
5646 variable, which specifies the default Fortran compiler for all
5647 Fortran versions. You only need to set $F95 if you need to use
5648 a specific compiler or compiler version for Fortran 95 files.
5649 F95COM The command line used to compile a Fortran 95 source file to an
5652 object file. You only need to set $F95COM if you need to use a
5653 specific command line for Fortran 95 files. You should normally
5654 set the $FORTRANCOM variable, which specifies the default com‐
5655 mand line for all Fortran versions.
5656 F95COMSTR
5659 The string displayed when a Fortran 95 source file is compiled
5660 to an object file. If this is not set, then $F95COM or $FOR‐
5661 TRANCOM (the command line) is displayed.
5662 F95FILESUFFIXES
5665 The list of file extensions for which the F95 dialect will be
5666 used. By default, this is ['.f95']
5667 F95FLAGS
5670 General user-specified options that are passed to the Fortran 95
5671 compiler. Note that this variable does not contain -I (or simi‐
5672 lar) include search path options that scons generates automati‐
5673 cally from $F95PATH. See $_F95INCFLAGS below, for the variable
5674 that expands to those options. You only need to set $F95FLAGS
5675 if you need to define specific user options for Fortran 95
5676 files. You should normally set the $FORTRANFLAGS variable,
5677 which specifies the user-specified options passed to the default
5678 Fortran compiler for all Fortran versions.
5679 _F95INCFLAGS
5682 An automatically-generated construction variable containing the
5683 Fortran 95 compiler command-line options for specifying directo‐
5684 ries to be searched for include files. The value of
5685 $_F95INCFLAGS is created by appending $INCPREFIX and $INCSUFFIX
5686 to the beginning and end of each directory in $F95PATH.
5687 F95PATH
5690 The list of directories that the Fortran 95 compiler will search
5691 for include directories. The implicit dependency scanner will
5692 search these directories for include files. Don't explicitly put
5693 include directory arguments in $F95FLAGS because the result will
5694 be non-portable and the directories will not be searched by the
5695 dependency scanner. Note: directory names in $F95PATH will be
5696 looked-up relative to the SConscript directory when they are
5697 used in a command. To force scons to look-up a directory rela‐
5698 tive to the root of the source tree use #: You only need to set
5699 $F95PATH if you need to define a specific include path for For‐
5700 tran 95 files. You should normally set the $FORTRANPATH vari‐
5701 able, which specifies the include path for the default Fortran
5702 compiler for all Fortran versions.
5703 env = Environment(F95PATH='#/include')
5705 The directory look-up can also be forced using the Dir() func‐
5707 tion:
5708 include = Dir('include')
5710 env = Environment(F95PATH=include)
5711 The directory list will be added to command lines through the
5713 automatically-generated $_F95INCFLAGS construction variable,
5714 which is constructed by appending the values of the $INCPRE‐
5715 FIXand$INCSUFFIX construction variables to the beginning and end
5716 of each directory in $F95PATH. Any command lines you define
5717 that need the F95PATH directory list should include
5718 $_F95INCFLAGS:
5719 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
5721 F95PPCOM
5724 The command line used to compile a Fortran 95 source file to an
5725 object file after first running the file through the C pre‐
5726 processor. Any options specified in the $F95FLAGS and $CPPFLAGS
5727 construction variables are included on this command line. You
5728 only need to set $F95PPCOM if you need to use a specific C-pre‐
5729 processor command line for Fortran 95 files. You should nor‐
5730 mally set the $FORTRANPPCOM variable, which specifies the
5731 default C-preprocessor command line for all Fortran versions.
5732 F95PPCOMSTR
5735 The string displayed when a Fortran 95 source file is compiled
5736 to an object file after first running the file through the C
5737 preprocessor. If this is not set, then $F95PPCOM or $FORTRANPP‐
5738 COM (the command line) is displayed.
5739 F95PPFILESUFFIXES
5742 The list of file extensions for which the compilation + pre‐
5743 processor pass for F95 dialect will be used. By default, this is
5744 empty
5745 File A function that converts a string into a File instance relative
5748 to the target being built.
5749 FORTRAN
5752 The default Fortran compiler for all versions of Fortran.
5753 FORTRANCOM
5756 The command line used to compile a Fortran source file to an
5757 object file. By default, any options specified in the $FORTRAN‐
5758 FLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FOR‐
5759 TRANINCFLAGS construction variables are included on this command
5760 line.
5761 FORTRANCOMSTR
5764 The string displayed when a Fortran source file is compiled to
5765 an object file. If this is not set, then $FORTRANCOM (the com‐
5766 mand line) is displayed.
5767 FORTRANFILESUFFIXES
5770 The list of file extensions for which the FORTRAN dialect will
5771 be used. By default, this is ['.f', '.for', '.ftn']
5772 FORTRANFLAGS
5775 General user-specified options that are passed to the Fortran
5776 compiler. Note that this variable does not contain -I (or simi‐
5777 lar) include or module search path options that scons generates
5778 automatically from $FORTRANPATH. See $_FORTRANINCFLAGSand$_FOR‐
5779 TRANMODFLAG, below, for the variables that expand those options.
5780 _FORTRANINCFLAGS
5783 An automatically-generated construction variable containing the
5784 Fortran compiler command-line options for specifying directories
5785 to be searched for include files and module files. The value of
5786 $_FORTRANINCFLAGS is created by prepending/appending $INCPREFIX
5787 and $INCSUFFIX to the beginning and end of each directory in
5788 $FORTRANPATH.
5789 FORTRANMODDIR
5792 Directory location where the Fortran compiler should place any
5793 module files it generates. This variable is empty, by default.
5794 Some Fortran compilers will internally append this directory in
5795 the search path for module files, as well.
5796 FORTRANMODDIRPREFIX
5799 The prefix used to specify a module directory on the Fortran
5800 compiler command line. This will be appended to the beginning
5801 of the directory in the $FORTRANMODDIR construction variables
5802 when the $_FORTRANMODFLAG variables is automatically generated.
5803 FORTRANMODDIRSUFFIX
5806 The suffix used to specify a module directory on the Fortran
5807 compiler command line. This will be appended to the beginning
5808 of the directory in the $FORTRANMODDIR construction variables
5809 when the $_FORTRANMODFLAG variables is automatically generated.
5810 _FORTRANMODFLAG
5813 An automatically-generated construction variable containing the
5814 Fortran compiler command-line option for specifying the direc‐
5815 tory location where the Fortran compiler should place any module
5816 files that happen to get generated during compilation. The
5817 value of $_FORTRANMODFLAG is created by prepending/appending
5818 $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the beginning
5819 and end of the directory in $FORTRANMODDIR.
5820 FORTRANMODPREFIX
5823 The module file prefix used by the Fortran compiler. SCons
5824 assumes that the Fortran compiler follows the quasi-standard
5825 naming convention for module files of module_name.mod. As a
5826 result, this variable is left empty, by default. For situations
5827 in which the compiler does not necessarily follow the normal
5828 convention, the user may use this variable. Its value will be
5829 appended to every module file name as scons attempts to resolve
5830 dependencies.
5831 FORTRANMODSUFFIX
5834 The module file suffix used by the Fortran compiler. SCons
5835 assumes that the Fortran compiler follows the quasi-standard
5836 naming convention for module files of module_name.mod. As a
5837 result, this variable is set to ".mod", by default. For situa‐
5838 tions in which the compiler does not necessarily follow the nor‐
5839 mal convention, the user may use this variable. Its value will
5840 be appended to every module file name as scons attempts to
5841 resolve dependencies.
5842 FORTRANPATH
5845 The list of directories that the Fortran compiler will search
5846 for include files and (for some compilers) module files. The
5847 Fortran implicit dependency scanner will search these directo‐
5848 ries for include files (but not module files since they are
5849 autogenerated and, as such, may not actually exist at the time
5850 the scan takes place). Don't explicitly put include directory
5851 arguments in FORTRANFLAGS because the result will be non-porta‐
5852 ble and the directories will not be searched by the dependency
5853 scanner. Note: directory names in FORTRANPATH will be looked-up
5854 relative to the SConscript directory when they are used in a
5855 command. To force scons to look-up a directory relative to the
5856 root of the source tree use #:
5857 env = Environment(FORTRANPATH='#/include')
5859 The directory look-up can also be forced using the Dir() func‐
5861 tion:
5862 include = Dir('include')
5864 env = Environment(FORTRANPATH=include)
5865 The directory list will be added to command lines through the
5867 automatically-generated $_FORTRANINCFLAGS construction variable,
5868 which is constructed by appending the values of the $INCPRE‐
5869 FIXand$INCSUFFIX construction variables to the beginning and end
5870 of each directory in $FORTRANPATH. Any command lines you define
5871 that need the FORTRANPATH directory list should include $_FOR‐
5872 TRANINCFLAGS:
5873 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
5875 FORTRANPPCOM
5878 The command line used to compile a Fortran source file to an
5879 object file after first running the file through the C pre‐
5880 processor. By default, any options specified in the $FORTRAN‐
5881 FLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FOR‐
5882 TRANINCFLAGS construction variables are included on this command
5883 line.
5884 FORTRANPPCOMSTR
5887 The string displayed when a Fortran source file is compiled to
5888 an object file after first running the file through the C pre‐
5889 processor. If this is not set, then $FORTRANPPCOM (the command
5890 line) is displayed.
5891 FORTRANPPFILESUFFIXES
5894 The list of file extensions for which the compilation + pre‐
5895 processor pass for FORTRAN dialect will be used. By default,
5896 this is ['.fpp', '.FPP']
5897 FORTRANSUFFIXES
5900 The list of suffixes of files that will be scanned for Fortran
5901 implicit dependencies (INCLUDE lines and USE statements). The
5902 default list is:
5903 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
5905 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
5906 FRAMEWORKPATH
5909 On Mac OS X with gcc, a list containing the paths to search for
5910 frameworks. Used by the compiler to find framework-style
5911 includes like #include <Fmwk/Header.h>. Used by the linker to
5912 find user-specified frameworks when linking (see $FRAMEWORKS).
5913 For example:
5914 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
5916 will add
5918 ... -Fmyframeworkdir
5920 to the compiler and linker command lines.
5922 _FRAMEWORKPATH
5925 On Mac OS X with gcc, an automatically-generated construction
5926 variable containing the linker command-line options correspond‐
5927 ing to $FRAMEWORKPATH.
5928 FRAMEWORKPATHPREFIX
5931 On Mac OS X with gcc, the prefix to be used for the FRAMEWORK‐
5932 PATH entries. (see $FRAMEWORKPATH). The default value is -F.
5933 FRAMEWORKPREFIX
5936 On Mac OS X with gcc, the prefix to be used for linking in
5937 frameworks (see $FRAMEWORKS). The default value is -framework.
5938 _FRAMEWORKS
5941 On Mac OS X with gcc, an automatically-generated construction
5942 variable containing the linker command-line options for linking
5943 with FRAMEWORKS.
5944 FRAMEWORKS
5947 On Mac OS X with gcc, a list of the framework names to be linked
5948 into a program or shared library or bundle. The default value
5949 is the empty list. For example:
5950 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
5952 FRAMEWORKSFLAGS
5954 On Mac OS X with gcc, general user-supplied frameworks options
5955 to be added at the end of a command line building a loadable
5956 module. (This has been largely superseded by the $FRAMEWORK‐
5957 PATH, $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS
5958 variables described above.)
5959 GS The Ghostscript program used to convert PostScript to PDF files.
5962 GSCOM The Ghostscript command line used to convert PostScript to PDF
5965 files.
5966 GSCOMSTR
5969 The string displayed when Ghostscript is used to convert a Post‐
5970 Script file to a PDF file. If this is not set, then $GSCOM (the
5971 command line) is displayed.
5972 GSFLAGS
5975 General options passed to the Ghostscript program when convert‐
5976 ing PostScript to PDF files.
5977 HOST_ARCH
5980 Sets the host architecture for Visual Studio compiler. If not
5981 set, default to the detected host architecture: note that this
5982 may depend on the python you are using. This variable must be
5983 passed as an argument to the Environment() constructor; setting
5984 it later has no effect.
5985 Valid values are the same as for $TARGET_ARCH.
5987 This is currently only used on Windows, but in the future it
5989 will be used on other OSes as well.
5990 HOST_OS
5993 The name of the host operating system used to create the
5994 Environment.
5995 If a platform is specified when creating the Environ‐
5996 ment, then
5997 that Platform's logic will handle setting this value.
5998 This value is immutable, and should not be changed by
5999 the user after
6000 the Environment is initialized.
6001 Currently only set for Win32.
6002 IDLSUFFIXES
6005 The list of suffixes of files that will be scanned for IDL
6006 implicit dependencies (#include or import lines). The default
6007 list is:
6008 [".idl", ".IDL"]
6010 IMPLICIT_COMMAND_DEPENDENCIES
6013 Controls whether or not SCons will add implicit dependencies for
6014 the commands executed to build targets.
6015 By default, SCons will add to each target an implicit dependency
6017 on the command represented by the first argument on any command
6018 line it executes. The specific file for the dependency is found
6019 by searching the PATH variable in the ENV environment used to
6020 execute the command.
6021 If the construction variable $IMPLICIT_COMMAND_DEPENDENCIES is
6023 set to a false value (None, False, 0, etc.), then the implicit
6024 dependency will not be added to the targets built with that con‐
6025 struction environment.
6026 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
6028 INCPREFIX
6031 The prefix used to specify an include directory on the C com‐
6032 piler command line. This will be appended to the beginning of
6033 each directory in the $CPPPATH and $FORTRANPATH construction
6034 variables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables
6035 are automatically generated.
6036 INCSUFFIX
6039 The suffix used to specify an include directory on the C com‐
6040 piler command line. This will be appended to the end of each
6041 directory in the $CPPPATH and $FORTRANPATH construction vari‐
6042 ables when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are
6043 automatically generated.
6044 INSTALL
6047 A function to be called to install a file into a destination
6048 file name. The default function copies the file into the desti‐
6049 nation (and sets the destination file's mode and permission bits
6050 to match the source file's). The function takes the following
6051 arguments:
6052 def install(dest, source, env):
6054 dest is the path name of the destination file. source is the
6056 path name of the source file. env is the construction environ‐
6057 ment (a dictionary of construction values) in force for this
6058 file installation.
6059 INSTALLSTR
6062 The string displayed when a file is installed into a destination
6063 file name. The default is:
6064 Install file: "$SOURCE" as "$TARGET"
6065 INTEL_C_COMPILER_VERSION
6068 Set by the "intelc" Tool to the major version number of the
6069 Intel C compiler selected for use.
6070 JAR The Java archive tool.
6073 JARCHDIR
6076 The directory to which the Java archive tool should change
6077 (using the -C option).
6078 JARCOM The command line used to call the Java archive tool.
6081 JARCOMSTR
6084 The string displayed when the Java archive tool is called If
6085 this is not set, then $JARCOM (the command line) is displayed.
6086 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
6088 JARFLAGS
6091 General options passed to the Java archive tool. By default
6092 this is set to cf to create the necessary jar file.
6093 JARSUFFIX
6096 The suffix for Java archives: .jar by default.
6097 JAVABOOTCLASSPATH
6100 Specifies the list of directories that will be added to the
6101 &javac; command line via the -bootclasspath option. The indi‐
6102 vidual directory names will be separated by the operating sys‐
6103 tem's path separate character (: on UNIX/Linux/POSIX, ; on Win‐
6104 dows).
6105 JAVAC The Java compiler.
6108 JAVACCOM
6111 The command line used to compile a directory tree containing
6112 Java source files to corresponding Java class files. Any
6113 options specified in the $JAVACFLAGS construction variable are
6114 included on this command line.
6115 JAVACCOMSTR
6118 The string displayed when compiling a directory tree of Java
6119 source files to corresponding Java class files. If this is not
6120 set, then $JAVACCOM (the command line) is displayed.
6121 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
6123 JAVACFLAGS
6126 General options that are passed to the Java compiler.
6127 JAVACLASSDIR
6130 The directory in which Java class files may be found. This is
6131 stripped from the beginning of any Java .class file names sup‐
6132 plied to the JavaH builder.
6133 JAVACLASSPATH
6136 Specifies the list of directories that will be searched for Java
6137 .class file. The directories in this list will be added to the
6138 &javac; and &javah; command lines via the -classpath option.
6139 The individual directory names will be separated by the operat‐
6140 ing system's path separate character (: on UNIX/Linux/POSIX, ;
6141 on Windows).
6142 Note that this currently just adds the specified directory via
6144 the -classpath option. &SCons; does not currently search the
6145 $JAVACLASSPATH directories for dependency .class files.
6146 JAVACLASSSUFFIX
6149 The suffix for Java class files; .class by default.
6150 JAVAH The Java generator for C header and stub files.
6153 JAVAHCOM
6156 The command line used to generate C header and stub files from
6157 Java classes. Any options specified in the $JAVAHFLAGS con‐
6158 struction variable are included on this command line.
6159 JAVAHCOMSTR
6162 The string displayed when C header and stub files are generated
6163 from Java classes. If this is not set, then $JAVAHCOM (the com‐
6164 mand line) is displayed.
6165 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
6167 JAVAHFLAGS
6170 General options passed to the C header and stub file generator
6171 for Java classes.
6172 JAVASOURCEPATH
6175 Specifies the list of directories that will be searched for
6176 input .java file. The directories in this list will be added to
6177 the &javac; command line via the -sourcepath option. The indi‐
6178 vidual directory names will be separated by the operating sys‐
6179 tem's path separate character (: on UNIX/Linux/POSIX, ; on Win‐
6180 dows).
6181 Note that this currently just adds the specified directory via
6183 the -sourcepath option. &SCons; does not currently search the
6184 $JAVASOURCEPATH directories for dependency .java files.
6185 JAVASUFFIX
6188 The suffix for Java files; .java by default.
6189 JAVAVERSION
6192 Specifies the Java version being used by the Java() builder.
6193 This is not currently used to select one version of the Java
6194 compiler vs. another. Instead, you should set this to specify
6195 the version of Java supported by your &javac; compiler. The
6196 default is 1.4.
6197 This is sometimes necessary because Java 1.5 changed the file
6199 names that are created for nested anonymous inner classes, which
6200 can cause a mismatch with the files that &SCons; expects will be
6201 generated by the &javac; compiler. Setting $JAVAVERSION to 1.5
6202 (or 1.6, as appropriate) can make &SCons; realize that a Java
6203 1.5 or 1.6 build is actually up to date.
6204 LATEX The LaTeX structured formatter and typesetter.
6207 LATEXCOM
6210 The command line used to call the LaTeX structured formatter and
6211 typesetter.
6212 LATEXCOMSTR
6215 The string displayed when calling the LaTeX structured formatter
6216 and typesetter. If this is not set, then $LATEXCOM (the command
6217 line) is displayed.
6218 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
6220 LATEXFLAGS
6223 General options passed to the LaTeX structured formatter and
6224 typesetter.
6225 LATEXRETRIES
6228 The maximum number of times that LaTeX will be re-run if the
6229 .log generated by the $LATEXCOM command indicates that there are
6230 undefined references. The default is to try to resolve unde‐
6231 fined references by re-running LaTeX up to three times.
6232 LATEXSUFFIXES
6235 The list of suffixes of files that will be scanned for LaTeX
6236 implicit dependencies (\include or \import files). The default
6237 list is:
6238 [".tex", ".ltx", ".latex"]
6240 LDMODULE
6243 The linker for building loadable modules. By default, this is
6244 the same as $SHLINK.
6245 LDMODULECOM
6248 The command line for building loadable modules. On Mac OS X,
6249 this uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS
6250 variables. On other systems, this is the same as $SHLINK.
6251 LDMODULECOMSTR
6254 The string displayed when building loadable modules. If this is
6255 not set, then $LDMODULECOM (the command line) is displayed.
6256 LDMODULEFLAGS
6259 General user options passed to the linker for building loadable
6260 modules.
6261 LDMODULEPREFIX
6264 The prefix used for loadable module file names. On Mac OS X,
6265 this is null; on other systems, this is the same as $SHLIBPRE‐
6266 FIX.
6267 LDMODULESUFFIX
6270 The suffix used for loadable module file names. On Mac OS X,
6271 this is null; on other systems, this is the same as $SHLIBSUF‐
6272 FIX.
6273 LEX The lexical analyzer generator.
6276 LEXCOM The command line used to call the lexical analyzer generator to
6279 generate a source file.
6280 LEXCOMSTR
6283 The string displayed when generating a source file using the
6284 lexical analyzer generator. If this is not set, then $LEXCOM
6285 (the command line) is displayed.
6286 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
6288 LEXFLAGS
6291 General options passed to the lexical analyzer generator.
6292 _LIBDIRFLAGS
6295 An automatically-generated construction variable containing the
6296 linker command-line options for specifying directories to be
6297 searched for library. The value of $_LIBDIRFLAGS is created by
6298 appending $LIBDIRPREFIX and $LIBDIRSUFFIX to the beginning and
6299 end of each directory in $LIBPATH.
6300 LIBDIRPREFIX
6303 The prefix used to specify a library directory on the linker
6304 command line. This will be appended to the beginning of each
6305 directory in the $LIBPATH construction variable when the $_LIB‐
6306 DIRFLAGS variable is automatically generated.
6307 LIBDIRSUFFIX
6310 The suffix used to specify a library directory on the linker
6311 command line. This will be appended to the end of each direc‐
6312 tory in the $LIBPATH construction variable when the $_LIB‐
6313 DIRFLAGS variable is automatically generated.
6314 LIBEMITTER
6317 TODO
6318 _LIBFLAGS
6321 An automatically-generated construction variable containing the
6322 linker command-line options for specifying libraries to be
6323 linked with the resulting target. The value of $_LIBFLAGS is
6324 created by appending $LIBLINKPREFIX and $LIBLINKSUFFIX to the
6325 beginning and end of each filename in $LIBS.
6326 LIBLINKPREFIX
6329 The prefix used to specify a library to link on the linker com‐
6330 mand line. This will be appended to the beginning of each
6331 library in the $LIBS construction variable when the $_LIBFLAGS
6332 variable is automatically generated.
6333 LIBLINKSUFFIX
6336 The suffix used to specify a library to link on the linker com‐
6337 mand line. This will be appended to the end of each library in
6338 the $LIBS construction variable when the $_LIBFLAGS variable is
6339 automatically generated.
6340 LIBPATH
6343 The list of directories that will be searched for libraries.
6344 The implicit dependency scanner will search these directories
6345 for include files. Don't explicitly put include directory argu‐
6346 ments in $LINKFLAGS or $SHLINKFLAGS because the result will be
6347 non-portable and the directories will not be searched by the
6348 dependency scanner. Note: directory names in LIBPATH will be
6349 looked-up relative to the SConscript directory when they are
6350 used in a command. To force scons to look-up a directory rela‐
6351 tive to the root of the source tree use #:
6352 env = Environment(LIBPATH='#/libs')
6354 The directory look-up can also be forced using the Dir() func‐
6356 tion:
6357 libs = Dir('libs')
6359 env = Environment(LIBPATH=libs)
6360 The directory list will be added to command lines through the
6362 automatically-generated $_LIBDIRFLAGS construction variable,
6363 which is constructed by appending the values of the $LIBDIRPRE‐
6364 FIXand$LIBDIRSUFFIX construction variables to the beginning and
6365 end of each directory in $LIBPATH. Any command lines you define
6366 that need the LIBPATH directory list should include $_LIB‐
6367 DIRFLAGS:
6368 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6370 LIBPREFIX
6373 The prefix used for (static) library file names. A default
6374 value is set for each platform (posix, win32, os2, etc.), but
6375 the value is overridden by individual tools (ar, mslib, sgiar,
6376 sunar, tlib, etc.) to reflect the names of the libraries they
6377 create.
6378 LIBPREFIXES
6381 A list of all legal prefixes for library file names. When
6382 searching for library dependencies, SCons will look for files
6383 with these prefixes, the base library name, and suffixes in the
6384 $LIBSUFFIXES list.
6385 LIBS A list of one or more libraries that will be linked with any
6388 executable programs created by this environment.
6389 The library list will be added to command lines through the
6391 automatically-generated $_LIBFLAGS construction variable, which
6392 is constructed by appending the values of the $LIBLINKPRE‐
6393 FIXand$LIBLINKSUFFIX construction variables to the beginning and
6394 end of each filename in $LIBS. Any command lines you define
6395 that need the LIBS library list should include $_LIBFLAGS:
6396 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
6398 If you add a File object to the $LIBS list, the name of that
6400 file will be added to $_LIBFLAGS, and thus the link line, as is,
6401 without $LIBLINKPREFIX or $LIBLINKSUFFIX. For example:
6402 env.Append(LIBS=File('/tmp/mylib.so'))
6404 In all cases, scons will add dependencies from the executable
6406 program to all the libraries in this list.
6407 LIBSUFFIX
6410 The suffix used for (static) library file names. A default
6411 value is set for each platform (posix, win32, os2, etc.), but
6412 the value is overridden by individual tools (ar, mslib, sgiar,
6413 sunar, tlib, etc.) to reflect the names of the libraries they
6414 create.
6415 LIBSUFFIXES
6418 A list of all legal suffixes for library file names. When
6419 searching for library dependencies, SCons will look for files
6420 with prefixes, in the $LIBPREFIXES list, the base library name,
6421 and these suffixes.
6422 LICENSE
6425 The abbreviated name of the license under which this project is
6426 released (gpl, lpgl, bsd etc.). See http://www.open‐
6427 source.org/licenses/alphabetical for a list of license names.
6428 LINESEPARATOR
6431 The separator used by the Substfile() and Textfile() builders.
6432 This value is used between sources when constructing the target.
6433 It defaults to the current system line separator.
6434 LINK The linker.
6437 LINKCOM
6440 The command line used to link object files into an executable.
6441 LINKCOMSTR
6444 The string displayed when object files are linked into an exe‐
6445 cutable. If this is not set, then $LINKCOM (the command line)
6446 is displayed.
6447 env = Environment(LINKCOMSTR = "Linking $TARGET")
6449 LINKFLAGS
6452 General user options passed to the linker. Note that this vari‐
6453 able should not contain -l (or similar) options for linking with
6454 the libraries listed in $LIBS, nor -L (or similar) library
6455 search path options that scons generates automatically from
6456 $LIBPATH. See $_LIBFLAGS above, for the variable that expands
6457 to library-link options, and $_LIBDIRFLAGS above, for the vari‐
6458 able that expands to library search path options.
6459 M4 The M4 macro preprocessor.
6462 M4COM The command line used to pass files through the M4 macro pre‐
6465 processor.
6466 M4COMSTR
6469 The string displayed when a file is passed through the M4 macro
6470 preprocessor. If this is not set, then $M4COM (the command
6471 line) is displayed.
6472 M4FLAGS
6475 General options passed to the M4 macro preprocessor.
6476 MAKEINDEX
6479 The makeindex generator for the TeX formatter and typesetter and
6480 the LaTeX structured formatter and typesetter.
6481 MAKEINDEXCOM
6484 The command line used to call the makeindex generator for the
6485 TeX formatter and typesetter and the LaTeX structured formatter
6486 and typesetter.
6487 MAKEINDEXCOMSTR
6490 The string displayed when calling the makeindex generator for
6491 the TeX formatter and typesetter and the LaTeX structured for‐
6492 matter and typesetter. If this is not set, then $MAKEINDEXCOM
6493 (the command line) is displayed.
6494 MAKEINDEXFLAGS
6497 General options passed to the makeindex generator for the TeX
6498 formatter and typesetter and the LaTeX structured formatter and
6499 typesetter.
6500 MAXLINELENGTH
6503 The maximum number of characters allowed on an external command
6504 line. On Win32 systems, link lines longer than this many char‐
6505 acters are linked via a temporary file name.
6506 MIDL The Microsoft IDL compiler.
6509 MIDLCOM
6512 The command line used to pass files to the Microsoft IDL com‐
6513 piler.
6514 MIDLCOMSTR
6517 The string displayed when the Microsoft IDL copmiler is called.
6518 If this is not set, then $MIDLCOM (the command line) is dis‐
6519 played.
6520 MIDLFLAGS
6523 General options passed to the Microsoft IDL compiler.
6524 MSSDK_DIR
6527 The directory containing the Microsoft SDK (either Platform SDK
6528 or Windows SDK) to be used for compilation.
6529 MSSDK_VERSION
6532 The version string of the Microsoft SDK (either Platform SDK or
6533 Windows SDK) to be used for compilation. Supported versions
6534 include 6.1, 6.0A, 6.0, 2003R2 and 2003R1.
6535 MSVC_BATCH
6538 When set to any true value, specifies that SCons should batch
6539 compilation of object files when calling the Microsoft Visual
6540 C/C++ compiler. All compilations of source files from the same
6541 source directory that generate target files in a same output
6542 directory and were configured in SCons using the same construc‐
6543 tion environment will be built in a single call to the compiler.
6544 Only source files that have changed since their object files
6545 were built will be passed to each compiler invocation (via the
6546 $CHANGED_SOURCES construction variable). Any compilations where
6547 the object (target) file base name (minus the .obj) does not
6548 match the source file base name will be compiled separately.
6549 MSVC_USE_SCRIPT
6552 Use a batch script to set up Microsoft Visual Studio compiler
6553 $MSVC_USE_SCRIPToverrides$MSVC_VERSIONand$TARGET_ARCH. If set
6555 to the name of a Visual Studio .bat file (e.g. vcvars.bat),
6556 SCons will run that bat file and extract the relevant variables
6557 from the result (typically %INCLUDE%, %LIB%, and %PATH%). Set‐
6558 ting MSVC_USE_SCRIPT to None bypasses the Visual Studio autode‐
6559 tection entirely; use this if you are running SCons in a Visual
6560 Studio cmd window and importing the shell's environment vari‐
6561 ables.
6562 MSVC_VERSION
6565 Sets the preferred version of Microsoft Visual C/C++ to use.
6566 If $MSVC_VERSION is not set, SCons will (by default) select the
6568 latest version of Visual C/C++ installed on your system. If the
6569 specified version isn't installed, tool initialization will
6570 fail. This variable must be passed as an argument to the Envi‐
6571 ronment() constructor; setting it later has no effect. Set it
6572 to an unexpected value (e.g. "XXX") to see the valid values on
6573 your system.
6574 MSVS When the Microsoft Visual Studio tools are initialized, they set
6577 up this dictionary with the following keys:
6578 VERSION: the version of MSVS being used (can be set via
6580 $MSVS_VERSION)
6581 VERSIONS: the available versions of MSVS installed
6583 VCINSTALLDIR: installed directory of Visual C++
6585 VSINSTALLDIR: installed directory of Visual Studio
6587 FRAMEWORKDIR: installed directory of the .NET framework
6589 FRAMEWORKVERSIONS: list of installed versions of the .NET frame‐
6591 work, sorted latest to oldest.
6592 FRAMEWORKVERSION: latest installed version of the .NET framework
6594 FRAMEWORKSDKDIR: installed location of the .NET SDK.
6596 PLATFORMSDKDIR: installed location of the Platform SDK.
6598 PLATFORMSDK_MODULES: dictionary of installed Platform SDK mod‐
6600 ules, where the dictionary keys are keywords for the various
6601 modules, and the values are 2-tuples where the first is the
6602 release date, and the second is the version number.
6603 If a value isn't set, it wasn't available in the registry.
6605 MSVS_ARCH
6608 Sets the architecture for which the generated project(s) should
6609 build.
6610 The default value is x86. amd64 is also supported by &SCons;
6612 for some Visual Studio versions. Trying to set $MSVS_ARCH to an
6613 architecture that's not supported for a given Visual Studio ver‐
6614 sion will generate an error.
6615 MSVS_PROJECT_GUID
6618 The string placed in a generated Microsoft Visual Studio project
6619 file as the value of the ProjectGUID attribute. There is no
6620 default value. If not defined, a new GUID is generated.
6621 MSVS_SCC_AUX_PATH
6624 The path name placed in a generated Microsoft Visual Studio
6625 project file as the value of the SccAuxPath attribute if the
6626 MSVS_SCC_PROVIDER construction variable is also set. There is
6627 no default value.
6628 MSVS_SCC_CONNECTION_ROOT
6631 The root path of projects in your SCC workspace, i.e the path
6632 under which all project and solution files will be generated. It
6633 is used as a reference path from which the relative paths of the
6634 generated Microsoft Visual Studio project and solution files are
6635 computed. The relative project file path is placed as the value
6636 of the SccLocalPath attribute of the project file and as the
6637 values of the SccProjectFilePathRelativizedFromConnection[i]
6638 (where [i] ranges from 0 to the number of projects in the solu‐
6639 tion) attributes of the GlobalSection(SourceCodeControl) section
6640 of the Microsoft Visual Studio solution file. Similarly the
6641 relative solution file path is placed as the values of the
6642 SccLocalPath[i] (where [i] ranges from 0 to the number of
6643 projects in the solution) attributes of the GlobalSec‐
6644 tion(SourceCodeControl) section of the Microsoft Visual Studio
6645 solution file. This is used only if the MSVS_SCC_PROVIDER con‐
6646 struction variable is also set. The default value is the cur‐
6647 rent working directory.
6648 MSVS_SCC_PROJECT_NAME
6651 The project name placed in a generated Microsoft Visual Studio
6652 project file as the value of the SccProjectName attribute if the
6653 MSVS_SCC_PROVIDER construction variable is also set. In this
6654 case the string is also placed in the SccProjectName0 attribute
6655 of the GlobalSection(SourceCodeControl) section of the Microsoft
6656 Visual Studio solution file. There is no default value.
6657 MSVS_SCC_PROVIDER
6660 The string placed in a generated Microsoft Visual Studio project
6661 file as the value of the SccProvider attribute. The string is
6662 also placed in the SccProvider0 attribute of the GlobalSec‐
6663 tion(SourceCodeControl) section of the Microsoft Visual Studio
6664 solution file. There is no default value.
6665 MSVS_VERSION
6668 Sets the preferred version of Microsoft Visual Studio to use.
6669 If $MSVS_VERSION is not set, &SCons; will (by default) select
6671 the latest version of Visual Studio installed on your system.
6672 So, if you have version 6 and version 7 (MSVS .NET) installed,
6673 it will prefer version 7. You can override this by specifying
6674 the MSVS_VERSION variable in the Environment initialization,
6675 setting it to the appropriate version ('6.0' or '7.0', for exam‐
6676 ple). If the specified version isn't installed, tool initial‐
6677 ization will fail.
6678 This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is
6680 set and $MSVC_VERSIONisnot,$MSVC_VERSIONwillbesetautomatical‐
6681 lyto$MSVS_VERSION. If both are set to different values, scons
6682 will raise an error.
6683 MSVSBUILDCOM
6686 The build command line placed in a generated Microsoft Visual
6687 Studio project file. The default is to have Visual Studio
6688 invoke SCons with any specified build targets.
6689 MSVSCLEANCOM
6692 The clean command line placed in a generated Microsoft Visual
6693 Studio project file. The default is to have Visual Studio
6694 invoke SCons with the -c option to remove any specified targets.
6695 MSVSENCODING
6698 The encoding string placed in a generated Microsoft Visual Stu‐
6699 dio project file. The default is encoding Windows-1252.
6700 MSVSPROJECTCOM
6703 The action used to generate Microsoft Visual Studio project
6704 files.
6705 MSVSPROJECTSUFFIX
6708 The suffix used for Microsoft Visual Studio project (DSP) files.
6709 The default value is .vcproj when using Visual Studio version
6710 7.x (.NET) or later version, and .dsp when using earlier ver‐
6711 sions of Visual Studio.
6712 MSVSREBUILDCOM
6715 The rebuild command line placed in a generated Microsoft Visual
6716 Studio project file. The default is to have Visual Studio
6717 invoke SCons with any specified rebuild targets.
6718 MSVSSCONS
6721 The SCons used in generated Microsoft Visual Studio project
6722 files. The default is the version of SCons being used to gener‐
6723 ate the project file.
6724 MSVSSCONSCOM
6727 The default SCons command used in generated Microsoft Visual
6728 Studio project files.
6729 MSVSSCONSCRIPT
6732 The sconscript file (that is, SConstruct or SConscript file)
6733 that will be invoked by Visual Studio project files (through the
6734 $MSVSSCONSCOM variable). The default is the same sconscript
6735 file that contains the call to MSVSProject() to build the
6736 project file.
6737 MSVSSCONSFLAGS
6740 The SCons flags used in generated Microsoft Visual Studio
6741 project files.
6742 MSVSSOLUTIONCOM
6745 The action used to generate Microsoft Visual Studio solution
6746 files.
6747 MSVSSOLUTIONSUFFIX
6750 The suffix used for Microsoft Visual Studio solution (DSW)
6751 files. The default value is .sln when using Visual Studio ver‐
6752 sion 7.x (.NET), and .dsw when using earlier versions of Visual
6753 Studio.
6754 MT The program used on Windows systems to embed manifests into DLLs
6757 and EXEs. See also $WINDOWS_EMBED_MANIFEST.
6758 MTEXECOM
6761 The Windows command line used to embed manifests into executa‐
6762 bles. See also $MTSHLIBCOM.
6763 MTFLAGS
6766 Flags passed to the $MT manifest embedding program (Windows
6767 only).
6768 MTSHLIBCOM
6771 The Windows command line used to embed manifests into shared
6772 libraries (DLLs). See also $MTEXECOM.
6773 MWCW_VERSION
6776 The version number of the MetroWerks CodeWarrior C compiler to
6777 be used.
6778 MWCW_VERSIONS
6781 A list of installed versions of the MetroWerks CodeWarrior C
6782 compiler on this system.
6783 NAME Specfies the name of the project to package.
6786 no_import_lib
6789 When set to non-zero, suppresses creation of a corresponding
6790 Windows static import lib by the SharedLibrary builder when used
6791 with MinGW, Microsoft Visual Studio or Metrowerks. This also
6792 suppresses creation of an export (.exp) file when using Micro‐
6793 soft Visual Studio.
6794 OBJPREFIX
6797 The prefix used for (static) object file names.
6798 OBJSUFFIX
6801 The suffix used for (static) object file names.
6802 P4 The Perforce executable.
6805 P4COM The command line used to fetch source files from Perforce.
6808 P4COMSTR
6811 The string displayed when fetching a source file from Perforce.
6812 If this is not set, then $P4COM (the command line) is displayed.
6813 P4FLAGS
6816 General options that are passed to Perforce.
6817 PACKAGEROOT
6820 Specifies the directory where all files in resulting archive
6821 will be placed if applicable. The default value is "$NAME-$VER‐
6822 SION".
6823 PACKAGETYPE
6826 Selects the package type to build. Currently these are avail‐
6827 able:
6828 * msi - Microsoft Installer
6830 * rpm - Redhat Package Manger
6831 * ipkg - Itsy Package Management System
6832 * tarbz2 - compressed tar
6833 * targz - compressed tar
6834 * zip - zip file
6835 * src_tarbz2 - compressed tar source
6836 * src_targz - compressed tar source
6837 * src_zip - zip file source
6838 This may be overridden with the "package_type" command line
6840 option.
6841 PACKAGEVERSION
6844 The version of the package (not the underlying project). This
6845 is currently only used by the rpm packager and should reflect
6846 changes in the packaging, not the underlying project code
6847 itself.
6848 PCH The Microsoft Visual C++ precompiled header that will be used
6851 when compiling object files. This variable is ignored by tools
6852 other than Microsoft Visual C++. When this variable is defined
6853 SCons will add options to the compiler command line to cause it
6854 to use the precompiled header, and will also set up the depen‐
6855 dencies for the PCH file. Example:
6856 env['PCH'] = 'StdAfx.pch'
6858 PCHCOM The command line used by the PCH() builder to generated a pre‐
6861 compiled header.
6862 PCHCOMSTR
6865 The string displayed when generating a precompiled header. If
6866 this is not set, then $PCHCOM (the command line) is displayed.
6867 PCHPDBFLAGS
6870 A construction variable that, when expanded, adds the /yD flag
6871 to the command line only if the $PDB construction variable is
6872 set.
6873 PCHSTOP
6876 This variable specifies how much of a source file is precom‐
6877 piled. This variable is ignored by tools other than Microsoft
6878 Visual C++, or when the PCH variable is not being used. When
6879 this variable is define it must be a string that is the name of
6880 the header that is included at the end of the precompiled por‐
6881 tion of the source files, or the empty string if the "#pragma
6882 hrdstop" construct is being used:
6883 env['PCHSTOP'] = 'StdAfx.h'
6885 PDB The Microsoft Visual C++ PDB file that will store debugging
6888 information for object files, shared libraries, and programs.
6889 This variable is ignored by tools other than Microsoft Visual
6890 C++. When this variable is defined SCons will add options to
6891 the compiler and linker command line to cause them to generate
6892 external debugging information, and will also set up the depen‐
6893 dencies for the PDB file. Example:
6894 env['PDB'] = 'hello.pdb'
6896 The Visual C++ compiler switch that SCons uses by default to
6898 generate PDB information is /Z7. This works correctly with par‐
6899 allel (-j) builds because it embeds the debug information in the
6900 intermediate object files, as opposed to sharing a single PDB
6901 file between multiple object files. This is also the only way
6902 to get debug information embedded into a static library. Using
6903 the /Zi instead may yield improved link-time performance,
6904 although parallel builds will no longer work. You can generate
6905 PDB files with the /Zi switch by overriding the default
6906 $CCPDBFLAGS variable; see the entry for that variable for spe‐
6907 cific examples.
6908 PDFCOM A deprecated synonym for $DVIPDFCOM.
6911 PDFLATEX
6914 The &pdflatex; utility.
6915 PDFLATEXCOM
6918 The command line used to call the &pdflatex; utility.
6919 PDFLATEXCOMSTR
6922 The string displayed when calling the &pdflatex; utility. If
6923 this is not set, then $PDFLATEXCOM (the command line) is dis‐
6924 played.
6925 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
6927 PDFLATEXFLAGS
6930 General options passed to the &pdflatex; utility.
6931 PDFPREFIX
6934 The prefix used for PDF file names.
6935 PDFSUFFIX
6938 The suffix used for PDF file names.
6939 PDFTEX The &pdftex; utility.
6942 PDFTEXCOM
6945 The command line used to call the &pdftex; utility.
6946 PDFTEXCOMSTR
6949 The string displayed when calling the &pdftex; utility. If this
6950 is not set, then $PDFTEXCOM (the command line) is displayed.
6951 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
6953 PDFTEXFLAGS
6956 General options passed to the &pdftex; utility.
6957 PKGCHK On Solaris systems, the package-checking program that will be
6960 used (along with $PKGINFO) to look for installed versions of the
6961 Sun PRO C++ compiler. The default is /usr/sbin/pgkchk.
6962 PKGINFO
6965 On Solaris systems, the package information program that will be
6966 used (along with $PKGCHK) to look for installed versions of the
6967 Sun PRO C++ compiler. The default is pkginfo.
6968 PLATFORM
6971 The name of the platform used to create the Environment. If no
6972 platform is specified when the Environment is created, scons
6973 autodetects the platform.
6974 env = Environment(tools = [])
6976 if env['PLATFORM'] == 'cygwin':
6977 Tool('mingw')(env)
6978 else:
6979 Tool('msvc')(env)
6980 PRINT_CMD_LINE_FUNC
6983 A Python function used to print the command lines as they are
6984 executed (assuming command printing is not disabled by the -q or
6985 -s options or their equivalents). The function should take four
6986 arguments: s, the command being executed (a string), target, the
6987 target being built (file node, list, or string name(s)), source,
6988 the source(s) used (file node, list, or string name(s)), and
6989 env, the environment being used.
6990 The function must do the printing itself. The default implemen‐
6992 tation, used if this variable is not set or is None, is:
6993 def print_cmd_line(s, target, source, env):
6994 sys.stdout.write(s + "\n")
6995 Here's an example of a more interesting function:
6997 def print_cmd_line(s, target, source, env):
6999 sys.stdout.write("Building %s -> %s...\n" %
7000 (' and '.join([str(x) for x in source]),
7001 ' and '.join([str(x) for x in target])))
7002 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
7003 env.Program('foo', 'foo.c')
7004 This just prints "Building targetname from sourcename..."
7006 instead of the actual commands. Such a function could also log
7007 the actual commands to a log file, for example.
7008 PROGEMITTER
7011 TODO
7012 PROGPREFIX
7015 The prefix used for executable file names.
7016 PROGSUFFIX
7019 The suffix used for executable file names.
7020 PSCOM The command line used to convert TeX DVI files into a PostScript
7023 file.
7024 PSCOMSTR
7027 The string displayed when a TeX DVI file is converted into a
7028 PostScript file. If this is not set, then $PSCOM (the command
7029 line) is displayed.
7030 PSPREFIX
7033 The prefix used for PostScript file names.
7034 PSSUFFIX
7037 The prefix used for PostScript file names.
7038 QT_AUTOSCAN
7041 Turn off scanning for mocable files. Use the Moc Builder to
7042 explicitly specify files to run moc on.
7043 QT_BINPATH
7046 The path where the qt binaries are installed. The default value
7047 is '$QTDIR/bin'.
7048 QT_CPPPATH
7051 The path where the qt header files are installed. The default
7052 value is '$QTDIR/include'. Note: If you set this variable to
7053 None, the tool won't change the $CPPPATH construction variable.
7054 QT_DEBUG
7057 Prints lots of debugging information while scanning for moc
7058 files.
7059 QT_LIB Default value is 'qt'. You may want to set this to 'qt-mt'.
7062 Note: If you set this variable to None, the tool won't change
7063 the $LIBS variable.
7064 QT_LIBPATH
7067 The path where the qt libraries are installed. The default
7068 value is '$QTDIR/lib'. Note: If you set this variable to None,
7069 the tool won't change the $LIBPATH construction variable.
7070 QT_MOC Default value is '$QT_BINPATH/moc'.
7073 QT_MOCCXXPREFIX
7076 Default value is ''. Prefix for moc output files, when source is
7077 a cxx file.
7078 QT_MOCCXXSUFFIX
7081 Default value is '.moc'. Suffix for moc output files, when
7082 source is a cxx file.
7083 QT_MOCFROMCXXCOM
7086 Command to generate a moc file from a cpp file.
7087 QT_MOCFROMCXXCOMSTR
7090 The string displayed when generating a moc file from a cpp file.
7091 If this is not set, then $QT_MOCFROMCXXCOM (the command line) is
7092 displayed.
7093 QT_MOCFROMCXXFLAGS
7096 Default value is '-i'. These flags are passed to moc, when mocc‐
7097 ing a C++ file.
7098 QT_MOCFROMHCOM
7101 Command to generate a moc file from a header.
7102 QT_MOCFROMHCOMSTR
7105 The string displayed when generating a moc file from a cpp file.
7106 If this is not set, then $QT_MOCFROMHCOM (the command line) is
7107 displayed.
7108 QT_MOCFROMHFLAGS
7111 Default value is ''. These flags are passed to moc, when moccing
7112 a header file.
7113 QT_MOCHPREFIX
7116 Default value is 'moc_'. Prefix for moc output files, when
7117 source is a header.
7118 QT_MOCHSUFFIX
7121 Default value is '$CXXFILESUFFIX'. Suffix for moc output files,
7122 when source is a header.
7123 QT_UIC Default value is '$QT_BINPATH/uic'.
7126 QT_UICCOM
7129 Command to generate header files from .ui files.
7130 QT_UICCOMSTR
7133 The string displayed when generating header files from .ui
7134 files. If this is not set, then $QT_UICCOM (the command line)
7135 is displayed.
7136 QT_UICDECLFLAGS
7139 Default value is ''. These flags are passed to uic, when creat‐
7140 ing a a h file from a .ui file.
7141 QT_UICDECLPREFIX
7144 Default value is ''. Prefix for uic generated header files.
7145 QT_UICDECLSUFFIX
7148 Default value is '.h'. Suffix for uic generated header files.
7149 QT_UICIMPLFLAGS
7152 Default value is ''. These flags are passed to uic, when creat‐
7153 ing a cxx file from a .ui file.
7154 QT_UICIMPLPREFIX
7157 Default value is 'uic_'. Prefix for uic generated implementation
7158 files.
7159 QT_UICIMPLSUFFIX
7162 Default value is '$CXXFILESUFFIX'. Suffix for uic generated
7163 implementation files.
7164 QT_UISUFFIX
7167 Default value is '.ui'. Suffix of designer input files.
7168 QTDIR The qt tool tries to take this from os.environ. It also ini‐
7171 tializes all QT_* construction variables listed below. (Note
7172 that all paths are constructed with python's os.path.join()
7173 method, but are listed here with the '/' separator for easier
7174 reading.) In addition, the construction environment variables
7175 $CPPPATH, $LIBPATH and $LIBS may be modified and the variables
7176 $PROGEMITTER,$SHLIBEMITTERand$LIBEMITTER are modified. Because
7177 the build-performance is affected when using this tool, you have
7178 to explicitly specify it at Environment creation:
7179 Environment(tools=['default','qt'])
7181 The qt tool supports the following operations:
7183 Automatic moc file generation from header files. You do not
7185 have to specify moc files explicitly, the tool does it for you.
7186 However, there are a few preconditions to do so: Your header
7187 file must have the same filebase as your implementation file and
7188 must stay in the same directory. It must have one of the suf‐
7189 fixes .h, .hpp, .H, .hxx, .hh. You can turn off automatic moc
7190 file generation by setting QT_AUTOSCAN to 0. See also the cor‐
7191 responding Moc()() builder method.
7192 Automatic moc file generation from cxx files. As stated in the
7194 qt documentation, include the moc file at the end of the cxx
7195 file. Note that you have to include the file, which is generated
7196 by the transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOC‐
7197 CXXSUFFIX}, by default <basename>.moc. A warning is generated
7198 after building the moc file, if you do not include the correct
7199 file. If you are using VariantDir, you may need to specify
7200 duplicate=1. You can turn off automatic moc file generation by
7201 setting QT_AUTOSCAN to 0. See also the corresponding Moc()
7202 builder method.
7203 Automatic handling of .ui files. The implementation files gen‐
7205 erated from .ui files are handled much the same as yacc or lex
7206 files. Each .ui file given as a source of Program, Library or
7207 SharedLibrary will generate three files, the declaration file,
7208 the implementation file and a moc file. Because there are also
7209 generated headers, you may need to specify duplicate=1 in calls
7210 to VariantDir. See also the corresponding Uic() builder method.
7211 RANLIB The archive indexer.
7214 RANLIBCOM
7217 The command line used to index a static library archive.
7218 RANLIBCOMSTR
7221 The string displayed when a static library archive is indexed.
7222 If this is not set, then $RANLIBCOM (the command line) is dis‐
7223 played.
7224 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
7226 RANLIBFLAGS
7229 General options passed to the archive indexer.
7230 RC The resource compiler used to build a Microsoft Visual C++
7233 resource file.
7234 RCCOM The command line used to build a Microsoft Visual C++ resource
7237 file.
7238 RCCOMSTR
7241 The string displayed when invoking the resource compiler to
7242 build a Microsoft Visual C++ resource file. If this is not set,
7243 then $RCCOM (the command line) is displayed.
7244 RCFLAGS
7247 The flags passed to the resource compiler by the RES builder.
7248 RCINCFLAGS
7251 An automatically-generated construction variable containing the
7252 command-line options for specifying directories to be searched
7253 by the resource compiler. The value of $RCINCFLAGS is created
7254 by appending $RCINCPREFIX and $RCINCSUFFIX to the beginning and
7255 end of each directory in $CPPPATH.
7256 RCINCPREFIX
7259 The prefix (flag) used to specify an include directory on the
7260 resource compiler command line. This will be appended to the
7261 beginning of each directory in the $CPPPATH construction vari‐
7262 able when the $RCINCFLAGS variable is expanded.
7263 RCINCSUFFIX
7266 The suffix used to specify an include directory on the resource
7267 compiler command line. This will be appended to the end of each
7268 directory in the $CPPPATH construction variable when the
7269 $RCINCFLAGS variable is expanded.
7270 RCS The RCS executable. Note that this variable is not actually
7273 used for the command to fetch source files from RCS; see the
7274 $RCS_CO construction variable, below.
7275 RCS_CO The RCS "checkout" executable, used to fetch source files from
7278 RCS.
7279 RCS_COCOM
7282 The command line used to fetch (checkout) source files from RCS.
7283 RCS_COCOMSTR
7286 The string displayed when fetching a source file from RCS. If
7287 this is not set, then $RCS_COCOM (the command line) is dis‐
7288 played.
7289 RCS_COFLAGS
7292 Options that are passed to the $RCS_CO command.
7293 RDirs A function that converts a string into a list of Dir instances
7296 by searching the repositories.
7297 REGSVR The program used on Windows systems to register a newly-built
7300 DLL library whenever the SharedLibrary() builder is passed a
7301 keyword argument of register=1.
7302 REGSVRCOM
7305 The command line used on Windows systems to register a newly-
7306 built DLL library whenever the SharedLibrary() builder is passed
7307 a keyword argument of register=1.
7308 REGSVRCOMSTR
7311 The string displayed when registering a newly-built DLL file.
7312 If this is not set, then $REGSVRCOM (the command line) is dis‐
7313 played.
7314 REGSVRFLAGS
7317 Flags passed to the DLL registration program on Windows systems
7318 when a newly-built DLL library is registered. By default, this
7319 includes the /s that prevents dialog boxes from popping up and
7320 requiring user attention.
7321 RMIC The Java RMI stub compiler.
7324 RMICCOM
7327 The command line used to compile stub and skeleton class files
7328 from Java classes that contain RMI implementations. Any options
7329 specified in the $RMICFLAGS construction variable are included
7330 on this command line.
7331 RMICCOMSTR
7334 The string displayed when compiling stub and skeleton class
7335 files from Java classes that contain RMI implementations. If
7336 this is not set, then $RMICCOM (the command line) is displayed.
7337 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
7339 RMICFLAGS
7342 General options passed to the Java RMI stub compiler.
7343 _RPATH An automatically-generated construction variable containing the
7346 rpath flags to be used when linking a program with shared
7347 libraries. The value of $_RPATH is created by appending $RPATH‐
7348 PREFIX and $RPATHSUFFIX to the beginning and end of each direc‐
7349 tory in $RPATH.
7350 RPATH A list of paths to search for shared libraries when running pro‐
7353 grams. Currently only used in the GNU (gnulink), IRIX (sgilink)
7354 and Sun (sunlink) linkers. Ignored on platforms and toolchains
7355 that don't support it. Note that the paths added to RPATH are
7356 not transformed by scons in any way: if you want an absolute
7357 path, you must make it absolute yourself.
7358 RPATHPREFIX
7361 The prefix used to specify a directory to be searched for shared
7362 libraries when running programs. This will be appended to the
7363 beginning of each directory in the $RPATH construction variable
7364 when the $_RPATH variable is automatically generated.
7365 RPATHSUFFIX
7368 The suffix used to specify a directory to be searched for shared
7369 libraries when running programs. This will be appended to the
7370 end of each directory in the $RPATH construction variable when
7371 the $_RPATH variable is automatically generated.
7372 RPCGEN The RPC protocol compiler.
7375 RPCGENCLIENTFLAGS
7378 Options passed to the RPC protocol compiler when generating
7379 client side stubs. These are in addition to any flags specified
7380 in the $RPCGENFLAGS construction variable.
7381 RPCGENFLAGS
7384 General options passed to the RPC protocol compiler.
7385 RPCGENHEADERFLAGS
7388 Options passed to the RPC protocol compiler when generating a
7389 header file. These are in addition to any flags specified in
7390 the $RPCGENFLAGS construction variable.
7391 RPCGENSERVICEFLAGS
7394 Options passed to the RPC protocol compiler when generating
7395 server side stubs. These are in addition to any flags specified
7396 in the $RPCGENFLAGS construction variable.
7397 RPCGENXDRFLAGS
7400 Options passed to the RPC protocol compiler when generating XDR
7401 routines. These are in addition to any flags specified in the
7402 $RPCGENFLAGS construction variable.
7403 SCANNERS
7406 A list of the available implicit dependency scanners. New file
7407 scanners may be added by appending to this list, although the
7408 more flexible approach is to associate scanners with a specific
7409 Builder. See the sections "Builder Objects" and "Scanner
7410 Objects," below, for more information.
7411 SCCS The SCCS executable.
7414 SCCSCOM
7417 The command line used to fetch source files from SCCS.
7418 SCCSCOMSTR
7421 The string displayed when fetching a source file from a CVS
7422 repository. If this is not set, then $SCCSCOM (the command
7423 line) is displayed.
7424 SCCSFLAGS
7427 General options that are passed to SCCS.
7428 SCCSGETFLAGS
7431 Options that are passed specifically to the SCCS "get" subcom‐
7432 mand. This can be set, for example, to -e to check out editable
7433 files from SCCS.
7434 SCONS_HOME
7437 The (optional) path to the SCons library directory, initialized
7438 from the external environment. If set, this is used to con‐
7439 struct a shorter and more efficient search path in the $MSVSS‐
7440 CONS command line executed from Microsoft Visual Studio project
7441 files.
7442 SHCC The C compiler used for generating shared-library objects.
7445 SHCCCOM
7448 The command line used to compile a C source file to a shared-
7449 library object file. Any options specified in the $SHCFLAGS,
7450 $SHCCFLAGS and $CPPFLAGS construction variables are included on
7451 this command line.
7452 SHCCCOMSTR
7455 The string displayed when a C source file is compiled to a
7456 shared object file. If this is not set, then $SHCCCOM (the com‐
7457 mand line) is displayed.
7458 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
7460 SHCCFLAGS
7463 Options that are passed to the C and C++ compilers to generate
7464 shared-library objects.
7465 SHCFLAGS
7468 Options that are passed to the C compiler (only; not C++) to
7469 generate shared-library objects.
7470 SHCXX The C++ compiler used for generating shared-library objects.
7473 SHCXXCOM
7476 The command line used to compile a C++ source file to a shared-
7477 library object file. Any options specified in the $SHCXXFLAGS
7478 and $CPPFLAGS construction variables are included on this com‐
7479 mand line.
7480 SHCXXCOMSTR
7483 The string displayed when a C++ source file is compiled to a
7484 shared object file. If this is not set, then $SHCXXCOM (the
7485 command line) is displayed.
7486 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
7488 SHCXXFLAGS
7491 Options that are passed to the C++ compiler to generate shared-
7492 library objects.
7493 SHELL A string naming the shell program that will be passed to the
7496 $SPAWN function. See the $SPAWN construction variable for more
7497 information.
7498 SHF77 The Fortran 77 compiler used for generating shared-library
7501 objects. You should normally set the $SHFORTRAN variable, which
7502 specifies the default Fortran compiler for all Fortran versions.
7503 You only need to set $SHF77 if you need to use a specific com‐
7504 piler or compiler version for Fortran 77 files.
7505 SHF77COM
7508 The command line used to compile a Fortran 77 source file to a
7509 shared-library object file. You only need to set $SHF77COM if
7510 you need to use a specific command line for Fortran 77 files.
7511 You should normally set the $SHFORTRANCOM variable, which speci‐
7512 fies the default command line for all Fortran versions.
7513 SHF77COMSTR
7516 The string displayed when a Fortran 77 source file is compiled
7517 to a shared-library object file. If this is not set, then
7518 $SHF77COM or $SHFORTRANCOM (the command line) is displayed.
7519 SHF77FLAGS
7522 Options that are passed to the Fortran 77 compiler to generated
7523 shared-library objects. You only need to set $SHF77FLAGS if you
7524 need to define specific user options for Fortran 77 files. You
7525 should normally set the $SHFORTRANFLAGS variable, which speci‐
7526 fies the user-specified options passed to the default Fortran
7527 compiler for all Fortran versions.
7528 SHF77PPCOM
7531 The command line used to compile a Fortran 77 source file to a
7532 shared-library object file after first running the file through
7533 the C preprocessor. Any options specified in the $SHF77FLAGS
7534 and $CPPFLAGS construction variables are included on this com‐
7535 mand line. You only need to set $SHF77PPCOM if you need to use
7536 a specific C-preprocessor command line for Fortran 77 files.
7537 You should normally set the $SHFORTRANPPCOM variable, which
7538 specifies the default C-preprocessor command line for all For‐
7539 tran versions.
7540 SHF77PPCOMSTR
7543 The string displayed when a Fortran 77 source file is compiled
7544 to a shared-library object file after first running the file
7545 through the C preprocessor. If this is not set, then
7546 $SHF77PPCOM or $SHFORTRANPPCOM (the command line) is displayed.
7547 SHF90 The Fortran 90 compiler used for generating shared-library
7550 objects. You should normally set the $SHFORTRAN variable, which
7551 specifies the default Fortran compiler for all Fortran versions.
7552 You only need to set $SHF90 if you need to use a specific com‐
7553 piler or compiler version for Fortran 90 files.
7554 SHF90COM
7557 The command line used to compile a Fortran 90 source file to a
7558 shared-library object file. You only need to set $SHF90COM if
7559 you need to use a specific command line for Fortran 90 files.
7560 You should normally set the $SHFORTRANCOM variable, which speci‐
7561 fies the default command line for all Fortran versions.
7562 SHF90COMSTR
7565 The string displayed when a Fortran 90 source file is compiled
7566 to a shared-library object file. If this is not set, then
7567 $SHF90COM or $SHFORTRANCOM (the command line) is displayed.
7568 SHF90FLAGS
7571 Options that are passed to the Fortran 90 compiler to generated
7572 shared-library objects. You only need to set $SHF90FLAGS if you
7573 need to define specific user options for Fortran 90 files. You
7574 should normally set the $SHFORTRANFLAGS variable, which speci‐
7575 fies the user-specified options passed to the default Fortran
7576 compiler for all Fortran versions.
7577 SHF90PPCOM
7580 The command line used to compile a Fortran 90 source file to a
7581 shared-library object file after first running the file through
7582 the C preprocessor. Any options specified in the $SHF90FLAGS
7583 and $CPPFLAGS construction variables are included on this com‐
7584 mand line. You only need to set $SHF90PPCOM if you need to use
7585 a specific C-preprocessor command line for Fortran 90 files.
7586 You should normally set the $SHFORTRANPPCOM variable, which
7587 specifies the default C-preprocessor command line for all For‐
7588 tran versions.
7589 SHF90PPCOMSTR
7592 The string displayed when a Fortran 90 source file is compiled
7593 to a shared-library object file after first running the file
7594 through the C preprocessor. If this is not set, then
7595 $SHF90PPCOM or $SHFORTRANPPCOM (the command line) is displayed.
7596 SHF95 The Fortran 95 compiler used for generating shared-library
7599 objects. You should normally set the $SHFORTRAN variable, which
7600 specifies the default Fortran compiler for all Fortran versions.
7601 You only need to set $SHF95 if you need to use a specific com‐
7602 piler or compiler version for Fortran 95 files.
7603 SHF95COM
7606 The command line used to compile a Fortran 95 source file to a
7607 shared-library object file. You only need to set $SHF95COM if
7608 you need to use a specific command line for Fortran 95 files.
7609 You should normally set the $SHFORTRANCOM variable, which speci‐
7610 fies the default command line for all Fortran versions.
7611 SHF95COMSTR
7614 The string displayed when a Fortran 95 source file is compiled
7615 to a shared-library object file. If this is not set, then
7616 $SHF95COM or $SHFORTRANCOM (the command line) is displayed.
7617 SHF95FLAGS
7620 Options that are passed to the Fortran 95 compiler to generated
7621 shared-library objects. You only need to set $SHF95FLAGS if you
7622 need to define specific user options for Fortran 95 files. You
7623 should normally set the $SHFORTRANFLAGS variable, which speci‐
7624 fies the user-specified options passed to the default Fortran
7625 compiler for all Fortran versions.
7626 SHF95PPCOM
7629 The command line used to compile a Fortran 95 source file to a
7630 shared-library object file after first running the file through
7631 the C preprocessor. Any options specified in the $SHF95FLAGS
7632 and $CPPFLAGS construction variables are included on this com‐
7633 mand line. You only need to set $SHF95PPCOM if you need to use
7634 a specific C-preprocessor command line for Fortran 95 files.
7635 You should normally set the $SHFORTRANPPCOM variable, which
7636 specifies the default C-preprocessor command line for all For‐
7637 tran versions.
7638 SHF95PPCOMSTR
7641 The string displayed when a Fortran 95 source file is compiled
7642 to a shared-library object file after first running the file
7643 through the C preprocessor. If this is not set, then
7644 $SHF95PPCOM or $SHFORTRANPPCOM (the command line) is displayed.
7645 SHFORTRAN
7648 The default Fortran compiler used for generating shared-library
7649 objects.
7650 SHFORTRANCOM
7653 The command line used to compile a Fortran source file to a
7654 shared-library object file.
7655 SHFORTRANCOMSTR
7658 The string displayed when a Fortran source file is compiled to a
7659 shared-library object file. If this is not set, then $SHFOR‐
7660 TRANCOM (the command line) is displayed.
7661 SHFORTRANFLAGS
7664 Options that are passed to the Fortran compiler to generate
7665 shared-library objects.
7666 SHFORTRANPPCOM
7669 The command line used to compile a Fortran source file to a
7670 shared-library object file after first running the file through
7671 the C preprocessor. Any options specified in the $SHFORTRAN‐
7672 FLAGS and $CPPFLAGS construction variables are included on this
7673 command line.
7674 SHFORTRANPPCOMSTR
7677 The string displayed when a Fortran source file is compiled to a
7678 shared-library object file after first running the file through
7679 the C preprocessor. If this is not set, then $SHFORTRANPPCOM
7680 (the command line) is displayed.
7681 SHLIBEMITTER
7684 TODO
7685 SHLIBPREFIX
7688 The prefix used for shared library file names.
7689 SHLIBSUFFIX
7692 The suffix used for shared library file names.
7693 SHLINK The linker for programs that use shared libraries.
7696 SHLINKCOM
7699 The command line used to link programs using shared libraries.
7700 SHLINKCOMSTR
7703 The string displayed when programs using shared libraries are
7704 linked. If this is not set, then $SHLINKCOM (the command line)
7705 is displayed.
7706 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
7708 SHLINKFLAGS
7711 General user options passed to the linker for programs using
7712 shared libraries. Note that this variable should not contain -l
7713 (or similar) options for linking with the libraries listed in
7714 $LIBS, nor -L (or similar) include search path options that
7715 scons generates automatically from $LIBPATH. See $_LIBFLAGS
7716 above, for the variable that expands to library-link options,
7717 and $_LIBDIRFLAGS above, for the variable that expands to
7718 library search path options.
7719 SHOBJPREFIX
7722 The prefix used for shared object file names.
7723 SHOBJSUFFIX
7726 The suffix used for shared object file names.
7727 SOURCE A reserved variable name that may not be set or used in a con‐
7730 struction environment. (See "Variable Substitution," below.)
7731 SOURCE_URL
7734 The URL (web address) of the location from which the project was
7735 retrieved. This is used to fill in the Source: field in the
7736 controlling information for Ipkg and RPM packages.
7737 SOURCES
7740 A reserved variable name that may not be set or used in a con‐
7741 struction environment. (See "Variable Substitution," below.)
7742 SPAWN A command interpreter function that will be called to execute
7745 command line strings. The function must expect the following
7746 arguments:
7747 def spawn(shell, escape, cmd, args, env):
7749 sh is a string naming the shell program to use. escape is a
7751 function that can be called to escape shell special characters
7752 in the command line. cmd is the path to the command to be exe‐
7753 cuted. args is the arguments to the command. env is a dictio‐
7754 nary of the environment variables in which the command should be
7755 executed.
7756 SUBST_DICT
7759 The dictionary used by the Substfile() or Textfile() builders
7760 for substitution values. It can be anything acceptable to the
7761 dict() constructor, so in addition to a dictionary, lists of
7762 tuples are also acceptable.
7763 SUBSTFILEPREFIX
7766 The prefix used for Substfile() file names, the null string by
7767 default.
7768 SUBSTFILESUFFIX
7771 The suffix used for Substfile() file names, the null string by
7772 default.
7773 SUMMARY
7776 A short summary of what the project is about. This is used to
7777 fill in the Summary: field in the controlling information for
7778 Ipkg and RPM packages, and as the Description: field in MSI
7779 packages.
7780 SWIG The scripting language wrapper and interface generator.
7783 SWIGCFILESUFFIX
7786 The suffix that will be used for intermediate C source files
7787 generated by the scripting language wrapper and interface gener‐
7788 ator. The default value is _wrap$CFILESUFFIX. By default, this
7789 value is used whenever the -c++ option is not specified as part
7790 of the $SWIGFLAGS construction variable.
7791 SWIGCOM
7794 The command line used to call the scripting language wrapper and
7795 interface generator.
7796 SWIGCOMSTR
7799 The string displayed when calling the scripting language wrapper
7800 and interface generator. If this is not set, then $SWIGCOM (the
7801 command line) is displayed.
7802 SWIGCXXFILESUFFIX
7805 The suffix that will be used for intermediate C++ source files
7806 generated by the scripting language wrapper and interface gener‐
7807 ator. The default value is _wrap$CFILESUFFIX. By default, this
7808 value is used whenever the -c++ option is specified as part of
7809 the $SWIGFLAGS construction variable.
7810 SWIGDIRECTORSUFFIX
7813 The suffix that will be used for intermediate C++ header files
7814 generated by the scripting language wrapper and interface gener‐
7815 ator. These are only generated for C++ code when the SWIG
7816 'directors' feature is turned on. The default value is _wrap.h.
7817 SWIGFLAGS
7820 General options passed to the scripting language wrapper and
7821 interface generator. This is where you should set -python,
7822 -perl5, -tcl, or whatever other options you want to specify to
7823 SWIG. If you set the -c++ option in this variable, scons will,
7824 by default, generate a C++ intermediate source file with the
7825 extension that is specified as the $CXXFILESUFFIX variable.
7826 _SWIGINCFLAGS
7829 An automatically-generated construction variable containing the
7830 SWIG command-line options for specifying directories to be
7831 searched for included files. The value of $_SWIGINCFLAGS is
7832 created by appending $SWIGINCPREFIX and $SWIGINCSUFFIX to the
7833 beginning and end of each directory in $SWIGPATH.
7834 SWIGINCPREFIX
7837 The prefix used to specify an include directory on the SWIG com‐
7838 mand line. This will be appended to the beginning of each
7839 directory in the $SWIGPATH construction variable when the
7840 $_SWIGINCFLAGS variable is automatically generated.
7841 SWIGINCSUFFIX
7844 The suffix used to specify an include directory on the SWIG com‐
7845 mand line. This will be appended to the end of each directory
7846 in the $SWIGPATH construction variable when the $_SWIGINCFLAGS
7847 variable is automatically generated.
7848 SWIGOUTDIR
7851 Specifies the output directory in which the scripting language
7852 wrapper and interface generator should place generated language-
7853 specific files. This will be used by SCons to identify the
7854 files that will be generated by the &swig; call, and translated
7855 into the swig -outdir option on the command line.
7856 SWIGPATH
7859 The list of directories that the scripting language wrapper and
7860 interface generate will search for included files. The SWIG
7861 implicit dependency scanner will search these directories for
7862 include files. The default is to use the same path specified as
7863 $CPPPATH.
7864 Don't explicitly put include directory arguments in SWIGFLAGS;
7866 the result will be non-portable and the directories will not be
7867 searched by the dependency scanner. Note: directory names in
7868 SWIGPATH will be looked-up relative to the SConscript directory
7869 when they are used in a command. To force scons to look-up a
7870 directory relative to the root of the source tree use #:
7871 env = Environment(SWIGPATH='#/include')
7873 The directory look-up can also be forced using the Dir() func‐
7875 tion:
7876 include = Dir('include')
7878 env = Environment(SWIGPATH=include)
7879 The directory list will be added to command lines through the
7881 automatically-generated $_SWIGINCFLAGS construction variable,
7882 which is constructed by appending the values of the $SWIGINCPRE‐
7883 FIXand$SWIGINCSUFFIX construction variables to the beginning and
7884 end of each directory in $SWIGPATH. Any command lines you
7885 define that need the SWIGPATH directory list should include
7886 $_SWIGINCFLAGS:
7887 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SORUCES")
7889 SWIGVERSION
7892 The version number of the SWIG tool.
7893 TAR The tar archiver.
7896 TARCOM The command line used to call the tar archiver.
7899 TARCOMSTR
7902 The string displayed when archiving files using the tar
7903 archiver. If this is not set, then $TARCOM (the command line)
7904 is displayed.
7905 env = Environment(TARCOMSTR = "Archiving $TARGET")
7907 TARFLAGS
7910 General options passed to the tar archiver.
7911 TARGET A reserved variable name that may not be set or used in a con‐
7914 struction environment. (See "Variable Substitution," below.)
7915 TARGET_ARCH
7918 Sets the target architecture for Visual Studio compiler (i.e.
7919 the arch of the binaries generated by the compiler). If not set,
7920 default to $HOST_ARCH, or, if that is unset, to the architecture
7921 of the running machine's OS (note that the python build or
7922 architecture has no effect). This variable must be passed as an
7923 argument to the Environment() constructor; setting it later has
7924 no effect. This is currently only used on Windows, but in the
7925 future it will be used on other OSes as well.
7926 Valid values for Windows are x86, i386 (for 32 bits); amd64,
7928 emt64, x86_64 (for 64 bits); and ia64 (Itanium). For example,
7929 if you want to compile 64-bit binaries, you would set TAR‐
7930 GET_ARCH='x86_64' in your SCons environment.
7931 TARGET_OS
7934 The name of the target operating system for the compiled
7935 objects
7936 created by this Environment.
7937 This defaults to the value of HOST_OS, and the user can
7938 override it.
7939 Currently only set for Win32.
7940 TARGETS
7943 A reserved variable name that may not be set or used in a con‐
7944 struction environment. (See "Variable Substitution," below.)
7945 TARSUFFIX
7948 The suffix used for tar file names.
7949 TEMPFILEPREFIX
7952 The prefix for a temporary file used to execute lines longer
7953 than $MAXLINELENGTH. The default is '@'. This may be set for
7954 toolchains that use other values, such as '-@' for the diab com‐
7955 piler or '-via' for ARM toolchain.
7956 TEX The TeX formatter and typesetter.
7959 TEXCOM The command line used to call the TeX formatter and typesetter.
7962 TEXCOMSTR
7965 The string displayed when calling the TeX formatter and typeset‐
7966 ter. If this is not set, then $TEXCOM (the command line) is
7967 displayed.
7968 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
7970 TEXFLAGS
7973 General options passed to the TeX formatter and typesetter.
7974 TEXINPUTS
7977 List of directories that the LaTeX program will search for
7978 include directories. The LaTeX implicit dependency scanner will
7979 search these directories for \include and \import files.
7980 TEXTFILEPREFIX
7983 The prefix used for Textfile() file names, the null string by
7984 default.
7985 TEXTFILESUFFIX
7988 The suffix used for Textfile() file names; .txt by default.
7989 TOOLS A list of the names of the Tool specifications that are part of
7992 this construction environment.
7993 UNCHANGED_SOURCES
7996 A reserved variable name that may not be set or used in a con‐
7997 struction environment. (See "Variable Substitution," below.)
7998 UNCHANGED_TARGETS
8001 A reserved variable name that may not be set or used in a con‐
8002 struction environment. (See "Variable Substitution," below.)
8003 VENDOR The person or organization who supply the packaged software.
8006 This is used to fill in the Vendor: field in the controlling
8007 information for RPM packages, and the Manufacturer: field in the
8008 controlling information for MSI packages.
8009 VERSION
8012 The version of the project, specified as a string.
8013 WIN32_INSERT_DEF
8016 A deprecated synonym for $WINDOWS_INSERT_DEF.
8017 WIN32DEFPREFIX
8020 A deprecated synonym for $WINDOWSDEFPREFIX.
8021 WIN32DEFSUFFIX
8024 A deprecated synonym for $WINDOWSDEFSUFFIX.
8025 WIN32EXPPREFIX
8028 A deprecated synonym for $WINDOWSEXPSUFFIX.
8029 WIN32EXPSUFFIX
8032 A deprecated synonym for $WINDOWSEXPSUFFIX.
8033 WINDOWS_EMBED_MANIFEST
8036 Set this variable to True or 1 to embed the compiler-generated
8037 manifest (normally ${TARGET}.manifest) into all Windows exes and
8038 DLLs built with this environment, as a resource during their
8039 link step. This is done using $MT and $MTEXECOM and $MTSHLIB‐
8040 COM.
8041 WINDOWS_INSERT_DEF
8044 When this is set to true, a library build of a Windows shared
8045 library (.dllfile) will also build a corresponding .def file at
8046 the same time, if a .def file is not already listed as a build
8047 target. The default is 0 (do not build a .def file).
8048 WINDOWS_INSERT_MANIFEST
8051 When this is set to true, scons will be aware of the .manifest
8052 files generated by Microsoft Visua C/C++ 8.
8053 WINDOWSDEFPREFIX
8056 The prefix used for Windows .def file names.
8057 WINDOWSDEFSUFFIX
8060 The suffix used for Windows .def file names.
8061 WINDOWSEXPPREFIX
8064 The prefix used for Windows .exp file names.
8065 WINDOWSEXPSUFFIX
8068 The suffix used for Windows .exp file names.
8069 WINDOWSPROGMANIFESTPREFIX
8072 The prefix used for executable program .manifest files generated
8073 by Microsoft Visual C/C++.
8074 WINDOWSPROGMANIFESTSUFFIX
8077 The suffix used for executable program .manifest files generated
8078 by Microsoft Visual C/C++.
8079 WINDOWSSHLIBMANIFESTPREFIX
8082 The prefix used for shared library .manifest files generated by
8083 Microsoft Visual C/C++.
8084 WINDOWSSHLIBMANIFESTSUFFIX
8087 The suffix used for shared library .manifest files generated by
8088 Microsoft Visual C/C++.
8089 X_IPK_DEPENDS
8092 This is used to fill in the Depends: field in the controlling
8093 information for Ipkg packages.
8094 X_IPK_DESCRIPTION
8097 This is used to fill in the Description: field in the control‐
8098 ling information for Ipkg packages. The default value is $SUM‐
8099 MARY0DESCRIPTION
8100 X_IPK_MAINTAINER
8102 This is used to fill in the Maintainer: field in the controlling
8103 information for Ipkg packages.
8104 X_IPK_PRIORITY
8107 This is used to fill in the Priority: field in the controlling
8108 information for Ipkg packages.
8109 X_IPK_SECTION
8112 This is used to fill in the Section: field in the controlling
8113 information for Ipkg packages.
8114 X_MSI_LANGUAGE
8117 This is used to fill in the Language: attribute in the control‐
8118 ling information for MSI packages.
8119 X_MSI_LICENSE_TEXT
8122 The text of the software license in RTF format. Carriage return
8123 characters will be replaced with the RTF equivalent \\par.
8124 X_MSI_UPGRADE_CODE
8127 TODO
8128 X_RPM_AUTOREQPROV
8131 This is used to fill in the AutoReqProv: field in the RPM .spec
8132 file.
8133 X_RPM_BUILD
8136 internal, but overridable
8137 X_RPM_BUILDREQUIRES
8140 This is used to fill in the BuildRequires: field in the RPM
8141 .spec file.
8142 X_RPM_BUILDROOT
8145 internal, but overridable
8146 X_RPM_CLEAN
8149 internal, but overridable
8150 X_RPM_CONFLICTS
8153 This is used to fill in the Conflicts: field in the RPM .spec
8154 file.
8155 X_RPM_DEFATTR
8158 This value is used as the default attributes for the files in
8159 the RPM package. The default value is (-,root,root).
8160 X_RPM_DISTRIBUTION
8163 This is used to fill in the Distribution: field in the RPM .spec
8164 file.
8165 X_RPM_EPOCH
8168 This is used to fill in the Epoch: field in the controlling
8169 information for RPM packages.
8170 X_RPM_EXCLUDEARCH
8173 This is used to fill in the ExcludeArch: field in the RPM .spec
8174 file.
8175 X_RPM_EXLUSIVEARCH
8178 This is used to fill in the ExclusiveArch: field in the RPM
8179 .spec file.
8180 X_RPM_GROUP
8183 This is used to fill in the Group: field in the RPM .spec file.
8184 X_RPM_GROUP_lang
8187 This is used to fill in the Group(lang): field in the RPM .spec
8188 file. Note that lang is not literal and should be replaced by
8189 the appropriate language code.
8190 X_RPM_ICON
8193 This is used to fill in the Icon: field in the RPM .spec file.
8194 X_RPM_INSTALL
8197 internal, but overridable
8198 X_RPM_PACKAGER
8201 This is used to fill in the Packager: field in the RPM .spec
8202 file.
8203 X_RPM_POSTINSTALL
8206 This is used to fill in the %post: section in the RPM .spec
8207 file.
8208 X_RPM_POSTUNINSTALL
8211 This is used to fill in the %postun: section in the RPM .spec
8212 file.
8213 X_RPM_PREFIX
8216 This is used to fill in the Prefix: field in the RPM .spec file.
8217 X_RPM_PREINSTALL
8220 This is used to fill in the %pre: section in the RPM .spec file.
8221 X_RPM_PREP
8224 internal, but overridable
8225 X_RPM_PREUNINSTALL
8228 This is used to fill in the %preun: section in the RPM .spec
8229 file.
8230 X_RPM_PROVIDES
8233 This is used to fill in the Provides: field in the RPM .spec
8234 file.
8235 X_RPM_REQUIRES
8238 This is used to fill in the Requires: field in the RPM .spec
8239 file.
8240 X_RPM_SERIAL
8243 This is used to fill in the Serial: field in the RPM .spec file.
8244 X_RPM_URL
8247 This is used to fill in the Url: field in the RPM .spec file.
8248 YACC The parser generator.
8251 YACCCOM
8254 The command line used to call the parser generator to generate a
8255 source file.
8256 YACCCOMSTR
8259 The string displayed when generating a source file using the
8260 parser generator. If this is not set, then $YACCCOM (the com‐
8261 mand line) is displayed.
8262 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
8264 YACCFLAGS
8267 General options passed to the parser generator. If $YACCFLAGS
8268 contains a -d option, SCons assumes that the call will also cre‐
8269 ate a .h file (if the yacc source file ends in a .y suffix) or a
8270 .hpp file (if the yacc source file ends in a .yy suffix)
8271 YACCHFILESUFFIX
8274 The suffix of the C header file generated by the parser genera‐
8275 tor when the -d option is used. Note that setting this variable
8276 does not cause the parser generator to generate a header file
8277 with the specified suffix, it exists to allow you to specify
8278 what suffix the parser generator will use of its own accord.
8279 The default value is .h.
8280 YACCHXXFILESUFFIX
8283 The suffix of the C++ header file generated by the parser gener‐
8284 ator when the -d option is used. Note that setting this vari‐
8285 able does not cause the parser generator to generate a header
8286 file with the specified suffix, it exists to allow you to spec‐
8287 ify what suffix the parser generator will use of its own accord.
8288 The default value is .hpp, except on Mac OS X, where the default
8289 is ${TARGET.suffix}.h. because the default &bison; parser gen‐
8290 erator just appends .h to the name of the generated C++ file.
8291 YACCVCGFILESUFFIX
8294 The suffix of the file containing the VCG grammar automaton def‐
8295 inition when the --graph= option is used. Note that setting
8296 this variable does not cause the parser generator to generate a
8297 VCG file with the specified suffix, it exists to allow you to
8298 specify what suffix the parser generator will use of its own
8299 accord. The default value is .vcg.
8300 ZIP The zip compression and file packaging utility.
8303 ZIPCOM The command line used to call the zip utility, or the internal
8306 Python function used to create a zip archive.
8307 ZIPCOMPRESSION
8310 The compression flag from the Python zipfile module used by the
8311 internal Python function to control whether the zip archive is
8312 compressed or not. The default value is zipfile.ZIP_DEFLATED,
8313 which creates a compressed zip archive. This value has no
8314 effect if the zipfile module is unavailable.
8315 ZIPCOMSTR
8318 The string displayed when archiving files using the zip utility.
8319 If this is not set, then $ZIPCOM (the command line or internal
8320 Python function) is displayed.
8321 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
8323 ZIPFLAGS
8326 General options passed to the zip utility.
8327 ZIPSUFFIX
8330 The suffix used for zip file names.
8331 Construction variables can be retrieved and set using the Dictionary
8334 method of the construction environment:
8335 dict = env.Dictionary()
8337 dict["CC"] = "cc"
8338 or using the [] operator:
8340 env["CC"] = "cc"
8342 Construction variables can also be passed to the construction environ‐
8344 ment constructor:
8345 env = Environment(CC="cc")
8347 or when copying a construction environment using the Clone method:
8349 env2 = env.Clone(CC="cl.exe")
8351 Configure Contexts
8354 scons supports configure contexts, an integrated mechanism similar to
8355 the various AC_CHECK macros in GNU autoconf for testing for the exis‐
8356 tence of C header files, libraries, etc. In contrast to autoconf,
8357 scons does not maintain an explicit cache of the tested values, but
8358 uses its normal dependency tracking to keep the checked values up to
8359 date. However, users may override this behaviour with the --config com‐
8360 mand line option.
8361 The following methods can be used to perform checks:
8363 Configure(env, [custom_tests, conf_dir, log_file, config_h, clean,
8366 help])
8367 env.Configure([custom_tests, conf_dir, log_file, config_h, clean,
8369 help])
8370 This creates a configure context, which can be used to perform
8371 checks. env specifies the environment for building the tests.
8372 This environment may be modified when performing checks. cus‐
8373 tom_tests is a dictionary containing custom tests. See also the
8374 section about custom tests below. By default, no custom tests
8375 are added to the configure context. conf_dir specifies a direc‐
8376 tory where the test cases are built. Note that this directory
8377 is not used for building normal targets. The default value is
8378 the directory #/.sconf_temp. log_file specifies a file which
8379 collects the output from commands that are executed to check for
8380 the existence of header files, libraries, etc. The default is
8381 the file #/config.log. If you are using the VariantDir()
8382 method, you may want to specify a subdirectory under your vari‐
8383 ant directory. config_h specifies a C header file where the
8384 results of tests will be written, e.g. #define HAVE_STDIO_H,
8385 #define HAVE_LIBM, etc. The default is to not write a config.h
8386 file. You can specify the same config.h file in multiple calls
8387 to Configure, in which case scons will concatenate all results
8388 in the specified file. Note that SCons uses its normal depen‐
8389 dency checking to decide if it's necessary to rebuild the speci‐
8390 fied config_h file. This means that the file is not necessarily
8391 re-built each time scons is run, but is only rebuilt if its con‐
8392 tents will have changed and some target that depends on the con‐
8393 fig_h file is being built.
8394 The optional clean and help arguments can be used to suppress
8396 execution of the configuration tests when the -c/--clean or
8397 -H/-h/--help options are used, respectively. The default behav‐
8398 ior is always to execute configure context tests, since the
8399 results of the tests may affect the list of targets to be
8400 cleaned or the help text. If the configure tests do not affect
8401 these, then you may add the clean=False or help=False arguments
8402 (or both) to avoid unnecessary test execution.
8403 A created Configure instance has the following associated methods:
8405 SConf.Finish(context)
8408 sconf.Finish()
8410 This method should be called after configuration is done. It
8411 returns the environment as modified by the configuration checks
8412 performed. After this method is called, no further checks can
8413 be performed with this configuration context. However, you can
8414 create a new Configure context to perform additional checks.
8415 Only one context should be active at a time.
8416 The following Checks are predefined. (This list will likely
8418 grow larger as time goes by and developers contribute new useful
8419 tests.)
8420 SConf.CheckHeader(context, header, [include_quotes, language])
8423 sconf.CheckHeader(header, [include_quotes, language])
8425 Checks if header is usable in the specified language. header
8426 may be a list, in which case the last item in the list is the
8427 header file to be checked, and the previous list items are
8428 header files whose #include lines should precede the header line
8429 being checked for. The optional argument include_quotes must be
8430 a two character string, where the first character denotes the
8431 opening quote and the second character denotes the closing
8432 quote. By default, both characters are " (double quote). The
8433 optional argument language should be either C or C++ and selects
8434 the compiler to be used for the check. Returns 1 on success and
8435 0 on failure.
8436 SConf.CheckCHeader(context, header, [include_quotes])
8439 sconf.CheckCHeader(header, [include_quotes])
8441 This is a wrapper around SConf.CheckHeader which checks if
8442 header is usable in the C language. header may be a list, in
8443 which case the last item in the list is the header file to be
8444 checked, and the previous list items are header files whose
8445 #include lines should precede the header line being checked for.
8446 The optional argument include_quotes must be a two character
8447 string, where the first character denotes the opening quote and
8448 the second character denotes the closing quote (both default to
8449 "). Returns 1 on success and 0 on failure.
8450 SConf.CheckCXXHeader(context, header, [include_quotes])
8453 sconf.CheckCXXHeader(header, [include_quotes])
8455 This is a wrapper around SConf.CheckHeader which checks if
8456 header is usable in the C++ language. header may be a list, in
8457 which case the last item in the list is the header file to be
8458 checked, and the previous list items are header files whose
8459 #include lines should precede the header line being checked for.
8460 The optional argument include_quotes must be a two character
8461 string, where the first character denotes the opening quote and
8462 the second character denotes the closing quote (both default to
8463 "). Returns 1 on success and 0 on failure.
8464 SConf.CheckFunc(context,, function_name, [header, language])
8467 sconf.CheckFunc(function_name, [header, language])
8469 Checks if the specified C or C++ function is available. func‐
8470 tion_name is the name of the function to check for. The
8471 optional header argument is a string that will be placed at the
8472 top of the test file that will be compiled to check if the func‐
8473 tion exists; the default is:
8474 #ifdef __cplusplus
8475 extern "C"
8476 #endif
8477 char function_name();
8478 The optional language argument should be C or C++ and selects the com‐
8479 piler to be used for the check; the default is "C".
8480 SConf.CheckLib(context, [library, symbol, header, language, autoadd=1])
8483 sconf.CheckLib([library, symbol, header, language, autoadd=1])
8485 Checks if library provides symbol. If the value of autoadd is 1
8486 and the library provides the specified symbol, appends the
8487 library to the LIBS construction environment variable. library
8488 may also be None (the default), in which case symbol is checked
8489 with the current LIBS variable, or a list of library names, in
8490 which case each library in the list will be checked for symbol.
8491 If symbol is not set or is None, then SConf.CheckLib() just
8492 checks if you can link against the specified library. The
8493 optional language argument should be C or C++ and selects the
8494 compiler to be used for the check; the default is "C". The
8495 default value for autoadd is 1. This method returns 1 on suc‐
8496 cess and 0 on error.
8497 SConf.CheckLibWithHeader(context, library, header, language, [call,
8500 autoadd])
8501 sconf.CheckLibWithHeader(library, header, language, [call, autoadd])
8503 In contrast to the SConf.CheckLib call, this call provides a
8505 more sophisticated way to check against libraries. Again,
8506 library specifies the library or a list of libraries to check.
8507 header specifies a header to check for. header may be a list,
8508 in which case the last item in the list is the header file to be
8509 checked, and the previous list items are header files whose
8510 #include lines should precede the header line being checked for.
8511 language may be one of 'C','c','CXX','cxx','C++' and 'c++'.
8512 call can be any valid expression (with a trailing ';'). If call
8513 is not set, the default simply checks that you can link against
8514 the specified library. autoadd specifies whether to add the
8515 library to the environment (only if the check succeeds). This
8516 method returns 1 on success and 0 on error.
8517 SConf.CheckType(context, type_name, [includes, language])
8520 sconf.CheckType(type_name, [includes, language])
8522 Checks for the existence of a type defined by typedef.
8523 type_name specifies the typedef name to check for. includes is
8524 a string containing one or more #include lines that will be
8525 inserted into the program that will be run to test for the exis‐
8526 tence of the type. The optional language argument should be C
8527 or C++ and selects the compiler to be used for the check; the
8528 default is "C". Example:
8529 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
8530 Configure.CheckCC(self)
8533 Checks whether the C compiler (as defined by the CC construction
8534 variable) works by trying to compile a small source file.
8535 By default, SCons only detects if there is a program with the
8537 correct name, not if it is a functioning compiler.
8538 This uses the exact same command than the one used by the object
8540 builder for C source file, so it can be used to detect if a par‐
8541 ticular compiler flag works or not.
8542 Configure.CheckCXX(self)
8545 Checks whether the C++ compiler (as defined by the CXX construc‐
8546 tion variable) works by trying to compile a small source file.
8547 By default, SCons only detects if there is a program with the
8548 correct name, not if it is a functioning compiler.
8549 This uses the exact same command than the one used by the object
8551 builder for CXX source files, so it can be used to detect if a
8552 particular compiler flag works or not.
8553 Configure.CheckSHCC(self)
8556 Checks whether the C compiler (as defined by the SHCC construc‐
8557 tion variable) works by trying to compile a small source file.
8558 By default, SCons only detects if there is a program with the
8559 correct name, not if it is a functioning compiler.
8560 This uses the exact same command than the one used by the object
8562 builder for C source file, so it can be used to detect if a par‐
8563 ticular compiler flag works or not. This does not check whether
8564 the object code can be used to build a shared library, only that
8565 the compilation (not link) succeeds.
8566 Configure.CheckSHCXX(self)
8569 Checks whether the C++ compiler (as defined by the SHCXX con‐
8570 struction variable) works by trying to compile a small source
8571 file. By default, SCons only detects if there is a program with
8572 the correct name, not if it is a functioning compiler.
8573 This uses the exact same command than the one used by the object
8575 builder for CXX source files, so it can be used to detect if a
8576 particular compiler flag works or not. This does not check
8577 whether the object code can be used to build a shared library,
8578 only that the compilation (not link) succeeds.
8579 Example of a typical Configure usage:
8581 env = Environment()
8583 conf = Configure( env )
8584 if not conf.CheckCHeader( 'math.h' ):
8585 print 'We really need math.h!'
8586 Exit(1)
8587 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
8588 'QApplication qapp(0,0);' ):
8589 # do stuff for qt - usage, e.g.
8590 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
8591 env = conf.Finish()
8592 SConf.CheckTypeSize(context, type_name, [header, language, expect])
8595 sconf.CheckTypeSize(type_name, [header, language, expect])
8597 Checks for the size of a type defined by typedef. type_name
8598 specifies the typedef name to check for. The optional header
8599 argument is a string that will be placed at the top of the test
8600 file that will be compiled to check if the function exists; the
8601 default is empty. The optional language argument should be C or
8602 C++ and selects the compiler to be used for the check; the
8603 default is "C". The optional expect argument should be an inte‐
8604 ger. If this argument is used, the function will only check
8605 whether the type given in type_name has the expected size (in
8606 bytes). For example, CheckTypeSize('short', expect = 2) will
8607 return success only if short is two bytes.
8608 SConf.CheckDeclaration(context, symbol, [includes, language])
8612 sconf.CheckDeclaration(symbol, [includes, language])
8614 Checks if the specified symbol is declared. includes is a
8615 string containing one or more #include lines that will be
8616 inserted into the program that will be run to test for the exis‐
8617 tence of the type. The optional language argument should be C
8618 or C++ and selects the compiler to be used for the check; the
8619 default is "C".
8620 SConf.Define(context, symbol, [value, comment])
8623 sconf.Define(symbol, [value, comment])
8625 This function does not check for anything, but defines a pre‐
8626 processor symbol that will be added to the configuration header
8627 file. It is the equivalent of AC_DEFINE, and defines the symbol
8628 name with the optional value and the optional comment comment.
8629 Examples:
8632 env = Environment()
8634 conf = Configure( env )
8635 # Puts the following line in the config header file:
8637 # #define A_SYMBOL
8638 conf.Define('A_SYMBOL')
8639 # Puts the following line in the config header file:
8641 # #define A_SYMBOL 1
8642 conf.Define('A_SYMBOL', 1)
8643 Be careful about quoting string values, though:
8646 env = Environment()
8648 conf = Configure( env )
8649 # Puts the following line in the config header file:
8651 # #define A_SYMBOL YA
8652 conf.Define('A_SYMBOL', "YA")
8653 # Puts the following line in the config header file:
8655 # #define A_SYMBOL "YA"
8656 conf.Define('A_SYMBOL', '"YA"')
8657 For comment:
8660 env = Environment()
8662 conf = Configure( env )
8663 # Puts the following lines in the config header file:
8665 # /* Set to 1 if you have a symbol */
8666 # #define A_SYMBOL 1
8667 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
8668 You can define your own custom checks. in addition to the predefined
8670 checks. These are passed in a dictionary to the Configure function.
8671 This dictionary maps the names of the checks to user defined Python
8672 callables (either Python functions or class instances implementing the
8673 __call__ method). The first argument of the call is always a CheckCon‐
8674 text instance followed by the arguments, which must be supplied by the
8675 user of the check. These CheckContext instances define the following
8676 methods:
8677 CheckContext.Message(self, text)
8680 Usually called before the check is started. text will be dis‐
8682 played to the user, e.g. 'Checking for library X...'
8683 CheckContext.Result(self,, res)
8686 Usually called after the check is done. res can be either an
8688 integer or a string. In the former case, 'yes' (res != 0) or
8689 'no' (res == 0) is displayed to the user, in the latter case the
8690 given string is displayed.
8691 CheckContext.TryCompile(self, text, extension)
8694 Checks if a file with the specified extension (e.g. '.c') con‐
8695 taining text can be compiled using the environment's Object
8696 builder. Returns 1 on success and 0 on failure.
8697 CheckContext.TryLink(self, text, extension)
8700 Checks, if a file with the specified extension (e.g. '.c') con‐
8701 taining text can be compiled using the environment's Program
8702 builder. Returns 1 on success and 0 on failure.
8703 CheckContext.TryRun(self, text, extension)
8706 Checks, if a file with the specified extension (e.g. '.c') con‐
8707 taining text can be compiled using the environment's Program
8708 builder. On success, the program is run. If the program executes
8709 successfully (that is, its return status is 0), a tuple (1, out‐
8710 putStr) is returned, where outputStr is the standard output of
8711 the program. If the program fails execution (its return status
8712 is non-zero), then (0, '') is returned.
8713 CheckContext.TryAction(self, action, [text, extension])
8716 Checks if the specified action with an optional source file
8717 (contents text , extension extension = '' ) can be executed.
8718 action may be anything which can be converted to a scons Action.
8719 On success, (1, outputStr) is returned, where outputStr is the
8720 content of the target file. On failure (0, '') is returned.
8721 CheckContext.TryBuild(self, builder, [text, extension])
8724 Low level implementation for testing specific builds; the meth‐
8725 ods above are based on this method. Given the Builder instance
8726 builder and the optional text of a source file with optional
8727 extension, this method returns 1 on success and 0 on failure. In
8728 addition, self.lastTarget is set to the build target node, if
8729 the build was successful.
8730 Example for implementing and using custom tests:
8732 def CheckQt(context, qtdir):
8734 context.Message( 'Checking for qt ...' )
8735 lastLIBS = context.env['LIBS']
8736 lastLIBPATH = context.env['LIBPATH']
8737 lastCPPPATH= context.env['CPPPATH']
8738 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
8739 ret = context.TryLink("""
8740 #include <qapp.h>
8741 int main(int argc, char **argv) {
8742 QApplication qapp(argc, argv);
8743 return 0;
8744 }
8745 """)
8746 if not ret:
8747 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
8748 context.Result( ret )
8749 return ret
8750 env = Environment()
8752 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
8753 if not conf.CheckQt('/usr/lib/qt'):
8754 print 'We really need qt!'
8755 Exit(1)
8756 env = conf.Finish()
8757 Command-Line Construction Variables
8760 Often when building software, some variables must be specified at build
8761 time. For example, libraries needed for the build may be in non-stan‐
8762 dard locations, or site-specific compiler options may need to be passed
8763 to the compiler. scons provides a Variables object to support overrid‐
8764 ing construction variables on the command line:
8765 $ scons VARIABLE=foo
8766 The variable values can also be specified in a text-based SConscript
8767 file. To create a Variables object, call the Variables() function:
8768 Variables([files], [args])
8771 This creates a Variables object that will read construction
8772 variables from the file or list of filenames specified in files.
8773 If no files are specified, or the files argument is None, then
8774 no files will be read. The optional argument args is a dictio‐
8775 nary of values that will override anything read from the speci‐
8776 fied files; it is primarily intended to be passed the ARGUMENTS
8777 dictionary that holds variables specified on the command line.
8778 Example:
8779 vars = Variables('custom.py')
8781 vars = Variables('overrides.py', ARGUMENTS)
8782 vars = Variables(None, {FOO:'expansion', BAR:7})
8783 Variables objects have the following methods:
8785 Add(key, [help, default, validator, converter])
8788 This adds a customizable construction variable to the Variables
8789 object. key is the name of the variable. help is the help text
8790 for the variable. default is the default value of the variable;
8791 if the default value is None and there is no explicit value
8792 specified, the construction variable will not be added to the
8793 construction environment. validator is called to validate the
8794 value of the variable, and should take three arguments: key,
8795 value, and environment. The recommended way to handle an
8796 invalid value is to raise an exception (see example below).
8797 converter is called to convert the value before putting it in
8798 the environment, and should take either a value, or the value
8799 and environment, as parameters. The converter must return a
8800 value, which will be converted into a string before being vali‐
8801 dated by the validator (if any) and then added to the environ‐
8802 ment.
8803 Examples:
8805 vars.Add('CC', 'The C compiler')
8807 def validate_color(key, val, env):
8809 if not val in ['red', 'blue', 'yellow']:
8810 raise Exception("Invalid color value '%s'" % val)
8811 vars.Add('COLOR', validator=valid_color)
8812 AddVariables(list)
8815 A wrapper script that adds multiple customizable construction
8816 variables to a Variables object. list is a list of tuple or
8817 list objects that contain the arguments for an individual call
8818 to the Add method.
8819 opt.AddVariables(
8821 ('debug', '', 0),
8822 ('CC', 'The C compiler'),
8823 ('VALIDATE', 'An option for testing validation',
8824 'notset', validator, None),
8825 )
8826 Update(env, [args])
8829 This updates a construction environment env with the customized
8830 construction variables. Any specified variables that are not
8831 configured for the Variables object will be saved and may be
8832 retrieved with the UnknownVariables() method, below.
8833 Normally this method is not called directly, but is called indi‐
8835 rectly by passing the Variables object to the Environment()
8836 function:
8837 env = Environment(variables=vars)
8839 The text file(s) that were specified when the Variables object
8842 was created are executed as Python scripts, and the values of
8843 (global) Python variables set in the file are added to the con‐
8844 struction environment.
8845 Example:
8847 CC = 'my_cc'
8849 UnknownVariables()
8852 Returns a dictionary containing any variables that were speci‐
8853 fied either in the files or the dictionary with which the Vari‐
8854 ables object was initialized, but for which the Variables object
8855 was not configured.
8856 env = Environment(variables=vars)
8858 for key, value in vars.UnknownVariables():
8859 print "unknown variable: %s=%s" % (key, value)
8860 Save(filename, env)
8863 This saves the currently set variables into a script file named
8864 filename that can be used on the next invocation to automati‐
8865 cally load the current settings. This method combined with the
8866 Variables method can be used to support caching of variables
8867 between runs.
8868 env = Environment()
8870 vars = Variables(['variables.cache', 'custom.py'])
8871 vars.Add(...)
8872 vars.Update(env)
8873 vars.Save('variables.cache', env)
8874 GenerateHelpText(env, [sort])
8877 This generates help text documenting the customizable construc‐
8878 tion variables suitable to passing in to the Help() function.
8879 env is the construction environment that will be used to get the
8880 actual values of customizable variables. Calling with an
8881 optional sort function will cause the output to be sorted by the
8882 specified argument. The specific sort function should take two
8883 arguments and return -1, 0 or 1 (like the standard Python cmp
8884 function).
8885 Help(vars.GenerateHelpText(env))
8887 Help(vars.GenerateHelpText(env, sort=cmp))
8888 FormatVariableHelpText(env, opt, help, default, actual)
8891 This method returns a formatted string containing the printable
8892 help text for one option. It is normally not called directly,
8893 but is called by the GenerateHelpText() method to create the
8894 returned help text. It may be overridden with your own function
8895 that takes the arguments specified above and returns a string of
8896 help text formatted to your liking. Note that the GenerateHelp‐
8897 Text() will not put any blank lines or extra characters in
8898 between the entries, so you must add those characters to the
8899 returned string if you want the entries separated.
8900 def my_format(env, opt, help, default, actual):
8902 fmt = "108s: default=%s actual=%s (%s)0
8903 return fmt % (opt, default. actual, help)
8904 vars.FormatVariableHelpText = my_format
8905 To make it more convenient to work with customizable Variables, scons
8907 provides a number of functions that make it easy to set up various
8908 types of Variables:
8909 BoolVariable(key, help, default)
8912 Return a tuple of arguments to set up a Boolean option. The
8913 option will use the specified name key, have a default value of
8914 default, and display the specified help text. The option will
8915 interpret the values y, yes, t, true, 1, on and all as true, and
8916 the values n, no, f, false, 0, off and none as false.
8917 EnumVariable(key, help, default, allowed_values, [map, ignorecase])
8920 Return a tuple of arguments to set up an option whose value may
8921 be one of a specified list of legal enumerated values. The
8922 option will use the specified name key, have a default value of
8923 default, and display the specified help text. The option will
8924 only support those values in the allowed_values list. The
8925 optional map argument is a dictionary that can be used to con‐
8926 vert input values into specific legal values in the allowed_val‐
8927 ues list. If the value of ignore_case is 0 (the default), then
8928 the values are case-sensitive. If the value of ignore_case is
8929 1, then values will be matched case-insensitive. If the value
8930 of ignore_case is 1, then values will be matched case-insensi‐
8931 tive, and all input values will be converted to lower case.
8932 ListVariable(key, help, default, names, [,map])
8935 Return a tuple of arguments to set up an option whose value may
8936 be one or more of a specified list of legal enumerated values.
8937 The option will use the specified name key, have a default value
8938 of default, and display the specified help text. The option
8939 will only support the values all, none, or the values in the
8940 names list. More than one value may be specified, with all val‐
8941 ues separated by commas. The default may be a string of comma-
8942 separated default values, or a list of the default values. The
8943 optional map argument is a dictionary that can be used to con‐
8944 vert input values into specific legal values in the names list.
8945 PackageVariable(key, help, default)
8948 Return a tuple of arguments to set up an option whose value is a
8949 path name of a package that may be enabled, disabled or given an
8950 explicit path name. The option will use the specified name key,
8951 have a default value of default, and display the specified help
8952 text. The option will support the values yes, true, on, enable
8953 or search, in which case the specified default will be used, or
8954 the option may be set to an arbitrary string (typically the path
8955 name to a package that is being enabled). The option will also
8956 support the values no, false, off or disable to disable use of
8957 the specified option.
8958 PathVariable(key, help, default, [validator])
8961 Return a tuple of arguments to set up an option whose value is
8962 expected to be a path name. The option will use the specified
8963 name key, have a default value of default, and display the spec‐
8964 ified help text. An additional validator may be specified that
8965 will be called to verify that the specified path is acceptable.
8966 SCons supplies the following ready-made validators: PathVari‐
8967 able.PathExists (the default), which verifies that the specified
8968 path exists; PathVariable.PathIsFile, which verifies that the
8969 specified path is an existing file; PathVariable.PathIsDir,
8970 which verifies that the specified path is an existing directory;
8971 PathVariable.PathIsDirCreate, which verifies that the specified
8972 path is a directory and will create the specified directory if
8973 the path does not exist; and PathVariable.PathAccept, which sim‐
8974 ply accepts the specific path name argument without validation,
8975 and which is suitable if you want your users to be able to spec‐
8976 ify a directory path that will be created as part of the build
8977 process, for example. You may supply your own validator func‐
8978 tion, which must take three arguments (key, the name of the
8979 variable to be set; val, the specified value being checked; and
8980 env, the construction environment) and should raise an exception
8981 if the specified value is not acceptable.
8982 These functions make it convenient to create a number of variables with
8984 consistent behavior in a single call to the AddVariables method:
8985 vars.AddVariables(
8987 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
8988 EnumVariable('debug', 'debug output and symbols', 'no'
8989 allowed_values=('yes', 'no', 'full'),
8990 map={}, ignorecase=0), # case sensitive
8991 ListVariable('shared',
8992 'libraries to build as shared libraries',
8993 'all',
8994 names = list_of_libs),
8995 PackageVariable('x11',
8996 'use X11 installed here (yes = search some places)',
8997 'yes'),
8998 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
8999 PathVariable('foopath', 'where the foo library is installed', foopath,
9000 PathVariable.PathIsDir),
9001 )
9003 File and Directory Nodes
9006 The File() and Dir() functions return File and Dir Nodes, respectively.
9007 python objects, respectively. Those objects have several user-visible
9008 attributes and methods that are often useful:
9009 path The build path of the given file or directory. This path is
9012 relative to the top-level directory (where the SConstruct file
9013 is found). The build path is the same as the source path if
9014 variant_dir is not being used.
9015 abspath
9018 The absolute build path of the given file or directory.
9019 srcnode()
9022 The srcnode() method returns another File or Dir object repre‐
9023 senting the source path of the given File or Dir. The
9024 # Get the current build dir's path, relative to top.
9026 Dir('.').path
9027 # Current dir's absolute path
9028 Dir('.').abspath
9029 # Next line is always '.', because it is the top dir's path relative to itself.
9030 Dir('#.').path
9031 File('foo.c').srcnode().path # source path of the given source file.
9032 # Builders also return File objects:
9034 foo = env.Program('foo.c')
9035 print "foo will be built in %s"%foo.path
9036 A Dir Node or File Node can also be used to create file and subdirec‐
9038 tory Nodes relative to the generating Node. A Dir Node will place the
9039 new Nodes within the directory it represents. A File node will place
9040 the new Nodes within its parent directory (that is, "beside" the file
9041 in question). If d is a Dir (directory) Node and f is a File (file)
9042 Node, then these methods are available:
9043 d.Dir(name)
9046 Returns a directory Node for a subdirectory of d named name.
9047 d.File(name)
9050 Returns a file Node for a file within d named name.
9051 d.Entry(name)
9054 Returns an unresolved Node within d named name.
9055 f.Dir(name)
9058 Returns a directory named name within the parent directory of f.
9059 f.File(name)
9062 Returns a file named name within the parent directory of f.
9063 f.Entry(name)
9066 Returns an unresolved Node named name within the parent direc‐
9067 tory of f.
9068 For example:
9070 # Get a Node for a file within a directory
9072 incl = Dir('include')
9073 f = incl.File('header.h')
9074 # Get a Node for a subdirectory within a directory
9076 dist = Dir('project-3.2.1)
9077 src = dist.Dir('src')
9078 # Get a Node for a file in the same directory
9080 cfile = File('sample.c')
9081 hfile = cfile.File('sample.h')
9082 # Combined example
9084 docs = Dir('docs')
9085 html = docs.Dir('html')
9086 index = html.File('index.html')
9087 css = index.File('app.css')
9088
9091 Builder Objects
9092 scons can be extended to build different types of targets by adding new
9093 Builder objects to a construction environment. In general, you should
9094 only need to add a new Builder object when you want to build a new type
9095 of file or other external target. If you just want to invoke a differ‐
9096 ent compiler or other tool to build a Program, Object, Library, or any
9097 other type of output file for which scons already has an existing
9098 Builder, it is generally much easier to use those existing Builders in
9099 a construction environment that sets the appropriate construction vari‐
9100 ables (CC, LINK, etc.).
9101 Builder objects are created using the Builder function. The Builder
9103 function accepts the following arguments:
9104 action The command line string used to build the target from the
9107 source. action can also be: a list of strings representing the
9108 command to be executed and its arguments (suitable for enclosing
9109 white space in an argument), a dictionary mapping source file
9110 name suffixes to any combination of command line strings (if the
9111 builder should accept multiple source file extensions), a Python
9112 function; an Action object (see the next section); or a list of
9113 any of the above.
9114 An action function takes three arguments: source - a list of
9116 source nodes, target - a list of target nodes, env - the con‐
9117 struction environment.
9118 prefix The prefix that will be prepended to the target file name. This
9121 may be specified as a:
9122 * string,
9125 * callable object - a function or other callable that takes
9128 two arguments (a construction environment and a list of
9129 sources) and returns a prefix,
9130 * dictionary - specifies a mapping from a specific source
9133 suffix (of the first source specified) to a correspond‐
9134 ing target prefix. Both the source suffix and target
9135 prefix specifications may use environment variable sub‐
9136 stitution, and the target prefix (the 'value' entries
9137 in the dictionary) may also be a callable object. The
9138 default target prefix may be indicated by a dictionary
9139 entry with a key value of None.
9140 b = Builder("build_it < $SOURCE > $TARGET",
9142 prefix = "file-")
9143 def gen_prefix(env, sources):
9145 return "file-" + env['PLATFORM'] + '-'
9146 b = Builder("build_it < $SOURCE > $TARGET",
9147 prefix = gen_prefix)
9148 b = Builder("build_it < $SOURCE > $TARGET",
9150 suffix = { None: "file-",
9151 "$SRC_SFX_A": gen_prefix })
9152 suffix The suffix that will be appended to the target file name. This
9155 may be specified in the same manner as the prefix above. If the
9156 suffix is a string, then scons will append a '.' to the begin‐
9157 ning of the suffix if it's not already there. The string
9158 returned by callable object (or obtained from the dictionary) is
9159 untouched and must append its own '.' to the beginning if one
9160 is desired.
9161 b = Builder("build_it < $SOURCE > $TARGET"
9163 suffix = "-file")
9164 def gen_suffix(env, sources):
9166 return "." + env['PLATFORM'] + "-file"
9167 b = Builder("build_it < $SOURCE > $TARGET",
9168 suffix = gen_suffix)
9169 b = Builder("build_it < $SOURCE > $TARGET",
9171 suffix = { None: ".sfx1",
9172 "$SRC_SFX_A": gen_suffix })
9173 ensure_suffix
9176 When set to any true value, causes scons to add the target suf‐
9177 fix specified by the suffix keyword to any target strings that
9178 have a different suffix. (The default behavior is to leave
9179 untouched any target file name that looks like it already has
9180 any suffix.)
9181 b1 = Builder("build_it < $SOURCE > $TARGET"
9183 suffix = ".out")
9184 b2 = Builder("build_it < $SOURCE > $TARGET"
9185 suffix = ".out",
9186 ensure_suffix)
9187 env = Environment()
9188 env['BUILDERS']['B1'] = b1
9189 env['BUILDERS']['B2'] = b2
9190 # Builds "foo.txt" because ensure_suffix is not set.
9192 env.B1('foo.txt', 'foo.in')
9193 # Builds "bar.txt.out" because ensure_suffix is set.
9195 env.B2('bar.txt', 'bar.in')
9196 src_suffix
9199 The expected source file name suffix. This may be a string or a
9200 list of strings.
9201 target_scanner
9204 A Scanner object that will be invoked to find implicit dependen‐
9205 cies for this target file. This keyword argument should be used
9206 for Scanner objects that find implicit dependencies based only
9207 on the target file and the construction environment, not for
9208 implicit dependencies based on source files. (See the section
9209 "Scanner Objects" below, for information about creating Scanner
9210 objects.)
9211 source_scanner
9214 A Scanner object that will be invoked to find implicit dependen‐
9215 cies in any source files used to build this target file. This
9216 is where you would specify a scanner to find things like
9217 #include lines in source files. The pre-built DirScanner Scan‐
9218 ner object may be used to indicate that this Builder should scan
9219 directory trees for on-disk changes to files that scons does not
9220 know about from other Builder or function calls. (See the sec‐
9221 tion "Scanner Objects" below, for information about creating
9222 your own Scanner objects.)
9223 target_factory
9226 A factory function that the Builder will use to turn any targets
9227 specified as strings into SCons Nodes. By default, SCons
9228 assumes that all targets are files. Other useful target_factory
9229 values include Dir, for when a Builder creates a directory tar‐
9230 get, and Entry, for when a Builder can create either a file or
9231 directory target.
9232 Example:
9234 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
9236 env = Environment()
9237 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
9238 env.MakeDirectory('new_directory', [])
9239 Note that the call to the MakeDirectory Builder needs to specify
9242 an empty source list to make the string represent the builder's
9243 target; without that, it would assume the argument is the
9244 source, and would try to deduce the target name from it, which
9245 in the absence of an automatically-added prefix or suffix would
9246 lead to a matching target and source name and a circular depen‐
9247 dency.
9248 source_factory
9251 A factory function that the Builder will use to turn any sources
9252 specified as strings into SCons Nodes. By default, SCons
9253 assumes that all source are files. Other useful source_factory
9254 values include Dir, for when a Builder uses a directory as a
9255 source, and Entry, for when a Builder can use files or directo‐
9256 ries (or both) as sources.
9257 Example:
9259 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
9261 env = Environment()
9262 env.Append(BUILDERS = {'Collect':CollectBuilder})
9263 env.Collect('archive', ['directory_name', 'file_name'])
9264 emitter
9267 A function or list of functions to manipulate the target and
9268 source lists before dependencies are established and the tar‐
9269 get(s) are actually built. emitter can also be a string con‐
9270 taining a construction variable to expand to an emitter function
9271 or list of functions, or a dictionary mapping source file suf‐
9272 fixes to emitter functions. (Only the suffix of the first
9273 source file is used to select the actual emitter function from
9274 an emitter dictionary.)
9275 An emitter function takes three arguments: source - a list of
9277 source nodes, target - a list of target nodes, env - the con‐
9278 struction environment. An emitter must return a tuple contain‐
9279 ing two lists, the list of targets to be built by this builder,
9280 and the list of sources for this builder.
9281 Example:
9283 def e(target, source, env):
9285 return (target + ['foo.foo'], source + ['foo.src'])
9286 # Simple association of an emitter function with a Builder.
9288 b = Builder("my_build < $TARGET > $SOURCE",
9289 emitter = e)
9290 def e2(target, source, env):
9292 return (target + ['bar.foo'], source + ['bar.src'])
9293 # Simple association of a list of emitter functions with a Builder.
9295 b = Builder("my_build < $TARGET > $SOURCE",
9296 emitter = [e, e2])
9297 # Calling an emitter function through a construction variable.
9299 env = Environment(MY_EMITTER = e)
9300 b = Builder("my_build < $TARGET > $SOURCE",
9301 emitter = '$MY_EMITTER')
9302 # Calling a list of emitter functions through a construction variable.
9304 env = Environment(EMITTER_LIST = [e, e2])
9305 b = Builder("my_build < $TARGET > $SOURCE",
9306 emitter = '$EMITTER_LIST')
9307 # Associating multiple emitters with different file
9309 # suffixes using a dictionary.
9310 def e_suf1(target, source, env):
9311 return (target + ['another_target_file'], source)
9312 def e_suf2(target, source, env):
9313 return (target, source + ['another_source_file'])
9314 b = Builder("my_build < $TARGET > $SOURCE",
9315 emitter = {'.suf1' : e_suf1,
9316 '.suf2' : e_suf2})
9317 multi Specifies whether this builder is allowed to be called multiple
9320 times for the same target file(s). The default is 0, which means
9321 the builder can not be called multiple times for the same target
9322 file(s). Calling a builder multiple times for the same target
9323 simply adds additional source files to the target; it is not
9324 allowed to change the environment associated with the target,
9325 specify addition environment overrides, or associate a different
9326 builder with the target.
9327 env A construction environment that can be used to fetch source code
9330 using this Builder. (Note that this environment is not used for
9331 normal builds of normal target files, which use the environment
9332 that was used to call the Builder for the target file.)
9333 generator
9336 A function that returns a list of actions that will be executed
9337 to build the target(s) from the source(s). The returned
9338 action(s) may be an Action object, or anything that can be con‐
9339 verted into an Action object (see the next section).
9340 The generator function takes four arguments: source - a list of
9342 source nodes, target - a list of target nodes, env - the con‐
9343 struction environment, for_signature - a Boolean value that
9344 specifies whether the generator is being called for generating a
9345 build signature (as opposed to actually executing the command).
9346 Example:
9347 def g(source, target, env, for_signature):
9349 return [["gcc", "-c", "-o"] + target + source]
9350 b = Builder(generator=g)
9352 The generator and action arguments must not both be used for the
9355 same Builder.
9356 src_builder
9359 Specifies a builder to use when a source file name suffix does
9360 not match any of the suffixes of the builder. Using this argu‐
9361 ment produces a multi-stage builder.
9362 single_source
9365 Specifies that this builder expects exactly one source file per
9366 call. Giving more than one source file without target files
9367 results in implicitely calling the builder multiple times (once
9368 for each source given). Giving multiple source files together
9369 with target files results in a UserError exception.
9370 The generator and action arguments must not both be used for the
9373 same Builder.
9374 source_ext_match
9377 When the specified action argument is a dictionary, the default
9378 behavior when a builder is passed multiple source files is to
9379 make sure that the extensions of all the source files match. If
9380 it is legal for this builder to be called with a list of source
9381 files with different extensions, this check can be suppressed by
9382 setting source_ext_match to None or some other non-true value.
9383 When source_ext_match is disable, scons will use the suffix of
9384 the first specified source file to select the appropriate action
9385 from the action dictionary.
9386 In the following example, the setting of source_ext_match pre‐
9388 vents scons from exiting with an error due to the mismatched
9389 suffixes of foo.in and foo.extra.
9390 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
9392 source_ext_match = None)
9393 env = Environment(BUILDERS = {'MyBuild':b})
9395 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
9396 env A construction environment that can be used to fetch source code
9399 using this Builder. (Note that this environment is not used for
9400 normal builds of normal target files, which use the environment
9401 that was used to call the Builder for the target file.)
9402 b = Builder(action="build < $SOURCE > $TARGET")
9404 env = Environment(BUILDERS = {'MyBuild' : b})
9405 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
9406 chdir A directory from which scons will execute the action(s) speci‐
9409 fied for this Builder. If the chdir argument is a string or a
9410 directory Node, scons will change to the specified directory.
9411 If the chdir is not a string or Node and is non-zero, then scons
9412 will change to the target file's directory.
9413 Note that scons will not automatically modify its expansion of
9415 construction variables like $TARGET and $SOURCE when using the
9416 chdir keyword argument--that is, the expanded file names will
9417 still be relative to the top-level SConstruct directory, and
9418 consequently incorrect relative to the chdir directory.
9419 Builders created using chdir keyword argument, will need to use
9420 construction variable expansions like ${TARGET.file} and
9421 ${SOURCE.file} to use just the filename portion of the targets
9422 and source.
9423 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
9425 chdir=1)
9426 env = Environment(BUILDERS = {'MyBuild' : b})
9427 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
9428 WARNING: Python only keeps one current directory location for all of
9430 the threads. This means that use of the chdir argument will not work
9431 with the SCons -j option, because individual worker threads spawned by
9432 SCons interfere with each other when they start changing directory.
9433 Any additional keyword arguments supplied when a Builder object is cre‐
9435 ated (that is, when the Builder() function is called) will be set in
9436 the executing construction environment when the Builder object is
9437 called. The canonical example here would be to set a construction
9438 variable to the repository of a source code system.
9439 Any additional keyword arguments supplied when a Builder object is
9441 called will only be associated with the target created by that particu‐
9442 lar Builder call (and any other files built as a result of the call).
9443 These extra keyword arguments are passed to the following functions:
9445 command generator functions, function Actions, and emitter functions.
9446 Action Objects
9449 The Builder() function will turn its action keyword argument into an
9450 appropriate internal Action object. You can also explicity create
9451 Action objects using the Action() global function, which can then be
9452 passed to the Builder() function. This can be used to configure an
9453 Action object more flexibly, or it may simply be more efficient than
9454 letting each separate Builder object create a separate Action when mul‐
9455 tiple Builder objects need to do the same thing.
9456 The Action() global function returns an appropriate object for the
9458 action represented by the type of the first argument:
9459 Action If the first argument is already an Action object, the object is
9462 simply returned.
9463 String If the first argument is a string, a command-line Action is
9466 returned. Note that the command-line string may be preceded by
9467 an @ (at-sign) to suppress printing of the specified command
9468 line, or by a - (hyphen) to ignore the exit status from the
9469 specified command:
9470 Action('$CC -c -o $TARGET $SOURCES')
9472 # Doesn't print the line being executed.
9474 Action('@build $TARGET $SOURCES')
9475 # Ignores return value
9477 Action('-build $TARGET $SOURCES')
9478 List If the first argument is a list, then a list of Action objects
9481 is returned. An Action object is created as necessary for each
9482 element in the list. If an element within the list is itself a
9483 list, the internal list is the command and arguments to be exe‐
9484 cuted via the command line. This allows white space to be
9485 enclosed in an argument by defining a command in a list within a
9486 list:
9487 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
9489 Function
9492 If the first argument is a Python function, a function Action is
9493 returned. The Python function must take three keyword argu‐
9494 ments, target (a Node object representing the target file),
9495 source (a Node object representing the source file) and env (the
9496 construction environment used for building the target file).
9497 The target and source arguments may be lists of Node objects if
9498 there is more than one target file or source file. The actual
9499 target and source file name(s) may be retrieved from their Node
9500 objects via the built-in Python str() function:
9501 target_file_name = str(target)
9503 source_file_names = map(lambda x: str(x), source)
9504 The function should return 0 or None to indicate a successful
9506 build of the target file(s). The function may raise an excep‐
9507 tion or return a non-zero exit status to indicate an unsuccess‐
9508 ful build.
9509 def build_it(target = None, source = None, env = None):
9511 # build the target from the source
9512 return 0
9513 a = Action(build_it)
9515 If the action argument is not one of the above, None is returned.
9517 The second argument is optional and is used to define the output which
9519 is printed when the Action is actually performed. In the absence of
9520 this parameter, or if it's an empty string, a default output depending
9521 on the type of the action is used. For example, a command-line action
9522 will print the executed command. The argument must be either a Python
9523 function or a string.
9524 In the first case, it's a function that returns a string to be printed
9526 to describe the action being executed. The function may also be speci‐
9527 fied by the strfunction= keyword argument. Like a function to build a
9528 file, this function must take three keyword arguments: target (a Node
9529 object representing the target file), source (a Node object represent‐
9530 ing the source file) and env (a construction environment). The target
9531 and source arguments may be lists of Node objects if there is more than
9532 one target file or source file.
9533 In the second case, you provide the string itself. The string may also
9535 be specified by the cmdstr= keyword argument. The string typically
9536 contains variables, notably $TARGET(S) and $SOURCE(S), or consists of
9537 just a single variable, which is optionally defined somewhere else.
9538 SCons itself heavily uses the latter variant.
9539 Examples:
9541 def build_it(target, source, env):
9543 # build the target from the source
9544 return 0
9545 def string_it(target, source, env):
9547 return "building '%s' from '%s'" % (target[0], source[0])
9548 # Use a positional argument.
9550 f = Action(build_it, string_it)
9551 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
9552 # Alternatively, use a keyword argument.
9554 f = Action(build_it, strfunction=string_it)
9555 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
9556 # You can provide a configurable variable.
9558 l = Action(build_it, '$STRINGIT')
9559 The third and succeeding arguments, if present, may either be a con‐
9561 struction variable or a list of construction variables whose values
9562 will be included in the signature of the Action when deciding whether a
9563 target should be rebuilt because the action changed. The variables may
9564 also be specified by a varlist= keyword parameter; if both are present,
9565 they are combined. This is necessary whenever you want a target to be
9566 rebuilt when a specific construction variable changes. This is not
9567 often needed for a string action, as the expanded variables will nor‐
9568 mally be part of the command line, but may be needed if a Python func‐
9569 tion action uses the value of a construction variable when generating
9570 the command line.
9571 def build_it(target, source, env):
9573 # build the target from the 'XXX' construction variable
9574 open(target[0], 'w').write(env['XXX'])
9575 return 0
9576 # Use positional arguments.
9578 a = Action(build_it, '$STRINGIT', ['XXX'])
9579 # Alternatively, use a keyword argument.
9581 a = Action(build_it, varlist=['XXX'])
9582 The Action() global function can be passed the following optional key‐
9584 word arguments to modify the Action object's behavior:
9585 chdir The chdir keyword argument specifies that scons will exe‐
9588 cute the action after changing to the specified directory. If
9589 the chdir argument is a string or a directory Node, scons will
9590 change to the specified directory. If the chdir argument is not
9591 a string or Node and is non-zero, then scons will change to the
9592 target file's directory.
9593 Note that scons will not automatically modify its expansion of
9595 construction variables like $TARGET and $SOURCE when using the
9596 chdir keyword argument--that is, the expanded file names will
9597 still be relative to the top-level SConstruct directory, and
9598 consequently incorrect relative to the chdir directory.
9599 Builders created using chdir keyword argument, will need to use
9600 construction variable expansions like ${TARGET.file} and
9601 ${SOURCE.file} to use just the filename portion of the targets
9602 and source.
9603 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9605 chdir=1)
9606 exitstatfunc The Action() global function also takes an exit‐
9609 statfunc keyword argument which specifies a function that is
9610 passed the exit status (or return value) from the specified
9611 action and can return an arbitrary or modified value. This can
9612 be used, for example, to specify that an Action object's return
9613 value should be ignored under special conditions and SCons
9614 should, therefore, consider that the action always suceeds:
9615 def always_succeed(s):
9617 # Always return 0, which indicates success.
9618 return 0
9619 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
9620 exitstatfunc=always_succeed)
9621 batch_key The batch_key keyword argument can be used to specify
9624 that the Action can create multiple target files by processing
9625 multiple independent source files simultaneously. (The canoni‐
9626 cal example is "batch compilation" of multiple object files by
9627 passing multiple source files to a single invocation of a com‐
9628 piler such as Microsoft's Visual C / C++ compiler.) If the
9629 batch_key argument is any non-False, non-callable Python value,
9630 the configured Action object will cause scons to collect all
9631 targets built with the Action object and configured with the
9632 same construction environment into single invocations of the
9633 Action object's command line or function. Command lines will
9634 typically want to use the CHANGED_SOURCES construction variable
9635 (and possibly CHANGED_TARGETS as well) to only pass to the com‐
9636 mand line those sources that have actually changed since their
9637 targets were built.
9638 Example:
9640 a = Action('build $CHANGED_SOURCES', batch_key=True)
9642 The batch_key argument may also be a callable function that returns a
9644 key that will be used to identify different "batches" of target files
9645 to be collected for batch building. A batch_key function must take the
9646 following arguments:
9647 action The action object.
9650 env The construction environment configured for the target.
9653 target The list of targets for a particular configured action.
9656 source The list of source for a particular configured action.
9659 The returned key should typically be a tuple of values derived
9661 from the arguments, using any appropriate logic to decide how
9662 multiple invocations should be batched. For example, a
9663 batch_key function may decide to return the value of a specific
9664 construction variable from the env argument which will cause
9665 scons to batch-build targets with matching values of that vari‐
9666 able, or perhaps return the id() of the entire construction
9667 environment, in which case scons will batch-build all targets
9668 configured with the same construction environment. Returning
9669 None indicates that the particular target should not be part of
9670 any batched build, but instead will be built by a separate invo‐
9671 cation of action's command or function. Example:
9672 def batch_key(action, env, target, source):
9674 tdir = target[0].dir
9675 if tdir.name == 'special':
9676 # Don't batch-build any target
9677 # in the special/ subdirectory.
9678 return None
9679 return (id(action), id(env), tdir)
9680 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
9681 Miscellaneous Action Functions
9684 scons supplies a number of functions that arrange for various common
9685 file and directory manipulations to be performed. These are similar in
9686 concept to "tasks" in the Ant build tool, although the implementation
9687 is slightly different. These functions do not actually perform the
9688 specified action at the time the function is called, but instead return
9689 an Action object that can be executed at the appropriate time. (In
9690 Object-Oriented terminology, these are actually Action Factory func‐
9691 tions that return Action objects.)
9692 In practice, there are two natural ways that these Action Functions are
9694 intended to be used.
9695 First, if you need to perform the action at the time the SConscript
9697 file is being read, you can use the Execute global function to do so:
9698 Execute(Touch('file'))
9699 Second, you can use these functions to supply Actions in a list for use
9701 by the Command method. This can allow you to perform more complicated
9702 sequences of file manipulation without relying on platform-specific
9703 external commands: that
9704 env = Environment(TMPBUILD = '/tmp/builddir')
9705 env.Command('foo.out', 'foo.in',
9706 [Mkdir('$TMPBUILD'),
9707 Copy('$TMPBUILD', '${SOURCE.dir}'),
9708 "cd $TMPBUILD && make",
9709 Delete('$TMPBUILD')])
9710 Chmod(dest, mode)
9713 Returns an Action object that changes the permissions on the
9714 specified dest file or directory to the specified mode. Exam‐
9715 ples:
9716 Execute(Chmod('file', 0755))
9718 env.Command('foo.out', 'foo.in',
9720 [Copy('$TARGET', '$SOURCE'),
9721 Chmod('$TARGET', 0755)])
9722 Copy(dest, src)
9725 Returns an Action object that will copy the src source file or
9726 directory to the dest destination file or directory. Examples:
9727 Execute(Copy('foo.output', 'foo.input'))
9729 env.Command('bar.out', 'bar.in',
9731 Copy('$TARGET', '$SOURCE'))
9732 Delete(entry, [must_exist])
9735 Returns an Action that deletes the specified entry, which may be
9736 a file or a directory tree. If a directory is specified, the
9737 entire directory tree will be removed. If the must_exist flag
9738 is set, then a Python error will be thrown if the specified
9739 entry does not exist; the default is must_exist=0, that is, the
9740 Action will silently do nothing if the entry does not exist.
9741 Examples:
9742 Execute(Delete('/tmp/buildroot'))
9744 env.Command('foo.out', 'foo.in',
9746 [Delete('${TARGET.dir}'),
9747 MyBuildAction])
9748 Execute(Delete('file_that_must_exist', must_exist=1))
9750 Mkdir(dir)
9753 Returns an Action that creates the specified directory dir .
9754 Examples:
9755 Execute(Mkdir('/tmp/outputdir'))
9757 env.Command('foo.out', 'foo.in',
9759 [Mkdir('/tmp/builddir'),
9760 Copy('/tmp/builddir/foo.in', '$SOURCE'),
9761 "cd /tmp/builddir && make",
9762 Copy('$TARGET', '/tmp/builddir/foo.out')])
9763 Move(dest, src)
9766 Returns an Action that moves the specified src file or directory
9767 to the specified dest file or directory. Examples:
9768 Execute(Move('file.destination', 'file.source'))
9770 env.Command('output_file', 'input_file',
9772 [MyBuildAction,
9773 Move('$TARGET', 'file_created_by_MyBuildAction')])
9774 Touch(file)
9777 Returns an Action that updates the modification time on the
9778 specified file. Examples:
9779 Execute(Touch('file_to_be_touched'))
9781 env.Command('marker', 'input_file',
9783 [MyBuildAction,
9784 Touch('$TARGET')])
9785 Variable Substitution
9788 Before executing a command, scons performs construction variable inter‐
9789 polation on the strings that make up the command line of builders.
9790 Variables are introduced by a $ prefix. Besides construction vari‐
9791 ables, scons provides the following variables for each command execu‐
9792 tion:
9793 CHANGED_SOURCES
9796 The file names of all sources of the build command that have
9797 changed since the target was last built.
9798 CHANGED_TARGETS
9801 The file names of all targets that would be built from sources
9802 that have changed since the target was last built.
9803 SOURCE The file name of the source of the build command, or the file
9806 name of the first source if multiple sources are being built.
9807 SOURCES
9810 The file names of the sources of the build command.
9811 TARGET The file name of the target being built, or the file name of the
9814 first target if multiple targets are being built.
9815 TARGETS
9818 The file names of all targets being built.
9819 UNCHANGED_SOURCES
9822 The file names of all sources of the build command that have not
9823 changed since the target was last built.
9824 UNCHANGED_TARGETS
9827 The file names of all targets that would be built from sources
9828 that have not changed since the target was last built.
9829 (Note that the above variables are reserved and may not be set
9831 in a construction environment.)
9832 For example, given the construction variable CC='cc', targets=['foo'],
9835 and sources=['foo.c', 'bar.c']:
9836 action='$CC -c -o $TARGET $SOURCES'
9838 would produce the command line:
9840 cc -c -o foo foo.c bar.c
9842 Variable names may be surrounded by curly braces ({}) to separate the
9844 name from the trailing characters. Within the curly braces, a variable
9845 name may have a Python slice subscript appended to select one or more
9846 items from a list. In the previous example, the string:
9847 ${SOURCES[1]}
9849 would produce:
9851 bar.c
9853 Additionally, a variable name may have the following special modifiers
9855 appended within the enclosing curly braces to modify the interpolated
9856 string:
9857 base The base path of the file name, including the directory path but
9860 excluding any suffix.
9861 dir The name of the directory in which the file exists.
9864 file The file name, minus any directory portion.
9867 filebase
9870 Just the basename of the file, minus any suffix and minus the
9871 directory.
9872 suffix Just the file suffix.
9875 abspath
9878 The absolute path name of the file.
9879 posix The POSIX form of the path, with directories separated by /
9882 (forward slashes) not backslashes. This is sometimes necessary
9883 on Windows systems when a path references a file on other
9884 (POSIX) systems.
9885 srcpath
9888 The directory and file name to the source file linked to this
9889 file through VariantDir(). If this file isn't linked, it just
9890 returns the directory and filename unchanged.
9891 srcdir The directory containing the source file linked to this file
9894 through VariantDir(). If this file isn't linked, it just
9895 returns the directory part of the filename.
9896 rsrcpath
9899 The directory and file name to the source file linked to this
9900 file through VariantDir(). If the file does not exist locally
9901 but exists in a Repository, the path in the Repository is
9902 returned. If this file isn't linked, it just returns the direc‐
9903 tory and filename unchanged.
9904 rsrcdir
9907 The Repository directory containing the source file linked to
9908 this file through VariantDir(). If this file isn't linked, it
9909 just returns the directory part of the filename.
9910 For example, the specified target will expand as follows for the corre‐
9913 sponding modifiers:
9914 $TARGET => sub/dir/file.x
9916 ${TARGET.base} => sub/dir/file
9917 ${TARGET.dir} => sub/dir
9918 ${TARGET.file} => file.x
9919 ${TARGET.filebase} => file
9920 ${TARGET.suffix} => .x
9921 ${TARGET.abspath} => /top/dir/sub/dir/file.x
9922 SConscript('src/SConscript', variant_dir='sub/dir')
9924 $SOURCE => sub/dir/file.x
9925 ${SOURCE.srcpath} => src/file.x
9926 ${SOURCE.srcdir} => src
9927 Repository('/usr/repository')
9929 $SOURCE => sub/dir/file.x
9930 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
9931 ${SOURCE.rsrcdir} => /usr/repository/src
9932 Note that curly braces braces may also be used to enclose arbitrary
9934 Python code to be evaluated. (In fact, this is how the above modifiers
9935 are substituted, they are simply attributes of the Python objects that
9936 represent TARGET, SOURCES, etc.) See the section "Python Code Substi‐
9937 tution" below, for more thorough examples of how this can be used.
9938 Lastly, a variable name may be a callable Python function associated
9940 with a construction variable in the environment. The function should
9941 take four arguments: target - a list of target nodes, source - a list
9942 of source nodes, env - the construction environment, for_signature - a
9943 Boolean value that specifies whether the function is being called for
9944 generating a build signature. SCons will insert whatever the called
9945 function returns into the expanded string:
9946 def foo(target, source, env, for_signature):
9948 return "bar"
9949 # Will expand $BAR to "bar baz"
9951 env=Environment(FOO=foo, BAR="$FOO baz")
9952 You can use this feature to pass arguments to a Python function by cre‐
9954 ating a callable class that stores one or more arguments in an object,
9955 and then uses them when the __call__() method is called. Note that in
9956 this case, the entire variable expansion must be enclosed by curly
9957 braces so that the arguments will be associated with the instantiation
9958 of the class:
9959 class foo(object):
9961 def __init__(self, arg):
9962 self.arg = arg
9963 def __call__(self, target, source, env, for_signature):
9965 return self.arg + " bar"
9966 # Will expand $BAR to "my argument bar baz"
9968 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
9969 The special pseudo-variables $( and $) may be used to surround parts of
9972 a command line that may change without causing a rebuild--that is,
9973 which are not included in the signature of target files built with this
9974 command. All text between $( and $) will be removed from the command
9975 line before it is added to file signatures, and the $( and $) will be
9976 removed before the command is executed. For example, the command line:
9977 echo Last build occurred $( $TODAY $). > $TARGET
9979 would execute the command:
9982 echo Last build occurred $TODAY. > $TARGET
9984 but the command signature added to any target files would be:
9987 echo Last build occurred . > $TARGET
9989 Python Code Substitution
9992 Any python code within ${-} pairs gets evaluated by python 'eval', with
9993 the python globals set to the current environment's set of construction
9994 variables. So in the following case:
9995 env['COND'] = 0
9996 env.Command('foo.out', 'foo.in',
9997 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
9998 the command executed will be either
9999 echo FOO > foo.out
10000 or
10001 echo BAR > foo.out
10002 according to the current value of env['COND'] when the command is exe‐
10003 cuted. The evaluation occurs when the target is being built, not when
10004 the SConscript is being read. So if env['COND'] is changed later in
10005 the SConscript, the final value will be used.
10006 Here's a more interesting example. Note that all of COND, FOO, and BAR
10008 are environment variables, and their values are substituted into the
10009 final command. FOO is a list, so its elements are interpolated sepa‐
10010 rated by spaces.
10011 env=Environment()
10013 env['COND'] = 0
10014 env['FOO'] = ['foo1', 'foo2']
10015 env['BAR'] = 'barbar'
10016 env.Command('foo.out', 'foo.in',
10017 'echo ${COND==1 and FOO or BAR} > $TARGET')
10018 # Will execute this:
10020 # echo foo1 foo2 > foo.out
10021 SCons uses the following rules when converting construction variables
10023 into command lines:
10024 String When the value is a string it is interpreted as a space delim‐
10027 ited list of command line arguments.
10028 List When the value is a list it is interpreted as a list of command
10031 line arguments. Each element of the list is converted to a
10032 string.
10033 Other Anything that is not a list or string is converted to a string
10036 and interpreted as a single command line argument.
10037 Newline
10040 Newline characters (\n) delimit lines. The newline parsing is
10041 done after all other parsing, so it is not possible for argu‐
10042 ments (e.g. file names) to contain embedded newline characters.
10043 This limitation will likely go away in a future version of
10044 SCons.
10045 Scanner Objects
10048 You can use the Scanner function to define objects to scan new file
10049 types for implicit dependencies. The Scanner function accepts the fol‐
10050 lowing arguments:
10051 function
10054 This can be either: 1) a Python function that will process the
10055 Node (file) and return a list of File Nodes representing the
10056 implicit dependencies (file names) found in the contents; or: 2)
10057 a dictionary that maps keys (typically the file suffix, but see
10058 below for more discussion) to other Scanners that should be
10059 called.
10060 If the argument is actually a Python function, the function must
10062 take three or four arguments:
10063 def scanner_function(node, env, path):
10065 def scanner_function(node, env, path, arg=None):
10067 The node argument is the internal SCons node representing the
10069 file. Use str(node) to fetch the name of the file, and
10070 node.get_contents() to fetch contents of the file. Note that
10071 the file is not guaranteed to exist before the scanner is
10072 called, so the scanner function should check that if there's any
10073 chance that the scanned file might not exist (for example, if
10074 it's built from other files).
10075 The env argument is the construction environment for the scan.
10077 Fetch values from it using the env.Dictionary() method.
10078 The path argument is a tuple (or list) of directories that can
10080 be searched for files. This will usually be the tuple returned
10081 by the path_function argument (see below).
10082 The arg argument is the argument supplied when the scanner was
10084 created, if any.
10085 name The name of the Scanner. This is mainly used to identify the
10088 Scanner internally.
10089 argument
10092 An optional argument that, if specified, will be passed to the
10093 scanner function (described above) and the path function (speci‐
10094 fied below).
10095 skeys An optional list that can be used to determine which scanner
10098 should be used for a given Node. In the usual case of scanning
10099 for file names, this argument will be a list of suffixes for the
10100 different file types that this Scanner knows how to scan. If
10101 the argument is a string, then it will be expanded into a list
10102 by the current environment.
10103 path_function
10106 A Python function that takes four or five arguments: a construc‐
10107 tion environment, a Node for the directory containing the SCon‐
10108 script file in which the first target was defined, a list of
10109 target nodes, a list of source nodes, and an optional argument
10110 supplied when the scanner was created. The path_function
10111 returns a tuple of directories that can be searched for files to
10112 be returned by this Scanner object. (Note that the Find‐
10113 PathDirs() function can be used to return a ready-made
10114 path_function for a given construction variable name, instead of
10115 having to write your own function from scratch.)
10116 node_class
10119 The class of Node that should be returned by this Scanner
10120 object. Any strings or other objects returned by the scanner
10121 function that are not of this class will be run through the
10122 node_factory function.
10123 node_factory
10126 A Python function that will take a string or other object and
10127 turn it into the appropriate class of Node to be returned by
10128 this Scanner object.
10129 scan_check
10132 An optional Python function that takes two arguments, a Node
10133 (file) and a construction environment, and returns whether the
10134 Node should, in fact, be scanned for dependencies. This check
10135 can be used to eliminate unnecessary calls to the scanner func‐
10136 tion when, for example, the underlying file represented by a
10137 Node does not yet exist.
10138 recursive
10141 An optional flag that specifies whether this scanner should be
10142 re-invoked on the dependency files returned by the scanner.
10143 When this flag is not set, the Node subsystem will only invoke
10144 the scanner on the file being scanned, and not (for example)
10145 also on the files specified by the #include lines in the file
10146 being scanned. recursive may be a callable function, in which
10147 case it will be called with a list of Nodes found and should
10148 return a list of Nodes that should be scanned recursively; this
10149 can be used to select a specific subset of Nodes for additional
10150 scanning.
10151 Note that scons has a global SourceFileScanner object that is used by
10153 the Object(), SharedObject(), and StaticObject() builders to decide
10154 which scanner should be used for different file extensions. You can
10155 using the SourceFileScanner.add_scanner() method to add your own Scan‐
10156 ner object to the scons infrastructure that builds target programs or
10157 libraries from a list of source files of different types:
10158 def xyz_scan(node, env, path):
10160 contents = node.get_text_contents()
10161 # Scan the contents and return the included files.
10162 XYZScanner = Scanner(xyz_scan)
10164 SourceFileScanner.add_scanner('.xyz', XYZScanner)
10166 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
10168
10171 SCons and its configuration files are very portable, due largely to its
10172 implementation in Python. There are, however, a few portability issues
10173 waiting to trap the unwary.
10174 .C file suffix
10176 SCons handles the upper-case .C file suffix differently, depending on
10177 the capabilities of the underlying system. On a case-sensitive system
10178 such as Linux or UNIX, SCons treats a file with a .C suffix as a C++
10179 source file. On a case-insensitive system such as Windows, SCons
10180 treats a file with a .C suffix as a C source file.
10181 .F file suffix
10183 SCons handles the upper-case .F file suffix differently, depending on
10184 the capabilities of the underlying system. On a case-sensitive system
10185 such as Linux or UNIX, SCons treats a file with a .F suffix as a For‐
10186 tran source file that is to be first run through the standard C pre‐
10187 processor. On a case-insensitive system such as Windows, SCons treats
10188 a file with a .F suffix as a Fortran source file that should not be run
10189 through the C preprocessor.
10190 Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
10192 Cygwin supplies a set of tools and utilities that let users work on a
10193 Windows system using a more POSIX-like environment. The Cygwin tools,
10194 including Cygwin Python, do this, in part, by sharing an ability to
10195 interpret UNIX-like path names. For example, the Cygwin tools will
10196 internally translate a Cygwin path name like /cygdrive/c/mydir to an
10197 equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
10198 Versions of Python that are built for native Windows execution, such as
10200 the python.org and ActiveState versions, do not have the Cygwin path
10201 name semantics. This means that using a native Windows version of
10202 Python to build compiled programs using Cygwin tools (such as gcc,
10203 bison, and flex) may yield unpredictable results. "Mixing and match‐
10204 ing" in this way can be made to work, but it requires careful attention
10205 to the use of path names in your SConscript files.
10206 In practice, users can sidestep the issue by adopting the following
10208 rules: When using gcc, use the Cygwin-supplied Python interpreter to
10209 run SCons; when using Microsoft Visual C/C++ (or some other Windows
10210 compiler) use the python.org or ActiveState version of Python to run
10211 SCons.
10212 Windows: scons.bat file
10214 On Windows systems, SCons is executed via a wrapper scons.bat file.
10215 This has (at least) two ramifications:
10216 First, Windows command-line users that want to use variable assignment
10218 on the command line may have to put double quotes around the assign‐
10219 ments:
10220 scons "FOO=BAR" "BAZ=BLEH"
10222 Second, the Cygwin shell does not recognize this file as being the same
10224 as an scons command issued at the command-line prompt. You can work
10225 around this either by executing scons.bat from the Cygwin command line,
10226 or by creating a wrapper shell script named scons .
10227 MinGW
10230 The MinGW bin directory must be in your PATH environment variable or
10231 the PATH variable under the ENV construction variable for SCons to
10232 detect and use the MinGW tools. When running under the native Windows
10233 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
10234 tools, if they are both installed, regardless of the order of the bin
10235 directories in the PATH variable. If you have both MSVC and MinGW
10236 installed and you want to use MinGW instead of MSVC, then you must
10237 explictly tell SCons to use MinGW by passing
10238 tools=['mingw']
10240 to the Environment() function, because SCons will prefer the MSVC tools
10242 over the MinGW tools.
10243
10246 To help you get started using SCons, this section contains a brief
10247 overview of some common tasks.
10248 Basic Compilation From a Single Source File
10251 env = Environment()
10252 env.Program(target = 'foo', source = 'foo.c')
10253 Note: Build the file by specifying the target as an argument ("scons
10255 foo" or "scons foo.exe"). or by specifying a dot ("scons .").
10256 Basic Compilation From Multiple Source Files
10259 env = Environment()
10260 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
10261 Setting a Compilation Flag
10264 env = Environment(CCFLAGS = '-g')
10265 env.Program(target = 'foo', source = 'foo.c')
10266 Search The Local Directory For .h Files
10269 Note: You do not need to set CCFLAGS to specify -I options by hand.
10270 SCons will construct the right -I options from CPPPATH.
10271 env = Environment(CPPPATH = ['.'])
10273 env.Program(target = 'foo', source = 'foo.c')
10274 Search Multiple Directories For .h Files
10277 env = Environment(CPPPATH = ['include1', 'include2'])
10278 env.Program(target = 'foo', source = 'foo.c')
10279 Building a Static Library
10282 env = Environment()
10283 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
10284 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
10285 Building a Shared Library
10288 env = Environment()
10289 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
10290 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
10291 Linking a Local Library Into a Program
10294 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
10295 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
10296 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
10297 Defining Your Own Builder Object
10300 Notice that when you invoke the Builder, you can leave off the target
10301 file suffix, and SCons will add it automatically.
10302 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10304 suffix = '.pdf',
10305 src_suffix = '.tex')
10306 env = Environment(BUILDERS = {'PDFBuilder' : bld})
10307 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10308 # The following creates "bar.pdf" from "bar.tex"
10310 env.PDFBuilder(target = 'bar', source = 'bar')
10311 Note also that the above initialization overwrites the default Builder
10313 objects, so the Environment created above can not be used call Builders
10314 like env.Program(), env.Object(), env.StaticLibrary(), etc.
10315 Adding Your Own Builder Object to an Environment
10318 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
10319 suffix = '.pdf',
10320 src_suffix = '.tex')
10321 env = Environment()
10322 env.Append(BUILDERS = {'PDFBuilder' : bld})
10323 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
10324 env.Program(target = 'bar', source = 'bar.c')
10325 You also can use other Pythonic techniques to add to the BUILDERS con‐
10327 struction variable, such as:
10328 env = Environment()
10330 env['BUILDERS]['PDFBuilder'] = bld
10331 Defining Your Own Scanner Object
10334 The following example shows an extremely simple scanner (the
10335 kfile_scan() function) that doesn't use a search path at all and simply
10336 returns the file names present on any include lines in the scanned
10337 file. This would implicitly assume that all included files live in the
10338 top-level directory:
10339 import re
10341 include_re = re.compile(r'^include\s+(\S+)$', re.M)
10343 def kfile_scan(node, env, path, arg):
10345 contents = node.get_text_contents()
10346 includes = include_re.findall(contents)
10347 return env.File(includes)
10348 kscan = Scanner(name = 'kfile',
10350 function = kfile_scan,
10351 argument = None,
10352 skeys = ['.k'])
10353 scanners = Environment().Dictionary('SCANNERS')
10354 env = Environment(SCANNERS = scanners + [kscan])
10355 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
10357 bar_in = File('bar.in')
10359 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
10360 bar_in.target_scanner = kscan
10361 It is important to note that you have to return a list of File nodes
10363 from the scan function, simple strings for the file names won't do. As
10364 in the examples we are showing here, you can use the File() function of
10365 your current Environment in order to create nodes on the fly from a
10366 sequence of file names with relative paths.
10367 Here is a similar but more complete example that searches a path of
10369 directories (specified as the MYPATH construction variable) for files
10370 that actually exist:
10371 import re
10373 import os
10374 include_re = re.compile(r'^include\s+(\S+)$', re.M)
10375 def my_scan(node, env, path, arg):
10377 contents = node.get_text_contents()
10378 includes = include_re.findall(contents)
10379 if includes == []:
10380 return []
10381 results = []
10382 for inc in includes:
10383 for dir in path:
10384 file = str(dir) + os.sep + inc
10385 if os.path.exists(file):
10386 results.append(file)
10387 break
10388 return env.File(results)
10389 scanner = Scanner(name = 'myscanner',
10391 function = my_scan,
10392 argument = None,
10393 skeys = ['.x'],
10394 path_function = FindPathDirs('MYPATH')
10395 )
10396 scanners = Environment().Dictionary('SCANNERS')
10397 env = Environment(SCANNERS = scanners + [scanner],
10398 MYPATH = ['incs'])
10399 env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
10401 The FindPathDirs() function used in the previous example returns a
10403 function (actually a callable Python object) that will return a list of
10404 directories specified in the $MYPATH construction variable. It lets
10405 SCons detect the file incs/foo.inc , even if foo.x contains the line
10406 include foo.inc only. If you need to customize how the search path is
10407 derived, you would provide your own path_function argument when creat‐
10408 ing the Scanner object, as follows:
10409 # MYPATH is a list of directories to search for files in
10411 def pf(env, dir, target, source, arg):
10412 top_dir = Dir('#').abspath
10413 results = []
10414 if 'MYPATH' in env:
10415 for p in env['MYPATH']:
10416 results.append(top_dir + os.sep + p)
10417 return results
10418 scanner = Scanner(name = 'myscanner',
10420 function = my_scan,
10421 argument = None,
10422 skeys = ['.x'],
10423 path_function = pf
10424 )
10425 Creating a Hierarchical Build
10428 Notice that the file names specified in a subdirectory's SConscript
10429 file are relative to that subdirectory.
10430 SConstruct:
10432 env = Environment()
10434 env.Program(target = 'foo', source = 'foo.c')
10435 SConscript('sub/SConscript')
10437 sub/SConscript:
10439 env = Environment()
10441 # Builds sub/foo from sub/foo.c
10442 env.Program(target = 'foo', source = 'foo.c')
10443 SConscript('dir/SConscript')
10445 sub/dir/SConscript:
10447 env = Environment()
10449 # Builds sub/dir/foo from sub/dir/foo.c
10450 env.Program(target = 'foo', source = 'foo.c')
10451 Sharing Variables Between SConscript Files
10454 You must explicitly Export() and Import() variables that you want to
10455 share between SConscript files.
10456 SConstruct:
10458 env = Environment()
10460 env.Program(target = 'foo', source = 'foo.c')
10461 Export("env")
10463 SConscript('subdirectory/SConscript')
10464 subdirectory/SConscript:
10466 Import("env")
10468 env.Program(target = 'foo', source = 'foo.c')
10469 Building Multiple Variants From the Same Source
10472 Use the variant_dir keyword argument to the SConscript function to
10473 establish one or more separate variant build directory trees for a
10474 given source directory:
10475 SConstruct:
10477 cppdefines = ['FOO']
10479 Export("cppdefines")
10480 SConscript('src/SConscript', variant_dir='foo')
10481 cppdefines = ['BAR']
10483 Export("cppdefines")
10484 SConscript('src/SConscript', variant_dir='bar')
10485 src/SConscript:
10487 Import("cppdefines")
10489 env = Environment(CPPDEFINES = cppdefines)
10490 env.Program(target = 'src', source = 'src.c')
10491 Note the use of the Export() method to set the "cppdefines" variable to
10493 a different value each time we call the SConscript function.
10494 Hierarchical Build of Two Libraries Linked With a Program
10497 SConstruct:
10498 env = Environment(LIBPATH = ['#libA', '#libB'])
10500 Export('env')
10501 SConscript('libA/SConscript')
10502 SConscript('libB/SConscript')
10503 SConscript('Main/SConscript')
10504 libA/SConscript:
10506 Import('env')
10508 env.Library('a', Split('a1.c a2.c a3.c'))
10509 libB/SConscript:
10511 Import('env')
10513 env.Library('b', Split('b1.c b2.c b3.c'))
10514 Main/SConscript:
10516 Import('env')
10518 e = env.Copy(LIBS = ['a', 'b'])
10519 e.Program('foo', Split('m1.c m2.c m3.c'))
10520 The '#' in the LIBPATH directories specify that they're relative to the
10522 top-level directory, so they don't turn into "Main/libA" when they're
10523 used in Main/SConscript.
10524 Specifying only 'a' and 'b' for the library names allows SCons to
10526 append the appropriate library prefix and suffix for the current plat‐
10527 form (for example, 'liba.a' on POSIX systems, 'a.lib' on Windows).
10528 Customizing construction variables from the command line.
10531 The following would allow the C compiler to be specified on the command
10532 line or in the file custom.py.
10533 vars = Variables('custom.py')
10535 vars.Add('CC', 'The C compiler.')
10536 env = Environment(variables=vars)
10537 Help(vars.GenerateHelpText(env))
10538 The user could specify the C compiler on the command line:
10540 scons "CC=my_cc"
10542 or in the custom.py file:
10544 CC = 'my_cc'
10546 or get documentation on the options:
10548 $ scons -h
10550 CC: The C compiler.
10552 default: None
10553 actual: cc
10554 Using Microsoft Visual C++ precompiled headers
10558 Since windows.h includes everything and the kitchen sink, it can take
10559 quite some time to compile it over and over again for a bunch of object
10560 files, so Microsoft provides a mechanism to compile a set of headers
10561 once and then include the previously compiled headers in any object
10562 file. This technology is called precompiled headers. The general recipe
10563 is to create a file named "StdAfx.cpp" that includes a single header
10564 named "StdAfx.h", and then include every header you want to precompile
10565 in "StdAfx.h", and finally include "StdAfx.h" as the first header in
10566 all the source files you are compiling to object files. For example:
10567 StdAfx.h:
10569 #include <windows.h>
10570 #include <my_big_header.h>
10571 StdAfx.cpp:
10573 #include <StdAfx.h>
10574 Foo.cpp:
10576 #include <StdAfx.h>
10577 /* do some stuff */
10579 Bar.cpp:
10581 #include <StdAfx.h>
10582 /* do some other stuff */
10584 SConstruct:
10586 env=Environment()
10587 env['PCHSTOP'] = 'StdAfx.h'
10588 env['PCH'] = env.PCH('StdAfx.cpp')[0]
10589 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10590 For more information see the document for the PCH builder, and the PCH
10592 and PCHSTOP construction variables. To learn about the details of pre‐
10593 compiled headers consult the MSDN documention for /Yc, /Yu, and /Yp.
10594 Using Microsoft Visual C++ external debugging information
10597 Since including debugging information in programs and shared libraries
10598 can cause their size to increase significantly, Microsoft provides a
10599 mechanism for including the debugging information in an external file
10600 called a PDB file. SCons supports PDB files through the PDB construc‐
10601 tion variable.
10602 SConstruct:
10604 env=Environment()
10605 env['PDB'] = 'MyApp.pdb'
10606 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
10607 For more information see the document for the PDB construction vari‐
10609 able.
10610
10613 SCONS_LIB_DIR
10614 Specifies the directory that contains the SCons Python module
10615 directory (e.g. /home/aroach/scons-src-0.01/src/engine).
10616 SCONSFLAGS
10619 A string of options that will be used by scons in addition to
10620 those passed on the command line.
10621
10624 scons User Manual, scons Design Document, scons source code.
10625
10628 Steven Knight <knight@baldmt.com>
10629 Anthony Roach <aroach@electriceyeball.com>
10630 September 2011 SCONS(1)