1SCONS(1) SCons 4.1.0 SCONS(1)
2
6 scons - a software construction tool
7
9 scons [options...] [name=val...] [targets...]
10
12 scons orchestrates the construction of software (and other tangible
13 products such as documentation files) by determining which component
14 pieces must be built or rebuilt and invoking the necessary commands to
15 build them. SCons offers many features to improve developer
16 productivity such as parallel builds, caching of build artifacts, and a
17 database of information about previous builds so details do not have to
18 be recalculated each run.
19 You set up an SCons build system by writing a script that describes
21 things to build (targets), and, if necessary, the rules to build those
22 files (actions). SCons comes with a collection of Builder methods
23 which apply premade rules for building many common software components
24 such as executable programs, object files and libraries, so that for
25 many software projects, only the targets and input files (sources) need
26 be specified in a call to a builder. scons thus can operate at a level
27 of abstraction above that of pure files. For example if you specify a
28 library target named "foo", scons keeps track of the actual operating
29 system dependent filename (for example libfoo.so on a GNU/Linux
30 system), and how to refer to that library in later construction steps
31 that want to use it, so you don't have to specify that precise
32 information yourself. scons can also scan automatically for dependency
33 information, such as header files included by source code files, so
34 this does not have to be specified manually.
35 When invoked, scons looks for a file named SConstruct in the current
37 directory and reads the build configuration from that file (other names
38 are possible, see the section called “SConscript Files” for more
39 information). The SConstruct file may specify subsidiary configuration
40 files by calling the SConscript function. By convention, these
41 subsidiary files are named SConscript, although any name may be used.
42 As a result of this naming convention, the term SConscript files is
43 often used to refer generically to the complete set of configuration
44 files for a project (including the SConstruct file), regardless of the
45 actual file names or number of such files.
46 Before reading the SConscript files, scons looks for a directory named
48 site_scons in various system directories and in the directory
49 containing the SConstruct file or, if specified, the directory from the
50 --site-dir option instead, and prepends the ones it finds to the Python
51 module search path (sys.path), thus allowing modules in such
52 directories to be imported in the normal Python way in SConscript
53 files. For each found site directory, (1) if it contains a file
54 site_init.py that file is evaluated, and (2) if it contains a directory
55 site_tools the path to that directory is prepended to the default
56 toolpath. See the --site-dir and --no-site-dir options for details on
57 default paths and controlling the site directories.
58 SConscript files are written in the Python programming language,
60 although it is normally not necessary to be a Python programmer to use
61 scons effectively. SConscript files are invoked in a context that makes
62 the facilities described in this manual page available in their local
63 namespace without any special steps. Standard Python scripting
64 capabilities such as flow control, data manipulation, and imported
65 Python libraries are available to use to handle complicated build
66 situations. Other Python files can be made a part of the build system,
67 but they do not automatically have the SCons context and need to import
68 it if they need access (described later).
69 scons reads and executes all of the included SConscript files before it
71 begins building any targets. To make this clear, scons prints the
72 following messages about what it is doing:
73 $ scons foo.out
75 scons: Reading SConscript files ...
76 scons: done reading SConscript files.
77 scons: Building targets ...
78 cp foo.in foo.out
79 scons: done building targets.
80 $
81 The status messages (lines beginning with the scons: tag) may be
83 suppressed using the -Q option.
84 scons does not automatically propagate the external environment used to
86 execute scons to the commands used to build target files. This is so
87 that builds will be guaranteed repeatable regardless of the environment
88 variables set at the time scons is invoked. This also means that if the
89 compiler or other commands that you want to use to build your target
90 files are not in standard system locations, scons will not find them
91 unless you explicitly include the locations into the execution
92 environment by setting the path in the ENV construction variable in the
93 internal construction environment:
94 import os
96 env = Environment(ENV={'PATH': os.environ['PATH']})
97 Similarly, if the commands use specific external environment variables
99 that scons does not recognize, they can be propagated into the
100 execution environment:
101 import os
103 env = Environment(
105 ENV={
106 'PATH': os.environ['PATH'],
107 'ANDROID_HOME': os.environ['ANDROID_HOME'],
108 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME'],
109 }
110 )
111 Or you may explicitly propagate the invoking user's complete external
113 environment:
114 import os
116 env = Environment(ENV=os.environ)
117 This comes at the expense of making your build dependent on the user's
119 environment being set correctly, but it may be more convenient for many
120 configurations. It should not cause problems if done in a build setup
121 which tightly controls how the environment is set up before invoking
122 scons, as in many continuous integration setups.
123 scons can scan known input files automatically for dependency
125 information (for example, #include preprocessor directives in C or C++
126 files) and will rebuild dependent files appropriately whenever any
127 "included" input file changes. scons supports the ability to define
128 new scanners for unknown input file types.
129 scons is normally executed in a top-level directory containing an
131 SConstruct file. When scons is invoked, the command line (including the
132 contents of the SCONSFLAGS environment variable, if set) is processed.
133 Command-line options (see the section called “OPTIONS”) are consumed.
134 Any variable argument assignments (see the section called “Command-Line
135 Construction Variables”) are collected, and remaining arguments are
136 taken as targets to build.
137 Values of variables to be passed to the SConscript files may be
139 specified on the command line:
140 scons debug=1
142 These variables are available through the ARGUMENTS dictionary, and can
144 be used in the SConscript files to modify the build in any way:
145 if ARGUMENTS.get('debug', 0):
147 env = Environment(CCFLAGS='-g')
148 else:
149 env = Environment()
150 The command-line variable arguments are also available in the ARGLIST
152 list, indexed by their order on the command line. This allows you to
153 process them in order rather than by name, if necessary. Each ARGLIST
154 entry is a tuple containing (argname, argvalue).
155 SCons acts on the selected targets, whether the requested operation is
157 build, no-exec or clean. Targets are selected as follows:
158 1. Targets specified on the command line. These may be files,
160 directories, or phony targets defined using the Alias function.
161 Directory targets are scanned by scons for any targets that may be
162 found with a destination in or under that directory. The targets
163 listed on the command line are made available in the
164 COMMAND_LINE_TARGETS list.
165 2. If no targets are specified on the command line, scons will select
167 those targets specified in the SConscript files via calls to the
168 Default function. These are known as the default targets, and are
169 made available in the DEFAULT_TARGETS list.
170 3. If there are no targets from the previous steps, scons selects the
172 current directory for scanning, unless command-line options which
173 affect the target scan are detected (-C, -D, -u, -U). Since targets
174 thus selected were not the result of user instructions, this target
175 list is not made available for direct inspection; use the
176 --debug=explain option if they need to be examined.
177 4. scons always adds to the selected targets any intermediate targets
179 which are necessary to build the specified ones. For example, if
180 constructing a shared library or dll from C source files, scons
181 will also build the object files which will make up the library.
182 To ignore the default targets specified through calls to Default and
184 instead build all target files in or below the current directory
185 specify the current directory (.) as a command-line target:
186 scons .
188 To build all target files, including any files outside of the current
190 directory, supply a command-line target of the root directory (on POSIX
191 systems):
192 scons /
194 or the path name(s) of the volume(s) in which all the targets should be
196 built (on Windows systems):
197 scons C:\ D:\
199 A subset of a hierarchical tree may be built by remaining at the
201 top-level directory (where the SConstruct file lives) and specifying
202 the subdirectory as the target to build:
203 scons src/subdir
205 or by changing directory and invoking scons with the -u option, which
207 traverses up the directory hierarchy until it finds the SConstruct
208 file, and then builds targets relatively to the current subdirectory
209 (see also the related -D and -U options):
210 cd src/subdir
212 scons -u .
213 In all cases, more files may be built than are requested, as scons
215 needs to make sure any dependent files are built.
216 Specifying "cleanup" targets in SConscript files is usually not
218 necessary. The -c flag removes all selected targets:
219 scons -c .
221 to remove all target files in or under the current directory, or:
223 scons -c build export
225 to remove target files under build and export.
227 Additional files or directories to remove can be specified using the
229 Clean function in the SConscript files. Conversely, targets that would
230 normally be removed by the -c invocation can be retained by calling the
231 NoClean function with those targets.
232 scons supports building multiple targets in parallel via a -j option
234 that takes, as its argument, the number of simultaneous tasks that may
235 be spawned:
236 scons -j 4
238 builds four targets in parallel, for example.
240 scons can maintain a cache of target (derived) files that can be shared
242 between multiple builds. When derived-file caching is enabled in an
243 SConscript file, any target files built by scons will be copied to the
244 cache. If an up-to-date target file is found in the cache, it will be
245 retrieved from the cache instead of being rebuilt locally. Caching
246 behavior may be disabled and controlled in other ways by the
247 --cache-force, --cache-disable, --cache-readonly, and --cache-show
248 command-line options. The --random option is useful to prevent multiple
249 builds from trying to update the cache simultaneously.
250 By default, scons searches for known programming tools on various
252 systems and initializes itself based on what is found. On Windows
253 systems which identify as win32, scons searches in order for the
254 Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler
255 tools, and the PharLap ETS compiler. On Windows system which identify
256 as cygwin (that is, if scons is invoked from a cygwin shell), the order
257 changes to prefer the GCC toolchain over the MSVC tools. On OS/2
258 systems, scons searches in order for the OS/2 compiler, the GCC tool
259 chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX,
260 Hewlett Packard HP-UX, and Oracle Solaris systems, scons searches for
261 the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools
262 respectively) and the GCC tool chain. On all other platforms, including
263 POSIX (Linux and UNIX) platforms, scons searches in order for the GCC
264 tool chain, and the Intel compiler tools. These default values may be
265 overridden by appropriate setting of construction variables.
266 scons requires Python 3.5 or higher. There should be no other
268 dependencies or requirements to run scons.
269
271 In general, scons supports the same command-line options as GNU Make
272 and many of those supported by cons.
273 -b
275 Ignored for compatibility with non-GNU versions of Make
276 -c, --clean, --remove
278 Clean up by removing the selected targets, well as any files or
279 directories associated with a selected target through calls to the
280 Clean function. Will not remove any targets which are marked for
281 preservation through calls to the NoClean function.
282 --cache-debug=file
284 Write debug information about derived-file caching to the specified
285 file. If file is a hyphen (-), the debug information is printed to
286 the standard output. The printed messages describe what
287 signature-file names are being looked for in, retrieved from, or
288 written to the derived-file cache specified by CacheDir.
289 --cache-disable, --no-cache
291 Disable derived-file caching. scons will neither retrieve files
292 from the cache nor copy files to the cache. This option can be used
293 to temporarily disable the cache without modifying the build
294 scripts.
295 --cache-force, --cache-populate
297 When using CacheDir, populate a derived-file cache by copying any
298 already-existing, up-to-date derived files to the cache, in
299 addition to files built by this invocation. This is useful to
300 populate a new cache with all the current derived files, or to add
301 to the cache any derived files recently built with caching disabled
302 via the --cache-disable option.
303 --cache-readonly
305 Use the derived-file cache, if enabled, to retrieve files, but do
306 not not update the cache with any files actually built during this
307 invocation.
308 --cache-show
310 When using a derived-file cache and retrieving a file from it, show
311 the command that would have been executed to build the file.
312 Without this option, scons reports "Retrieved `file' from cache.".
313 This allows producing consistent output for build logs, regardless
314 of whether a target file was rebuilt or retrieved from the cache.
315 --config=mode
317 Control how the Configure call should use or generate the results
318 of configuration tests. modeshould be specified from among the
319 following choices:
320 auto
322 scons will use its normal dependency mechanisms to decide if a
323 test must be rebuilt or not. This saves time by not running the
324 same configuration tests every time you invoke scons, but will
325 overlook changes in system header files or external commands
326 (such as compilers) if you don't specify those dependecies
327 explicitly. This is the default behavior.
328 force
330 If this option is specified, all configuration tests will be
331 re-run regardless of whether the cached results are out of
332 date. This can be used to explicitly force the configuration
333 tests to be updated in response to an otherwise unconfigured
334 change in a system header file or compiler.
335 cache
337 If this option is specified, no configuration tests will be
338 rerun and all results will be taken from cache. scons will
339 report an error if --config=cache is specified and a necessary
340 test does not have any results in the cache.
341 -C directory, --directory=directory
344 Run as if scons was started in directory instead of the current
345 working directory. That is, change directory before searching for
346 the SConstruct, Sconstruct, sconstruct, SConstruct.py,
347 Sconstruct.py or sconstruct.py file or doing anything else. When
348 multiple -C options are given, each subsequent non-absolute -C
349 directory is interpreted relative to the preceding one. This option
350 is similar to using -f directory/SConstruct, but -f does not search
351 for any of the predefined SConstruct names in the specified
352 directory. See also options -u, -U and -D to change the SConstruct
353 search behavior when this option is used.
354 -D
356 Works exactly the same way as the -u option except for the way
357 default targets are handled. When this option is used and no
358 targets are specified on the command line, all default targets are
359 built, whether or not they are below the current directory.
360 --debug=type[,type...]
362 Debug the build process. type specifies the kind of debugging info
363 to emit. Multiple types may be specified, separated by commas. The
364 following entries show the recognized types:
365 action-timestamps
367 Prints additional time profiling information. For each command,
368 shows the absolute start and end times. This may be useful in
369 debugging parallel builds. Implies the --debug=time option.
370 Available since scons 3.1.
372 count
374 Print how many objects are created of the various classes used
375 internally by SCons before and after reading the SConscript
376 files and before and after building targets. This is not
377 supported when SCons is executed with the Python -O (optimized)
378 option or when the SCons modules have been compiled with
379 optimization (that is, when executing from *.pyo files).
380 duplicate
382 Print a line for each unlink/relink (or copy) of a variant file
383 from its source file. Includes debugging info for unlinking
384 stale variant files, as well as unlinking old targets before
385 building them.
386 explain
388 Print an explanation of why scons is deciding to (re-)build the
389 targets it selects for building.
390 findlibs
392 Instruct the scanner that searches for libraries to print a
393 message about each potential library name it is searching for,
394 and about the actual libraries it finds.
395 includes
397 Print the include tree after each top-level target is built.
398 This is generally used to find out what files are included by
399 the sources of a given derived file:
400 $ scons --debug=includes foo.o
402 memoizer
404 Prints a summary of hits and misses using the Memoizer, an
405 internal subsystem that counts how often SCons uses cached
406 values in memory instead of recomputing them each time they're
407 needed.
408 memory
410 Prints how much memory SCons uses before and after reading the
411 SConscript files and before and after building targets.
412 objects
414 Prints a list of the various objects of the various classes
415 used internally by SCons.
416 pdb
418 Re-run scons under the control of the pdb Python debugger.
419 prepare
421 Print a line each time any target (internal or external) is
422 prepared for building. scons prints this for each target it
423 considers, even if that target is up to date (see also
424 --debug=explain). This can help debug problems with targets
425 that aren't being built; it shows whether scons is at least
426 considering them or not.
427 presub
429 Print the raw command line used to build each target before the
430 construction environment variables are substituted. Also shows
431 which targets are being built by this command. Output looks
432 something like this:
433 $ scons --debug=presub
435 Building myprog.o with action(s):
436 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
437 ...
438 stacktrace
440 Prints an internal Python stack trace when encountering an
441 otherwise unexplained error.
442 time
444 Prints various time profiling information:
445 • The time spent executing each individual build command
447 • The total build time (time SCons ran from beginning to end)
449 • The total time spent reading and executing SConscript files
451 • The total time SCons itself spent running (that is, not
453 counting reading and executing SConscript files)
454 • The total time spent executing all build commands
456 • The elapsed wall-clock time spent executing those build
458 commands
459 • The time spent processing each file passed to the
461 SConscript function
462 (When scons is executed without the -j option, the elapsed
464 wall-clock time will typically be slightly longer than the
465 total time spent executing all the build commands, due to the
466 SCons processing that takes place in between executing each
467 command. When scons is executed with the -j option, and your
468 build configuration allows good parallelization, the elapsed
469 wall-clock time should be significantly smaller than the total
470 time spent executing all the build commands, since multiple
471 build commands and intervening SCons processing should take
472 place in parallel.)
473 --diskcheck=type[,type...]
476 Enable specific checks for whether or not there is a file on disk
477 where the SCons configuration expects a directory (or vice versa),
478 and whether or not RCS or SCCS sources exist when searching for
479 source and include files. The type argument can be set to:
480 all
482 Enable all checks explicitly (the default behavior).
483 none
485 Disable all such checks.
486 match
488 to check that files and directories on disk match SCons'
489 expected configuration.
490 rcs
492 Check for the existence of an RCS source for any missing source
493 or include files.
494 sccs
496 Check for the existence of an SCCS source for any missing
497 source or include files.
498 Multiple checks can be specified separated by commas. for example,
500 --diskcheck=sccs,rcs would still check for SCCS and RCS sources,
501 but disable the check for on-disk matches of files and directories.
502 Disabling some or all of these checks can provide a performance
503 boost for large configurations, or when the configuration will
504 check for files and/or directories across networked or shared file
505 systems, at the slight increased risk of an incorrect build or of
506 not handling errors gracefully (if include files really should be
507 found in SCCS or RCS, for example, or if a file really does exist
508 where the SCons configuration expects a directory).
509 --duplicate=ORDER
511 There are three ways to duplicate files in a build tree: hard
512 links, soft (symbolic) links and copies. The default behaviour of
513 SCons is to prefer hard links to soft links to copies. You can
514 specify different behaviours with this option. ORDER must be one
515 of hard-soft-copy (the default), soft-hard-copy, hard-copy,
516 soft-copy or copy. SCons will attempt to duplicate files using the
517 mechanisms in the specified order.
518 --enable-virtualenv
520 Import virtualenv-related variables to SCons.
521 -f file, --file=file, --makefile=file, --sconstruct=file
523 Use file as the initial SConscript file. Multiple -f options may be
524 specified, in which case scons will read all of the specified
525 files.
526 -h, --help
528 Print a local help message for this project, if one is defined in
529 the SConscript files (see the Help function), plus a line that
530 refers to the standard SCons help message. If no local help message
531 is defined, prints the standard SCons help message (as for the -H
532 option) plus help for any local options defined through AddOption.
533 Exits after displaying the appropriate message.
534 Note that use of this option requires SCons to process the
536 SConscript files, so syntax errors may cause the help message not
537 to be displayed.
538 -H, --help-options
540 Print the standard help message about SCons command-line options
541 and exit.
542 -i, --ignore-errors
544 Ignore all errors from commands executed to rebuild files.
545 -I directory, --include-dir=directory
547 Specifies a directory to search for imported Python modules. If
548 several -I options are used, the directories are searched in the
549 order specified.
550 --ignore-virtualenv
552 Suppress importing virtualenv-related variables to SCons.
553 --implicit-cache
555 Cache implicit dependencies. This causes scons to use the implicit
556 (scanned) dependencies from the last time it was run instead of
557 scanning the files for implicit dependencies. This can
558 significantly speed up SCons, but with the following limitations:
559 scons will not detect changes to implicit dependency search paths
561 (e.g. CPPPATH, LIBPATH) that would ordinarily cause different
562 versions of same-named files to be used.
563 scons will miss changes in the implicit dependencies in cases where
565 a new implicit dependency is added earlier in the implicit
566 dependency search path (e.g. CPPPATH, LIBPATH) than a current
567 implicit dependency with the same name.
568 --implicit-deps-changed
570 Forces SCons to ignore the cached implicit dependencies. This
571 causes the implicit dependencies to be rescanned and recached. This
572 implies --implicit-cache.
573 --implicit-deps-unchanged
575 Force SCons to ignore changes in the implicit dependencies. This
576 causes cached implicit dependencies to always be used. This implies
577 --implicit-cache.
578 --install-sandbox=sandbox_path
580 When using the Install builders, prepend sandbox_path to the
581 installation paths such that all installed files will be placed
582 under that directory. This option is unavailable if one of Install,
583 InstallAs or InstallVersionedLib is not used in the SConscript
584 files.
585 --interactive
587 Starts SCons in interactive mode. The SConscript files are read
588 once and a scons>>> prompt is printed. Targets may now be rebuilt
589 by typing commands at interactive prompt without having to re-read
590 the SConscript files and re-initialize the dependency graph from
591 scratch.
592 SCons interactive mode supports the following commands:
594 build [OPTIONS] [TARGETS] ...
596 Builds the specified TARGETS (and their dependencies) with the
597 specified SCons command-line OPTIONS. b and scons are synonyms
598 for build.
599 The following SCons command-line options affect the build
601 command:
602 --cache-debug=FILE
604 --cache-disable, --no-cache
605 --cache-force, --cache-populate
606 --cache-readonly
607 --cache-show
608 --debug=TYPE
609 -i, --ignore-errors
610 -j N, --jobs=N
611 -k, --keep-going
612 -n, --no-exec, --just-print, --dry-run, --recon
613 -Q
614 -s, --silent, --quiet
615 --taskmastertrace=FILE
616 --tree=OPTIONS
617 Any other SCons command-line options that are specified do not
619 cause errors but have no effect on the build command (mainly
620 because they affect how the SConscript files are read, which
621 only happens once at the beginning of interactive mode).
622 clean [OPTIONS] [TARGETS] ...
624 Cleans the specified TARGETS (and their dependencies) with the
625 specified OPTIONS. c is a synonym. This command is itself a
626 synonym for build --clean
627 exit
629 Exits SCons interactive mode. You can also exit by terminating
630 input (Ctrl+D UNIX or Linux systems, (Ctrl+Z on Windows
631 systems).
632 help [COMMAND]
634 Provides a help message about the commands available in SCons
635 interactive mode. If COMMAND is specified, h and ? are
636 synonyms.
637 shell [COMMANDLINE]
639 Executes the specified COMMANDLINE in a subshell. If no
640 COMMANDLINE is specified, executes the interactive command
641 interpreter specified in the SHELL environment variable (on
642 UNIX and Linux systems) or the COMSPEC environment variable (on
643 Windows systems). sh and ! are synonyms.
644 version
646 Prints SCons version information.
647 An empty line repeats the last typed command. Command-line editing
649 can be used if the readline module is available.
650 $ scons --interactive
652 scons: Reading SConscript files ...
653 scons: done reading SConscript files.
654 scons>>> build -n prog
655 scons>>> exit
656 -j N, --jobs=N
658 Specifies the maximum number of comcurrent jobs (commands) to run.
659 If there is more than one -j option, the last one is effective.
660 -k, --keep-going
662 Continue as much as possible after an error. The target that failed
663 and those that depend on it will not be remade, but other targets
664 specified on the command line will still be processed.
665 -m
667 Ignored for compatibility with non-GNU versions of Make.
668 --max-drift=SECONDS
670 Set the maximum expected drift in the modification time of files to
671 SECONDS. This value determines how long a file must be unmodified
672 before its cached content signature will be used instead of
673 calculating a new content signature (MD5 checksum) of the file's
674 contents. The default value is 2 days, which means a file must have
675 a modification time of at least two days ago in order to have its
676 cached content signature used. A negative value means to never
677 cache the content signature and to ignore the cached value if there
678 already is one. A value of 0 means to always use the cached
679 signature, no matter how old the file is.
680 --md5-chunksize=KILOBYTES
682 Set the block size used to compute MD5 signatures to KILOBYTES.
683 This value determines the size of the chunks which are read in at
684 once when computing MD5 signatures. Files below that size are fully
685 stored in memory before performing the signature computation while
686 bigger files are read in block-by-block. A huge block-size leads to
687 high memory consumption while a very small block-size slows down
688 the build considerably.
689 The default value is to use a chunk size of 64 kilobytes, which
691 should be appropriate for most uses.
692 -n, --no-exec, --just-print, --dry-run, --recon
694 No execute. Print the commands that would be executed to build any
695 out-of-date target files, but do not execute the commands.
696 --no-site-dir
698 Prevents the automatic addition of the standard site_scons dirs to
699 sys.path. Also prevents loading the site_scons/site_init.py modules
700 if they exist, and prevents adding their site_scons/site_tools dirs
701 to the toolpath.
702 --package-type=type
704 The type or types of package to create when using the Package
705 builder. In the case of multiple types, type should be a
706 comma-separated string; SCons will try to build for all of those
707 packages. Note this option is only available if the packaging tool
708 has been enabled.
709 --profile=file
711 Run SCons under the Python profiler and save the results in the
712 specified file. The results may be analyzed using the Python pstats
713 module.
714 -q, --question
716 Do not run any commands, or print anything. Just return an exit
717 status that is zero if the specified targets are already up to
718 date, non-zero otherwise.
719 -Q
721 Quiets SCons status messages about reading SConscript files,
722 building targets and entering directories. Commands that are
723 executed to rebuild target files are still printed.
724 --random
726 Build dependencies in a random order. This is useful when building
727 multiple trees simultaneously with caching enabled, to prevent
728 multiple builds from simultaneously trying to build or retrieve the
729 same target files.
730 -s, --silent, --quiet
732 Silent. Do not print commands that are executed to rebuild target
733 files. Also suppresses SCons status messages.
734 -S, --no-keep-going, --stop
736 Ignored for compatibility with GNU Make
737 --site-dir=dir
739 Uses the named dir as the site directory rather than the default
740 site_scons directories. This directory will be prepended to
741 sys.path, the module dir/site_init.py will be loaded if it exists,
742 and dir/site_tools will be added to the default toolpath.
743 The default set of site_scons directories used when --site-dir is
745 not specified depends on the system platform, as follows.
746 Directories are examined in the order given, from most generic to
747 most specific, so the last-executed site_init.py file is the most
748 specific one (which gives it the chance to override everything
749 else), and the directories are prepended to the paths, again so the
750 last directory examined comes first in the resulting path.
751 Windows:
753 %ALLUSERSPROFILE/Application Data/scons/site_scons
755 %USERPROFILE%/Local Settings/Application Data/scons/site_scons
756 %APPDATA%/scons/site_scons
757 %HOME%/.scons/site_scons
758 ./site_scons
759 Mac OS X:
761 /Library/Application Support/SCons/site_scons
763 /opt/local/share/scons/site_scons (for MacPorts)
764 /sw/share/scons/site_scons (for Fink)
765 $HOME/Library/Application Support/SCons/site_scons
766 $HOME/.scons/site_scons
767 ./site_scons
768 Solaris:
770 /opt/sfw/scons/site_scons
772 /usr/share/scons/site_scons
773 $HOME/.scons/site_scons
774 ./site_scons
775 Linux, HPUX, and other Posix-like systems:
777 /usr/share/scons/site_scons
779 $HOME/.scons/site_scons
780 ./site_scons
781 --stack-size=KILOBYTES
783 Set the size stack used to run threads to KILOBYTES. This value
784 determines the stack size of the threads used to run jobs. These
785 threads execute the actions of the builders for the nodes that are
786 out-of-date. This option has no effect unless the number of
787 concurrent build jobs is larger than one (as set by -j N or
788 --jobs=N on the command line or SetOption in a script).
789 Using a stack size that is too small may cause stack overflow
791 errors. This usually shows up as segmentation faults that cause
792 scons to abort before building anything. Using a stack size that is
793 too large will cause scons to use more memory than required and may
794 slow down the entire build process. The default value is to use a
795 stack size of 256 kilobytes, which should be appropriate for most
796 uses. You should not need to increase this value unless you
797 encounter stack overflow errors.
798 -t, --touch
800 Ignored for compatibility with GNU Make. (Touching a file to make
801 it appear up-to-date is unnecessary when using scons.)
802 --taskmastertrace=file
804 Prints trace information to the specified file about how the
805 internal Taskmaster object evaluates and controls the order in
806 which Nodes are built. A file name of - may be used to specify the
807 standard output.
808 --tree=type[,type...]
810 Prints a tree of the dependencies after each top-level target is
811 built. This prints out some or all of the tree, in various formats,
812 depending on the type specified:
813 all
815 Print the entire dependency tree after each top-level target is
816 built. This prints out the complete dependency tree, including
817 implicit dependencies and ignored dependencies.
818 derived
820 Restricts the tree output to only derived (target) files, not
821 source files.
822 linedraw
824 Draw the tree output using Unicode line-drawing characters
825 instead of plain ASCII text. This option acts as a modifier to
826 the selected type(s). If specified alone, without any type, it
827 behaves as if all had been specified.
828 Available since scons 4.0.
830 status
832 Prints status information for each displayed node.
833 prune
835 Prunes the tree to avoid repeating dependency information for
836 nodes that have already been displayed. Any node that has
837 already been displayed will have its name printed in [square
838 brackets], as an indication that the dependencies for that node
839 can be found by searching for the relevant output higher up in
840 the tree.
841 Multiple type choices may be specified, separated by commas:
843 # Prints only derived files, with status information:
845 scons --tree=derived,status
846 # Prints all dependencies of target, with status information
848 # and pruning dependencies of already-visited Nodes:
849 scons --tree=all,prune,status target
850 -u, --up, --search-up
852 Walks up the directory structure until an SConstruct, Sconstruct,
853 sconstruct, SConstruct.py, Sconstruct.py or sconstruct.py file is
854 found, and uses that as the top of the directory tree. If no
855 targets are specified on the command line, only targets at or below
856 the current directory will be built.
857 -U
859 Works exactly the same way as the -u option except for the way
860 default targets are handled. When this option is used and no
861 targets are specified on the command line, all default targets that
862 are defined in the SConscript(s) in the current directory are
863 built, regardless of what directory the resultant targets end up
864 in.
865 -v, --version
867 Print the scons version, copyright information, list of authors,
868 and any other relevant information. Then exit.
869 -w, --print-directory
871 Print a message containing the working directory before and after
872 other processing.
873 --no-print-directory
875 Turn off -w, even if it was turned on implicitly.
876 --warn=type, --warn=no-type
878 Enable or disable (with the no- prefix) warnings. type specifies
879 the type of warnings to be enabled or disabled:
880 all
882 All warnings.
883 cache-version
885 Warnings about the derived-file cache directory specified by
886 CacheDir not using the latest configuration information. These
887 warnings are enabled by default.
888 cache-write-error
890 Warnings about errors trying to write a copy of a built file to
891 a specified derived-file cache specified by CacheDir. These
892 warnings are disabled by default.
893 corrupt-sconsign
895 Warnings about unfamiliar signature data in .sconsign files.
896 These warnings are enabled by default.
897 dependency
899 Warnings about dependencies. These warnings are disabled by
900 default.
901 deprecated
903 Warnings about use of currently deprecated features. These
904 warnings are enabled by default. Not all deprecation warnings
905 can be disabled with the --warn=no-deprecated option as some
906 deprecated features which are late in the deprecation cycle may
907 have been designated as mandatory warnings, and these will
908 still display. Warnings for certain deprecated features may
909 also be enabled or disabled individually; see below.
910 duplicate-environment
912 Warnings about attempts to specify a build of a target with two
913 different construction environments that use the same action.
914 These warnings are enabled by default.
915 fortran-cxx-mix
917 Warnings about linking Fortran and C++ object files in a single
918 executable, which can yield unpredictable behavior with some
919 compilers.
920 future-deprecated
922 Warnings about features that will be deprecated in the future.
923 Such warnings are disabled by default. Enabling future
924 deprecation warnings is recommended for projects that
925 redistribute SCons configurations for other users to build, so
926 that the project can be warned as soon as possible about
927 to-be-deprecated features that may require changes to the
928 configuration.
929 link
931 Warnings about link steps.
932 misleading-keywords
934 Warnings about the use of two commonly misspelled keywords
935 targets and sources to Builder calls. The correct spelling is
936 the singular form, even though target and source can themselves
937 refer to lists of names or nodes.
938 missing-sconscript
940 Warnings about missing SConscript files. These warnings are
941 enabled by default.
942 no-object-count
944 Warnings about the --debug=object feature not working when
945 scons is run with the Python -O option or from optimized Python
946 (.pyo) modules.
947 no-parallel-support
949 Warnings about the version of Python not being able to support
950 parallel builds when the -j option is used. These warnings are
951 enabled by default.
952 python-version
954 Warnings about running SCons with a deprecated version of
955 Python. These warnings are enabled by default.
956 reserved-variable
958 Warnings about attempts to set the reserved construction
959 variable names $CHANGED_SOURCES, $CHANGED_TARGETS, $TARGET,
960 $TARGETS, $SOURCE, $SOURCES, $UNCHANGED_SOURCES or
961 $UNCHANGED_TARGETS. These warnings are disabled by default.
962 stack-size
964 Warnings about requests to set the stack size that could not be
965 honored. These warnings are enabled by default.
966 target_not_build
968 Warnings about a build rule not building the expected targets.
969 These warnings are disabled by default.
970 -Y repository, --repository=repository, --srcdir=repository
973 Search the specified repository for any input and target files not
974 found in the local directory hierarchy. Multiple -Y options may be
975 specified, in which case the repositories are searched in the order
976 specified.
977
979 SConscript Files
980 The build configuration is described by one or more files, known as
981 SConscript files. There must be at least one file for a valid build
982 (scons will quit if it does not find one). scons by default looks for
983 this file by the name SConstruct in the directory from which you run
984 scons, though if necessary, also looks for alternative file names
985 Sconstruct, sconstruct, SConstruct.py, Sconstruct.py and sconstruct.py
986 in that order. A different file name (which can include a pathname
987 part) may be specified via the -f option. Except for the SConstruct
988 file, these files are not searched for automatically; you add
989 additional configuration files to the build by calling the SConscript
990 function. This allows parts of the build to be conditionally included
991 or excluded at run-time depending on how scons is invoked.
992 Each SConscript file in a build configuration is invoked independently
994 in a separate context. This provides necessary isolation so that
995 different parts of the build don't accidentally step on each other. You
996 have to be explicit about sharing information, by using the Export
997 function or the exports argument to the SConscript function, as well as
998 the Return function in a called SConscript file, and comsume shared
999 information by using the Import function.
1000 The following sections describe the various SCons facilities that can
1002 be used in SConscript files. Quick links:
1003 Construction Environments
1004 Tools
1005 Builder Methods
1006 Methods and Functions to do Things
1007 SConscript Variables
1008 Construction Variables
1009 Configure Contexts
1010 Command-Line Construction Variables
1011 Node Objects
1012 Construction Environments
1014 A Construction Environment is the basic means by which SConscript files
1015 communicate build information to scons. A new construction environment
1016 is created using the Environment function:
1017 env = Environment()
1019 Construction environment attributes called Construction Variables may
1021 be set either by specifying them as keyword arguments when the object
1022 is created or by assigning them a value after the object is created.
1023 These two are nominally equivalent:
1024 env = Environment(FOO='foo')
1026 env['FOO'] = 'foo'
1027 Note that certain settings which affect tool detection are referenced
1029 only during initialization, and so need to be supplied as part of the
1030 call to Environment. For example, setting $MSVC_VERSION selects the
1031 version of Microsoft Visual C++ you wish to use, but setting it after
1032 the construction environment is constructed has no effect.
1033 As a convenience, construction variables may also be set or modified by
1035 the parse_flags keyword argument during object creation, which has the
1036 effect of the env.MergeFlags method being applied to the argument value
1037 after all other processing is completed. This is useful either if the
1038 exact content of the flags is unknown (for example, read from a control
1039 file) or if the flags need to be distributed to a number of
1040 construction variables. env.ParseFlags describes how these arguments
1041 are distributed to construction variables.
1042 env = Environment(parse_flags='-Iinclude -DEBUG -lm')
1044 This example adds 'include' to the CPPPATH construction variable,
1046 'EBUG' to CPPDEFINES, and 'm' to LIBS.
1047 An existing construction environment can be duplicated by calling the
1049 env.Clone method. Without arguments, it will be a copy with the same
1050 settings. Otherwise, env.Clone takes the same arguments as Environment,
1051 and uses the arguments to create a modified copy.
1052 SCons provides a special construction environment called the Default
1054 Environment. The default environment is used only for global functions,
1055 that is, construction activities called without the context of a
1056 regular construction environment. See DefaultEnvironment for more
1057 information.
1058 By default, a new construction environment is initialized with a set of
1060 builder methods and construction variables that are appropriate for the
1061 current platform. The optional platform keyword argument may be used to
1062 specify that the construction environment should be initialized for a
1063 different platform:
1064 env = Environment(platform='cygwin')
1066 env = Environment(platform='os2')
1067 env = Environment(platform='posix')
1068 env = Environment(platform='win32')
1069 Specifying a platform initializes the appropriate construction
1071 variables in the environment to use and generate file names with
1072 prefixes and suffixes appropriate for that platform.
1073 Note that the win32 platform adds the SystemDrive and SystemRoot
1075 variables from the user's external environment to the construction
1076 environment's ENV dictionary. This is so that any executed commands
1077 that use sockets to connect with other systems (such as fetching source
1078 files from external CVS repository specifications like
1079 :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) will work on
1080 Windows systems.
1081 The platform argument may be a function or callable object, in which
1083 case the Environment method will call it to update the new construction
1084 environment:
1085 def my_platform(env):
1087 env['VAR'] = 'xyzzy'
1088 env = Environment(platform=my_platform)
1090 The optional tools and toolpath keyword arguments affect the way tools
1092 available to the environment are initialized. See the section called
1093 “Tools” for details.
1094 The optional variables keyword argument allows passing a Variables
1096 object which will be used in the initialization of the construction
1097 environment See the section called “Command-Line Construction
1098 Variables” for details.
1099 Tools
1101 SCons has a large number of predefined tools (more properly, tool
1102 specifications) which are used to help initialize the construction
1103 environment. An scons tool is only responsible for setup. For example,
1104 if the SConscript file declares the need to construct an object file
1105 from a C-language source file by calling the Object builder, then a
1106 tool representing an available C compiler needs to have run first, to
1107 set up the builder and all the construction variables it needs in the
1108 associated construction environment; the tool itself is not called in
1109 the process of the build. Normally this happens invisibly: scons has
1110 per-platform lists of default tools, and it runs through those tools,
1111 calling the ones which are actually applicable, skipping those where
1112 necessary programs are not installed on the build system, or other
1113 preconditions are not met.
1114 A specific set of tools with which to initialize an environment when
1116 creating it may be specified using the optional keyword argument tools,
1117 which takes a list of tool names. This is useful to override the
1118 defaults, to specify non-default built-in tools, and to supply added
1119 tools:
1120 env = Environment(tools=['msvc', 'lex'])
1122 Tools can also be directly called by using the Tool method (see below).
1124 The tools argument overrides the default tool list, it does not add to
1126 it, so be sure to include all the tools you need. For example if you
1127 are building a c/c++ program you must specify a tool for at least a
1128 compiler and a linker, as in tools=['clang', 'link']. The tool name
1129 'default' can be used to retain the default list.
1130 If no tools argument is specified, or if tools includes 'default', then
1132 scons will auto-detect usable tools, using the execution environment
1133 value of PATH (that is, env['ENV']['PATH'] - the external evironment
1134 PATH from os.environ is not used) for looking up any backing programs,
1135 and the platform name in effect to determine the default tools for that
1136 platform. Changing the PATH variable after the construction environment
1137 is constructed will not cause the tools to be re-detected.
1138 Additional tools can be added to a project either by placing them in a
1140 site_tools subdirectory of a site directory, or in a custom location
1141 specified to scons by giving the toolpath keyword argument. toolpath
1142 also takes a list as its value:
1143 env = Environment(tools=['default', 'foo'], toolpath=['tools'])
1145 This looks for a tool specification module foo.py in directory tools
1147 and in the standard locations, as well as using the ordinary default
1148 tools for the platform.
1149 Directories specified via toolpath are prepended to the existing tool
1151 path. The default tool path is any site_tools directories, so tools in
1152 a specified toolpath take priority, followed by tools in a site_tools
1153 directory, followed by built-in tools. For example, adding a tool
1154 specification module gcc.py to the toolpath directory would override
1155 the built-in gcc tool. The tool path is stored in the environment and
1156 will be used by subsequent calls to the Tool method, as well as by
1157 env.Clone.
1158 base = Environment(toolpath=['custom_path'])
1160 derived = base.Clone(tools=['custom_tool'])
1161 derived.CustomBuilder()
1162 A tool specification module must include two functions:
1164 generate(env, **kwargs)
1166 Modifies the environment referenced by env to set up variables so
1167 that the facilities represented by the tool can be executed. It may
1168 use any keyword arguments that the user supplies in kwargs to vary
1169 its initialization.
1170 exists(env)
1172 Return True if the tool can be called in the context of env.
1173 Usually this means looking up one or more known programs using the
1174 PATH from the supplied env, but the tool can make the "exists"
1175 decision in any way it chooses.
1176 Note
1178 At the moment, user-added tools do not automatically have their
1179 exists function called. As a result, it is recommended that the
1180 generate function be defensively coded - that is, do not rely on
1181 any necessary existence checks already having been performed. This
1182 is expected to be a temporary limitation, and the exists function
1183 should still be provided.
1184 The elements of the tools list may also be functions or callable
1186 objects, in which case the Environment method will call those objects
1187 to update the new construction environment (see Tool for more details):
1188 def my_tool(env):
1190 env['XYZZY'] = 'xyzzy'
1191 env = Environment(tools=[my_tool])
1193 The individual elements of the tools list may also themselves be lists
1195 or tuples of the form (toolname, kw_dict). SCons searches for the
1196 toolname specification file as described above, and passes kw_dict,
1197 which must be a dictionary, as keyword arguments to the tool's generate
1198 function. The generate function can use the arguments to modify the
1199 tool's behavior by setting up the environment in different ways or
1200 otherwise changing its initialization.
1201 # in tools/my_tool.py:
1203 def generate(env, **kwargs):
1204 # Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
1205 env['MY_TOOL'] = kwargs.get('arg1', '1')
1206 def exists(env):
1208 return True
1209 # in SConstruct:
1211 env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
1212 toolpath=['tools'])
1213 The tool specification (my_tool in the example) can use the PLATFORM
1215 variable from the construction environment it is passed to customize
1216 the tool for different platforms.
1217 Tools can be "nested" - that is, they can be located within a
1219 subdirectory in the toolpath. A nested tool name uses a dot to
1220 represent a directory separator
1221 # namespaced builder
1223 env = Environment(ENV=os.environ, tools=['SubDir1.SubDir2.SomeTool'])
1224 env.SomeTool(targets, sources)
1225 # Search Paths
1227 # SCons\Tool\SubDir1\SubDir2\SomeTool.py
1228 # SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
1229 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
1230 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
1231 SCons supports the following tool specifications out of the box:
1233 386asm
1235 Sets construction variables for the 386ASM assembler for the Phar
1236 Lap ETS embedded operating system.
1237 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1239 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1241 aixc++
1243 Sets construction variables for the IMB xlc / Visual Age C++
1244 compiler.
1245 Sets: $CXX, $CXXVERSION, $SHCXX, $SHOBJSUFFIX.
1247 aixcc
1249 Sets construction variables for the IBM xlc / Visual Age C
1250 compiler.
1251 Sets: $CC, $CCVERSION, $SHCC.
1253 aixf77
1255 Sets construction variables for the IBM Visual Age f77 Fortran
1256 compiler.
1257 Sets: $F77, $SHF77.
1259 aixlink
1261 Sets construction variables for the IBM Visual Age linker.
1262 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1264 applelink
1266 Sets construction variables for the Apple linker (similar to the
1267 GNU linker).
1268 Sets: $APPLELINK_COMPATIBILITY_VERSION, $APPLELINK_CURRENT_VERSION,
1270 $APPLELINK_NO_COMPATIBILITY_VERSION, $APPLELINK_NO_CURRENT_VERSION,
1271 $FRAMEWORKPATHPREFIX, $LDMODULECOM, $LDMODULEFLAGS,
1272 $LDMODULEPREFIX, $LDMODULESUFFIX, $LINKCOM, $SHLINKCOM,
1273 $SHLINKFLAGS, $_APPLELINK_COMPATIBILITY_VERSION,
1274 $_APPLELINK_CURRENT_VERSION, $_FRAMEWORKPATH, $_FRAMEWORKS.
1275 Uses: $FRAMEWORKSFLAGS.
1277 ar
1279 Sets construction variables for the ar library archiver.
1280 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $RANLIB,
1282 $RANLIBCOM, $RANLIBFLAGS.
1283 as
1285 Sets construction variables for the as assembler.
1286 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1288 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1290 bcc32
1292 Sets construction variables for the bcc32 compiler.
1293 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1295 $CPPDEFSUFFIX, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS,
1296 $SHCFLAGS, $SHOBJSUFFIX.
1297 Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS.
1299 cc
1301 Sets construction variables for generic POSIX C compilers.
1302 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1304 $CPPDEFSUFFIX, $FRAMEWORKPATH, $FRAMEWORKS, $INCPREFIX, $INCSUFFIX,
1305 $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX.
1306 Uses: $CCCOMSTR, $PLATFORM, $SHCCCOMSTR.
1308 clang
1310 Set construction variables for the Clang C compiler.
1311 Sets: $CC, $CCVERSION, $SHCCFLAGS.
1313 clangxx
1315 Set construction variables for the Clang C++ compiler.
1316 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX,
1318 $STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME.
1319 compilation_db
1321 Sets up CompilationDatabase builder which generates a clang tooling
1322 compatible compilation database.
1323 Sets: $COMPILATIONDB_COMSTR, $COMPILATIONDB_PATH_FILTER,
1325 $COMPILATIONDB_USE_ABSPATH.
1326 cvf
1328 Sets construction variables for the Compaq Visual Fortran compiler.
1329 Sets: $FORTRAN, $FORTRANCOM, $FORTRANMODDIR, $FORTRANMODDIRPREFIX,
1331 $FORTRANMODDIRSUFFIX, $FORTRANPPCOM, $OBJSUFFIX, $SHFORTRANCOM,
1332 $SHFORTRANPPCOM.
1333 Uses: $CPPFLAGS, $FORTRANFLAGS, $SHFORTRANFLAGS, $_CPPDEFFLAGS,
1335 $_FORTRANINCFLAGS, $_FORTRANMODFLAG.
1336 cXX
1338 Sets construction variables for generic POSIX C++ compilers.
1339 Sets: $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX,
1341 $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJSUFFIX, $SHCXX, $SHCXXCOM,
1342 $SHCXXFLAGS, $SHOBJSUFFIX.
1343 Uses: $CXXCOMSTR, $SHCXXCOMSTR.
1345 cyglink
1347 Set construction variables for cygwin linker/loader.
1348 Sets: $IMPLIBPREFIX, $IMPLIBSUFFIX, $LDMODULEVERSIONFLAGS,
1350 $LINKFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBPREFIX, $SHLIBSUFFIX,
1351 $SHLIBVERSIONFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1352 $_LDMODULEVERSIONFLAGS, $_SHLIBVERSIONFLAGS.
1353 default
1355 Sets construction variables for a default list of Tool modules. Use
1356 default in the tools list to retain the original defaults, since
1357 the tools parameter is treated as a literal statement of the tools
1358 to be made available in that construction environment, not an
1359 addition.
1360 The list of tools selected by default is not static, but is
1362 dependent both on the platform and on the software installed on the
1363 platform. Some tools will not initialize if an underlying command
1364 is not found, and some tools are selected from a list of choices on
1365 a first-found basis. The finished tool list can be examined by
1366 inspecting the TOOLS construction variable in the construction
1367 environment.
1368 On all platforms, all tools from the following list are selected
1370 whose respective conditions are met: filesystem, wix, lex, yacc,
1371 rpcgen, swig, jar, javac, javah, rmic, dvipdf, dvips, gs, tex,
1372 latex, pdflatex, pdftex, tar, zip, textfile.
1373 On Linux systems, the default tools list selects (first-found): a C
1375 compiler from gcc, intelc, icc, cc; a C++ compiler from g++,
1376 intelc, icc, cxx; an assembler from gas, nasm, masm; a linker from
1377 gnulink, ilink; a Fortran compiler from gfortran, g77, ifort, ifl,
1378 f95, f90, f77; and a static archiver 'ar'. It also selects all
1379 found from the list m4, rpm.
1380 On Windows systems, the default tools list selects (first-found): a
1382 C compiler from msvc, mingw, gcc, intelc, icl, icc, cc, bcc32; a
1383 C++ compiler from msvc, intelc, icc, g++, cxx, bcc32; an assembler
1384 from masm, nasm, gas, 386asm; a linker from mslink, gnulink, ilink,
1385 linkloc, ilink32; a Fortran compiler from gfortran, g77, ifl, cvf,
1386 f95, f90, fortran; and a static archiver from mslib, ar, tlib; It
1387 also selects all found from the list msvs, midl.
1388 On MacOS systems, the default tools list selects (first-found): a C
1390 compiler from gcc, cc; a C++ compiler from g++, cxx; an assembler
1391 'as'; a linker from applelink, gnulink; a Fortran compiler from
1392 gfortran, f95, f90, g77; and a static archiver ar. It also selects
1393 all found from the list m4, rpm.
1394 Default lists for other platforms can be found by examining the
1396 scons source code (see SCons/Tool/__init__.py).
1397 dmd
1399 Sets construction variables for D language compiler DMD.
1400 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1402 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1403 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1404 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1405 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1406 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1407 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1408 $SHDLINKCOM, $SHDLINKFLAGS.
1409 docbook
1411 This tool tries to make working with Docbook in SCons a little
1412 easier. It provides several toolchains for creating different
1413 output formats, like HTML or PDF. Contained in the package is a
1414 distribution of the Docbook XSL stylesheets as of version 1.76.1.
1415 As long as you don't specify your own stylesheets for
1416 customization, these official versions are picked as
1417 default...which should reduce the inevitable setup hassles for you.
1418 Implicit dependencies to images and XIncludes are detected
1420 automatically if you meet the HTML requirements. The additional
1421 stylesheet utils/xmldepend.xsl by Paul DuBois is used for this
1422 purpose.
1423 Note, that there is no support for XML catalog resolving offered!
1425 This tool calls the XSLT processors and PDF renderers with the
1426 stylesheets you specified, that's it. The rest lies in your hands
1427 and you still have to know what you're doing when resolving names
1428 via a catalog.
1429 For activating the tool "docbook", you have to add its name to the
1431 Environment constructor, like this
1432 env = Environment(tools=['docbook'])
1434 On its startup, the Docbook tool tries to find a required xsltproc
1436 processor, and a PDF renderer, e.g. fop. So make sure that these
1437 are added to your system's environment PATH and can be called
1438 directly, without specifying their full path.
1439 For the most basic processing of Docbook to HTML, you need to have
1441 installed
1442 • the Python lxml binding to libxml2, or
1444 • a standalone XSLT processor, currently detected are xsltproc,
1446 saxon, saxon-xslt and xalan.
1447 Rendering to PDF requires you to have one of the applications fop
1449 or xep installed.
1450 Creating a HTML or PDF document is very simple and straightforward.
1452 Say
1453 env = Environment(tools=['docbook'])
1455 env.DocbookHtml('manual.html', 'manual.xml')
1456 env.DocbookPdf('manual.pdf', 'manual.xml')
1457 to get both outputs from your XML source manual.xml. As a shortcut,
1459 you can give the stem of the filenames alone, like this:
1460 env = Environment(tools=['docbook'])
1462 env.DocbookHtml('manual')
1463 env.DocbookPdf('manual')
1464 and get the same result. Target and source lists are also
1466 supported:
1467 env = Environment(tools=['docbook'])
1469 env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])
1470 or even
1472 env = Environment(tools=['docbook'])
1474 env.DocbookHtml(['manual','reference'])
1475 Important
1478 Whenever you leave out the list of sources, you may not specify
1479 a file extension! The Tool uses the given names as file stems,
1480 and adds the suffixes for target and source files accordingly.
1481 The rules given above are valid for the Builders DocbookHtml,
1482 DocbookPdf, DocbookEpub, DocbookSlidesPdf and DocbookXInclude. For
1483 the DocbookMan transformation you can specify a target name, but
1484 the actual output names are automatically set from the refname
1485 entries in your XML source.
1486 The Builders DocbookHtmlChunked, DocbookHtmlhelp and
1488 DocbookSlidesHtml are special, in that:
1489 1. they create a large set of files, where the exact names and
1491 their number depend on the content of the source file, and
1492 2. the main target is always named index.html, i.e. the output
1494 name for the XSL transformation is not picked up by the
1495 stylesheets.
1496 As a result, there is simply no use in specifying a target HTML
1498 name. So the basic syntax for these builders is always:
1499 env = Environment(tools=['docbook'])
1501 env.DocbookHtmlhelp('manual')
1502 If you want to use a specific XSL file, you can set the additional
1504 xsl parameter to your Builder call as follows:
1505 env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl')
1507 Since this may get tedious if you always use the same local naming
1509 for your customized XSL files, e.g. html.xsl for HTML and pdf.xsl
1510 for PDF output, a set of variables for setting the default XSL name
1511 is provided. These are:
1512 DOCBOOK_DEFAULT_XSL_HTML
1514 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
1515 DOCBOOK_DEFAULT_XSL_HTMLHELP
1516 DOCBOOK_DEFAULT_XSL_PDF
1517 DOCBOOK_DEFAULT_XSL_EPUB
1518 DOCBOOK_DEFAULT_XSL_MAN
1519 DOCBOOK_DEFAULT_XSL_SLIDESPDF
1520 DOCBOOK_DEFAULT_XSL_SLIDESHTML
1521 and you can set them when constructing your environment:
1523 env = Environment(tools=['docbook'],
1525 DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
1526 DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl')
1527 env.DocbookHtml('manual') # now uses html.xsl
1528 Sets: $DOCBOOK_DEFAULT_XSL_EPUB, $DOCBOOK_DEFAULT_XSL_HTML,
1530 $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED, $DOCBOOK_DEFAULT_XSL_HTMLHELP,
1531 $DOCBOOK_DEFAULT_XSL_MAN, $DOCBOOK_DEFAULT_XSL_PDF,
1532 $DOCBOOK_DEFAULT_XSL_SLIDESHTML, $DOCBOOK_DEFAULT_XSL_SLIDESPDF,
1533 $DOCBOOK_FOP, $DOCBOOK_FOPCOM, $DOCBOOK_FOPFLAGS, $DOCBOOK_XMLLINT,
1534 $DOCBOOK_XMLLINTCOM, $DOCBOOK_XMLLINTFLAGS, $DOCBOOK_XSLTPROC,
1535 $DOCBOOK_XSLTPROCCOM, $DOCBOOK_XSLTPROCFLAGS,
1536 $DOCBOOK_XSLTPROCPARAMS.
1537 Uses: $DOCBOOK_FOPCOMSTR, $DOCBOOK_XMLLINTCOMSTR,
1539 $DOCBOOK_XSLTPROCCOMSTR.
1540 dvi
1542 Attaches the DVI builder to the construction environment.
1543 dvipdf
1545 Sets construction variables for the dvipdf utility.
1546 Sets: $DVIPDF, $DVIPDFCOM, $DVIPDFFLAGS.
1548 Uses: $DVIPDFCOMSTR.
1550 dvips
1552 Sets construction variables for the dvips utility.
1553 Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX.
1555 Uses: $PSCOMSTR.
1557 f03
1559 Set construction variables for generic POSIX Fortran 03 compilers.
1560 Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM,
1562 $SHF03FLAGS, $SHF03PPCOM, $_F03INCFLAGS.
1563 Uses: $F03COMSTR, $F03PPCOMSTR, $SHF03COMSTR, $SHF03PPCOMSTR.
1565 f08
1567 Set construction variables for generic POSIX Fortran 08 compilers.
1568 Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM,
1570 $SHF08FLAGS, $SHF08PPCOM, $_F08INCFLAGS.
1571 Uses: $F08COMSTR, $F08PPCOMSTR, $SHF08COMSTR, $SHF08PPCOMSTR.
1573 f77
1575 Set construction variables for generic POSIX Fortran 77 compilers.
1576 Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM,
1578 $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHF77,
1579 $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM,
1580 $SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS.
1581 Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMSTR, $FORTRANPPCOMSTR,
1583 $SHF77COMSTR, $SHF77PPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANPPCOMSTR.
1584 f90
1586 Set construction variables for generic POSIX Fortran 90 compilers.
1587 Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM,
1589 $SHF90FLAGS, $SHF90PPCOM, $_F90INCFLAGS.
1590 Uses: $F90COMSTR, $F90PPCOMSTR, $SHF90COMSTR, $SHF90PPCOMSTR.
1592 f95
1594 Set construction variables for generic POSIX Fortran 95 compilers.
1595 Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM,
1597 $SHF95FLAGS, $SHF95PPCOM, $_F95INCFLAGS.
1598 Uses: $F95COMSTR, $F95PPCOMSTR, $SHF95COMSTR, $SHF95PPCOMSTR.
1600 fortran
1602 Set construction variables for generic POSIX Fortran compilers.
1603 Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN,
1605 $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM.
1606 Uses: $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SHFORTRANCOMSTR,
1608 $SHFORTRANPPCOMSTR.
1609 g++
1611 Set construction variables for the gXX C++ compiler.
1612 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX.
1614 g77
1616 Set construction variables for the g77 Fortran compiler. Calls the
1617 f77 Tool module to set variables.
1618 gas
1620 Sets construction variables for the gas assembler. Calls the as
1621 module.
1622 Sets: $AS.
1624 gcc
1626 Set construction variables for the gcc C compiler.
1627 Sets: $CC, $CCVERSION, $SHCCFLAGS.
1629 gdc
1631 Sets construction variables for the D language compiler GDC.
1632 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1634 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1635 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1636 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1637 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1638 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1639 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1640 $SHDLINKCOM, $SHDLINKFLAGS.
1641 gettext
1643 This is actually a toolset, which supports internationalization and
1644 localization of software being constructed with SCons. The toolset
1645 loads following tools:
1646 • xgettext - to extract internationalized messages from source
1650 code to POT file(s),
1651 • msginit - may be optionally used to initialize PO files,
1653 • msgmerge - to update PO files, that already contain translated
1655 messages,
1656 • msgfmt - to compile textual PO file to binary installable MO
1658 file.
1659 When you enable gettext, it internally loads all abovementioned
1661 tools, so you're encouraged to see their individual documentation.
1662 Each of the above tools provides its own builder(s) which may be
1664 used to perform particular activities related to software
1665 internationalization. You may be however interested in top-level
1666 builder Translate described few paragraphs later.
1667 To use gettext tools add 'gettext' tool to your environment:
1669 env = Environment( tools = ['default', 'gettext'] )
1671 gfortran
1673 Sets construction variables for the GNU F95/F2003 GNU compiler.
1674 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1676 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1677 gnulink
1679 Set construction variables for GNU linker/loader.
1680 Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX,
1682 $SHLIBVERSIONFLAGS, $SHLINKFLAGS, $_LDMODULESONAME, $_SHLIBSONAME.
1683 gs
1685 This Tool sets the required construction variables for working with
1686 the Ghostscript command. It also registers an appropriate Action
1687 with the PDF Builder (PDF), such that the conversion from PS/EPS to
1688 PDF happens automatically for the TeX/LaTeX toolchain. Finally, it
1689 adds an explicit Ghostscript Builder (Gs) to the environment.
1690 Sets: $GS, $GSCOM, $GSFLAGS.
1692 Uses: $GSCOMSTR.
1694 hpc++
1696 Set construction variables for the compilers aCC on HP/UX systems.
1697 hpcc
1699 Set construction variables for the aCC on HP/UX systems. Calls the
1700 cXX tool for additional variables.
1701 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS.
1703 hplink
1705 Sets construction variables for the linker on HP/UX systems.
1706 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1708 icc
1710 Sets construction variables for the icc compiler on OS/2 systems.
1711 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1713 $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX.
1714 Uses: $CCFLAGS, $CFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1716 icl
1718 Sets construction variables for the Intel C/C++ compiler. Calls the
1719 intelc Tool module to set its variables.
1720 ifl
1722 Sets construction variables for the Intel Fortran compiler.
1723 Sets: $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHFORTRANCOM,
1725 $SHFORTRANPPCOM.
1726 Uses: $CPPFLAGS, $FORTRANFLAGS, $_CPPDEFFLAGS, $_FORTRANINCFLAGS.
1728 ifort
1730 Sets construction variables for newer versions of the Intel Fortran
1731 compiler for Linux.
1732 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1734 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1735 ilink
1737 Sets construction variables for the ilink linker on OS/2 systems.
1738 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1740 $LINK, $LINKCOM, $LINKFLAGS.
1741 ilink32
1743 Sets construction variables for the Borland ilink32 linker.
1744 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1746 $LINK, $LINKCOM, $LINKFLAGS.
1747 install
1749 Sets construction variables for file and directory installation.
1750 Sets: $INSTALL, $INSTALLSTR.
1752 intelc
1754 Sets construction variables for the Intel C/C++ compiler (Linux and
1755 Windows, version 7 and later). Calls the gcc or msvc (on Linux and
1756 Windows, respectively) to set underlying variables.
1757 Sets: $AR, $CC, $CXX, $INTEL_C_COMPILER_VERSION, $LINK.
1759 jar
1761 Sets construction variables for the jar utility.
1762 Sets: $JAR, $JARCOM, $JARFLAGS, $JARSUFFIX.
1764 Uses: $JARCOMSTR.
1766 javac
1768 Sets construction variables for the javac compiler.
1769 Sets: $JAVABOOTCLASSPATH, $JAVAC, $JAVACCOM, $JAVACFLAGS,
1771 $JAVACLASSPATH, $JAVACLASSSUFFIX, $JAVAINCLUDES, $JAVASOURCEPATH,
1772 $JAVASUFFIX.
1773 Uses: $JAVACCOMSTR.
1775 javah
1777 Sets construction variables for the javah tool.
1778 Sets: $JAVACLASSSUFFIX, $JAVAH, $JAVAHCOM, $JAVAHFLAGS.
1780 Uses: $JAVACLASSPATH, $JAVAHCOMSTR.
1782 latex
1784 Sets construction variables for the latex utility.
1785 Sets: $LATEX, $LATEXCOM, $LATEXFLAGS.
1787 Uses: $LATEXCOMSTR.
1789 ldc
1791 Sets construction variables for the D language compiler LDC2.
1792 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1794 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1795 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1796 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1797 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1798 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1799 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1800 $SHDLINKCOM, $SHDLINKFLAGS.
1801 lex
1803 Sets construction variables for the lex lexical analyser.
1804 Sets: $LEX, $LEXCOM, $LEXFLAGS, $LEXUNISTD.
1806 Uses: $LEXCOMSTR.
1808 link
1810 Sets construction variables for generic POSIX linkers. This is a
1811 "smart" linker tool which selects a compiler to complete the
1812 linking based on the types of source files.
1813 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS,
1815 $LDMODULENOVERSIONSYMLINKS, $LDMODULEPREFIX, $LDMODULESUFFIX,
1816 $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREFIX,
1817 $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM,
1818 $LINKFLAGS, $SHLIBSUFFIX, $SHLINK, $SHLINKCOM, $SHLINKFLAGS,
1819 $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS.
1820 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $SHLINKCOMSTR.
1822 linkloc
1824 Sets construction variables for the LinkLoc linker for the Phar Lap
1825 ETS embedded operating system.
1826 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1828 $LINK, $LINKCOM, $LINKFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
1829 Uses: $LINKCOMSTR, $SHLINKCOMSTR.
1831 m4
1833 Sets construction variables for the m4 macro processor.
1834 Sets: $M4, $M4COM, $M4FLAGS.
1836 Uses: $M4COMSTR.
1838 masm
1840 Sets construction variables for the Microsoft assembler.
1841 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1843 Uses: $ASCOMSTR, $ASPPCOMSTR, $CPPFLAGS, $_CPPDEFFLAGS,
1845 $_CPPINCFLAGS.
1846 midl
1848 Sets construction variables for the Microsoft IDL compiler.
1849 Sets: $MIDL, $MIDLCOM, $MIDLFLAGS.
1851 Uses: $MIDLCOMSTR.
1853 mingw
1855 Sets construction variables for MinGW (Minimal Gnu on Windows).
1856 Sets: $AS, $CC, $CXX, $LDMODULECOM, $LIBPREFIX, $LIBSUFFIX,
1858 $OBJSUFFIX, $RC, $RCCOM, $RCFLAGS, $RCINCFLAGS, $RCINCPREFIX,
1859 $RCINCSUFFIX, $SHCCFLAGS, $SHCXXFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1860 $SHOBJSUFFIX, $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX.
1861 Uses: $RCCOMSTR, $SHLINKCOMSTR.
1863 msgfmt
1865 This scons tool is a part of scons gettext toolset. It provides
1866 scons interface to msgfmt(1) command, which generates binary
1867 message catalog (MO) from a textual translation description (PO).
1868 Sets: $MOSUFFIX, $MSGFMT, $MSGFMTCOM, $MSGFMTCOMSTR, $MSGFMTFLAGS,
1870 $POSUFFIX.
1871 Uses: $LINGUAS_FILE.
1873 msginit
1875 This scons tool is a part of scons gettext toolset. It provides
1876 scons interface to msginit(1) program, which creates new PO file,
1877 initializing the meta information with values from user's
1878 environment (or options).
1879 Sets: $MSGINIT, $MSGINITCOM, $MSGINITCOMSTR, $MSGINITFLAGS,
1881 $POAUTOINIT, $POCREATE_ALIAS, $POSUFFIX, $POTSUFFIX,
1882 $_MSGINITLOCALE.
1883 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1885 msgmerge
1887 This scons tool is a part of scons gettext toolset. It provides
1888 scons interface to msgmerge(1) command, which merges two Uniform
1889 style .po files together.
1890 Sets: $MSGMERGE, $MSGMERGECOM, $MSGMERGECOMSTR, $MSGMERGEFLAGS,
1892 $POSUFFIX, $POTSUFFIX, $POUPDATE_ALIAS.
1893 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1895 mslib
1897 Sets construction variables for the Microsoft mslib library
1898 archiver.
1899 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
1901 Uses: $ARCOMSTR.
1903 mslink
1905 Sets construction variables for the Microsoft linker.
1906 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX,
1908 $LDMODULESUFFIX, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
1909 $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $REGSVR, $REGSVRCOM,
1910 $REGSVRFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS, $WIN32DEFPREFIX,
1911 $WIN32DEFSUFFIX, $WIN32EXPPREFIX, $WIN32EXPSUFFIX,
1912 $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX, $WINDOWSEXPPREFIX,
1913 $WINDOWSEXPSUFFIX, $WINDOWSPROGMANIFESTPREFIX,
1914 $WINDOWSPROGMANIFESTSUFFIX, $WINDOWSSHLIBMANIFESTPREFIX,
1915 $WINDOWSSHLIBMANIFESTSUFFIX, $WINDOWS_INSERT_DEF.
1916 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $REGSVRCOMSTR, $SHLINKCOMSTR.
1918 mssdk
1920 Sets variables for Microsoft Platform SDK and/or Windows SDK. Note
1921 that unlike most other Tool modules, mssdk does not set
1922 construction variables, but sets the environment variables in the
1923 environment SCons uses to execute the Microsoft toolchain:
1924 %INCLUDE%, %LIB%, %LIBPATH% and %PATH%.
1925 Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION.
1927 msvc
1929 Sets construction variables for the Microsoft Visual C/C++
1930 compiler.
1931 Sets: $BUILDERS, $CC, $CCCOM, $CCFLAGS, $CCPCHFLAGS, $CCPDBFLAGS,
1933 $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM,
1934 $CXXFILESUFFIX, $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJPREFIX,
1935 $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM, $RCFLAGS, $SHCC,
1936 $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS,
1937 $SHOBJPREFIX, $SHOBJSUFFIX.
1938 Uses: $CCCOMSTR, $CXXCOMSTR, $PCH, $PCHSTOP, $PDB, $SHCCCOMSTR,
1940 $SHCXXCOMSTR.
1941 msvs
1943 Sets construction variables for Microsoft Visual Studio.
1944 Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM,
1946 $MSVSREBUILDCOM, $MSVSSCONS, $MSVSSCONSCOM, $MSVSSCONSCRIPT,
1947 $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM.
1948 mwcc
1950 Sets construction variables for the Metrowerks CodeWarrior
1951 compiler.
1952 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1954 $CXX, $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX,
1955 $MWCW_VERSION, $MWCW_VERSIONS, $SHCC, $SHCCCOM, $SHCCFLAGS,
1956 $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS.
1957 Uses: $CCCOMSTR, $CXXCOMSTR, $SHCCCOMSTR, $SHCXXCOMSTR.
1959 mwld
1961 Sets construction variables for the Metrowerks CodeWarrior linker.
1962 Sets: $AR, $ARCOM, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
1964 $LIBLINKSUFFIX, $LINK, $LINKCOM, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
1965 nasm
1967 Sets construction variables for the nasm Netwide Assembler.
1968 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1970 Uses: $ASCOMSTR, $ASPPCOMSTR.
1972 packaging
1974 Sets construction variables for the Package Builder. If this tool
1975 is enabled, the --package-type command-line option is also enabled.
1976 pdf
1978 Sets construction variables for the Portable Document Format
1979 builder.
1980 Sets: $PDFPREFIX, $PDFSUFFIX.
1982 pdflatex
1984 Sets construction variables for the pdflatex utility.
1985 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS.
1987 Uses: $PDFLATEXCOMSTR.
1989 pdftex
1991 Sets construction variables for the pdftex utility.
1992 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS,
1994 $PDFTEX, $PDFTEXCOM, $PDFTEXFLAGS.
1995 Uses: $PDFLATEXCOMSTR, $PDFTEXCOMSTR.
1997 python
1999 Loads the Python source scanner into the invoking environment. When
2000 loaded, the scanner will attempt to find implicit dependencies for
2001 any Python source files in the list of sources provided to an
2002 Action that uses this environment.
2003 Available since scons 4.0..
2005 qt
2007 Sets construction variables for building Qt applications.
2008 Sets: $QTDIR, $QT_AUTOSCAN, $QT_BINPATH, $QT_CPPPATH, $QT_LIB,
2010 $QT_LIBPATH, $QT_MOC, $QT_MOCCXXPREFIX, $QT_MOCCXXSUFFIX,
2011 $QT_MOCFROMCXXCOM, $QT_MOCFROMCXXFLAGS, $QT_MOCFROMHCOM,
2012 $QT_MOCFROMHFLAGS, $QT_MOCHPREFIX, $QT_MOCHSUFFIX, $QT_UIC,
2013 $QT_UICCOM, $QT_UICDECLFLAGS, $QT_UICDECLPREFIX, $QT_UICDECLSUFFIX,
2014 $QT_UICIMPLFLAGS, $QT_UICIMPLPREFIX, $QT_UICIMPLSUFFIX,
2015 $QT_UISUFFIX.
2016 rmic
2018 Sets construction variables for the rmic utility.
2019 Sets: $JAVACLASSSUFFIX, $RMIC, $RMICCOM, $RMICFLAGS.
2021 Uses: $RMICCOMSTR.
2023 rpcgen
2025 Sets construction variables for building with RPCGEN.
2026 Sets: $RPCGEN, $RPCGENCLIENTFLAGS, $RPCGENFLAGS,
2028 $RPCGENHEADERFLAGS, $RPCGENSERVICEFLAGS, $RPCGENXDRFLAGS.
2029 sgiar
2031 Sets construction variables for the SGI library archiver.
2032 Sets: $AR, $ARCOMSTR, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $SHLINK,
2034 $SHLINKFLAGS.
2035 Uses: $ARCOMSTR, $SHLINKCOMSTR.
2037 sgic++
2039 Sets construction variables for the SGI C++ compiler.
2040 Sets: $CXX, $CXXFLAGS, $SHCXX, $SHOBJSUFFIX.
2042 sgicc
2044 Sets construction variables for the SGI C compiler.
2045 Sets: $CXX, $SHOBJSUFFIX.
2047 sgilink
2049 Sets construction variables for the SGI linker.
2050 Sets: $LINK, $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2052 sunar
2054 Sets construction variables for the Sun library archiver.
2055 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2057 Uses: $ARCOMSTR.
2059 sunc++
2061 Sets construction variables for the Sun C++ compiler.
2062 Sets: $CXX, $CXXVERSION, $SHCXX, $SHCXXFLAGS, $SHOBJPREFIX,
2064 $SHOBJSUFFIX.
2065 suncc
2067 Sets construction variables for the Sun C compiler.
2068 Sets: $CXX, $SHCCFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.
2070 sunf77
2072 Set construction variables for the Sun f77 Fortran compiler.
2073 Sets: $F77, $FORTRAN, $SHF77, $SHF77FLAGS, $SHFORTRAN,
2075 $SHFORTRANFLAGS.
2076 sunf90
2078 Set construction variables for the Sun f90 Fortran compiler.
2079 Sets: $F90, $FORTRAN, $SHF90, $SHF90FLAGS, $SHFORTRAN,
2081 $SHFORTRANFLAGS.
2082 sunf95
2084 Set construction variables for the Sun f95 Fortran compiler.
2085 Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN,
2087 $SHFORTRANFLAGS.
2088 sunlink
2090 Sets construction variables for the Sun linker.
2091 Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2093 swig
2095 Sets construction variables for the SWIG interface generator.
2096 Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX,
2098 $SWIGDIRECTORSUFFIX, $SWIGFLAGS, $SWIGINCPREFIX, $SWIGINCSUFFIX,
2099 $SWIGPATH, $SWIGVERSION, $_SWIGINCFLAGS.
2100 Uses: $SWIGCOMSTR.
2102 tar
2104 Sets construction variables for the tar archiver.
2105 Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX.
2107 Uses: $TARCOMSTR.
2109 tex
2111 Sets construction variables for the TeX formatter and typesetter.
2112 Sets: $BIBTEX, $BIBTEXCOM, $BIBTEXFLAGS, $LATEX, $LATEXCOM,
2114 $LATEXFLAGS, $MAKEINDEX, $MAKEINDEXCOM, $MAKEINDEXFLAGS, $TEX,
2115 $TEXCOM, $TEXFLAGS.
2116 Uses: $BIBTEXCOMSTR, $LATEXCOMSTR, $MAKEINDEXCOMSTR, $TEXCOMSTR.
2118 textfile
2120 Set construction variables for the Textfile and Substfile builders.
2121 Sets: $LINESEPARATOR, $SUBSTFILEPREFIX, $SUBSTFILESUFFIX,
2123 $TEXTFILEPREFIX, $TEXTFILESUFFIX.
2124 Uses: $SUBST_DICT.
2126 tlib
2128 Sets construction variables for the Borlan tib library archiver.
2129 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2131 Uses: $ARCOMSTR.
2133 xgettext
2135 This scons tool is a part of scons gettext toolset. It provides
2136 scons interface to xgettext(1) program, which extracts
2137 internationalized messages from source code. The tool provides
2138 POTUpdate builder to make PO Template files.
2139 Sets: $POTSUFFIX, $POTUPDATE_ALIAS, $XGETTEXTCOM, $XGETTEXTCOMSTR,
2141 $XGETTEXTFLAGS, $XGETTEXTFROM, $XGETTEXTFROMPREFIX,
2142 $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPATHPREFIX,
2143 $XGETTEXTPATHSUFFIX, $_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS,
2144 $_XGETTEXTPATHFLAGS.
2145 Uses: $POTDOMAIN.
2147 yacc
2149 Sets construction variables for the yacc parse generator.
2150 Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX,
2152 $YACCHXXFILESUFFIX, $YACCVCGFILESUFFIX.
2153 Uses: $YACCCOMSTR.
2155 zip
2157 Sets construction variables for the zip archiver.
2158 Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX.
2160 Uses: $ZIPCOMSTR.
2162 Builder Methods
2164 You tell scons what to build by calling Builders, functions which know
2165 to take a particular action to produce a particular result type when
2166 given source files of a particular type. scons defines a number of
2167 builders, and you can also write your own. Builders are attached to a
2168 construction environment as methods, and the available builder methods
2169 are listed as key-value pairs in the BUILDERS attribute of the
2170 construction environment. The available builders can be displayed like
2171 this for debugging purposes:
2172 print("Builders:", list(env['BUILDERS']))
2174 Builder methods always take two arguments: target (a target or a list
2176 of targets to be built) and source (a source or list of sources to be
2177 used as input when building), although in some circumstances, the
2178 target argument can actually be omitted (see below). Builder methods
2179 also take a variety of keyword arguments, described below.
2180 Because long lists of file names can lead to a lot of quoting, scons
2182 supplies a Split global function and a same-named environment method
2183 that splits a single string into a list, using strings of white-space
2184 characters as the delimiter. (similar to the Python string split
2185 method, but succeeds even if the input isn't a string.)
2186 The target and source arguments to a builder method can be specified
2188 either as positional arguments, in which case the target comes first,
2189 or as keyword arguments, using target= and source=. The following are
2190 equivalent examples of calling the Program builder method:
2191 env.Program('bar', ['bar.c', 'foo.c'])
2193 env.Program('bar', Split('bar.c foo.c'))
2194 env.Program('bar', env.Split('bar.c foo.c'))
2195 env.Program(source=['bar.c', 'foo.c'], target='bar')
2196 env.Program(target='bar', source=Split('bar.c foo.c'))
2197 env.Program(target='bar', source=env.Split('bar.c foo.c'))
2198 env.Program('bar', source='bar.c foo.c'.split())
2199 Python follows the POSIX pathname convention for path strings: if a
2201 string begins with the operating system pathname separator (on Windows
2202 both the slash and backslash separator work, and any leading drive
2203 specifier is ignored for the determination) it is considered an
2204 absolute path, otherwise it is a relative path. If the path string
2205 contains no separator characters, it is searched for as a file in the
2206 current directory. If it contains separator characters, the search
2207 follows down from the starting point, which is the top of the directory
2208 tree for an absolute path and the current directory for a relative
2209 path.
2210 scons recognizes a third way to specify path strings: if the string
2212 begins with the # character it is top-relative - it works like a
2213 relative path but the search follows down from the directory containing
2214 the top-level SConstruct rather than from the current directory. The #
2215 is allowed to be followed by a pathname separator, which is ignored if
2216 found in that position. Top-relative paths only work in places where
2217 scons will interpret the path (see some examples below). To be used in
2218 other contexts the string will need to be converted to a relative or
2219 absolute path first.
2220 Target and source pathnames can be absolute, relative, or top-relative.
2222 Relative pathnames are searched considering the directory of the
2223 SConscript file currently being processed as the "current directory".
2224 Examples:
2226 # The comments describing the targets that will be built
2228 # assume these calls are in a SConscript file in the
2229 # a subdirectory named "subdir".
2230 # Builds the program "subdir/foo" from "subdir/foo.c":
2232 env.Program('foo', 'foo.c')
2233 # Builds the program "/tmp/bar" from "subdir/bar.c":
2235 env.Program('/tmp/bar', 'bar.c')
2236 # An initial '#' or '#/' are equivalent; the following
2238 # calls build the programs "foo" and "bar" (in the
2239 # top-level SConstruct directory) from "subdir/foo.c" and
2240 # "subdir/bar.c", respectively:
2241 env.Program('#foo', 'foo.c')
2242 env.Program('#/bar', 'bar.c')
2243 # Builds the program "other/foo" (relative to the top-level
2245 # SConstruct directory) from "subdir/foo.c":
2246 env.Program('#other/foo', 'foo.c')
2247 # This will not work, only SCons interfaces understand '#',
2249 # os.path.exists is pure Python:
2250 if os.path.exists('#inc/foo.h'):
2251 env.Append(CPPPATH='#inc')
2252 When the target shares the same base name as the source and only the
2254 suffix varies, and if the builder method has a suffix defined for the
2255 target file type, then the target argument may be omitted completely,
2256 and scons will deduce the target file name from the source file name.
2257 The following examples all build the executable program bar (on POSIX
2258 systems) or bar.exe (on Windows systems) from the bar.c source file:
2259 env.Program(target='bar', source='bar.c')
2261 env.Program('bar', source='bar.c')
2262 env.Program(source='bar.c')
2263 env.Program('bar.c')
2264 As a convenience, a srcdir keyword argument may be specified when
2266 calling a Builder. When specified, all source file strings that are not
2267 absolute paths or top-relative paths will be interpreted relative to
2268 the specified srcdir. The following example will build the build/prog
2269 (or build/prog.exe on Windows) program from the files src/f1.c and
2270 src/f2.c:
2271 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
2273 Keyword arguments that are not specifically recognized are treated as
2275 construction variable overrides, which replace or add those variables
2276 on a limited basis. These overrides will only be in effect when
2277 building the target of the builder call, and will not affect other
2278 parts of the build. For example, if you want to specify some libraries
2279 needed by just one program:
2280 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
2282 or generate a shared library with a non-standard suffix:
2284 env.SharedLibrary(
2286 target='word',
2287 source='word.cpp',
2288 SHLIBSUFFIX='.ocx',
2289 LIBSUFFIXES=['.ocx'],
2290 )
2291 Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
2293 if you want scons to search automatically for dependencies on the
2294 non-standard library names; see the descriptions below of these
2295 variables for more information.
2296 The optional parse_flags keyword argument is recognized by builders.
2298 This works similarly to the env.MergeFlags method, where the argument
2299 value is broken into individual settings and merged into the
2300 appropriate construction variables.
2301 env = Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
2303 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
2305 to LIBS.
2306 Although the builder methods defined by scons are, in fact, methods of
2308 a construction environment object, many may also be called without an
2309 explicit environment:
2310 Program('hello', 'hello.c')
2312 SharedLibrary('word', 'word.cpp')
2313 If called this way, methods will internally use the default environment
2315 that consists of the tools and values that scons has determined are
2316 appropriate for the local system.
2317 Builder methods that can be called without an explicit environment
2319 (indicated in the listing of builders without a leading env.) may be
2320 called from custom Python modules that you import into an SConscript
2321 file by adding the following to the Python module:
2322 from SCons.Script import *
2324 All builder methods return a list-like object containing Nodes that
2326 will be built. A Node is an internal SCons object which represents
2327 build targets or sources. See the section called “File and Directory
2328 Nodes” for more information.
2329 The returned Node-list object can be passed to other builder methods as
2331 source(s) or passed to any SCons function or method where a filename
2332 would normally be accepted. For example, if it were necessary to add a
2333 specific preprocessor define when compiling one specific object file:
2334 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2336 env.Program(source=['foo.c', bar_obj_list, 'main.c'])
2337 Using a Node in this way makes for a more portable build by avoiding
2339 having to specify a platform-specific object suffix when calling the
2340 Program builder method.
2341 Builder calls will automatically "flatten" lists passed as source and
2343 target, so they are free to contain elements which are themselves
2344 lists, such as bar_obj_list returned by the StaticObject call above. If
2345 you need to manipulate a list of lists returned by builders directly in
2346 Python code, you can either build a new list by hand:
2347 foo = Object('foo.c')
2349 bar = Object('bar.c')
2350 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2351 for obj in objects:
2352 print(str(obj))
2353 Or you can use the Flatten function supplied by scons to create a list
2355 containing just the Nodes, which may be more convenient:
2356 foo = Object('foo.c')
2358 bar = Object('bar.c')
2359 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2360 for obj in objects:
2361 print(str(obj))
2362 SCons builder calls return a list-like object, not an actual Python
2364 list, so it is not appropriate to use the Python add operator (+ or +=)
2365 to append builder results to a Python list. Because the list and the
2366 object are different types, Python will not update the original list in
2367 place, but will instead create a new Node-list object containing the
2368 concatenation of the list elements and the builder results. This will
2369 cause problems for any other Python variables in your SCons
2370 configuration that still hold on to a reference to the original list.
2371 Instead, use the Python list extend method to make sure the list is
2372 updated in-place. Example:
2373 object_files = []
2375 # Do NOT use += here:
2377 # object_files += Object('bar.c')
2378 #
2379 # It will not update the object_files list in place.
2380 #
2381 # Instead, use the list extend method:
2382 object_files.extend(Object('bar.c'))
2383 The path name for a Node's file may be used by passing the Node to
2385 Python's builtin str function:
2386 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2388 print("The path to bar_obj is:", str(bar_obj_list[0]))
2389 Note again that because the Builder call returns a list, we have to
2391 access the first element in the list ((bar_obj_list[0])) to get at the
2392 Node that actually represents the object file.
2393 Builder calls support a chdir keyword argument that specifies that the
2395 Builder's action(s) should be executed after changing directory. If the
2396 chdir argument is a string or a directory Node, scons will change to
2397 the specified directory. If the chdir is not a string or Node and is
2398 non-zero, then scons will change to the target file's directory.
2399 # scons will change to the "sub" subdirectory
2401 # before executing the "cp" command.
2402 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2403 "cp dir/foo.in dir/foo.out",
2404 chdir='sub')
2405 # Because chdir is not a string, scons will change to the
2407 # target's directory ("sub/dir") before executing the
2408 # "cp" command.
2409 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2410 "cp foo.in foo.out",
2411 chdir=1)
2412 Note that SCons will not automatically modify its expansion of
2414 construction variables like $TARGET and $SOURCE when using the chdir
2415 keyword argument--that is, the expanded file names will still be
2416 relative to the top-level directory where SConstruct was found, and
2417 consequently incorrect relative to the chdir directory. If you use the
2418 chdir keyword argument, you will typically need to supply a different
2419 command line using expansions like ${TARGET.file} and ${SOURCE.file} to
2420 use just the filename portion of the targets and source.
2421 scons predefines the following builder methods. Depending on the setup
2423 of a particular construction environment and on the type and software
2424 installation status of the underlying system, not all builders may be
2425 available to that construction environment.
2426 CFile(), env.CFile()
2428 Builds a C source file given a lex (.l) or yacc (.y) input file.
2429 The suffix specified by the $CFILESUFFIX construction variable (.c
2430 by default) is automatically added to the target if it is not
2431 already present. Example:
2432 # builds foo.c
2434 env.CFile(target = 'foo.c', source = 'foo.l')
2435 # builds bar.c
2436 env.CFile(target = 'bar', source = 'bar.y')
2437 Command(), env.Command()
2439 The Command "Builder" is actually a function that looks like a
2440 Builder, but takes a required third argument, which is the action
2441 to take to construct the target from the source, used for "one-off"
2442 builds where a full builder is not needed. Thus it does not follow
2443 the builder calling rules described at the start of this section.
2444 See instead the Command function description for the calling syntax
2445 and details.
2446 CompilationDatabase(), env.CompilationDatabase()
2448 CompilationDatabase is a special builder which adds a target to
2450 create a JSON formatted compilation database compatible with clang
2451 tooling (see the LLVM specification[1]). This database is suitable
2452 for consumption by various tools and editors who can use it to
2453 obtain build and dependency information which otherwise would be
2454 internal to SCons. The builder does not require any source files to
2455 be specified, rather it arranges to emit information about all of
2456 the C, C++ and assembler source/output pairs identified in the
2457 build that are not excluded by the optional filter
2458 $COMPILATIONDB_PATH_FILTER. The target is subject to the usual
2459 SCons target selection rules.
2460 If called with no arguments, the builder will default to a target
2462 name of compile_commands.json.
2463 If called with a single positional argument, scons will "deduce"
2465 the target name from that source argument, giving it the same name,
2466 and then ignore the source. This is the usual way to call the
2467 builder if a non-default target name is wanted.
2468 If called with either the target= or source= keyword arguments, the
2470 value of the argument is taken as the target name. If called with
2471 both, the target= value is used and source= is ignored. If called
2472 with multiple sources, the source list will be ignored, since there
2473 is no way to deduce what the intent was; in this case the default
2474 target name will be used.
2475 Note
2477 You must load the compilation_db tool prior to specifying any
2478 part of your build or some source/output files will not show up
2479 in the compilation database.
2480 Available since scons 4.0.
2481 CXXFile(), env.CXXFile()
2483 Builds a C++ source file given a lex (.ll) or yacc (.yy) input
2484 file. The suffix specified by the $CXXFILESUFFIX construction
2485 variable (.cc by default) is automatically added to the target if
2486 it is not already present. Example:
2487 # builds foo.cc
2489 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
2490 # builds bar.cc
2491 env.CXXFile(target = 'bar', source = 'bar.yy')
2492 DocbookEpub(), env.DocbookEpub()
2494 A pseudo-Builder, providing a Docbook toolchain for EPUB output.
2495 env = Environment(tools=['docbook'])
2497 env.DocbookEpub('manual.epub', 'manual.xml')
2498 or simply
2500 env = Environment(tools=['docbook'])
2502 env.DocbookEpub('manual')
2503 DocbookHtml(), env.DocbookHtml()
2505 A pseudo-Builder, providing a Docbook toolchain for HTML output.
2506 env = Environment(tools=['docbook'])
2508 env.DocbookHtml('manual.html', 'manual.xml')
2509 or simply
2511 env = Environment(tools=['docbook'])
2513 env.DocbookHtml('manual')
2514 DocbookHtmlChunked(), env.DocbookHtmlChunked()
2516 A pseudo-Builder, providing a Docbook toolchain for chunked HTML
2517 output. It supports the base.dir parameter. The chunkfast.xsl file
2518 (requires "EXSLT") is used as the default stylesheet. Basic syntax:
2519 env = Environment(tools=['docbook'])
2521 env.DocbookHtmlChunked('manual')
2522 where manual.xml is the input file.
2524 If you use the root.filename parameter in your own stylesheets you
2526 have to specify the new target name. This ensures that the
2527 dependencies get correct, especially for the cleanup via “scons
2528 -c”:
2529 env = Environment(tools=['docbook'])
2531 env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
2532 Some basic support for the base.dir is provided. You can add the
2534 base_dir keyword to your Builder call, and the given prefix gets
2535 prepended to all the created filenames:
2536 env = Environment(tools=['docbook'])
2538 env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
2539 Make sure that you don't forget the trailing slash for the base
2541 folder, else your files get renamed only!
2542 DocbookHtmlhelp(), env.DocbookHtmlhelp()
2544 A pseudo-Builder, providing a Docbook toolchain for HTMLHELP
2545 output. Its basic syntax is:
2546 env = Environment(tools=['docbook'])
2548 env.DocbookHtmlhelp('manual')
2549 where manual.xml is the input file.
2551 If you use the root.filename parameter in your own stylesheets you
2553 have to specify the new target name. This ensures that the
2554 dependencies get correct, especially for the cleanup via “scons
2555 -c”:
2556 env = Environment(tools=['docbook'])
2558 env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
2559 Some basic support for the base.dir parameter is provided. You can
2561 add the base_dir keyword to your Builder call, and the given prefix
2562 gets prepended to all the created filenames:
2563 env = Environment(tools=['docbook'])
2565 env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
2566 Make sure that you don't forget the trailing slash for the base
2568 folder, else your files get renamed only!
2569 DocbookMan(), env.DocbookMan()
2571 A pseudo-Builder, providing a Docbook toolchain for Man page
2572 output. Its basic syntax is:
2573 env = Environment(tools=['docbook'])
2575 env.DocbookMan('manual')
2576 where manual.xml is the input file. Note, that you can specify a
2578 target name, but the actual output names are automatically set from
2579 the refname entries in your XML source.
2580 DocbookPdf(), env.DocbookPdf()
2582 A pseudo-Builder, providing a Docbook toolchain for PDF output.
2583 env = Environment(tools=['docbook'])
2585 env.DocbookPdf('manual.pdf', 'manual.xml')
2586 or simply
2588 env = Environment(tools=['docbook'])
2590 env.DocbookPdf('manual')
2591 DocbookSlidesHtml(), env.DocbookSlidesHtml()
2593 A pseudo-Builder, providing a Docbook toolchain for HTML slides
2594 output.
2595 env = Environment(tools=['docbook'])
2597 env.DocbookSlidesHtml('manual')
2598 If you use the titlefoil.html parameter in your own stylesheets you
2600 have to give the new target name. This ensures that the
2601 dependencies get correct, especially for the cleanup via “scons
2602 -c”:
2603 env = Environment(tools=['docbook'])
2605 env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
2606 Some basic support for the base.dir parameter is provided. You can
2608 add the base_dir keyword to your Builder call, and the given prefix
2609 gets prepended to all the created filenames:
2610 env = Environment(tools=['docbook'])
2612 env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
2613 Make sure that you don't forget the trailing slash for the base
2615 folder, else your files get renamed only!
2616 DocbookSlidesPdf(), env.DocbookSlidesPdf()
2618 A pseudo-Builder, providing a Docbook toolchain for PDF slides
2619 output.
2620 env = Environment(tools=['docbook'])
2622 env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
2623 or simply
2625 env = Environment(tools=['docbook'])
2627 env.DocbookSlidesPdf('manual')
2628 DocbookXInclude(), env.DocbookXInclude()
2630 A pseudo-Builder, for resolving XIncludes in a separate processing
2631 step.
2632 env = Environment(tools=['docbook'])
2634 env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
2635 DocbookXslt(), env.DocbookXslt()
2637 A pseudo-Builder, applying a given XSL transformation to the input
2638 file.
2639 env = Environment(tools=['docbook'])
2641 env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
2642 Note, that this builder requires the xsl parameter to be set.
2644 DVI(), env.DVI()
2646 Builds a .dvi file from a .tex, .ltx or .latex input file. If the
2647 source file suffix is .tex, scons will examine the contents of the
2648 file; if the string \documentclass or \documentstyle is found, the
2649 file is assumed to be a LaTeX file and the target is built by
2650 invoking the $LATEXCOM command line; otherwise, the $TEXCOM command
2651 line is used. If the file is a LaTeX file, the DVI builder method
2652 will also examine the contents of the .aux file and invoke the
2653 $BIBTEX command line if the string bibdata is found, start
2654 $MAKEINDEX to generate an index if a .ind file is found and will
2655 examine the contents .log file and re-run the $LATEXCOM command if
2656 the log file says it is necessary.
2657 The suffix .dvi (hard-coded within TeX itself) is automatically
2659 added to the target if it is not already present. Examples:
2660 # builds from aaa.tex
2662 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
2663 # builds bbb.dvi
2664 env.DVI(target = 'bbb', source = 'bbb.ltx')
2665 # builds from ccc.latex
2666 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
2667 Gs(), env.Gs()
2669 A Builder for explicitly calling the gs executable. Depending on
2670 the underlying OS, the different names gs, gsos2 and gswin32c are
2671 tried.
2672 env = Environment(tools=['gs'])
2674 env.Gs('cover.jpg','scons-scons.pdf',
2675 GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q')
2676 )
2677 Install(), env.Install()
2679 Installs one or more source files or directories in the specified
2680 target, which must be a directory. The names of the specified
2681 source files or directories remain the same within the destination
2682 directory. The sources may be given as a string or as a node
2683 returned by a builder.
2684 env.Install(target='/usr/local/bin', source=['foo', 'bar'])
2686 Note that if target paths chosen for the Install builder (and the
2688 related InstallAs and InstallVersionedLib builders) are outside the
2689 project tree, such as in the example above, they may not be
2690 selected for "building" by default, since in the absence of other
2691 instructions scons builds targets that are underneath the top
2692 directory (the directory that contains the SConstruct file, usually
2693 the current directory). Use command line targets or the Default
2694 function in this case.
2695 If the --install-sandbox command line option is given, the target
2697 directory will be prefixed by the directory path specified. This is
2698 useful to test installs without installing to a "live" location in
2699 the system.
2700 See also FindInstalledFiles. For more thoughts on installation, see
2702 the User Guide (particularly the section on Command-Line Targets
2703 and the chapters on Installing Files and on Alias Targets).
2704 InstallAs(), env.InstallAs()
2706 Installs one or more source files or directories to specific names,
2707 allowing changing a file or directory name as part of the
2708 installation. It is an error if the target and source arguments
2709 list different numbers of files or directories.
2710 env.InstallAs(target='/usr/local/bin/foo',
2712 source='foo_debug')
2713 env.InstallAs(target=['../lib/libfoo.a', '../lib/libbar.a'],
2714 source=['libFOO.a', 'libBAR.a'])
2715 See the note under Install.
2717 InstallVersionedLib(), env.InstallVersionedLib()
2719 Installs a versioned shared library. The symlinks appropriate to
2720 the architecture will be generated based on symlinks of the source
2721 library.
2722 env.InstallVersionedLib(target='/usr/local/bin/foo',
2724 source='libxyz.1.5.2.so')
2725 See the note under Install.
2727 Jar(), env.Jar()
2729 Builds a Java archive (.jar) file from the specified list of
2730 sources. Any directories in the source list will be searched for
2731 .class files). Any .java files in the source list will be compiled
2732 to .class files by calling the Java Builder.
2733 If the $JARCHDIR value is set, the jar command will change to the
2735 specified directory using the -C option. If $JARCHDIR is not set
2736 explicitly, SCons will use the top of any subdirectory tree in
2737 which Java .class were built by the Java Builder.
2738 If the contents any of the source files begin with the string
2740 Manifest-Version, the file is assumed to be a manifest and is
2741 passed to the jar command with the m option set.
2742 env.Jar(target = 'foo.jar', source = 'classes')
2744 env.Jar(target = 'bar.jar',
2746 source = ['bar1.java', 'bar2.java'])
2747 Java(), env.Java()
2749 Builds one or more Java class files. The sources may be any
2750 combination of explicit .java files, or directory trees which will
2751 be scanned for .java files.
2752 SCons will parse each source .java file to find the classes
2754 (including inner classes) defined within that file, and from that
2755 figure out the target .class files that will be created. The class
2756 files will be placed underneath the specified target directory.
2757 SCons will also search each Java file for the Java package name,
2759 which it assumes can be found on a line beginning with the string
2760 package in the first column; the resulting .class files will be
2761 placed in a directory reflecting the specified package name. For
2762 example, the file Foo.java defining a single public Foo class and
2763 containing a package name of sub.dir will generate a corresponding
2764 sub/dir/Foo.class class file.
2765 Examples:
2767 env.Java(target = 'classes', source = 'src')
2769 env.Java(target = 'classes', source = ['src1', 'src2'])
2770 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
2771 Java source files can use the native encoding for the underlying
2774 OS. Since SCons compiles in simple ASCII mode by default, the
2775 compiler will generate warnings about unmappable characters, which
2776 may lead to errors as the file is processed further. In this case,
2777 the user must specify the LANG environment variable to tell the
2778 compiler what encoding is used. For portibility, it's best if the
2779 encoding is hard-coded so that the compile will work if it is done
2780 on a system with a different encoding.
2781 env = Environment()
2783 env['ENV']['LANG'] = 'en_GB.UTF-8'
2784 JavaH(), env.JavaH()
2787 Builds C header and source files for implementing Java native
2788 methods. The target can be either a directory in which the header
2789 files will be written, or a header file name which will contain all
2790 of the definitions. The source can be the names of .class files,
2791 the names of .java files to be compiled into .class files by
2792 calling the Java builder method, or the objects returned from the
2793 Java builder method.
2794 If the construction variable $JAVACLASSDIR is set, either in the
2796 environment or in the call to the JavaH builder method itself, then
2797 the value of the variable will be stripped from the beginning of
2798 any .class file names.
2799 Examples:
2801 # builds java_native.h
2803 classes = env.Java(target="classdir", source="src")
2804 env.JavaH(target="java_native.h", source=classes)
2805 # builds include/package_foo.h and include/package_bar.h
2807 env.JavaH(target="include", source=["package/foo.class", "package/bar.class"])
2808 # builds export/foo.h and export/bar.h
2810 env.JavaH(
2811 target="export",
2812 source=["classes/foo.class", "classes/bar.class"],
2813 JAVACLASSDIR="classes",
2814 )
2815 Library(), env.Library()
2817 A synonym for the StaticLibrary builder method.
2818 LoadableModule(), env.LoadableModule()
2820 On most systems, this is the same as SharedLibrary. On Mac OS X
2821 (Darwin) platforms, this creates a loadable module bundle.
2822 M4(), env.M4()
2824 Builds an output file from an M4 input file. This uses a default
2825 $M4FLAGS value of -E, which considers all warnings to be fatal and
2826 stops on the first warning when using the GNU version of m4.
2827 Example:
2828 env.M4(target = 'foo.c', source = 'foo.c.m4')
2830 Moc(), env.Moc()
2832 Builds an output file from a moc input file. Moc input files are
2833 either header files or cxx files. This builder is only available
2834 after using the tool 'qt'. See the $QTDIR variable for more
2835 information. Example:
2836 env.Moc('foo.h') # generates moc_foo.cc
2838 env.Moc('foo.cpp') # generates foo.moc
2839 MOFiles(), env.MOFiles()
2841 This builder belongs to msgfmt tool. The builder compiles PO files
2842 to MO files.
2843 Example 1. Create pl.mo and en.mo by compiling pl.po and en.po:
2846 # ...
2848 env.MOFiles(['pl', 'en'])
2849 Example 2. Compile files for languages defined in LINGUAS file:
2852 # ...
2854 env.MOFiles(LINGUAS_FILE = 1)
2855 Example 3. Create pl.mo and en.mo by compiling pl.po and en.po plus
2858 files for languages defined in LINGUAS file:
2859 # ...
2861 env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
2862 Example 4. Compile files for languages defined in LINGUAS file
2865 (another version):
2866 # ...
2868 env['LINGUAS_FILE'] = 1
2869 env.MOFiles()
2870 MSVSProject(), env.MSVSProject()
2872 Builds a Microsoft Visual Studio project file, and by default
2873 builds a solution file as well.
2874 This builds a Visual Studio project file, based on the version of
2876 Visual Studio that is configured (either the latest installed
2877 version, or the version specified by $MSVS_VERSION in the
2878 Environment constructor). For Visual Studio 6, it will generate a
2879 .dsp file. For Visual Studio 7, 8, and 9, it will generate a
2880 .vcproj file. For Visual Studio 10 and later, it will generate a
2881 .vcxproj file.
2882 By default, this also generates a solution file for the specified
2884 project, a .dsw file for Visual Studio 6 or a .sln file for Visual
2885 Studio 7 and later. This behavior may be disabled by specifying
2886 auto_build_solution=0 when you call MSVSProject, in which case you
2887 presumably want to build the solution file(s) by calling the
2888 MSVSSolution Builder (see below).
2889 The MSVSProject builder takes several lists of filenames to be
2891 placed into the project file. These are currently limited to srcs,
2892 incs, localincs, resources, and misc. These are pretty
2893 self-explanatory, but it should be noted that these lists are added
2894 to the $SOURCES construction variable as strings, NOT as SCons File
2895 Nodes. This is because they represent file names to be added to the
2896 project file, not the source files used to build the project file.
2897 The above filename lists are all optional, although at least one
2899 must be specified for the resulting project file to be non-empty.
2900 In addition to the above lists of values, the following values may
2902 be specified:
2903 target
2905 The name of the target .dsp or .vcproj file. The correct suffix
2906 for the version of Visual Studio must be used, but the
2907 $MSVSPROJECTSUFFIX construction variable will be defined to the
2908 correct value (see example below).
2909 variant
2911 The name of this particular variant. For Visual Studio 7
2912 projects, this can also be a list of variant names. These are
2913 typically things like "Debug" or "Release", but really can be
2914 anything you want. For Visual Studio 7 projects, they may also
2915 specify a target platform separated from the variant name by a
2916 | (vertical pipe) character: Debug|Xbox. The default target
2917 platform is Win32. Multiple calls to MSVSProject with different
2918 variants are allowed; all variants will be added to the project
2919 file with their appropriate build targets and sources.
2920 cmdargs
2922 Additional command line arguments for the different variants.
2923 The number of cmdargs entries must match the number of variant
2924 entries, or be empty (not specified). If you give only one, it
2925 will automatically be propagated to all variants.
2926 cppdefines
2928 Preprocessor definitions for the different variants. The number
2929 of cppdefines entries must match the number of variant entries,
2930 or be empty (not specified). If you give only one, it will
2931 automatically be propagated to all variants. If you don't give
2932 this parameter, SCons will use the invoking environment's
2933 CPPDEFINES entry for all variants.
2934 cppflags
2936 Compiler flags for the different variants. If a /std:c++ flag
2937 is found then /Zc:__cplusplus is appended to the flags if not
2938 already found, this ensures that intellisense uses the /std:c++
2939 switch. The number of cppflags entries must match the number of
2940 variant entries, or be empty (not specified). If you give only
2941 one, it will automatically be propagated to all variants. If
2942 you don't give this parameter, SCons will combine the invoking
2943 environment's CCFLAGS, CXXFLAGS, CPPFLAGS entries for all
2944 variants.
2945 cpppaths
2947 Compiler include paths for the different variants. The number
2948 of cpppaths entries must match the number of variant entries,
2949 or be empty (not specified). If you give only one, it will
2950 automatically be propagated to all variants. If you don't give
2951 this parameter, SCons will use the invoking environment's
2952 CPPPATH entry for all variants.
2953 buildtarget
2955 An optional string, node, or list of strings or nodes (one per
2956 build variant), to tell the Visual Studio debugger what output
2957 target to use in what build variant. The number of buildtarget
2958 entries must match the number of variant entries.
2959 runfile
2961 The name of the file that Visual Studio 7 and later will run
2962 and debug. This appears as the value of the Output field in the
2963 resulting Visual Studio project file. If this is not specified,
2964 the default is the same as the specified buildtarget value.
2965 Note that because SCons always executes its build commands from the
2967 directory in which the SConstruct file is located, if you generate
2968 a project file in a different directory than the SConstruct
2969 directory, users will not be able to double-click on the file name
2970 in compilation error messages displayed in the Visual Studio
2971 console output window. This can be remedied by adding the Visual
2972 C/C++ /FC compiler option to the $CCFLAGS variable so that the
2973 compiler will print the full path name of any files that cause
2974 compilation errors.
2975 Example usage:
2977 barsrcs = ['bar.cpp']
2979 barincs = ['bar.h']
2980 barlocalincs = ['StdAfx.h']
2981 barresources = ['bar.rc','resource.h']
2982 barmisc = ['bar_readme.txt']
2983 dll = env.SharedLibrary(target='bar.dll',
2985 source=barsrcs)
2986 buildtarget = [s for s in dll if str(s).endswith('dll')]
2987 env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
2988 srcs=barsrcs,
2989 incs=barincs,
2990 localincs=barlocalincs,
2991 resources=barresources,
2992 misc=barmisc,
2993 buildtarget=buildtarget,
2994 variant='Release')
2995 Starting with version 2.4 of SCons it is also possible to specify
2998 the optional argument DebugSettings, which creates files for
2999 debugging under Visual Studio:
3000 DebugSettings
3002 A dictionary of debug settings that get written to the
3003 .vcproj.user or the .vcxproj.user file, depending on the
3004 version installed. As it is done for cmdargs (see above), you
3005 can specify a DebugSettings dictionary per variant. If you give
3006 only one, it will be propagated to all variants.
3007 Currently, only Visual Studio v9.0 and Visual Studio version v11
3009 are implemented, for other versions no file is generated. To
3010 generate the user file, you just need to add a DebugSettings
3011 dictionary to the environment with the right parameters for your
3012 MSVS version. If the dictionary is empty, or does not contain any
3013 good value, no file will be generated.
3014 Following is a more contrived example, involving the setup of a
3016 project for variants and DebugSettings:
3017 # Assuming you store your defaults in a file
3019 vars = Variables('variables.py')
3020 msvcver = vars.args.get('vc', '9')
3021 # Check command args to force one Microsoft Visual Studio version
3023 if msvcver == '9' or msvcver == '11':
3024 env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False)
3025 else:
3026 env = Environment()
3027 AddOption('--userfile', action='store_true', dest='userfile', default=False,
3029 help="Create Visual Studio Project user file")
3030 #
3032 # 1. Configure your Debug Setting dictionary with options you want in the list
3033 # of allowed options, for instance if you want to create a user file to launch
3034 # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
3035 #
3036 V9DebugSettings = {
3037 'Command':'c:\\myapp\\using\\thisdll.exe',
3038 'WorkingDirectory': 'c:\\myapp\\using\\',
3039 'CommandArguments': '-p password',
3040 # 'Attach':'false',
3041 # 'DebuggerType':'3',
3042 # 'Remote':'1',
3043 # 'RemoteMachine': None,
3044 # 'RemoteCommand': None,
3045 # 'HttpUrl': None,
3046 # 'PDBPath': None,
3047 # 'SQLDebugging': None,
3048 # 'Environment': '',
3049 # 'EnvironmentMerge':'true',
3050 # 'DebuggerFlavor': None,
3051 # 'MPIRunCommand': None,
3052 # 'MPIRunArguments': None,
3053 # 'MPIRunWorkingDirectory': None,
3054 # 'ApplicationCommand': None,
3055 # 'ApplicationArguments': None,
3056 # 'ShimCommand': None,
3057 # 'MPIAcceptMode': None,
3058 # 'MPIAcceptFilter': None,
3059 }
3060 #
3062 # 2. Because there are a lot of different options depending on the Microsoft
3063 # Visual Studio version, if you use more than one version you have to
3064 # define a dictionary per version, for instance if you want to create a user
3065 # file to launch a specific application for testing your dll with Microsoft
3066 # Visual Studio 2012 (v11):
3067 #
3068 V10DebugSettings = {
3069 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
3070 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
3071 'LocalDebuggerCommandArguments': '-p password',
3072 # 'LocalDebuggerEnvironment': None,
3073 # 'DebuggerFlavor': 'WindowsLocalDebugger',
3074 # 'LocalDebuggerAttach': None,
3075 # 'LocalDebuggerDebuggerType': None,
3076 # 'LocalDebuggerMergeEnvironment': None,
3077 # 'LocalDebuggerSQLDebugging': None,
3078 # 'RemoteDebuggerCommand': None,
3079 # 'RemoteDebuggerCommandArguments': None,
3080 # 'RemoteDebuggerWorkingDirectory': None,
3081 # 'RemoteDebuggerServerName': None,
3082 # 'RemoteDebuggerConnection': None,
3083 # 'RemoteDebuggerDebuggerType': None,
3084 # 'RemoteDebuggerAttach': None,
3085 # 'RemoteDebuggerSQLDebugging': None,
3086 # 'DeploymentDirectory': None,
3087 # 'AdditionalFiles': None,
3088 # 'RemoteDebuggerDeployDebugCppRuntime': None,
3089 # 'WebBrowserDebuggerHttpUrl': None,
3090 # 'WebBrowserDebuggerDebuggerType': None,
3091 # 'WebServiceDebuggerHttpUrl': None,
3092 # 'WebServiceDebuggerDebuggerType': None,
3093 # 'WebServiceDebuggerSQLDebugging': None,
3094 }
3095 #
3097 # 3. Select the dictionary you want depending on the version of visual Studio
3098 # Files you want to generate.
3099 #
3100 if not env.GetOption('userfile'):
3101 dbgSettings = None
3102 elif env.get('MSVC_VERSION', None) == '9.0':
3103 dbgSettings = V9DebugSettings
3104 elif env.get('MSVC_VERSION', None) == '11.0':
3105 dbgSettings = V10DebugSettings
3106 else:
3107 dbgSettings = None
3108 #
3110 # 4. Add the dictionary to the DebugSettings keyword.
3111 #
3112 barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
3113 barincs = ['targetver.h']
3114 barlocalincs = ['StdAfx.h']
3115 barresources = ['bar.rc','resource.h']
3116 barmisc = ['ReadMe.txt']
3117 dll = env.SharedLibrary(target='bar.dll',
3119 source=barsrcs)
3120 env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
3122 srcs=barsrcs,
3123 incs=barincs,
3124 localincs=barlocalincs,
3125 resources=barresources,
3126 misc=barmisc,
3127 buildtarget=[dll[0]] * 2,
3128 variant=('Debug|Win32', 'Release|Win32'),
3129 cmdargs='vc=%s' % msvcver,
3130 DebugSettings=(dbgSettings, {}))
3131 MSVSSolution(), env.MSVSSolution()
3134 Builds a Microsoft Visual Studio solution file.
3135 This builds a Visual Studio solution file, based on the version of
3137 Visual Studio that is configured (either the latest installed
3138 version, or the version specified by $MSVS_VERSION in the
3139 construction environment). For Visual Studio 6, it will generate a
3140 .dsw file. For Visual Studio 7 (.NET), it will generate a .sln
3141 file.
3142 The following values must be specified:
3144 target
3146 The name of the target .dsw or .sln file. The correct suffix
3147 for the version of Visual Studio must be used, but the value
3148 $MSVSSOLUTIONSUFFIX will be defined to the correct value (see
3149 example below).
3150 variant
3152 The name of this particular variant, or a list of variant names
3153 (the latter is only supported for MSVS 7 solutions). These are
3154 typically things like "Debug" or "Release", but really can be
3155 anything you want. For MSVS 7 they may also specify target
3156 platform, like this "Debug|Xbox". Default platform is Win32.
3157 projects
3159 A list of project file names, or Project nodes returned by
3160 calls to the MSVSProject Builder, to be placed into the
3161 solution file. It should be noted that these file names are NOT
3162 added to the $SOURCES environment variable in form of files,
3163 but rather as strings. This is because they represent file
3164 names to be added to the solution file, not the source files
3165 used to build the solution file.
3166 Example Usage:
3168 env.MSVSSolution(
3170 target="Bar" + env["MSVSSOLUTIONSUFFIX"],
3171 projects=["bar" + env["MSVSPROJECTSUFFIX"]],
3172 variant="Release",
3173 )
3174 Object(), env.Object()
3177 A synonym for the StaticObject builder method.
3178 Package(), env.Package()
3180 Builds software distribution packages. A Package is a container
3181 format which includes files to install along with metadata.
3182 Packaging is optional, and must be enabled by specifying the
3183 packaging tool. For example:
3184 env = Environment(tools=['default', 'packaging'])
3186 SCons can build packages in a number of well known packaging
3189 formats. The target package type may be selected with the the
3190 $PACKAGETYPE construction variable or the --package-type command
3191 line option. The package type may be a list, in which case SCons
3192 will attempt to build packages for each type in the list. Example:
3193 env.Package(PACKAGETYPE=['src_zip', 'src_targz'], ...other args...)
3195 The currently supported packagers are:
3197 ┌───────────┬────────────────────────────┐
3199 │msi │ Microsoft Installer │
3200 │ │ package │
3201 ├───────────┼────────────────────────────┤
3202 │rpm │ RPM Package Manger package │
3203 ├───────────┼────────────────────────────┤
3204 │ipkg │ Itsy Package Management │
3205 │ │ package │
3206 ├───────────┼────────────────────────────┤
3207 │tarbz2 │ bzip2-compressed tar file │
3208 ├───────────┼────────────────────────────┤
3209 │targz │ gzip-compressed tar file │
3210 ├───────────┼────────────────────────────┤
3211 │tarxz │ xz-compressed tar file │
3212 ├───────────┼────────────────────────────┤
3213 │zip │ zip file │
3214 ├───────────┼────────────────────────────┤
3215 │src_tarbz2 │ bzip2-compressed tar file │
3216 │ │ suitable as source to │
3217 │ │ another packager │
3218 ├───────────┼────────────────────────────┤
3219 │src_targz │ gzip-compressed tar file │
3220 │ │ suitable as source to │
3221 │ │ another packager │
3222 ├───────────┼────────────────────────────┤
3223 │src_tarxz │ xz-compressed tar file │
3224 │ │ suitable as source to │
3225 │ │ another packager │
3226 ├───────────┼────────────────────────────┤
3227 │src_zip │ zip file suitable as │
3228 │ │ source to another packager │
3229 └───────────┴────────────────────────────┘
3230 The file list to include in the package may be specified with the
3231 source keyword argument. If omitted, the FindInstalledFiles
3232 function is called behind the scenes to select all files that have
3233 an Install, InstallAs or InstallVersionedLib Builder attached. If
3234 the target keyword argument is omitted, the target name(s) will be
3235 deduced from the package type(s).
3236 The metadata comes partly from attributes of the files to be
3238 packaged, and partly from packaging tags. Tags can be passed as
3239 keyword arguments to the Package builder call, and may also be
3240 attached to files (or more accurately, Nodes representing files)
3241 with the Tag function. Some package-level tags are mandatory, and
3242 will lead to errors if omitted. The mandatory tags vary depending
3243 on the package type.
3244 While packaging, the builder uses a temporary location named by the
3246 value of the $PACKAGEROOT variable - the package sources are copied
3247 there before packaging.
3248 Packaging example:
3250 env = Environment(tools=["default", "packaging"])
3252 env.Install("/bin/", "my_program")
3253 env.Package(
3254 NAME="foo",
3255 VERSION="1.2.3",
3256 PACKAGEVERSION=0,
3257 PACKAGETYPE="rpm",
3258 LICENSE="gpl",
3259 SUMMARY="balalalalal",
3260 DESCRIPTION="this should be really really long",
3261 X_RPM_GROUP="Application/fu",
3262 SOURCE_URL="http://foo.org/foo-1.2.3.tar.gz",
3263 )
3264 In this example, the target /bin/my_program created by the Install
3266 call would not be built by default since it is not under the
3267 project top directory. However, since no source is specified to the
3268 Package builder, it is selected for packaging by the default
3269 sources rule. Since packaging is done using $PACKAGEROOT, no write
3270 is actually done to the system's /bin directory, and the target
3271 will be selected since after rebasing to underneath $PACKAGEROOT it
3272 is now under the top directory of the project.
3273 PCH(), env.PCH()
3275 Builds a Microsoft Visual C++ precompiled header. Calling this
3276 builder method returns a list of two targets: the PCH as the first
3277 element, and the object file as the second element. Normally the
3278 object file is ignored. This builder method is only provided when
3279 Microsoft Visual C++ is being used as the compiler. The PCH builder
3280 method is generally used in conjunction with the PCH construction
3281 variable to force object files to use the precompiled header:
3282 env['PCH'] = env.PCH('StdAfx.cpp')[0]
3284 PDF(), env.PDF()
3286 Builds a .pdf file from a .dvi input file (or, by extension, a
3287 .tex, .ltx, or .latex input file). The suffix specified by the
3288 $PDFSUFFIX construction variable (.pdf by default) is added
3289 automatically to the target if it is not already present. Example:
3290 # builds from aaa.tex
3292 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
3293 # builds bbb.pdf from bbb.dvi
3294 env.PDF(target = 'bbb', source = 'bbb.dvi')
3295 POInit(), env.POInit()
3297 This builder belongs to msginit tool. The builder initializes
3298 missing PO file(s) if $POAUTOINIT is set. If $POAUTOINIT is not set
3299 (default), POInit prints instruction for user (that is supposed to
3300 be a translator), telling how the PO file should be initialized. In
3301 normal projects you should not use POInit and use POUpdate instead.
3302 POUpdate chooses intelligently between msgmerge(1) and msginit(1).
3303 POInit always uses msginit(1) and should be regarded as builder for
3304 special purposes or for temporary use (e.g. for quick, one time
3305 initialization of a bunch of PO files) or for tests.
3306 Target nodes defined through POInit are not built by default
3308 (they're Ignored from '.' node) but are added to special Alias
3309 ('po-create' by default). The alias name may be changed through the
3310 $POCREATE_ALIAS construction variable. All PO files defined through
3311 POInit may be easily initialized by scons po-create.
3312 Example 1. Initialize en.po and pl.po from messages.pot:
3315 # ...
3317 env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
3318 Example 2. Initialize en.po and pl.po from foo.pot:
3321 # ...
3323 env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
3324 Example 3. Initialize en.po and pl.po from foo.pot but using
3327 $POTDOMAIN construction variable:
3328 # ...
3330 env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
3331 Example 4. Initialize PO files for languages defined in LINGUAS
3334 file. The files will be initialized from template messages.pot:
3335 # ...
3337 env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3338 Example 5. Initialize en.po and pl.pl PO files plus files for
3341 languages defined in LINGUAS file. The files will be initialized
3342 from template messages.pot:
3343 # ...
3345 env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
3346 Example 6. You may preconfigure your environment first, and then
3349 initialize PO files:
3350 # ...
3352 env['POAUTOINIT'] = 1
3353 env['LINGUAS_FILE'] = 1
3354 env['POTDOMAIN'] = 'foo'
3355 env.POInit()
3356 which has same efect as:
3358 # ...
3360 env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
3361 PostScript(), env.PostScript()
3363 Builds a .ps file from a .dvi input file (or, by extension, a .tex,
3364 .ltx, or .latex input file). The suffix specified by the $PSSUFFIX
3365 construction variable (.ps by default) is added automatically to
3366 the target if it is not already present. Example:
3367 # builds from aaa.tex
3369 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
3370 # builds bbb.ps from bbb.dvi
3371 env.PostScript(target = 'bbb', source = 'bbb.dvi')
3372 POTUpdate(), env.POTUpdate()
3374 The builder belongs to xgettext tool. The builder updates target
3375 POT file if exists or creates one if it doesn't. The node is not
3376 built by default (i.e. it is Ignored from '.'), but only on demand
3377 (i.e. when given POT file is required or when special alias is
3378 invoked). This builder adds its targe node (messages.pot, say) to a
3379 special alias (pot-update by default, see $POTUPDATE_ALIAS) so you
3380 can update/create them easily with scons pot-update. The file is
3381 not written until there is no real change in internationalized
3382 messages (or in comments that enter POT file).
3383 Note
3386 You may see xgettext(1) being invoked by the xgettext tool even
3387 if there is no real change in internationalized messages (so
3388 the POT file is not being updated). This happens every time a
3389 source file has changed. In such case we invoke xgettext(1) and
3390 compare its output with the content of POT file to decide
3391 whether the file should be updated or not.
3392 Example 1. Let's create po/ directory and place following
3395 SConstruct script there:
3396 # SConstruct in 'po/' subdir
3398 env = Environment( tools = ['default', 'xgettext'] )
3399 env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
3400 env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
3401 Then invoke scons few times:
3403 user@host:$ scons # Does not create foo.pot nor bar.pot
3405 user@host:$ scons foo.pot # Updates or creates foo.pot
3406 user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
3407 user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
3408 the results shall be as the comments above say.
3410 Example 2. The POTUpdate builder may be used with no target
3413 specified, in which case default target messages.pot will be used.
3414 The default target may also be overridden by setting $POTDOMAIN
3415 construction variable or providing it as an override to POTUpdate
3416 builder:
3417 # SConstruct script
3420 env = Environment( tools = ['default', 'xgettext'] )
3421 env['POTDOMAIN'] = "foo"
3422 env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
3423 env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
3424 Example 3. The sources may be specified within separate file, for
3427 example POTFILES.in:
3428 # POTFILES.in in 'po/' subdirectory
3431 ../a.cpp
3432 ../b.cpp
3433 # end of file
3434 The name of the file (POTFILES.in) containing the list of sources
3436 is provided via $XGETTEXTFROM:
3437 # SConstruct file in 'po/' subdirectory
3440 env = Environment( tools = ['default', 'xgettext'] )
3441 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
3442 Example 4. You may use $XGETTEXTPATH to define source search path.
3445 Assume, for example, that you have files a.cpp, b.cpp,
3446 po/SConstruct, po/POTFILES.in. Then your POT-related files could
3447 look as below:
3448 # POTFILES.in in 'po/' subdirectory
3450 a.cpp
3451 b.cpp
3452 # end of file
3453 # SConstruct file in 'po/' subdirectory
3455 env = Environment( tools = ['default', 'xgettext'] )
3456 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
3457 Example 5. Multiple search directories may be defined within a
3460 list, i.e. XGETTEXTPATH = ['dir1', 'dir2', ...]. The order in the
3461 list determines the search order of source files. The path to the
3462 first file found is used.
3463 Let's create 0/1/po/SConstruct script:
3465 # SConstruct file in '0/1/po/' subdirectory
3467 env = Environment( tools = ['default', 'xgettext'] )
3468 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
3469 and 0/1/po/POTFILES.in:
3471 # POTFILES.in in '0/1/po/' subdirectory
3473 a.cpp
3474 # end of file
3475 Write two *.cpp files, the first one is 0/a.cpp:
3477 /* 0/a.cpp */
3479 gettext("Hello from ../../a.cpp")
3480 and the second is 0/1/a.cpp:
3482 /* 0/1/a.cpp */
3484 gettext("Hello from ../a.cpp")
3485 then run scons. You'll obtain 0/1/po/messages.pot with the message
3487 "Hello from ../a.cpp". When you reverse order in $XGETTEXTFOM, i.e.
3488 when you write SConscript as
3489 # SConstruct file in '0/1/po/' subdirectory
3491 env = Environment( tools = ['default', 'xgettext'] )
3492 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
3493 then the messages.pot will contain msgid "Hello from ../../a.cpp"
3495 line and not msgid "Hello from ../a.cpp".
3496 POUpdate(), env.POUpdate()
3498 The builder belongs to msgmerge tool. The builder updates PO files
3499 with msgmerge(1), or initializes missing PO files as described in
3500 documentation of msginit tool and POInit builder (see also
3501 $POAUTOINIT). Note, that POUpdate does not add its targets to
3502 po-create alias as POInit does.
3503 Target nodes defined through POUpdate are not built by default
3505 (they're Ignored from '.' node). Instead, they are added
3506 automatically to special Alias ('po-update' by default). The alias
3507 name may be changed through the $POUPDATE_ALIAS construction
3508 variable. You can easily update PO files in your project by scons
3509 po-update.
3510 Example 1. Update en.po and pl.po from messages.pot template (see
3513 also $POTDOMAIN), assuming that the later one exists or there is
3514 rule to build it (see POTUpdate):
3515 # ...
3517 env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
3518 Example 2. Update en.po and pl.po from foo.pot template:
3521 # ...
3523 env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
3524 Example 3. Update en.po and pl.po from foo.pot (another version):
3527 # ...
3529 env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
3530 Example 4. Update files for languages defined in LINGUAS file. The
3533 files are updated from messages.pot template:
3534 # ...
3536 env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3537 Example 5. Same as above, but update from foo.pot template:
3540 # ...
3542 env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
3543 Example 6. Update en.po and pl.po plus files for languages defined
3546 in LINGUAS file. The files are updated from messages.pot template:
3547 # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
3549 env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
3550 Example 7. Use $POAUTOINIT to automatically initialize PO file if
3553 it doesn't exist:
3554 # ...
3556 env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
3557 Example 8. Update PO files for languages defined in LINGUAS file.
3560 The files are updated from foo.pot template. All necessary settings
3561 are pre-configured via environment.
3562 # ...
3564 env['POAUTOINIT'] = 1
3565 env['LINGUAS_FILE'] = 1
3566 env['POTDOMAIN'] = 'foo'
3567 env.POUpdate()
3568 Program(), env.Program()
3570 Builds an executable given one or more object files or C, C++, D,
3571 or Fortran source files. If any C, C++, D or Fortran source files
3572 are specified, then they will be automatically compiled to object
3573 files using the Object builder method; see that builder method's
3574 description for a list of legal source file suffixes and how they
3575 are interpreted. The target executable file prefix, specified by
3576 the $PROGPREFIX construction variable (nothing by default), and
3577 suffix, specified by the $PROGSUFFIX construction variable (by
3578 default, .exe on Windows systems, nothing on POSIX systems), are
3579 automatically added to the target if not already present. Example:
3580 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
3582 ProgramAllAtOnce(), env.ProgramAllAtOnce()
3584 Builds an executable from D sources without first creating
3585 individual objects for each file.
3586 D sources can be compiled file-by-file as C and C++ source are, and
3588 D is integrated into the scons Object and Program builders for this
3589 model of build. D codes can though do whole source meta-programming
3590 (some of the testing frameworks do this). For this it is imperative
3591 that all sources are compiled and linked in a single call to the D
3592 compiler. This builder serves that purpose.
3593 env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
3595 This command will compile the modules mod_a, mod_b, and mod_c in a
3598 single compilation process without first creating object files for
3599 the modules. Some of the D compilers will create executable.o
3600 others will not.
3601 RES(), env.RES()
3603 Builds a Microsoft Visual C++ resource file. This builder method is
3604 only provided when Microsoft Visual C++ or MinGW is being used as
3605 the compiler. The .res (or .o for MinGW) suffix is added to the
3606 target name if no other suffix is given. The source file is scanned
3607 for implicit dependencies as though it were a C file. Example:
3608 env.RES('resource.rc')
3610 RMIC(), env.RMIC()
3612 Builds stub and skeleton class files for remote objects from Java
3613 .class files. The target is a directory relative to which the stub
3614 and skeleton class files will be written. The source can be the
3615 names of .class files, or the objects return from the Java builder
3616 method.
3617 If the construction variable $JAVACLASSDIR is set, either in the
3619 environment or in the call to the RMIC builder method itself, then
3620 the value of the variable will be stripped from the beginning of
3621 any .class file names.
3622 classes = env.Java(target = 'classdir', source = 'src')
3624 env.RMIC(target = 'outdir1', source = classes)
3625 env.RMIC(target = 'outdir2',
3627 source = ['package/foo.class', 'package/bar.class'])
3628 env.RMIC(target = 'outdir3',
3630 source = ['classes/foo.class', 'classes/bar.class'],
3631 JAVACLASSDIR = 'classes')
3632 RPCGenClient(), env.RPCGenClient()
3634 Generates an RPC client stub (_clnt.c) file from a specified RPC
3635 (.x) source file. Because rpcgen only builds output files in the
3636 local directory, the command will be executed in the source file's
3637 directory by default.
3638 # Builds src/rpcif_clnt.c
3640 env.RPCGenClient('src/rpcif.x')
3641 RPCGenHeader(), env.RPCGenHeader()
3643 Generates an RPC header (.h) file from a specified RPC (.x) source
3644 file. Because rpcgen only builds output files in the local
3645 directory, the command will be executed in the source file's
3646 directory by default.
3647 # Builds src/rpcif.h
3649 env.RPCGenHeader('src/rpcif.x')
3650 RPCGenService(), env.RPCGenService()
3652 Generates an RPC server-skeleton (_svc.c) file from a specified RPC
3653 (.x) source file. Because rpcgen only builds output files in the
3654 local directory, the command will be executed in the source file's
3655 directory by default.
3656 # Builds src/rpcif_svc.c
3658 env.RPCGenClient('src/rpcif.x')
3659 RPCGenXDR(), env.RPCGenXDR()
3661 Generates an RPC XDR routine (_xdr.c) file from a specified RPC
3662 (.x) source file. Because rpcgen only builds output files in the
3663 local directory, the command will be executed in the source file's
3664 directory by default.
3665 # Builds src/rpcif_xdr.c
3667 env.RPCGenClient('src/rpcif.x')
3668 SharedLibrary(), env.SharedLibrary()
3670 Builds a shared library (.so on a POSIX system, .dll on Windows)
3671 given one or more object files or C, C++, D or Fortran source
3672 files. If any source files are given, then they will be
3673 automatically compiled to object files. The target library file
3674 prefix, specified by the $SHLIBPREFIX construction variable (by
3675 default, lib on POSIX systems, nothing on Windows systems), and
3676 suffix, specified by the $SHLIBSUFFIX construction variable (by
3677 default, .dll on Windows systems, .so on POSIX systems), are
3678 automatically added to the target if not already present. Example:
3679 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
3681 On Windows systems, the SharedLibrary builder method will always
3683 build an import library (.lib) in addition to the shared library
3684 (.dll), adding a .lib library with the same basename if there is
3685 not already a .lib file explicitly listed in the targets.
3686 On Cygwin systems, the SharedLibrary builder method will always
3688 build an import library (.dll.a) in addition to the shared library
3689 (.dll), adding a .dll.a library with the same basename if there is
3690 not already a .dll.a file explicitly listed in the targets.
3691 Any object files listed in the source must have been built for a
3693 shared library (that is, using the SharedObject builder method).
3694 scons will raise an error if there is any mismatch.
3695 On some platforms, there is a distinction between a shared library
3697 (loaded automatically by the system to resolve external references)
3698 and a loadable module (explicitly loaded by user action). For
3699 maximum portability, use the LoadableModule builder for the latter.
3700 When the $SHLIBVERSION construction variable is defined, a
3702 versioned shared library is created. This modifies $SHLINKFLAGS as
3703 required, adds the version number to the library name, and creates
3704 any symbolic links that are needed.
3705 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
3707 On a POSIX system, versions with a single token create exactly one
3709 symlink: libbar.so.6 would have symlink libbar.so only. On a POSIX
3710 system, versions with two or more tokens create exactly two
3711 symlinks: libbar.so.2.3.1 would have symlinks libbar.so and
3712 libbar.so.2; on a Darwin (OSX) system the library would be
3713 libbar.2.3.1.dylib and the link would be libbar.dylib.
3714 On Windows systems, specifying register=1 will cause the .dll to be
3716 registered after it is built. The command that is run is determined
3717 by the $REGSVR construction variable (regsvr32 by default), and the
3718 flags passed are determined by $REGSVRFLAGS. By default,
3719 $REGSVRFLAGS includes the /s option, to prevent dialogs from
3720 popping up and requiring user attention when it is run. If you
3721 change $REGSVRFLAGS, be sure to include the /s option. For example,
3722 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
3724 will register bar.dll as a COM object when it is done linking it.
3726 SharedObject(), env.SharedObject()
3728 Builds an object file intended for inclusion in a shared library.
3729 Source files must have one of the same set of extensions specified
3730 above for the StaticObject builder method. On some platforms
3731 building a shared object requires additional compiler option (e.g.
3732 -fPIC for gcc) in addition to those needed to build a normal
3733 (static) object, but on some platforms there is no difference
3734 between a shared object and a normal (static) one. When there is a
3735 difference, SCons will only allow shared objects to be linked into
3736 a shared library, and will use a different suffix for shared
3737 objects. On platforms where there is no difference, SCons will
3738 allow both normal (static) and shared objects to be linked into a
3739 shared library, and will use the same suffix for shared and normal
3740 (static) objects. The target object file prefix, specified by the
3741 $SHOBJPREFIX construction variable (by default, the same as
3742 $OBJPREFIX), and suffix, specified by the $SHOBJSUFFIX construction
3743 variable, are automatically added to the target if not already
3744 present. Examples:
3745 env.SharedObject(target='ddd', source='ddd.c')
3747 env.SharedObject(target='eee.o', source='eee.cpp')
3748 env.SharedObject(target='fff.obj', source='fff.for')
3749 Note that the source files will be scanned according to the suffix
3751 mappings in the SourceFileScanner object. See the section "Scanner
3752 Objects," below, for more information.
3753 StaticLibrary(), env.StaticLibrary()
3755 Builds a static library given one or more object files or C, C++, D
3756 or Fortran source files. If any source files are given, then they
3757 will be automatically compiled to object files. The static library
3758 file prefix, specified by the $LIBPREFIX construction variable (by
3759 default, lib on POSIX systems, nothing on Windows systems), and
3760 suffix, specified by the $LIBSUFFIX construction variable (by
3761 default, .lib on Windows systems, .a on POSIX systems), are
3762 automatically added to the target if not already present. Example:
3763 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
3765 Any object files listed in the source must have been built for a
3767 static library (that is, using the StaticObject builder method).
3768 scons will raise an error if there is any mismatch.
3769 StaticObject(), env.StaticObject()
3771 Builds a static object file from one or more C, C++, D, or Fortran
3772 source files. Source files must have one of the following
3773 extensions:
3774 .asm assembly language file
3776 .ASM assembly language file
3777 .c C file
3778 .C Windows: C file
3779 POSIX: C++ file
3780 .cc C++ file
3781 .cpp C++ file
3782 .cxx C++ file
3783 .cxx C++ file
3784 .c++ C++ file
3785 .C++ C++ file
3786 .d D file
3787 .f Fortran file
3788 .F Windows: Fortran file
3789 POSIX: Fortran file + C pre-processor
3790 .for Fortran file
3791 .FOR Fortran file
3792 .fpp Fortran file + C pre-processor
3793 .FPP Fortran file + C pre-processor
3794 .m Object C file
3795 .mm Object C++ file
3796 .s assembly language file
3797 .S Windows: assembly language file
3798 ARM: CodeSourcery Sourcery Lite
3799 .sx assembly language file + C pre-processor
3800 POSIX: assembly language file + C pre-processor
3801 .spp assembly language file + C pre-processor
3802 .SPP assembly language file + C pre-processor
3803 The target object file prefix, specified by the $OBJPREFIX
3805 construction variable (nothing by default), and suffix, specified
3806 by the $OBJSUFFIX construction variable (.obj on Windows systems,
3807 .o on POSIX systems), are automatically added to the target if not
3808 already present. Examples:
3809 env.StaticObject(target='aaa', source='aaa.c')
3811 env.StaticObject(target='bbb.o', source='bbb.c++')
3812 env.StaticObject(target='ccc.obj', source='ccc.f')
3813 Note that the source files will be scanned according to the suffix
3815 mappings in the SourceFileScanner object. See the section "Scanner
3816 Objects," below, for more information.
3817 Substfile(), env.Substfile()
3819 The Substfile builder creates a single text file from a template
3820 consisting of a file or set of files (or nodes), replacing text
3821 using the $SUBST_DICT construction variable (if set). If a set,
3822 they are concatenated into the target file using the value of the
3823 $LINESEPARATOR construction variable as a separator between
3824 contents; the separator is not emitted after the contents of the
3825 last file. Nested lists of source files are flattened. See also
3826 Textfile.
3827 If a single source file name is specified and has a .in suffix, the
3829 suffix is stripped and the remainder of the name is used as the
3830 default target name.
3831 The prefix and suffix specified by the $SUBSTFILEPREFIX and
3833 $SUBSTFILESUFFIX construction variables (an empty string by default
3834 in both cases) are automatically added to the target if they are
3835 not already present.
3836 If a construction variable named $SUBST_DICT is present, it may be
3838 either a Python dictionary or a sequence of (key, value) tuples. If
3839 it is a dictionary it is converted into a list of tuples with
3840 unspecified order, so if one key is a prefix of another key or if
3841 one substitution could be further expanded by another subsitition,
3842 it is unpredictable whether the expansion will occur.
3843 Any occurrences of a key in the source are replaced by the
3845 corresponding value, which may be a Python callable function or a
3846 string. If the value is a callable, it is called with no arguments
3847 to get a string. Strings are subst-expanded and the result replaces
3848 the key.
3849 env = Environment(tools=['default'])
3851 env['prefix'] = '/usr/bin'
3853 script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
3854 env.Substfile('script.in', SUBST_DICT=script_dict)
3855 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
3857 env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict)
3858 # UNPREDICTABLE - one key is a prefix of another
3860 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
3861 env.Substfile('foo.in', SUBST_DICT=bad_foo)
3862 # PREDICTABLE - keys are applied longest first
3864 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
3865 env.Substfile('foo.in', SUBST_DICT=good_foo)
3866 # UNPREDICTABLE - one substitution could be futher expanded
3868 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
3869 env.Substfile('bar.in', SUBST_DICT=bad_bar)
3870 # PREDICTABLE - substitutions are expanded in order
3872 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
3873 env.Substfile('bar.in', SUBST_DICT=good_bar)
3874 # the SUBST_DICT may be in common (and not an override)
3876 substutions = {}
3877 subst = Environment(tools=['textfile'], SUBST_DICT=substitutions)
3878 substitutions['@foo@'] = 'foo'
3879 subst['SUBST_DICT']['@bar@'] = 'bar'
3880 subst.Substfile(
3881 'pgm1.c',
3882 [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"],
3883 )
3884 subst.Substfile(
3885 'pgm2.c',
3886 [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"],
3887 )
3888 Tar(), env.Tar()
3891 Builds a tar archive of the specified files and/or directories.
3892 Unlike most builder methods, the Tar builder method may be called
3893 multiple times for a given target; each additional call adds to the
3894 list of entries that will be built into the archive. Any source
3895 directories will be scanned for changes to any on-disk files,
3896 regardless of whether or not scons knows about them from other
3897 Builder or function calls.
3898 env.Tar('src.tar', 'src')
3900 # Create the stuff.tar file.
3902 env.Tar('stuff', ['subdir1', 'subdir2'])
3903 # Also add "another" to the stuff.tar file.
3904 env.Tar('stuff', 'another')
3905 # Set TARFLAGS to create a gzip-filtered archive.
3907 env = Environment(TARFLAGS = '-c -z')
3908 env.Tar('foo.tar.gz', 'foo')
3909 # Also set the suffix to .tgz.
3911 env = Environment(TARFLAGS = '-c -z',
3912 TARSUFFIX = '.tgz')
3913 env.Tar('foo')
3914 Textfile(), env.Textfile()
3916 The Textfile builder generates a single text file from a template
3917 consisting of a list of strings, replacing text using the
3918 $SUBST_DICT construction variable (if set) - see Substfile for a
3919 description of replacement. The strings will be separated in the
3920 target file using the value of the $LINESEPARATOR construction
3921 variable; the line separator is not emitted after the last string.
3922 Nested lists of source strings are flattened. Source strings need
3923 not literally be Python strings: they can be Nodes or Python
3924 objects that convert cleanly to Value nodes
3925 The prefix and suffix specified by the $TEXTFILEPREFIX and
3927 $TEXTFILESUFFIX construction variables (by default an empty string
3928 and .txt, respectively) are automatically added to the target if
3929 they are not already present. Examples:
3930 # builds/writes foo.txt
3932 env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller'])
3933 # builds/writes bar.txt
3935 env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*')
3936 # nested lists are flattened automatically
3938 env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei'])
3939 # files may be used as input by wraping them in File()
3941 env.Textfile(
3942 target='concat', # concatenate files with a marker between
3943 source=[File('concat1'), File('concat2')],
3944 LINESEPARATOR='====================\n',
3945 )
3946 Results:
3948 foo.txt
3950 Goethe
3952 42
3953 Schiller
3954 bar.txt
3956 lalala|*tanteratei
3958 blob.txt
3960 lalala
3962 Goethe
3963 42
3964 Schiller
3965 tanteratei
3966 Translate(), env.Translate()
3968 This pseudo-builder belongs to gettext toolset. The builder
3969 extracts internationalized messages from source files, updates POT
3970 template (if necessary) and then updates PO translations (if
3971 necessary). If $POAUTOINIT is set, missing PO files will be
3972 automatically created (i.e. without translator person
3973 intervention). The variables $LINGUAS_FILE and $POTDOMAIN are taken
3974 into acount too. All other construction variables used by
3975 POTUpdate, and POUpdate work here too.
3976 Example 1. The simplest way is to specify input files and output
3979 languages inline in a SCons script when invoking Translate
3980 # SConscript in 'po/' directory
3982 env = Environment( tools = ["default", "gettext"] )
3983 env['POAUTOINIT'] = 1
3984 env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
3985 Example 2. If you wish, you may also stick to conventional style
3988 known from autotools, i.e. using POTFILES.in and LINGUAS files
3989 # LINGUAS
3991 en pl
3992 #end
3993 # POTFILES.in
3995 a.cpp
3996 b.cpp
3997 # end
3998 # SConscript
4000 env = Environment( tools = ["default", "gettext"] )
4001 env['POAUTOINIT'] = 1
4002 env['XGETTEXTPATH'] = ['../']
4003 env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
4004 The last approach is perhaps the recommended one. It allows easily
4006 split internationalization/localization onto separate SCons
4007 scripts, where a script in source tree is responsible for
4008 translations (from sources to PO files) and script(s) under variant
4009 directories are responsible for compilation of PO to MO files to
4010 and for installation of MO files. The "gluing factor" synchronizing
4011 these two scripts is then the content of LINGUAS file. Note, that
4012 the updated POT and PO files are usually going to be committed back
4013 to the repository, so they must be updated within the source
4014 directory (and not in variant directories). Additionaly, the file
4015 listing of po/ directory contains LINGUAS file, so the source tree
4016 looks familiar to translators, and they may work with the project
4017 in their usual way.
4018 Example 3. Let's prepare a development tree as below
4021 project/
4023 + SConstruct
4024 + build/
4025 + src/
4026 + po/
4027 + SConscript
4028 + SConscript.i18n
4029 + POTFILES.in
4030 + LINGUAS
4031 with build being variant directory. Write the top-level SConstruct
4033 script as follows
4034 # SConstruct
4036 env = Environment( tools = ["default", "gettext"] )
4037 VariantDir('build', 'src', duplicate = 0)
4038 env['POAUTOINIT'] = 1
4039 SConscript('src/po/SConscript.i18n', exports = 'env')
4040 SConscript('build/po/SConscript', exports = 'env')
4041 the src/po/SConscript.i18n as
4043 # src/po/SConscript.i18n
4045 Import('env')
4046 env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
4047 and the src/po/SConscript
4049 # src/po/SConscript
4051 Import('env')
4052 env.MOFiles(LINGUAS_FILE = 1)
4053 Such setup produces POT and PO files under source tree in src/po/
4055 and binary MO files under variant tree in build/po/. This way the
4056 POT and PO files are separated from other output files, which must
4057 not be committed back to source repositories (e.g. MO files).
4058 Note
4061 In above example, the PO files are not updated, nor created
4062 automatically when you issue scons '.' command. The files must
4063 be updated (created) by hand via scons po-update and then MO
4064 files can be compiled by running scons '.'.
4065 TypeLibrary(), env.TypeLibrary()
4067 Builds a Windows type library (.tlb) file from an input IDL file
4068 (.idl). In addition, it will build the associated interface stub
4069 and proxy source files, naming them according to the base name of
4070 the .idl file. For example,
4071 env.TypeLibrary(source="foo.idl")
4073 Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c files.
4075 Uic(), env.Uic()
4077 Builds a header file, an implementation file and a moc file from an
4078 ui file. and returns the corresponding nodes in the above order.
4079 This builder is only available after using the tool 'qt'. Note: you
4080 can specify .ui files directly as source files to the Program,
4081 Library and SharedLibrary builders without using this builder.
4082 Using this builder lets you override the standard naming
4083 conventions (be careful: prefixes are always prepended to names of
4084 built files; if you don't want prefixes, you may set them to ``).
4085 See the $QTDIR variable for more information. Example:
4086 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
4088 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
4089 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
4090 Zip(), env.Zip()
4092 Builds a zip archive of the specified files and/or directories.
4093 Unlike most builder methods, the Zip builder method may be called
4094 multiple times for a given target; each additional call adds to the
4095 list of entries that will be built into the archive. Any source
4096 directories will be scanned for changes to any on-disk files,
4097 regardless of whether or not scons knows about them from other
4098 Builder or function calls.
4099 env.Zip('src.zip', 'src')
4101 # Create the stuff.zip file.
4103 env.Zip('stuff', ['subdir1', 'subdir2'])
4104 # Also add "another" to the stuff.tar file.
4105 env.Zip('stuff', 'another')
4106 All targets of builder methods automatically depend on their sources.
4108 An explicit dependency can be specified using the env.Depends method of
4109 a construction environment (see below).
4110 In addition, scons automatically scans source files for various
4112 programming languages, so the dependencies do not need to be specified
4113 explicitly. By default, SCons can C source files, C++ source files,
4114 Fortran source files with .F (POSIX systems only), .fpp, or .FPP file
4115 extensions, and assembly language files with .S (POSIX systems only),
4116 .spp, or .SPP files extensions for C preprocessor dependencies. SCons
4117 also has default support for scanning D source files, You can also
4118 write your own Scanners to add support for additional source file
4119 types. These can be added to the default Scanner object used by the
4120 Object, StaticObject and SharedObject Builders by adding them to the
4121 SourceFileScanner object. See the section called “Scanner Objects” for
4122 more information about defining your own Scanner objects and using the
4123 SourceFileScanner object.
4124 Methods and Functions To Do Things
4126 In addition to Builder methods, scons provides a number of other
4127 construction environment methods and global functions to manipulate the
4128 build configuration.
4129 Usually, a construction environment method and global function with the
4131 same name both exist for convenience. In the following list, the global
4132 function is documented in this style:
4133 Function(arguments, [optional arguments])
4135 and the construction environment method looks like:
4137 env.Function(arguments, [optional arguments])
4139 If the function can be called both ways, then both forms are listed.
4141 The global function and same-named construction environment method
4143 provide almost identical functionality, with a couple of exceptions.
4144 First, many of the construction environment methods affect only that
4145 construction environment, while the global function has a global
4146 effect. Second, where appropriate, calling the functionality through a
4147 construction environment will substitute construction variables into
4148 any supplied string arguments, while the global function doesn't have
4149 the context of a construction environment to pick variables from, so it
4150 cannot perform the substitution. For example:
4151 Default('$FOO')
4153 env = Environment(FOO='foo')
4155 env.Default('$FOO')
4156 In the above example, the call to the global Default function will add
4158 a target named $FOO to the list of default targets, while the call to
4159 the env.Default construction environment method will expand the value
4160 and add a target named foo to the list of default targets. For more on
4161 construction variable expansion, see the next section on construction
4162 variables.
4163 Global functions may be called from custom Python modules that you
4165 import into an SConscript file by adding the following import to the
4166 Python module:
4167 from SCons.Script import *
4169 Construction environment methods and global functions provided by scons
4171 include:
4172 Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]),
4174 env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])
4175 A factory function to create an Action object for the specified
4176 action. See the manpage section "Action Objects" for a complete
4177 explanation of the arguments and behavior.
4178 Note that the env.Action form of the invocation will expand
4180 construction variables in any argument strings, including the
4181 action argument, at the time it is called using the construction
4182 variables in the env construction environment through which
4183 env.Action was called. The Action global function form delays all
4184 variable expansion until the Action object is actually used.
4185 AddMethod(object, function, [name]), env.AddMethod(function, [name])
4187 Adds function to an object as a method. function will be called
4188 with an instance object as the first argument as for other methods.
4189 If name is given, it is used as the name of the new method, else
4190 the name of function is used.
4191 When the global function AddMethod is called, the object to add the
4193 method to must be passed as the first argument; typically this will
4194 be Environment, in order to create a method which applies to all
4195 construction environments subsequently constructed. When called
4196 using the env.AddMethod form, the method is added to the specified
4197 construction environment only. Added methods propagate through
4198 env.Clone calls.
4199 Examples:
4201 # Function to add must accept an instance argument.
4203 # The Python convention is to call this 'self'.
4204 def my_method(self, arg):
4205 print("my_method() got", arg)
4206 # Use the global function to add a method to the Environment class:
4208 AddMethod(Environment, my_method)
4209 env = Environment()
4210 env.my_method('arg')
4211 # Use the optional name argument to set the name of the method:
4213 env.AddMethod(my_method, 'other_method_name')
4214 env.other_method_name('another arg')
4215 AddOption(arguments)
4217 Adds a local (project-specific) command-line option. arguments are
4218 the same as those supported by the add_option method in the
4219 standard Python library module optparse, with a few additional
4220 capabilities noted below. See the documentation for optparse for a
4221 thorough discussion of its option-processing capabities.
4222 In addition to the arguments and values supported by the optparse
4224 add_option method, AddOption allows setting the nargs keyword value
4225 to a string consisting of a question mark ('?') to indicate that
4226 the option argument for that option string is optional. If the
4227 option string is present on the command line but has no matching
4228 option argument, the value of the const keyword argument is
4229 produced as the value of the option. If the option string is
4230 omitted from the command line, the value of the default keyword
4231 argument is produced, as usual; if there is no default keyword
4232 argument in the AddOption call, None is produced.
4233 optparse recognizes abbreviations of long option names, as long as
4236 they can be unambiguously resolved. For example, if add_option is
4237 called to define a --devicename option, it will recognize --device,
4238 --dev and so forth as long as there is no other option which could
4239 also match to the same abbreviation. Options added via AddOption do
4240 not support the automatic recognition of abbreviations. Instead, to
4241 allow specific abbreviations, include them as synonyms in the
4242 AddOption call itself.
4243 Once a new command-line option has been added with AddOption, the
4245 option value may be accessed using GetOption or env.GetOption.
4246 SetOption is not currently supported for options added with
4247 AddOption.
4248 Help text for an option is a combination of the string supplied in
4250 the help keyword argument to AddOption and information collected
4251 from the other keyword arguments. Such help is displayed if the -h
4252 command line option is used (but not with -H). Help for all local
4253 options is displayed under the separate heading Local Options. The
4254 options are unsorted - they will appear in the help text in the
4255 order in which the AddOption calls occur.
4256 Example:
4258 AddOption(
4260 '--prefix',
4261 dest='prefix',
4262 nargs=1,
4263 type='string',
4264 action='store',
4265 metavar='DIR',
4266 help='installation prefix',
4267 )
4268 env = Environment(PREFIX=GetOption('prefix'))
4269 For that example, the following help text would be produced:
4271 Local Options:
4273 --prefix=DIR installation prefix
4274 Help text for local options may be unavailable if the Help function
4276 has been called, see the Help documentation for details.
4277 Note
4279 As an artifact of the internal implementation, the behavior of
4280 options added by AddOption which take option arguments is
4281 undefined if whitespace (rather than an = sign) is used as the
4282 separator on the command line. Users should avoid such usage;
4283 it is recommended to add a note to this effect to project
4284 documentation if the situation is likely to arise. In addition,
4285 if the nargs keyword is used to specify more than one following
4286 option argument (that is, with a value of 2 or greater), such
4287 arguments would necessarily be whitespace separated, triggering
4288 the issue. Developers should not use AddOption this way. Future
4289 versions of SCons will likely forbid such usage.
4290 AddPostAction(target, action), env.AddPostAction(target, action)
4292 Arranges for the specified action to be performed after the
4293 specified target has been built. The specified action(s) may be an
4294 Action object, or anything that can be converted into an Action
4295 object See the manpage section "Action Objects" for a complete
4296 explanation.
4297 When multiple targets are supplied, the action may be called
4299 multiple times, once after each action that generates one or more
4300 targets in the list.
4301 AddPreAction(target, action), env.AddPreAction(target, action)
4303 Arranges for the specified action to be performed before the
4304 specified target is built. The specified action(s) may be an Action
4305 object, or anything that can be converted into an Action object See
4306 the manpage section "Action Objects" for a complete explanation.
4307 When multiple targets are specified, the action(s) may be called
4309 multiple times, once before each action that generates one or more
4310 targets in the list.
4311 Note that if any of the targets are built in multiple steps, the
4313 action will be invoked just before the "final" action that
4314 specifically generates the specified target(s). For example, when
4315 building an executable program from a specified source .c file via
4316 an intermediate object file:
4317 foo = Program('foo.c')
4319 AddPreAction(foo, 'pre_action')
4320 The specified pre_action would be executed before scons calls the
4322 link command that actually generates the executable program binary
4323 foo, not before compiling the foo.c file into an object file.
4324 Alias(alias, [targets, [action]]), env.Alias(alias, [targets,
4326 [action]])
4327 Creates one or more phony targets that expand to one or more other
4328 targets. An optional action (command) or list of actions can be
4329 specified that will be executed whenever the any of the alias
4330 targets are out-of-date. Returns the Node object representing the
4331 alias, which exists outside of any file system. This Node object,
4332 or the alias name, may be used as a dependency of any other target,
4333 including another alias. Alias can be called multiple times for
4334 the same alias to add additional targets to the alias, or
4335 additional actions to the list for this alias. Aliases are global
4336 even if set through the construction environment method.
4337 Examples:
4339 Alias('install')
4341 Alias('install', '/usr/bin')
4342 Alias(['install', 'install-lib'], '/usr/local/lib')
4343 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
4345 env.Alias('install', ['/usr/local/man'])
4346 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
4348 AllowSubstExceptions([exception, ...])
4350 Specifies the exceptions that will be allowed when expanding
4351 construction variables. By default, any construction variable
4352 expansions that generate a NameError or IndexError exception will
4353 expand to a '' (an empty string) and not cause scons to fail. All
4354 exceptions not in the specified list will generate an error message
4355 and terminate processing.
4356 If AllowSubstExceptions is called multiple times, each call
4358 completely overwrites the previous list of allowed exceptions.
4359 Example:
4361 # Requires that all construction variable names exist.
4363 # (You may wish to do this if you want to enforce strictly
4364 # that all construction variables must be defined before use.)
4365 AllowSubstExceptions()
4366 # Also allow a string containing a zero-division expansion
4368 # like '${1 / 0}' to evalute to ''.
4369 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
4370 AlwaysBuild(target, ...), env.AlwaysBuild(target, ...)
4372 Marks each given target so that it is always assumed to be out of
4373 date, and will always be rebuilt if needed. Note, however, that
4374 AlwaysBuild does not add its target(s) to the default target list,
4375 so the targets will only be built if they are specified on the
4376 command line, or are a dependent of a target specified on the
4377 command line--but they will always be built if so specified.
4378 Multiple targets can be passed in to a single call to AlwaysBuild.
4379 env.Append(key=val, [...])
4381 Appends the specified keyword arguments to the end of construction
4382 variables in the environment. If the Environment does not have the
4383 specified construction variable, it is simply added to the
4384 environment. If the values of the construction variable and the
4385 keyword argument are the same type, then the two values will be
4386 simply added together. Otherwise, the construction variable and the
4387 value of the keyword argument are both coerced to lists, and the
4388 lists are added together. (See also the Prepend method).
4389 Example:
4391 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
4393 env.AppendENVPath(name, newpath, [envname, sep, delete_existing])
4395 This appends new path elements to the given path in the specified
4396 external environment (ENV by default). This will only add any
4397 particular path once (leaving the last one it encounters and
4398 ignoring the rest, to preserve path order), and to help assure
4399 this, will normalize all paths (using os.path.normpath and
4400 os.path.normcase). This can also handle the case where the given
4401 old path variable is a list instead of a string, in which case a
4402 list will be returned instead of a string.
4403 If delete_existing is 0, then adding a path that already exists
4405 will not move it to the end; it will stay where it is in the list.
4406 Example:
4408 print 'before:',env['ENV']['INCLUDE']
4410 include_path = '/foo/bar:/foo'
4411 env.AppendENVPath('INCLUDE', include_path)
4412 print 'after:',env['ENV']['INCLUDE']
4413 yields:
4415 before: /foo:/biz
4416 after: /biz:/foo/bar:/foo
4417 env.AppendUnique(key=val, [...], delete_existing=0)
4419 Appends the specified keyword arguments to the end of construction
4420 variables in the environment. If the Environment does not have the
4421 specified construction variable, it is simply added to the
4422 environment. If the construction variable being appended to is a
4423 list, then any value(s) that already exist in the construction
4424 variable will not be added again to the list. However, if
4425 delete_existing is 1, existing matching values are removed first,
4426 so existing values in the arg list move to the end of the list.
4427 Example:
4429 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4431 Builder(action, [arguments]), env.Builder(action, [arguments])
4433 Creates a Builder object for the specified action. See the manpage
4434 section "Builder Objects" for a complete explanation of the
4435 arguments and behavior.
4436 Note that the env.Builder() form of the invocation will expand
4438 construction variables in any arguments strings, including the
4439 action argument, at the time it is called using the construction
4440 variables in the env construction environment through which
4441 env.Builder was called. The Builder form delays all variable
4442 expansion until after the Builder object is actually called.
4443 CacheDir(cache_dir), env.CacheDir(cache_dir)
4445 Direct scons to maintain a derived-file cache in cache_dir. The
4446 derived files in the cache will be shared among all the builds
4447 specifying the same cache_dir. Specifying a cache_dir of None
4448 disables derived file caching.
4449 Calling the environment method env.CacheDir limits the effect to
4451 targets built through the specified construction environment.
4452 Calling the global function CacheDir sets a global default that
4453 will be used by all targets built through construction environments
4454 that do not set up environment-specific caching by calling
4455 env.CacheDir.
4456 When derived-file caching is being used and scons finds a derived
4458 file that needs to be rebuilt, it will first look in the cache to
4459 see if a file with matching build signature exists (indicating the
4460 input file(s) and build action(s) were identical to those for the
4461 current target), and if so, will retrieve the file from the cache.
4462 scons will report Retrieved `file' from cache instead of the normal
4463 build message. If the derived file is not present in the cache,
4464 scons will build it and then place a copy of the built file in the
4465 cache, identified by its build signature, for future use.
4466 The Retrieved `file' from cache messages are useful for human
4468 consumption, but less so when comparing log files between scons
4469 runs which will show differences that are noisy and not actually
4470 significant. To disable, use the --cache-show option. With this
4471 option, scons will print the action that would have been used to
4472 build the file without considering cache retrieval.
4473 Derived-file caching may be disabled for any invocation of scons by
4475 giving the --cache-disable command line option. Cache updating may
4476 be disabled, leaving cache fetching enabled, by giving the
4477 --cache-readonly.
4478 If the --cache-force option is used, scons will place a copy of all
4480 derived files in the cache, even if they already existed and were
4481 not built by this invocation. This is useful to populate a cache
4482 the first time a cache_dir is used for a build, or to bring a cache
4483 up to date after a build with cache updating disabled
4484 (--cache-disable or --cache-readonly) has been done.
4485 The NoCache method can be used to disable caching of specific
4487 files. This can be useful if inputs and/or outputs of some tool are
4488 impossible to predict or prohibitively large.
4489 Clean(targets, files_or_dirs), env.Clean(targets, files_or_dirs)
4491 This specifies a list of files or directories which should be
4492 removed whenever the targets are specified with the -c command line
4493 option. The specified targets may be a list or an individual
4494 target. Multiple calls to Clean are legal, and create new targets
4495 or add files and directories to the clean list for the specified
4496 targets.
4497 Multiple files or directories should be specified either as
4499 separate arguments to the Clean method, or as a list. Clean will
4500 also accept the return value of any of the construction environment
4501 Builder methods. Examples:
4502 The related NoClean function overrides calling Clean for the same
4504 target, and any targets passed to both functions will not be
4505 removed by the -c option.
4506 Examples:
4508 Clean('foo', ['bar', 'baz'])
4510 Clean('dist', env.Program('hello', 'hello.c'))
4511 Clean(['foo', 'bar'], 'something_else_to_clean')
4512 In this example, installing the project creates a subdirectory for
4514 the documentation. This statement causes the subdirectory to be
4515 removed if the project is deinstalled.
4516 Clean(docdir, os.path.join(docdir, projectname))
4518 env.Clone([key=val, ...])
4520 Returns a separate copy of a construction environment. If there are
4521 any keyword arguments specified, they are added to the returned
4522 copy, overwriting any existing values for the keywords.
4523 Example:
4525 env2 = env.Clone()
4527 env3 = env.Clone(CCFLAGS = '-g')
4528 Additionally, a list of tools and a toolpath may be specified, as
4530 in the Environment constructor:
4531 def MyTool(env): env['FOO'] = 'bar'
4533 env4 = env.Clone(tools = ['msvc', MyTool])
4534 The parse_flags keyword argument is also recognized to allow
4536 merging command-line style arguments into the appropriate
4537 construction variables (see env.MergeFlags).
4538 # create an environment for compiling programs that use wxWidgets
4540 wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
4541 Command(target, source, action, [key=val, ...]), env.Command(target,
4543 source, action, [key=val, ...])
4544 Executes a specific action (or list of actions) to build a target
4545 file or files from a source file or files. This is more convenient
4546 than defining a separate Builder object for a single special-case
4547 build.
4548 The Command function accepts source_scanner, target_scanner,
4550 source_factory, and target_factory keyword arguments. These
4551 arguments can be used to specify a Scanner object that will be used
4552 to apply a custom scanner for a source or target. For example, the
4553 global DirScanner object can be used if any of the sources will be
4554 directories that must be scanned on-disk for changes to files that
4555 aren't already specified in other Builder of function calls. The
4556 *_factory arguments take a factory function that Command will use
4557 to turn any sources or targets specified as strings into SCons
4558 Nodes. See the manpage section "Builder Objects" for more
4559 information about how these arguments work in a Builder.
4560 Any other keyword arguments specified override any same-named
4562 existing construction variables.
4563 An action can be an external command, specified as a string, or a
4565 callable Python object; see the manpage section "Action Objects"
4566 for more complete information. Also note that a string specifying
4567 an external command may be preceded by an at-sign (@) to suppress
4568 printing the command in question, or by a hyphen (-) to ignore the
4569 exit status of the external command.
4570 Examples:
4572 env.Command(
4574 target='foo.out',
4575 source='foo.in',
4576 action="$FOO_BUILD < $SOURCES > $TARGET"
4577 )
4578 env.Command(
4580 target='bar.out',
4581 source='bar.in',
4582 action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"],
4583 ENV={'PATH': '/usr/local/bin/'},
4584 )
4585 import os
4588 def rename(env, target, source):
4589 os.rename('.tmp', str(target[0]))
4590 env.Command(
4593 target='baz.out',
4594 source='baz.in',
4595 action=["$BAZ_BUILD < $SOURCES > .tmp", rename],
4596 )
4597 Note that the Command function will usually assume, by default,
4599 that the specified targets and/or sources are Files, if no other
4600 part of the configuration identifies what type of entries they are.
4601 If necessary, you can explicitly specify that targets or source
4602 nodes should be treated as directories by using the Dir or env.Dir
4603 functions.
4604 Examples:
4606 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
4608 env['DISTDIR'] = 'destination/directory'
4610 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
4611 Also note that SCons will usually automatically create any
4613 directory necessary to hold a target file, so you normally don't
4614 need to create directories by hand.
4615 Configure(env, [custom_tests, conf_dir, log_file, config_h]),
4617 env.Configure([custom_tests, conf_dir, log_file, config_h])
4618 Creates a Configure object for integrated functionality similar to
4619 GNU autoconf. See the manpage section "Configure Contexts" for a
4620 complete explanation of the arguments and behavior.
4621 Decider(function), env.Decider(function)
4623 Specifies that all up-to-date decisions for targets built through
4624 this construction environment will be handled by the specified
4625 function. function can be the name of a function or one of the
4626 following strings that specify the predefined decision function
4627 that will be applied:
4628 "timestamp-newer"
4630 Specifies that a target shall be considered out of date and
4631 rebuilt if the dependency's timestamp is newer than the target
4632 file's timestamp. This is the behavior of the classic Make
4633 utility, and make can be used a synonym for timestamp-newer.
4634 "timestamp-match"
4636 Specifies that a target shall be considered out of date and
4637 rebuilt if the dependency's timestamp is different than the
4638 timestamp recorded the last time the target was built. This
4639 provides behavior very similar to the classic Make utility (in
4640 particular, files are not opened up so that their contents can
4641 be checksummed) except that the target will also be rebuilt if
4642 a dependency file has been restored to a version with an
4643 earlier timestamp, such as can happen when restoring files from
4644 backup archives.
4645 "MD5"
4647 Specifies that a target shall be considered out of date and
4648 rebuilt if the dependency's content has changed since the last
4649 time the target was built, as determined be performing an MD5
4650 checksum on the dependency's contents and comparing it to the
4651 checksum recorded the last time the target was built. content
4652 can be used as a synonym for MD5.
4653 "MD5-timestamp"
4655 Specifies that a target shall be considered out of date and
4656 rebuilt if the dependency's content has changed since the last
4657 time the target was built, except that dependencies with a
4658 timestamp that matches the last time the target was rebuilt
4659 will be assumed to be up-to-date and not rebuilt. This provides
4660 behavior very similar to the MD5 behavior of always
4661 checksumming file contents, with an optimization of not
4662 checking the contents of files whose timestamps haven't
4663 changed. The drawback is that SCons will not detect if a file's
4664 content has changed but its timestamp is the same, as might
4665 happen in an automated script that runs a build, updates a
4666 file, and runs the build again, all within a single second.
4667 Examples:
4669 # Use exact timestamp matches by default.
4671 Decider('timestamp-match')
4672 # Use MD5 content signatures for any targets built
4674 # with the attached construction environment.
4675 env.Decider('content')
4676 In addition to the above already-available functions, the function
4678 argument may be a Python function you supply. Such a function must
4679 accept the following four arguments:
4680 dependency
4682 The Node (file) which should cause the target to be rebuilt if
4683 it has "changed" since the last tme target was built.
4684 target
4686 The Node (file) being built. In the normal case, this is what
4687 should get rebuilt if the dependency has "changed."
4688 prev_ni
4690 Stored information about the state of the dependency the last
4691 time the target was built. This can be consulted to match
4692 various file characteristics such as the timestamp, size, or
4693 content signature.
4694 repo_node
4696 If set, use this Node instead of the one specified by
4697 dependency to determine if the dependency has changed. This
4698 argument is optional so should be written as a default argument
4699 (typically it would be written as repo_node=None). A caller
4700 will normally only set this if the target only exists in a
4701 Repository.
4702 The function should return a value which evaluates True if the
4704 dependency has "changed" since the last time the target was built
4705 (indicating that the target should be rebuilt), and a value which
4706 evaluates False otherwise (indicating that the target should not be
4707 rebuilt). Note that the decision can be made using whatever
4708 criteria are appopriate. Ignoring some or all of the function
4709 arguments is perfectly normal.
4710 Example:
4712 def my_decider(dependency, target, prev_ni, repo_node=None):
4714 return not os.path.exists(str(target))
4715 env.Decider(my_decider)
4717 Default(targets...), env.Default(targets...)
4719 This specifies a list of default targets, which will be built by
4720 scons if no explicit targets are given on the command line.
4721 Multiple calls to Default are legal, and add to the list of default
4722 targets. As noted above, both forms of this call affect the same
4723 global list of default targets; the construction environment method
4724 applies construction variable expansion to the targets.
4725 Multiple targets should be specified as separate arguments to the
4727 Default method, or as a list. Default will also accept the Node
4728 returned by any of a construction environment's builder methods.
4729 Examples:
4731 Default('foo', 'bar', 'baz')
4733 env.Default(['a', 'b', 'c'])
4734 hello = env.Program('hello', 'hello.c')
4735 env.Default(hello)
4736 An argument to Default of None will clear all default targets.
4738 Later calls to Default will add to the (now empty) default-target
4739 list like normal.
4740 The current list of targets added using the Default function or
4742 method is available in the DEFAULT_TARGETS list; see below.
4743 DefaultEnvironment([**kwargs])
4745 Instantiates and returns the default construction environment
4746 object. The default environment is used internally by SCons in
4747 order to execute many of the global functions in this list (that
4748 is, those not called as methods of a specific construction
4749 environment). It is not mandatory to call DefaultEnvironment: the
4750 default environment will be instantiated automatically when the
4751 build phase begins if the function has not been called, however
4752 calling it explicitly gives the opportunity to affect and examine
4753 the contents of the default environment.
4754 The default environment is a singleton, so the keyword arguments
4756 affect it only on the first call, on subsequent calls the
4757 already-constructed object is returned and any keyword arguments
4758 are silently ignored. The default environment can be modified after
4759 instantiation in the same way as any construction environment.
4760 Modifying the default environment has no effect on the construction
4761 environment constructed by an Environment or Clone call.
4762 Depends(target, dependency), env.Depends(target, dependency)
4764 Specifies an explicit dependency; the target will be rebuilt
4765 whenever the dependency has changed. Both the specified target and
4766 dependency can be a string (usually the path name of a file or
4767 directory) or Node objects, or a list of strings or Node objects
4768 (such as returned by a Builder call). This should only be necessary
4769 for cases where the dependency is not caught by a Scanner for the
4770 file.
4771 Example:
4773 env.Depends('foo', 'other-input-file-for-foo')
4775 mylib = env.Library('mylib.c')
4777 installed_lib = env.Install('lib', mylib)
4778 bar = env.Program('bar.c')
4779 # Arrange for the library to be copied into the installation
4781 # directory before trying to build the "bar" program.
4782 # (Note that this is for example only. A "real" library
4783 # dependency would normally be configured through the $LIBS
4784 # and $LIBPATH variables, not using an env.Depends() call.)
4785 env.Depends(bar, installed_lib)
4787 env.Detect(progs)
4789 Find an executable from one or more choices: progs may be a string
4790 or a list of strings. Returns the first value from progs that was
4791 found, or None. Executable is searched by checking the paths
4792 specified by env['ENV']['PATH']. On Windows systems, additionally
4793 applies the filename suffixes found in env['ENV']['PATHEXT'] but
4794 will not include any such extension in the return value.
4795 env.Detect is a wrapper around env.WhereIs.
4796 env.Dictionary([vars])
4798 Returns a dictionary object containing the construction variables
4799 in the construction environment. If there are any arguments
4800 specified, the values of the specified construction variables are
4801 returned as a string (if one argument) or as a list of strings.
4802 Example:
4804 cvars = env.Dictionary()
4806 cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
4807 Dir(name, [directory]), env.Dir(name, [directory])
4809 Returns Directory Node(s). A Directory Node is an object that
4810 represents a directory. name can be a relative or absolute path or
4811 a list of such paths. directory is an optional directory that will
4812 be used as the parent directory. If no directory is specified, the
4813 current script's directory is used as the parent.
4814 If name is a single pathname, the corresponding node is returned.
4816 If name is a list, SCons returns a list of nodes. Construction
4817 variables are expanded in name.
4818 Directory Nodes can be used anywhere you would supply a string as a
4820 directory name to a Builder method or function. Directory Nodes
4821 have attributes and methods that are useful in many situations; see
4822 manpage section "File and Directory Nodes" for more information.
4823 env.Dump([key], [format])
4825 Serializes construction variables to a string. The method supports
4826 the following formats specified by format:
4827 pretty
4829 Returns a pretty printed representation of the environment (if
4830 format is not specified, this is the default).
4831 json
4833 Returns a JSON-formatted string representation of the
4834 environment.
4835 If key is None (the default) the entire dictionary of construction
4837 variables is serialized. If supplied, it is taken as the name of a
4838 construction variable whose value is serialized.
4839 This SConstruct:
4841 env=Environment()
4843 print(env.Dump('CCCOM'))
4844 will print:
4846 '$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
4848 While this SConstruct:
4850 env=Environment()
4852 print(env.Dump())
4853 will print:
4855 { 'AR': 'ar',
4857 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
4858 'ARFLAGS': ['r'],
4859 'AS': 'as',
4860 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
4861 'ASFLAGS': [],
4862 ...
4863 EnsurePythonVersion(major, minor), env.EnsurePythonVersion(major,
4865 minor)
4866 Ensure that the Python version is at least major.minor. This
4867 function will print out an error message and exit SCons with a
4868 non-zero exit code if the actual Python version is not late enough.
4869 Example:
4871 EnsurePythonVersion(2,2)
4873 EnsureSConsVersion(major, minor, [revision]),
4875 env.EnsureSConsVersion(major, minor, [revision])
4876 Ensure that the SCons version is at least major.minor, or
4877 major.minor.revision. if revision is specified. This function will
4878 print out an error message and exit SCons with a non-zero exit code
4879 if the actual SCons version is not late enough.
4880 Examples:
4882 EnsureSConsVersion(0,14)
4884 EnsureSConsVersion(0,96,90)
4886 Environment([key=value, ...]), env.Environment([key=value, ...])
4888 Return a new construction environment initialized with the
4889 specified key=value pairs. The keyword arguments parse_flags,
4890 platform, toolpath, tools and variables are also specially
4891 recognized. See the manpage section "Construction Environments" for
4892 more details.
4893 Execute(action, [strfunction, varlist]), env.Execute(action,
4895 [strfunction, varlist])
4896 Executes an Action object. The specified action may be an Action
4897 object (see manpage section "Action Objects" for an explanation of
4898 behavior), or it may be a command-line string, list of commands, or
4899 executable Python function, each of which will be converted into an
4900 Action object and then executed. Any additional arguments to
4901 Execute (strfunction, varlist) are passed on to the Action factory
4902 function which actually creates the Action object. The exit value
4903 of the command or return value of the Python function will be
4904 returned.
4905 Note that scons will print an error message if the executed action
4907 fails--that is, exits with or returns a non-zero value. scons will
4908 not, however, automatically terminate the build if the specified
4909 action fails. If you want the build to stop in response to a failed
4910 Execute call, you must explicitly check for a non-zero return
4911 value:
4912 Execute(Copy('file.out', 'file.in'))
4914 if Execute("mkdir sub/dir/ectory"):
4916 # The mkdir failed, don't try to build.
4917 Exit(1)
4918 Exit([value]), env.Exit([value])
4920 This tells scons to exit immediately with the specified value. A
4921 default exit value of 0 (zero) is used if no value is specified.
4922 Export([vars...], [key=value...]), env.Export([vars...],
4924 [key=value...])
4925 Exports variables from the current SConscript file to a global
4926 collection where they can be imported by other SConscript files.
4927 vars may be one or more strings representing variable names to be
4928 exported. If a string contains whitespace, it is split into
4929 separate strings, as if multiple string arguments had been given. A
4930 vars argument may also be a dictionary, which can be used to map
4931 variables to different names when exported. Keyword arguments can
4932 be used to provide names and their values.
4933 Export calls are cumulative. Specifying a previously exported
4936 variable will overwrite the earlier value. Both local variables and
4937 global variables can be exported.
4938 Examples:
4940 env = Environment()
4942 # Make env available for all SConscript files to Import().
4943 Export("env")
4944 package = 'my_name'
4946 # Make env and package available for all SConscript files:.
4947 Export("env", "package")
4948 # Make env and package available for all SConscript files:
4950 Export(["env", "package"])
4951 # Make env available using the name debug:
4953 Export(debug=env)
4954 # Make env available using the name debug:
4956 Export({"debug": env})
4957 Note that the SConscript function supports an exports argument that
4959 allows exporting a variable or set of variables to a specific
4960 SConscript file or files. See the description below.
4961 File(name, [directory]), env.File(name, [directory])
4963 Returns File Node(s). A File Node is an object that represents a
4964 file. name can be a relative or absolute path or a list of such
4965 paths. directory is an optional directory that will be used as the
4966 parent directory. If no directory is specified, the current
4967 script's directory is used as the parent.
4968 If name is a single pathname, the corresponding node is returned.
4970 If name is a list, SCons returns a list of nodes. Construction
4971 variables are expanded in name.
4972 File Nodes can be used anywhere you would supply a string as a file
4974 name to a Builder method or function. File Nodes have attributes
4975 and methods that are useful in many situations; see manpage section
4976 "File and Directory Nodes" for more information.
4977 FindFile(file, dirs), env.FindFile(file, dirs)
4979 Search for file in the path specified by dirs. dirs may be a list
4980 of directory names or a single directory name. In addition to
4981 searching for files that exist in the filesystem, this function
4982 also searches for derived files that have not yet been built.
4983 Example:
4985 foo = env.FindFile('foo', ['dir1', 'dir2'])
4987 FindInstalledFiles(), env.FindInstalledFiles()
4989 Returns the list of targets set up by the Install or InstallAs
4990 builders.
4991 This function serves as a convenient method to select the contents
4993 of a binary package.
4994 Example:
4996 Install( '/bin', [ 'executable_a', 'executable_b' ] )
4998 # will return the file node list
5000 # [ '/bin/executable_a', '/bin/executable_b' ]
5001 FindInstalledFiles()
5002 Install( '/lib', [ 'some_library' ] )
5004 # will return the file node list
5006 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
5007 FindInstalledFiles()
5008 FindPathDirs(variable)
5010 Returns a function (actually a callable Python object) intended to
5011 be used as the path_function of a Scanner object. The returned
5012 object will look up the specified variable in a construction
5013 environment and treat the construction variable's value as a list
5014 of directory paths that should be searched (like $CPPPATH,
5015 $LIBPATH, etc.).
5016 Note that use of FindPathDirs is generally preferable to writing
5018 your own path_function for the following reasons: 1) The returned
5019 list will contain all appropriate directories found in source trees
5020 (when VariantDir is used) or in code repositories (when Repository
5021 or the -Y option are used). 2) scons will identify expansions of
5022 variable that evaluate to the same list of directories as, in fact,
5023 the same list, and avoid re-scanning the directories for files,
5024 when possible.
5025 Example:
5027 def my_scan(node, env, path, arg):
5029 # Code to scan file contents goes here...
5030 return include_files
5031 scanner = Scanner(name = 'myscanner',
5033 function = my_scan,
5034 path_function = FindPathDirs('MYPATH'))
5035 FindSourceFiles(node='"."'), env.FindSourceFiles(node='"."')
5037 Returns the list of nodes which serve as the source of the built
5038 files. It does so by inspecting the dependency tree starting at the
5039 optional argument node which defaults to the '"."'-node. It will
5040 then return all leaves of node. These are all children which have
5041 no further children.
5042 This function is a convenient method to select the contents of a
5044 Source Package.
5045 Example:
5047 Program( 'src/main_a.c' )
5049 Program( 'src/main_b.c' )
5050 Program( 'main_c.c' )
5051 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
5053 FindSourceFiles()
5054 # returns ['src/main_b.c', 'src/main_a.c' ]
5056 FindSourceFiles( 'src' )
5057 As you can see build support files (SConstruct in the above
5059 example) will also be returned by this function.
5060 Flatten(sequence), env.Flatten(sequence)
5062 Takes a sequence (that is, a Python list or tuple) that may contain
5063 nested sequences and returns a flattened list containing all of the
5064 individual elements in any sequence. This can be helpful for
5065 collecting the lists returned by calls to Builders; other Builders
5066 will automatically flatten lists specified as input, but direct
5067 Python manipulation of these lists does not.
5068 Examples:
5070 foo = Object('foo.c')
5072 bar = Object('bar.c')
5073 # Because `foo' and `bar' are lists returned by the Object() Builder,
5075 # `objects' will be a list containing nested lists:
5076 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
5077 # Passing such a list to another Builder is all right because
5079 # the Builder will flatten the list automatically:
5080 Program(source = objects)
5081 # If you need to manipulate the list directly using Python, you need to
5083 # call Flatten() yourself, or otherwise handle nested lists:
5084 for object in Flatten(objects):
5085 print(str(object))
5086 GetBuildFailures()
5088 Returns a list of exceptions for the actions that failed while
5089 attempting to build targets. Each element in the returned list is a
5090 BuildError object with the following attributes that record various
5091 aspects of the build failure:
5092 .node The node that was being built when the build failure
5095 occurred.
5096 .status The numeric exit status returned by the command or Python
5099 function that failed when trying to build the specified Node.
5100 .errstr The SCons error string describing the build failure. (This
5103 is often a generic message like "Error 2" to indicate that an
5104 executed command exited with a status of 2.)
5105 .filename The name of the file or directory that actually caused
5108 the failure. This may be different from the .node attribute. For
5109 example, if an attempt to build a target named sub/dir/target fails
5110 because the sub/dir directory could not be created, then the .node
5111 attribute will be sub/dir/target but the .filename attribute will
5112 be sub/dir.
5113 .executor The SCons Executor object for the target Node being
5116 built. This can be used to retrieve the construction environment
5117 used for the failed action.
5118 .action The actual SCons Action object that failed. This will be
5121 one specific action out of the possible list of actions that would
5122 have been executed to build the target.
5123 .command The actual expanded command that was executed and failed,
5126 after expansion of $TARGET, $SOURCE, and other construction
5127 variables.
5128 Note that the GetBuildFailures function will always return an empty
5130 list until any build failure has occurred, which means that
5131 GetBuildFailures will always return an empty list while the
5132 SConscript files are being read. Its primary intended use is for
5133 functions that will be executed before SCons exits by passing them
5134 to the standard Python atexit.register() function. Example:
5135 import atexit
5137 def print_build_failures():
5139 from SCons.Script import GetBuildFailures
5140 for bf in GetBuildFailures():
5141 print("%s failed: %s" % (bf.node, bf.errstr))
5142 atexit.register(print_build_failures)
5144 GetBuildPath(file, [...]), env.GetBuildPath(file, [...])
5146 Returns the scons path name (or names) for the specified file (or
5147 files). The specified file or files may be scons Nodes or strings
5148 representing path names.
5149 GetLaunchDir(), env.GetLaunchDir()
5151 Returns the absolute path name of the directory from which scons
5152 was initially invoked. This can be useful when using the -u, -U or
5153 -D options, which internally change to the directory in which the
5154 SConstruct file is found.
5155 GetOption(name), env.GetOption(name)
5157 This function provides a way to query the value of SCons options
5158 set on scons command line (or set using the SetOption function).
5159 The options supported are:
5160 cache_debug
5162 which corresponds to --cache-debug;
5163 cache_disable
5165 which corresponds to --cache-disable;
5166 cache_force
5168 which corresponds to --cache-force;
5169 cache_show
5171 which corresponds to --cache-show;
5172 clean
5174 which corresponds to -c, --clean and --remove;
5175 config
5177 which corresponds to --config;
5178 directory
5180 which corresponds to -C and --directory;
5181 diskcheck
5183 which corresponds to --diskcheck;
5184 duplicate
5186 which corresponds to --duplicate;
5187 file
5189 which corresponds to -f, --file, --makefile and --sconstruct;
5190 help
5192 which corresponds to -h and --help;
5193 ignore_errors
5195 which corresponds to --ignore-errors;
5196 implicit_cache
5198 which corresponds to --implicit-cache;
5199 implicit_deps_changed
5201 which corresponds to --implicit-deps-changed;
5202 implicit_deps_unchanged
5204 which corresponds to --implicit-deps-unchanged;
5205 interactive
5207 which corresponds to --interact and --interactive;
5208 keep_going
5210 which corresponds to -k and --keep-going;
5211 max_drift
5213 which corresponds to --max-drift;
5214 no_exec
5216 which corresponds to -n, --no-exec, --just-print, --dry-run and
5217 --recon;
5218 no_site_dir
5220 which corresponds to --no-site-dir;
5221 num_jobs
5223 which corresponds to -j and --jobs;
5224 profile_file
5226 which corresponds to --profile;
5227 question
5229 which corresponds to -q and --question;
5230 random
5232 which corresponds to --random;
5233 repository
5235 which corresponds to -Y, --repository and --srcdir;
5236 silent
5238 which corresponds to -s, --silent and --quiet;
5239 site_dir
5241 which corresponds to --site-dir;
5242 stack_size
5244 which corresponds to --stack-size;
5245 taskmastertrace_file
5247 which corresponds to --taskmastertrace; and
5248 warn
5250 which corresponds to --warn and --warning.
5251 See the documentation for the corresponding command line option for
5253 information about each specific option.
5254 Glob(pattern, [ondisk, source, strings, exclude]), env.Glob(pattern,
5256 [ondisk, source, strings, exclude])
5257 Returns Nodes (or strings) that match the specified pattern,
5258 relative to the directory of the current SConscript file. The
5259 evironment method form (env.Glob) performs string substition on
5260 pattern and returns whatever matches the resulting expanded
5261 pattern.
5262 The specified pattern uses Unix shell style metacharacters for
5264 matching:
5265 * matches everything
5267 ? matches any single character
5268 [seq] matches any character in seq
5269 [!seq] matches any char not in seq
5270 If the first character of a filename is a dot, it must be matched
5272 explicitly. Character matches do not span directory separators.
5273 The Glob knows about repositories (see the Repository function) and
5275 source directories (see the VariantDir function) and returns a Node
5276 (or string, if so configured) in the local (SConscript) directory
5277 if a matching Node is found anywhere in a corresponding repository
5278 or source directory.
5279 The ondisk argument may be set to a value which evaluates False to
5281 disable the search for matches on disk, thereby only returning
5282 matches among already-configured File or Dir Nodes. The default
5283 behavior is to return corresponding Nodes for any on-disk matches
5284 found.
5285 The source argument may be set to a value which evaluates True to
5287 specify that, when the local directory is a VariantDir, the
5288 returned Nodes should be from the corresponding source directory,
5289 not the local directory.
5290 The strings argument may be set to a value which evaluates True to
5292 have the Glob function return strings, not Nodes, that represent
5293 the matched files or directories. The returned strings will be
5294 relative to the local (SConscript) directory. (Note that This may
5295 make it easier to perform arbitrary manipulation of file names, but
5296 if the returned strings are passed to a different SConscript file,
5297 any Node translation will be relative to the other SConscript
5298 directory, not the original SConscript directory.)
5299 The exclude argument may be set to a pattern or a list of patterns
5301 (following the same Unix shell semantics) which must be filtered
5302 out of returned elements. Elements matching a least one pattern of
5303 this list will be excluded.
5304 Examples:
5306 Program("foo", Glob("*.c"))
5308 Zip("/tmp/everything", Glob(".??*") + Glob("*"))
5309 sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \
5310 Glob( "os_%s_specific_*.cpp" % currentOS)
5311 Help(text, append=False), env.Help(text, append=False)
5313 Specifies a local help message to be printed if the -h argument is
5314 given to scons. Subsequent calls to Help append text to the
5315 previously defined local help text.
5316 For the first call to Help only, if append is False (the default)
5318 any local help message generated through AddOption calls is
5319 replaced. If append is True, text is appended to the existing help
5320 text.
5321 Ignore(target, dependency), env.Ignore(target, dependency)
5323 The specified dependency file(s) will be ignored when deciding if
5324 the target file(s) need to be rebuilt.
5325 You can also use Ignore to remove a target from the default build.
5327 In order to do this you must specify the directory the target will
5328 be built in as the target, and the file you want to skip building
5329 as the dependency.
5330 Note that this will only remove the dependencies listed from the
5332 files built by default. It will still be built if that dependency
5333 is needed by another object being built. See the third and forth
5334 examples below.
5335 Examples:
5337 env.Ignore('foo', 'foo.c')
5339 env.Ignore('bar', ['bar1.h', 'bar2.h'])
5340 env.Ignore('.','foobar.obj')
5341 env.Ignore('bar','bar/foobar.obj')
5342 Import(vars...), env.Import(vars...)
5344 Imports variables into the current SConscript file. vars must be
5345 strings representing names of variables which have been previously
5346 exported either by the Export function or by the exports argument
5347 to SConscript. Variables exported by SConscript take precedence.
5348 Multiple variable names can be passed to Import as separate
5349 arguments or as words in a space-separated string. The wildcard "*"
5350 can be used to import all available variables.
5351 Examples:
5353 Import("env")
5355 Import("env", "variable")
5356 Import(["env", "variable"])
5357 Import("*")
5358 Literal(string), env.Literal(string)
5360 The specified string will be preserved as-is and not have
5361 construction variables expanded.
5362 Local(targets), env.Local(targets)
5364 The specified targets will have copies made in the local tree, even
5365 if an already up-to-date copy exists in a repository. Returns a
5366 list of the target Node or Nodes.
5367 env.MergeFlags(arg, [unique])
5369 Merges the specified arg values to the construction environment's
5370 construction variables. If the arg argument is not a dictionary, it
5371 is converted to one by calling env.ParseFlags on the argument
5372 before the values are merged. Note that arg must be a single value,
5373 so multiple strings must be passed in as a list, not as separate
5374 arguments to env.MergeFlags.
5375 By default, duplicate values are eliminated; you can, however,
5377 specify unique=0 to allow duplicate values to be added. When
5378 eliminating duplicate values, any construction variables that end
5379 with the string PATH keep the left-most unique value. All other
5380 construction variables keep the right-most unique value.
5381 Examples:
5383 # Add an optimization flag to $CCFLAGS.
5385 env.MergeFlags('-O3')
5386 # Combine the flags returned from running pkg-config with an optimization
5388 # flag and merge the result into the construction variables.
5389 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
5390 # Combine an optimization flag with the flags returned from running pkg-config
5392 # twice and merge the result into the construction variables.
5393 env.MergeFlags(['-O3',
5394 '!pkg-config gtk+-2.0 --cflags --libs',
5395 '!pkg-config libpng12 --cflags --libs'])
5396 NoCache(target, ...), env.NoCache(target, ...)
5398 Specifies a list of files which should not be cached whenever the
5399 CacheDir method has been activated. The specified targets may be a
5400 list or an individual target.
5401 Multiple files should be specified either as separate arguments to
5403 the NoCache method, or as a list. NoCache will also accept the
5404 return value of any of the construction environment Builder
5405 methods.
5406 Calling NoCache on directories and other non-File Node types has no
5408 effect because only File Nodes are cached.
5409 Examples:
5411 NoCache('foo.elf')
5413 NoCache(env.Program('hello', 'hello.c'))
5414 NoClean(target, ...), env.NoClean(target, ...)
5416 Specifies a list of files or directories which should not be
5417 removed whenever the targets (or their dependencies) are specified
5418 with the -c command line option. The specified targets may be a
5419 list or an individual target. Multiple calls to NoClean are legal,
5420 and prevent each specified target from being removed by calls to
5421 the -c option.
5422 Multiple files or directories should be specified either as
5424 separate arguments to the NoClean method, or as a list. NoClean
5425 will also accept the return value of any of the construction
5426 environment Builder methods.
5427 Calling NoClean for a target overrides calling Clean for the same
5429 target, and any targets passed to both functions will not be
5430 removed by the -c option.
5431 Examples:
5433 NoClean('foo.elf')
5435 NoClean(env.Program('hello', 'hello.c'))
5436 env.ParseConfig(command, [function, unique])
5438 Calls the specified function to modify the environment as specified
5439 by the output of command. The default function is env.MergeFlags,
5440 which expects the output of a typical *-config command (for
5441 example, gtk-config) and adds the options to the appropriate
5442 construction variables. By default, duplicate values are not added
5443 to any construction variables; you can specify unique=0 to allow
5444 duplicate values to be added.
5445 Interpreted options and the construction variables they affect are
5447 as specified for the env.ParseFlags method (which this method
5448 calls). See that method's description for a table of options and
5449 construction variables.
5450 ParseDepends(filename, [must_exist, only_one]),
5452 env.ParseDepends(filename, [must_exist, only_one])
5453 Parses the contents of the specified filename as a list of
5454 dependencies in the style of Make or mkdep, and explicitly
5455 establishes all of the listed dependencies.
5456 By default, it is not an error if the specified filename does not
5458 exist. The optional must_exist argument may be set to a non-zero
5459 value to have scons throw an exception and generate an error if the
5460 file does not exist, or is otherwise inaccessible.
5461 The optional only_one argument may be set to a non-zero value to
5463 have scons thrown an exception and generate an error if the file
5464 contains dependency information for more than one target. This can
5465 provide a small sanity check for files intended to be generated by,
5466 for example, the gcc -M flag, which should typically only write
5467 dependency information for one output file into a corresponding .d
5468 file.
5469 The filename and all of the files listed therein will be
5471 interpreted relative to the directory of the SConscript file which
5472 calls the ParseDepends function.
5473 env.ParseFlags(flags, ...)
5475 Parses one or more strings containing typical command-line flags
5476 for GCC tool chains and returns a dictionary with the flag values
5477 separated into the appropriate SCons construction variables. This
5478 is intended as a companion to the env.MergeFlags method, but allows
5479 for the values in the returned dictionary to be modified, if
5480 necessary, before merging them into the construction environment.
5481 (Note that env.MergeFlags will call this method if its argument is
5482 not a dictionary, so it is usually not necessary to call
5483 env.ParseFlags directly unless you want to manipulate the values.)
5484 If the first character in any string is an exclamation mark (!),
5486 the rest of the string is executed as a command, and the output
5487 from the command is parsed as GCC tool chain command-line flags and
5488 added to the resulting dictionary.
5489 Flag values are translated accordig to the prefix found, and added
5491 to the following construction variables:
5492 -arch CCFLAGS, LINKFLAGS
5494 -D CPPDEFINES
5495 -framework FRAMEWORKS
5496 -frameworkdir= FRAMEWORKPATH
5497 -fmerge-all-constants CCFLAGS, LINKFLAGS
5498 -fopenmp CCFLAGS, LINKFLAGS
5499 -include CCFLAGS
5500 -imacros CCFLAGS
5501 -isysroot CCFLAGS, LINKFLAGS
5502 -isystem CCFLAGS
5503 -iquote CCFLAGS
5504 -idirafter CCFLAGS
5505 -I CPPPATH
5506 -l LIBS
5507 -L LIBPATH
5508 -mno-cygwin CCFLAGS, LINKFLAGS
5509 -mwindows LINKFLAGS
5510 -openmp CCFLAGS, LINKFLAGS
5511 -pthread CCFLAGS, LINKFLAGS
5512 -std= CFLAGS
5513 -Wa, ASFLAGS, CCFLAGS
5514 -Wl,-rpath= RPATH
5515 -Wl,-R, RPATH
5516 -Wl,-R RPATH
5517 -Wl, LINKFLAGS
5518 -Wp, CPPFLAGS
5519 - CCFLAGS
5520 + CCFLAGS, LINKFLAGS
5521 Any other strings not associated with options are assumed to be the
5523 names of libraries and added to the $LIBS construction variable.
5524 Examples (all of which produce the same result):
5526 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
5528 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
5529 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
5530 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
5531 Platform(string)
5533 The Platform form returns a callable object that can be used to
5534 initialize a construction environment using the platform keyword of
5535 the Environment function.
5536 Example:
5538 env = Environment(platform = Platform('win32'))
5540 The env.Platform form applies the callable object for the specified
5542 platform string to the environment through which the method was
5543 called.
5544 env.Platform('posix')
5546 Note that the win32 platform adds the SystemDrive and SystemRoot
5548 variables from the user's external environment to the construction
5549 environment's $ENV dictionary. This is so that any executed
5550 commands that use sockets to connect with other systems (such as
5551 fetching source files from external CVS repository specifications
5552 like :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) will
5553 work on Windows systems.
5554 Precious(target, ...), env.Precious(target, ...)
5556 Marks each given target as precious so it is not deleted before it
5557 is rebuilt. Normally scons deletes a target before building it.
5558 Multiple targets can be passed in to a single call to Precious.
5559 env.Prepend(key=val, [...])
5561 Appends the specified keyword arguments to the beginning of
5562 construction variables in the environment. If the Environment does
5563 not have the specified construction variable, it is simply added to
5564 the environment. If the values of the construction variable and the
5565 keyword argument are the same type, then the two values will be
5566 simply added together. Otherwise, the construction variable and the
5567 value of the keyword argument are both coerced to lists, and the
5568 lists are added together. (See also the Append method, above.)
5569 Example:
5571 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
5573 env.PrependENVPath(name, newpath, [envname, sep, delete_existing])
5575 This appends new path elements to the given path in the specified
5576 external environment ($ENV by default). This will only add any
5577 particular path once (leaving the first one it encounters and
5578 ignoring the rest, to preserve path order), and to help assure
5579 this, will normalize all paths (using os.path.normpath and
5580 os.path.normcase). This can also handle the case where the given
5581 old path variable is a list instead of a string, in which case a
5582 list will be returned instead of a string.
5583 If delete_existing is 0, then adding a path that already exists
5585 will not move it to the beginning; it will stay where it is in the
5586 list.
5587 Example:
5589 print 'before:',env['ENV']['INCLUDE']
5591 include_path = '/foo/bar:/foo'
5592 env.PrependENVPath('INCLUDE', include_path)
5593 print 'after:',env['ENV']['INCLUDE']
5594 The above example will print:
5596 before: /biz:/foo
5598 after: /foo/bar:/foo:/biz
5599 env.PrependUnique(key=val, delete_existing=0, [...])
5601 Appends the specified keyword arguments to the beginning of
5602 construction variables in the environment. If the Environment does
5603 not have the specified construction variable, it is simply added to
5604 the environment. If the construction variable being appended to is
5605 a list, then any value(s) that already exist in the construction
5606 variable will not be added again to the list. However, if
5607 delete_existing is 1, existing matching values are removed first,
5608 so existing values in the arg list move to the front of the list.
5609 Example:
5611 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
5613 Progress(callable, [interval]), Progress(string, [interval, file,
5615 overwrite]), Progress(list_of_strings, [interval, file, overwrite])
5616 Allows SCons to show progress made during the build by displaying a
5617 string or calling a function while evaluating Nodes (e.g. files).
5618 If the first specified argument is a Python callable (a function or
5620 an object that has a __call__ method), the function will be called
5621 once every interval times a Node is evaluated (default 1). The
5622 callable will be passed the evaluated Node as its only argument.
5623 (For future compatibility, it's a good idea to also add *args and
5624 **kwargs as arguments to your function or method signatures. This
5625 will prevent the code from breaking if SCons ever changes the
5626 interface to call the function with additional arguments in the
5627 future.)
5628 An example of a simple custom progress function that prints a
5630 string containing the Node name every 10 Nodes:
5631 def my_progress_function(node, *args, **kwargs):
5633 print('Evaluating node %s!' % node)
5634 Progress(my_progress_function, interval=10)
5635 A more complicated example of a custom progress display object that
5637 prints a string containing a count every 100 evaluated Nodes. Note
5638 the use of \r (a carriage return) at the end so that the string
5639 will overwrite itself on a display:
5640 import sys
5642 class ProgressCounter(object):
5643 count = 0
5644 def __call__(self, node, *args, **kw):
5645 self.count += 100
5646 sys.stderr.write('Evaluated %s nodes\r' % self.count)
5647 Progress(ProgressCounter(), interval=100)
5649 If the first argument to Progress is a string or list of strings,
5651 it is taken as text to be displayed every interval evaluated Nodes.
5652 If the first argument is a list of strings, then each string in the
5653 list will be displayed in rotating fashion every interval evaluated
5654 Nodes.
5655 The default is to print the string on standard output. An alternate
5657 output stream may be specified with the file keyword argument,
5658 which the caller must pass already opened.
5659 The following will print a series of dots on the error output, one
5661 dot for every 100 evaluated Nodes:
5662 import sys
5664 Progress('.', interval=100, file=sys.stderr)
5665 If the string contains the verbatim substring $TARGET;, it will be
5667 replaced with the Node. Note that, for performance reasons, this is
5668 not a regular SCons variable substition, so you can not use other
5669 variables or use curly braces. The following example will print the
5670 name of every evaluated Node, using a carriage return) (\r) to
5671 cause each line to overwritten by the next line, and the overwrite
5672 keyword argument (default False) to make sure the
5673 previously-printed file name is overwritten with blank spaces:
5674 import sys
5676 Progress('$TARGET\r', overwrite=True)
5677 A list of strings can be used to implement a "spinner" on the
5679 user's screen as follows, changing every five evaluated Nodes:
5680 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
5682 Pseudo(target, ...), env.Pseudo(target, ...)
5684 This indicates that each given target should not be created by the
5685 build rule, and if the target is created, an error will be
5686 generated. This is similar to the gnu make .PHONY target. However,
5687 in the vast majority of cases, an Alias is more appropriate.
5688 Multiple targets can be passed in to a single call to Pseudo.
5689 PyPackageDir(modulename), env.PyPackageDir(modulename)
5691 This returns a Directory Node similar to Dir. The python module /
5692 package is looked up and if located the directory is returned for
5693 the location. modulename Is a named python package / module to
5694 lookup the directory for it's location.
5695 If modulename is a list, SCons returns a list of Dir nodes.
5697 Construction variables are expanded in modulename.
5698 env.Replace(key=val, [...])
5700 Replaces construction variables in the Environment with the
5701 specified keyword arguments.
5702 Example:
5704 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5706 Repository(directory), env.Repository(directory)
5708 Specifies that directory is a repository to be searched for files.
5709 Multiple calls to Repository are legal, and each one adds to the
5710 list of repositories that will be searched.
5711 To scons, a repository is a copy of the source tree, from the
5713 top-level directory on down, which may contain both source files
5714 and derived files that can be used to build targets in the local
5715 source tree. The canonical example would be an official source tree
5716 maintained by an integrator. If the repository contains derived
5717 files, then the derived files should have been built using scons,
5718 so that the repository contains the necessary signature information
5719 to allow scons to figure out when it is appropriate to use the
5720 repository copy of a derived file, instead of building one locally.
5721 Note that if an up-to-date derived file already exists in a
5723 repository, scons will not make a copy in the local directory tree.
5724 In order to guarantee that a local copy will be made, use the Local
5725 method.
5726 Requires(target, prerequisite), env.Requires(target, prerequisite)
5728 Specifies an order-only relationship between the specified target
5729 file(s) and the specified prerequisite file(s). The prerequisite
5730 file(s) will be (re)built, if necessary, before the target file(s),
5731 but the target file(s) do not actually depend on the prerequisites
5732 and will not be rebuilt simply because the prerequisite file(s)
5733 change.
5734 Example:
5736 env.Requires('foo', 'file-that-must-be-built-before-foo')
5738 Return([vars..., stop=True])
5740 Return to the calling SConscript, optionally returning the values
5741 of variables named in vars. Multiple strings contaning variable
5742 names may be passed to Return. A string containing white space is
5743 split into individual variable names. Returns the value if one
5744 variable is specified, else returns a tuple of values. Returns an
5745 empty tuple if vars is omitted.
5746 By default Return stops processing the current SConscript and
5748 returns immediately. The optional stop keyword argument may be set
5749 to a false value to continue processing the rest of the SConscript
5750 file after the Return call (this was the default behavior prior to
5751 SCons 0.98.) However, the values returned are still the values of
5752 the variables in the named vars at the point Return was called.
5753 Examples:
5755 # Returns no values (evaluates False)
5757 Return()
5758 # Returns the value of the 'foo' Python variable.
5760 Return("foo")
5761 # Returns the values of the Python variables 'foo' and 'bar'.
5763 Return("foo", "bar")
5764 # Returns the values of Python variables 'val1' and 'val2'.
5766 Return('val1 val2')
5767 Scanner(function, [name, argument, skeys, path_function, node_class,
5769 node_factory, scan_check, recursive]), env.Scanner(function, [name,
5770 argument, skeys, path_function, node_class, node_factory, scan_check,
5771 recursive])
5772 Creates a Scanner object for the specified function. See manpage
5773 section "Scanner Objects" for a complete explanation of the
5774 arguments and behavior.
5775 SConscript(scripts, [exports, variant_dir, duplicate, must_exist]),
5777 env.SConscript(scripts, [exports, variant_dir, duplicate, must_exist]),
5778 SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate,
5779 must_exist]), env.SConscript(dirs=subdirs, [name=script, exports,
5780 variant_dir, duplicate, must_exist])
5781 Execute one or more subsidiary SConscript (configuration) files.
5782 There are two ways to call the SConscript function.
5783 The first calling style is to explicitly specify one or more
5785 scripts as the first argument. A single script may be specified as
5786 a string; multiple scripts must be specified as a list (either
5787 explicitly or as created by a function like Split). Examples:
5788 SConscript('SConscript') # run SConscript in the current directory
5790 SConscript('src/SConscript') # run SConscript in the src directory
5791 SConscript(['src/SConscript', 'doc/SConscript'])
5792 config = SConscript('MyConfig.py')
5793 The second way to call SConscript is to specify a list of
5795 (sub)directory names as a dirs=subdirs keyword argument. In this
5796 case, scons will execute a subsidiary configuration file named
5797 SConscript in each of the specified directories. You may specify a
5798 name other than SConscript by supplying an optional name=script
5799 keyword argument. The first three examples below have the same
5800 effect as the first three examples above:
5801 SConscript(dirs='.') # run SConscript in the current directory
5803 SConscript(dirs='src') # run SConscript in the src directory
5804 SConscript(dirs=['src', 'doc'])
5805 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5806 The optional exports argument provides a string or list of strings
5808 representing variable names, or a dictionary of named values, to
5809 export. These variables are locally exported only to the called
5810 SConscript file(s) and do not affect the global pool of variables
5811 managed by the Export function. The subsidiary SConscript files
5812 must use the Import function to import the variables. Examples:
5813 foo = SConscript('sub/SConscript', exports='env')
5815 SConscript('dir/SConscript', exports=['env', 'variable'])
5816 SConscript(dirs='subdir', exports='env variable')
5817 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5818 If the optional variant_dir argument is present, it causes an
5820 effect equivalent to the VariantDir function. The variant_dir
5821 argument is interpreted relative to the directory of the calling
5822 SConscript file. The optional duplicate argument is interpreted as
5823 for VariantDir. If variant_dir is omitted, the duplicate argument
5824 is ignored. See the description of VariantDir below for additional
5825 details and restrictions.
5826 If variant_dir is present, the source directory is the directory in
5828 which the SConscript file resides and the SConscript file is
5829 evaluated as if it were in the variant_dir directory:
5830 SConscript('src/SConscript', variant_dir='build')
5832 is equivalent to
5834 VariantDir('build', 'src')
5836 SConscript('build/SConscript')
5837 This later paradigm is often used when the sources are in the same
5839 directory as the SConstruct:
5840 SConscript('SConscript', variant_dir='build')
5842 is equivalent to
5844 VariantDir('build', '.')
5846 SConscript('build/SConscript')
5847 If the optional must_exist is True, causes an exception to be
5851 raised if a requested SConscript file is not found. The current
5852 default is False, causing only a warning to be emitted, but this
5853 default is deprecated (since 3.1). For scripts which truly intend
5854 to be optional, transition to explicitly supplying must_exist=False
5855 to the SConscript call.
5856 Here are some composite examples:
5858 # collect the configuration information and use it to build src and doc
5860 shared_info = SConscript('MyConfig.py')
5861 SConscript('src/SConscript', exports='shared_info')
5862 SConscript('doc/SConscript', exports='shared_info')
5863 # build debugging and production versions. SConscript
5865 # can use Dir('.').path to determine variant.
5866 SConscript('SConscript', variant_dir='debug', duplicate=0)
5867 SConscript('SConscript', variant_dir='prod', duplicate=0)
5868 # build debugging and production versions. SConscript
5870 # is passed flags to use.
5871 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5872 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5873 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5874 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5875 # build common documentation and compile for different architectures
5877 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5878 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5879 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5880 SConscript returns the values of any variables named by the
5883 executed SConscript(s) in arguments to the Return function (see
5884 above for details). If a single SConscript call causes multiple
5885 scripts to be executed, the return value is a tuple containing the
5886 returns of all of the scripts. If an executed script does not
5887 explicitly call Return, it returns None.
5888 SConscriptChdir(value), env.SConscriptChdir(value)
5890 By default, scons changes its working directory to the directory in
5891 which each subsidiary SConscript file lives. This behavior may be
5892 disabled by specifying either:
5893 SConscriptChdir(0)
5895 env.SConscriptChdir(0)
5896 in which case scons will stay in the top-level directory while
5898 reading all SConscript files. (This may be necessary when building
5899 from repositories, when all the directories in which SConscript
5900 files may be found don't necessarily exist locally.) You may enable
5901 and disable this ability by calling SConscriptChdir() multiple
5902 times.
5903 Example:
5905 env = Environment()
5907 SConscriptChdir(0)
5908 SConscript('foo/SConscript') # will not chdir to foo
5909 env.SConscriptChdir(1)
5910 SConscript('bar/SConscript') # will chdir to bar
5911 SConsignFile([name, dbm_module]), env.SConsignFile([name, dbm_module])
5913 Specify where to store the SCons file signature database, and which
5914 database format to use. This may be useful to specify alternate
5915 database files and/or file locations for different types of builds.
5916 The optional name argument is the base name of the database
5918 file(s). If not an absolute path name, these are placed relative to
5919 the directory containing the top-level SConstruct file. The default
5920 is .sconsign. The actual database file(s) stored on disk may have
5921 an appropriate suffix appended by the chosen dbm_module
5922 The optional dbm_module argument specifies which Python database
5924 module to use for reading/writing the file. The module must be
5925 imported first; then the imported module name is passed as the
5926 argument. The default is a custom SCons.dblite module that uses
5927 pickled Python data structures, which works on all Python versions.
5928 See documentation of the Python dbm module for other available
5929 types.
5930 If called with no arguments, the database will default to
5932 .sconsign.dblite in the top directory of the project, which is also
5933 the default if if SConsignFile is not called.
5934 The setting is global, so the only difference between the global
5936 function and the environment method form is variable expansion on
5937 name. There should only be one active call to this function/method
5938 in a given build setup.
5939 If name is set to None, scons will store file signatures in a
5941 separate .sconsign file in each directory, not in a single combined
5942 database file. This is a backwards-compatibility meaure to support
5943 what was the default behavior prior to SCons 0.97 (i.e. before
5944 2008). Use of this mode is discouraged and may be deprecated in a
5945 future SCons release.
5946 Examples:
5948 # Explicitly stores signatures in ".sconsign.dblite"
5950 # in the top-level SConstruct directory (the default behavior).
5951 SConsignFile()
5952 # Stores signatures in the file "etc/scons-signatures"
5954 # relative to the top-level SConstruct directory.
5955 # SCons will add a database suffix to this name.
5956 SConsignFile("etc/scons-signatures")
5957 # Stores signatures in the specified absolute file name.
5959 # SCons will add a database suffix to this name.
5960 SConsignFile("/home/me/SCons/signatures")
5961 # Stores signatures in a separate .sconsign file
5963 # in each directory.
5964 SConsignFile(None)
5965 # Stores signatures in a GNU dbm format .sconsign file
5967 import dbm.gnu
5968 SConsignFile(dbm_module=dbm.gnu)
5969 env.SetDefault(key=val, [...])
5971 Sets construction variables to default values specified with the
5972 keyword arguments if (and only if) the variables are not already
5973 set. The following statements are equivalent:
5974 env.SetDefault(FOO = 'foo')
5976 if 'FOO' not in env: env['FOO'] = 'foo'
5978 SetOption(name, value), env.SetOption(name, value)
5980 Sets scons option variable name to value. These options are all
5981 also settable via scons command-line options but the variable name
5982 may differ from the command-line option name (see table). A value
5983 set via command-line option will take precedence over one set with
5984 SetOption, which allows setting a project default in the scripts
5985 and temporarily overriding it via command line. Options which
5986 affect the reading and processing of SConscript files are not
5987 settable this way, since those files must be read in order to find
5988 the SetOption call.
5989 The settable variables with their associated command-line options
5991 are:
5992 ┌───────────────┬──────────────────────────┐
5994 │Variable │ Command-line options │
5995 ├───────────────┼──────────────────────────┤
5996 │clean │ -c, --clean, --remove │
5997 ├───────────────┼──────────────────────────┤
5998 │diskcheck │ --diskcheck │
5999 ├───────────────┼──────────────────────────┤
6000 │duplicate │ --duplicate │
6001 ├───────────────┼──────────────────────────┤
6002 │help │ -h, --help │
6003 ├───────────────┼──────────────────────────┤
6004 │implicit_cache │ --implicit-cache │
6005 ├───────────────┼──────────────────────────┤
6006 │max_drift │ --max-drift │
6007 ├───────────────┼──────────────────────────┤
6008 │md5_chunksize │ --md5-chunksize │
6009 ├───────────────┼──────────────────────────┤
6010 │no_exec │ -n, --no-exec, │
6011 │ │ --just-print, --dry-run, │
6012 │ │ --recon │
6013 ├───────────────┼──────────────────────────┤
6014 │no_progress │ -Q │
6015 ├───────────────┼──────────────────────────┤
6016 │num_jobs │ -j, --jobs │
6017 ├───────────────┼──────────────────────────┤
6018 │random │ --random │
6019 ├───────────────┼──────────────────────────┤
6020 │silent │ --silent. │
6021 ├───────────────┼──────────────────────────┤
6022 │stack_size │ --stack-size │
6023 ├───────────────┼──────────────────────────┤
6024 │warn │ --warn. │
6025 └───────────────┴──────────────────────────┘
6026 See the documentation in the manpage for the corresponding command
6027 line option for information about each specific option. Option
6028 values which are boolean in nature (that is, they are either on or
6029 off) should be set to a true value (True, 1) or a false value
6030 (False, 0).
6031 Note
6033 If no_progress is set via SetOption there will still be initial
6034 progress output as SCons has to start reading SConscript files
6035 before it can see the SetOption in an SConscript file: scons:
6036 Reading SConscript files ...
6037 Example:
6038 SetOption('max_drift', True)
6040 SideEffect(side_effect, target), env.SideEffect(side_effect, target)
6042 Declares side_effect as a side effect of building target. Both
6043 side_effect and target can be a list, a file name, or a node. A
6044 side effect is a target file that is created or updated as a side
6045 effect of building other targets. For example, a Windows PDB file
6046 is created as a side effect of building the .obj files for a static
6047 library, and various log files are created updated as side effects
6048 of various TeX commands. If a target is a side effect of multiple
6049 build commands, scons will ensure that only one set of commands is
6050 executed at a time. Consequently, you only need to use this method
6051 for side-effect targets that are built as a result of multiple
6052 build commands.
6053 Because multiple build commands may update the same side effect
6055 file, by default the side_effect target is not automatically
6056 removed when the target is removed by the -c option. (Note,
6057 however, that the side_effect might be removed as part of cleaning
6058 the directory in which it lives.) If you want to make sure the
6059 side_effect is cleaned whenever a specific target is cleaned, you
6060 must specify this explicitly with the Clean or env.Clean function.
6061 This function returns the list of side effect Node objects that
6063 were successfully added. If the list of side effects contained any
6064 side effects that had already been added, they are not added and
6065 included in the returned list.
6066 Split(arg), env.Split(arg)
6068 Returns a list of file names or other objects. If arg is a string,
6069 it will be split on strings of white-space characters within the
6070 string, making it easier to write long lists of file names. If arg
6071 is already a list, the list will be returned untouched. If arg is
6072 any other type of object, it will be returned as a list containing
6073 just the object.
6074 Example:
6076 files = Split("f1.c f2.c f3.c")
6078 files = env.Split("f4.c f5.c f6.c")
6079 files = Split("""
6080 f7.c
6081 f8.c
6082 f9.c
6083 """)
6084 env.subst(input, [raw, target, source, conv])
6086 Performs construction variable interpolation on the specified
6087 string or sequence argument input.
6088 By default, leading or trailing white space will be removed from
6090 the result. and all sequences of white space will be compressed to
6091 a single space character. Additionally, any $( and $) character
6092 sequences will be stripped from the returned string, The optional
6093 raw argument may be set to 1 if you want to preserve white space
6094 and $(-$) sequences. The raw argument may be set to 2 if you want
6095 to strip all characters between any $( and $) pairs (as is done for
6096 signature calculation).
6097 If the input is a sequence (list or tuple), the individual elements
6099 of the sequence will be expanded, and the results will be returned
6100 as a list.
6101 The optional target and source keyword arguments must be set to
6103 lists of target and source nodes, respectively, if you want the
6104 $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for
6105 expansion. This is usually necessary if you are calling env.subst
6106 from within a Python function used as an SCons action.
6107 Returned string values or sequence elements are converted to their
6109 string representation by default. The optional conv argument may
6110 specify a conversion function that will be used in place of the
6111 default. For example, if you want Python objects (including SCons
6112 Nodes) to be returned as Python objects, you can use the Python Λ
6113 idiom to pass in an unnamed function that simply returns its
6114 unconverted argument.
6115 Example:
6117 print(env.subst("The C compiler is: $CC"))
6119 def compile(target, source, env):
6121 sourceDir = env.subst("${SOURCE.srcdir}",
6122 target=target,
6123 source=source)
6124 source_nodes = env.subst('$EXPAND_TO_NODELIST',
6126 conv=lambda x: x)
6127 Tag(node, tags)
6129 Annotates file or directory Nodes with information about how the
6130 Package Builder should package those files or directories. All
6131 Node-level tags are optional.
6132 Examples:
6134 # makes sure the built library will be installed with 644 file access mode
6136 Tag(Library('lib.c'), UNIX_ATTR="0o644")
6137 # marks file2.txt to be a documentation file
6139 Tag('file2.txt', DOC)
6140 Tool(name, [toolpath, **kwargs]), env.Tool(name, [toolpath, **kwargs])
6142 Runs the tool identified by name, which is searched for in standard
6143 locations and any paths specified by the optional toolpath, to
6144 update a construction environment with construction variables
6145 needed to use the mechanisms that tool describes. Any additional
6146 keyword arguments kwargs are passed on to the tool module's
6147 generate function.
6148 When called as a construction environment method, the tool module
6150 is called to update the construction environment and the name of
6151 the tool is appended to the $TOOLS construction variable in that
6152 environment.
6153 Examples:
6155 env.Tool('gcc')
6157 env.Tool('opengl', toolpath=['build/tools'])
6158 When called as a global function, returns a callable tool object;
6160 the tool is not called at this time, as it lacks the context of an
6161 environment to update. This tool object can be passed to an
6162 Environment or Clone call as part of the tools keyword argument, or
6163 it can be called directly, passing a construction environment to
6164 update as the argument. Either approach will also update the $TOOLS
6165 construction variable.
6166 Examples:
6168 env = Environment(tools=[Tool('msvc')])
6170 env = Environment()
6172 t = Tool('msvc')
6173 t(env) # adds 'msvc' to the TOOLS variable
6174 u = Tool('opengl', toolpath = ['tools'])
6175 u(env) # adds 'opengl' to the TOOLS variable
6176 Value(value, [built_value], [name]), env.Value(value, [built_value],
6178 [name])
6179 Returns a Node object representing the specified Python value.
6180 Value Nodes can be used as dependencies of targets. If the result
6181 of calling str(value) changes between SCons runs, any targets
6182 depending on Value(value) will be rebuilt. (This is true even when
6183 using timestamps to decide if files are up-to-date.) When using
6184 timestamp source signatures, Value Nodes' timestamps are equal to
6185 the system time when the Node is created. name can be provided as
6186 an alternative name for the resulting Value node; this is advised
6187 if the value parameter can't be converted to a string.
6188 The returned Value Node object has a write() method that can be
6190 used to "build" a Value Node by setting a new value. The optional
6191 built_value argument can be specified when the Value Node is
6192 created to indicate the Node should already be considered "built."
6193 There is a corresponding read() method that will return the built
6194 value of the Node.
6195 Examples:
6197 env = Environment()
6199 def create(target, source, env):
6201 # A function that will write a 'prefix=$SOURCE'
6202 # string into the file name specified as the
6203 # $TARGET.
6204 with open(str(target[0]), 'wb') as f:
6205 f.write('prefix=' + source[0].get_contents())
6206 # Fetch the prefix= argument, if any, from the command
6208 # line, and use /usr/local as the default.
6209 prefix = ARGUMENTS.get('prefix', '/usr/local')
6210 # Attach a .Config() builder for the above function action
6212 # to the construction environment.
6213 env['BUILDERS']['Config'] = Builder(action = create)
6214 env.Config(target = 'package-config', source = Value(prefix))
6215 def build_value(target, source, env):
6217 # A function that "builds" a Python Value by updating
6218 # the the Python value with the contents of the file
6219 # specified as the source of the Builder call ($SOURCE).
6220 target[0].write(source[0].get_contents())
6221 output = env.Value('before')
6223 input = env.Value('after')
6224 # Attach a .UpdateValue() builder for the above function
6226 # action to the construction environment.
6227 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6228 env.UpdateValue(target = Value(output), source = Value(input))
6229 VariantDir(variant_dir, src_dir, [duplicate]),
6231 env.VariantDir(variant_dir, src_dir, [duplicate])
6232 Sets up an alternate build location. When building in the
6233 variant_dir, SCons backfills as needed with files from src_dir to
6234 create a complete build directory. VariantDir can be called
6235 multiple times with the same src_dir to set up multiple builds with
6236 different options (variants).
6237 The variant location must be in or underneath the project top
6239 directory, and src_dir may not be underneath variant_dir.
6240 By default, SCons physically duplicates the source files and
6242 SConscript files as needed into the variant tree. Thus, a build
6243 performed in the variant tree is guaranteed to be identical to a
6244 build performed in the source tree even if intermediate source
6245 files are generated during the build, or if preprocessors or other
6246 scanners search for included files relative to the source file, or
6247 if individual compilers or other invoked tools are hard-coded to
6248 put derived files in the same directory as source files. Only the
6249 files SCons calculates are needed for the build are duplicated into
6250 variant_dir.
6251 If possible on the platform, the duplication is performed by
6253 linking rather than copying. This behavior is affected by the
6254 --duplicate command-line option.
6255 Duplicating the source files may be disabled by setting the
6257 duplicate argument to False. This will cause SCons to invoke
6258 Builders using the path names of source files in src_dir and the
6259 path names of derived files within variant_dir. This is more
6260 efficient than duplicate=True, and is safe for most builds; revert
6261 to True if it causes problems.
6262 VariantDir works most naturally with used with a subsidiary
6265 SConscript file. The subsidiary SConscript file is called as if it
6266 were in variant_dir, regardless of the value of duplicate. This is
6267 how you tell scons which variant of a source tree to build:
6268 # run src/SConscript in two variant directories
6270 VariantDir('build/variant1', 'src')
6271 SConscript('build/variant1/SConscript')
6272 VariantDir('build/variant2', 'src')
6273 SConscript('build/variant2/SConscript')
6274 See also the SConscript function, described above, for another way
6276 to specify a variant directory in conjunction with calling a
6277 subsidiary SConscript file.
6278 Examples:
6280 # use names in the build directory, not the source directory
6282 VariantDir('build', 'src', duplicate=0)
6283 Program('build/prog', 'build/source.c')
6284 # this builds both the source and docs in a separate subtree
6286 VariantDir('build', '.', duplicate=0)
6287 SConscript(dirs=['build/src','build/doc'])
6288 # same as previous example, but only uses SConscript
6290 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6291 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6292 WhereIs(program, [path, pathext, reject]), env.WhereIs(program, [path,
6294 pathext, reject])
6295 Searches for the specified executable program, returning the full
6296 path to the program or None.
6297 When called as a construction environment method, searches the
6299 paths in the path keyword argument, or if None (the default) the
6300 paths listed in the construction environment (env['ENV']['PATH']).
6301 The external environment's path list (os.environ['PATH']) is used
6302 as a fallback if the key env['ENV']['PATH'] does not exist.
6303 On Windows systems, searches for executable programs with any of
6305 the file extensions listed in the pathext keyword argument, or if
6306 None (the default) the pathname extensions listed in the
6307 construction environment (env['ENV']['PATHEXT']). The external
6308 environment's pathname extensions list (os.environ['PATHEXT']) is
6309 used as a fallback if the key env['ENV']['PATHEXT'] does not exist.
6310 When called as a global function, uses the external environment's
6312 path os.environ['PATH'] and path extensions os.environ['PATHEXT'],
6313 respectively, if path and pathext are None.
6314 Will not select any path name or names in the optional reject list.
6316 SConscript Variables
6318 In addition to the global functions and methods, scons supports a
6319 number of variables that can be used in SConscript files to affect how
6320 you want the build to be performed.
6321 ARGLIST
6323 A list of the keyword=value arguments specified on the command
6324 line. Each element in the list is a tuple containing the argument.
6325 The separate keyword and value elements of the tuple can be
6326 accessed by subscripting for elements [0] and [1] of the tuple, or,
6327 more readably, by using tuple unpacking. Example:
6328 print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
6330 print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
6331 key, value = ARGLIST[2]
6332 print("third keyword, value =", key, value)
6333 for key, value in ARGLIST:
6334 # process key and value
6335 ARGUMENTS
6337 A dictionary of all the keyword=value arguments specified on the
6338 command line. The dictionary is not in order, and if a given
6339 keyword has more than one value assigned to it on the command line,
6340 the last (right-most) value is the one in the ARGUMENTS dictionary.
6341 Example:
6343 if ARGUMENTS.get('debug', 0):
6345 env = Environment(CCFLAGS='-g')
6346 else:
6347 env = Environment()
6348 BUILD_TARGETS
6350 A list of the targets which scons has been asked to build. The
6351 contents will be either those targets listed on the command line,
6352 or, if none, those targets set via calls to the Default function.
6353 It does not contain any dependent targets that scons selects for
6354 building as a result of making the sure the specified targets are
6355 up to date, if those targets did not appear on the command line.
6356 The list is empty if neither command line targets or Default calls
6357 are present.
6358 The elements of this list may be strings or nodes, so you should
6360 run the list through the Python str function to make sure any Node
6361 path names are converted to strings.
6362 Because this list may be taken from the list of targets specified
6364 using the Default function, the contents of the list may change on
6365 each successive call to Default. See the DEFAULT_TARGETS list,
6366 below, for additional information.
6367 Example:
6369 if 'foo' in BUILD_TARGETS:
6371 print("Don't forget to test the `foo' program!")
6372 if 'special/program' in BUILD_TARGETS:
6373 SConscript('special')
6374 COMMAND_LINE_TARGETS
6376 A list of the targets explicitly specified on the command line. If
6377 there are command line targets, this list will have the same
6378 contents as BUILD_TARGETS. If there are no targets specified on the
6379 command line, the list is empty. The elements of this list are
6380 strings. This can be used, for example, to take specific actions
6381 only when certain targets are explicitly being built.
6382 Example:
6384 if 'foo' in COMMAND_LINE_TARGETS:
6386 print("Don't forget to test the `foo' program!")
6387 if 'special/program' in COMMAND_LINE_TARGETS:
6388 SConscript('special')
6389 DEFAULT_TARGETS
6391 A list of the target nodes that have been specified using the
6392 Default function. If there are no command line targets, this list
6393 will have the same contents as BUILD_TARGETS. Since the elements of
6394 the list are nodes, you need to call the Python str function on
6395 them to get the path name for each Node.
6396 Example:
6398 print(str(DEFAULT_TARGETS[0]))
6400 if 'foo' in [str(t) for t in DEFAULT_TARGETS]:
6401 print("Don't forget to test the `foo' program!")
6402 The contents of the DEFAULT_TARGETS list change on on each
6404 successive call to the Default function:
6405 print([str(t) for t in DEFAULT_TARGETS]) # originally []
6407 Default('foo')
6408 print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo']
6409 Default('bar')
6410 print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo', 'bar']
6411 Default(None)
6412 print([str(t) for t in DEFAULT_TARGETS]) # back to []
6413 Consequently, be sure to use DEFAULT_TARGETS only after you've made
6415 all of your Default() calls, or else simply be careful of the order
6416 of these statements in your SConscript files so that you don't look
6417 for a specific default target before it's actually been added to
6418 the list.
6419 These variables may be accessed from custom Python modules that you
6421 import into an SConscript file by adding the following to the Python
6422 module:
6423 from SCons.Script import *
6425 Construction Variables
6427 A construction environment has an associated dictionary of construction
6428 variables that are used by built-in or user-supplied build rules.
6429 Construction variable naming must follow the same rules as Python
6430 identifier naming: the initial character must be an underscore or
6431 letter, followed by any number of underscores, letters, or digits. A
6432 construction environment is not a Python dictionary itself, but it can
6433 be indexed like one to access a construction variable:
6434 env["CC"] = "cc"
6436 Construction variables can also be retrieved and set by using the
6438 Dictionary method of the construction environment to create an actual
6439 dictionary:
6440 cvars = env.Dictionary()
6442 cvars["CC"] = "cc"
6443 Construction variables can also be passed to the construction
6445 environment constructor:
6446 env = Environment(CC="cc")
6448 or when copying a construction environment using the Clone method:
6450 env2 = env.Clone(CC="cl.exe")
6452 A number of useful construction variables are automatically defined by
6454 scons for each supported platform, and additional construction
6455 variables can be defined by the user. The following is a list of the
6456 possible automatically defined construction variables. The actual list
6457 available at execution time will not include all of these, as the ones
6458 detected as not being useful (wrong platform, necessary external
6459 command or files not installed, etc.) will not be set up. :
6460 __LDMODULEVERSIONFLAGS
6462 This construction variable automatically introduces
6463 $_LDMODULEVERSIONFLAGS if $LDMODULEVERSION is set. Othervise it
6464 evaluates to an empty string.
6465 __SHLIBVERSIONFLAGS
6467 This construction variable automatically introduces
6468 $_SHLIBVERSIONFLAGS if $SHLIBVERSION is set. Othervise it evaluates
6469 to an empty string.
6470 APPLELINK_COMPATIBILITY_VERSION
6472 On Mac OS X this is used to set the linker flag:
6473 -compatibility_version
6474 The value is specified as X[.Y[.Z]] where X is between 1 and 65535,
6476 Y can be omitted or between 1 and 255, Z can be omitted or between
6477 1 and 255. This value will be derived from $SHLIBVERSION if not
6478 specified. The lowest digit will be dropped and replaced by a 0.
6479 If the $APPLELINK_NO_COMPATIBILITY_VERSION is set then no
6481 -compatibility_version will be output.
6482 See MacOS's ld manpage for more details
6484 _APPLELINK_COMPATIBILITY_VERSION
6486 A macro (by default a generator function) used to create the linker
6487 flags to specify apple's linker's -compatibility_version flag. The
6488 default generator uses $APPLELINK_COMPATIBILITY_VERSION and
6489 $APPLELINK_NO_COMPATIBILITY_VERSION and $SHLIBVERSION to determine
6490 the correct flag.
6491 APPLELINK_CURRENT_VERSION
6493 On Mac OS X this is used to set the linker flag: -current_version
6494 The value is specified as X[.Y[.Z]] where X is between 1 and 65535,
6496 Y can be omitted or between 1 and 255, Z can be omitted or between
6497 1 and 255. This value will be set to $SHLIBVERSION if not
6498 specified.
6499 If the $APPLELINK_NO_CURRENT_VERSION is set then no
6501 -current_version will be output.
6502 See MacOS's ld manpage for more details
6504 _APPLELINK_CURRENT_VERSION
6506 A macro (by default a generator function) used to create the linker
6507 flags to specify apple's linker's -current_version flag. The
6508 default generator uses $APPLELINK_CURRENT_VERSION and
6509 $APPLELINK_NO_CURRENT_VERSION and $SHLIBVERSION to determine the
6510 correct flag.
6511 APPLELINK_NO_COMPATIBILITY_VERSION
6513 Set this to any True (1|True|non-empty string) value to disable
6514 adding -compatibility_version flag when generating versioned shared
6515 libraries.
6516 This overrides $APPLELINK_COMPATIBILITY_VERSION.
6518 APPLELINK_NO_CURRENT_VERSION
6520 Set this to any True (1|True|non-empty string) value to disable
6521 adding -current_version flag when generating versioned shared
6522 libraries.
6523 This overrides $APPLELINK_CURRENT_VERSION.
6525 AR
6527 The static library archiver.
6528 ARCHITECTURE
6530 Specifies the system architecture for which the package is being
6531 built. The default is the system architecture of the machine on
6532 which SCons is running. This is used to fill in the Architecture:
6533 field in an Ipkg control file, and the BuildArch: field in the RPM
6534 .spec file, as well as forming part of the name of a generated RPM
6535 package file.
6536 ARCOM
6538 The command line used to generate a static library from object
6539 files.
6540 ARCOMSTR
6542 The string displayed when a static library is generated from object
6543 files. If this is not set, then $ARCOM (the command line) is
6544 displayed.
6545 env = Environment(ARCOMSTR = "Archiving $TARGET")
6547 ARFLAGS
6549 General options passed to the static library archiver.
6550 AS
6552 The assembler.
6553 ASCOM
6555 The command line used to generate an object file from an
6556 assembly-language source file.
6557 ASCOMSTR
6559 The string displayed when an object file is generated from an
6560 assembly-language source file. If this is not set, then $ASCOM (the
6561 command line) is displayed.
6562 env = Environment(ASCOMSTR = "Assembling $TARGET")
6564 ASFLAGS
6566 General options passed to the assembler.
6567 ASPPCOM
6569 The command line used to assemble an assembly-language source file
6570 into an object file after first running the file through the C
6571 preprocessor. Any options specified in the $ASFLAGS and $CPPFLAGS
6572 construction variables are included on this command line.
6573 ASPPCOMSTR
6575 The string displayed when an object file is generated from an
6576 assembly-language source file after first running the file through
6577 the C preprocessor. If this is not set, then $ASPPCOM (the command
6578 line) is displayed.
6579 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
6581 ASPPFLAGS
6583 General options when an assembling an assembly-language source file
6584 into an object file after first running the file through the C
6585 preprocessor. The default is to use the value of $ASFLAGS.
6586 BIBTEX
6588 The bibliography generator for the TeX formatter and typesetter and
6589 the LaTeX structured formatter and typesetter.
6590 BIBTEXCOM
6592 The command line used to call the bibliography generator for the
6593 TeX formatter and typesetter and the LaTeX structured formatter and
6594 typesetter.
6595 BIBTEXCOMSTR
6597 The string displayed when generating a bibliography for TeX or
6598 LaTeX. If this is not set, then $BIBTEXCOM (the command line) is
6599 displayed.
6600 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
6602 BIBTEXFLAGS
6604 General options passed to the bibliography generator for the TeX
6605 formatter and typesetter and the LaTeX structured formatter and
6606 typesetter.
6607 BUILDERS
6609 A dictionary mapping the names of the builders available through
6610 the construction environment to underlying Builder objects. Custom
6611 builders need to be added to this to make them available.
6612 A platform-dependent default list of builders such as Program,
6614 Library etc. is used to populate this construction variable when
6615 the construction environment is initialized via the
6616 presence/absence of the tools those builders depend on. $BUILDERS
6617 can be examined to learn which builders will actually be available
6618 at run-time.
6619 Note that if you initialize this construction variable through
6621 assignment when the construction environment is created, that value
6622 for $BUILDERS will override any defaults:
6623 bld = Builder(action='foobuild < $SOURCE > $TARGET')
6625 env = Environment(BUILDERS={'NewBuilder': bld})
6626 To instead use a new Builder object in addition to the default
6628 Builders, add your new Builder object like this:
6629 env = Environment()
6631 env.Append(BUILDERS={'NewBuilder': bld})
6632 or this:
6634 env = Environment()
6636 env['BUILDERS']['NewBuilder'] = bld
6637 CC
6639 The C compiler.
6640 CCCOM
6642 The command line used to compile a C source file to a (static)
6643 object file. Any options specified in the $CFLAGS, $CCFLAGS and
6644 $CPPFLAGS construction variables are included on this command line.
6645 See also $SHCCCOM for compiling to shared objects.
6646 CCCOMSTR
6648 If set, the string displayed when a C source file is compiled to a
6649 (static) object file. If not set, then $CCCOM (the command line) is
6650 displayed. See also $SHCCCOMSTR for compiling to shared objects.
6651 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
6653 CCFLAGS
6655 General options that are passed to the C and C++ compilers. See
6656 also $SHCCFLAGS for compiling to shared objects.
6657 CCPCHFLAGS
6659 Options added to the compiler command line to support building with
6660 precompiled headers. The default value expands expands to the
6661 appropriate Microsoft Visual C++ command-line options when the $PCH
6662 construction variable is set.
6663 CCPDBFLAGS
6665 Options added to the compiler command line to support storing
6666 debugging information in a Microsoft Visual C++ PDB file. The
6667 default value expands expands to appropriate Microsoft Visual C++
6668 command-line options when the $PDB construction variable is set.
6669 The Visual C++ compiler option that SCons uses by default to
6671 generate PDB information is /Z7. This works correctly with parallel
6672 (-j) builds because it embeds the debug information in the
6673 intermediate object files, as opposed to sharing a single PDB file
6674 between multiple object files. This is also the only way to get
6675 debug information embedded into a static library. Using the /Zi
6676 instead may yield improved link-time performance, although parallel
6677 builds will no longer work.
6678 You can generate PDB files with the /Zi switch by overriding the
6680 default $CCPDBFLAGS variable as follows:
6681 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
6683 An alternative would be to use the /Zi to put the debugging
6685 information in a separate .pdb file for each object file by
6686 overriding the $CCPDBFLAGS variable as follows:
6687 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
6689 CCVERSION
6691 The version number of the C compiler. This may or may not be set,
6692 depending on the specific C compiler being used.
6693 CFILESUFFIX
6695 The suffix for C source files. This is used by the internal CFile
6696 builder when generating C files from Lex (.l) or YACC (.y) input
6697 files. The default suffix, of course, is .c (lower case). On
6698 case-insensitive systems (like Windows), SCons also treats .C
6699 (upper case) files as C files.
6700 CFLAGS
6702 General options that are passed to the C compiler (C only; not
6703 C++). See also $SHCFLAGS for compiling to shared objects.
6704 CHANGE_SPECFILE
6706 A hook for modifying the file that controls the packaging build
6707 (the .spec for RPM, the control for Ipkg, the .wxs for MSI). If
6708 set, the function will be called after the SCons template for the
6709 file has been written.
6710 CHANGED_SOURCES
6712 A reserved variable name that may not be set or used in a
6713 construction environment. (See the manpage section "Variable
6714 Substitution" for more information).
6715 CHANGED_TARGETS
6717 A reserved variable name that may not be set or used in a
6718 construction environment. (See the manpage section "Variable
6719 Substitution" for more information).
6720 CHANGELOG
6722 The name of a file containing the change log text to be included in
6723 the package. This is included as the %changelog section of the RPM
6724 .spec file.
6725 COMPILATIONDB_COMSTR
6727 The string displayed when the CompilationDatabase builder's action
6728 is run.
6729 COMPILATIONDB_PATH_FILTER
6731 A string which instructs CompilationDatabase to only include
6732 entries where the output member matches the pattern in the filter
6733 string using fnmatch, which uses glob style wildcards.
6734 The default value is an empty string '', which disables filtering.
6736 COMPILATIONDB_USE_ABSPATH
6738 A boolean flag to instruct CompilationDatabase whether to write the
6739 file and output members in the compilation database using absolute
6740 or relative paths.
6741 The default value is False (use relative paths)
6743 _concat
6745 A function used to produce variables like $_CPPINCFLAGS. It takes
6746 four or five arguments: a prefix to concatenate onto each element,
6747 a list of elements, a suffix to concatenate onto each element, an
6748 environment for variable interpolation, and an optional function
6749 that will be called to transform the list before concatenation.
6750 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
6752 CONFIGUREDIR
6754 The name of the directory in which Configure context test files are
6755 written. The default is .sconf_temp in the top-level directory
6756 containing the SConstruct file.
6757 CONFIGURELOG
6759 The name of the Configure context log file. The default is
6760 config.log in the top-level directory containing the SConstruct
6761 file.
6762 _CPPDEFFLAGS
6764 An automatically-generated construction variable containing the C
6765 preprocessor command-line options to define values. The value of
6766 $_CPPDEFFLAGS is created by respectively prepending and appending
6767 $CPPDEFPREFIX and $CPPDEFSUFFIX to the beginning and end of each
6768 definition in $CPPDEFINES.
6769 CPPDEFINES
6771 A platform independent specification of C preprocessor definitions.
6772 The definitions will be added to command lines through the
6773 automatically-generated $_CPPDEFFLAGS construction variable (see
6774 above), which is constructed according to the type of value of
6775 $CPPDEFINES:
6776 If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and
6778 $CPPDEFSUFFIX construction variables will be respectively prepended
6779 and appended to the beginning and end of each definition in
6780 $CPPDEFINES.
6781 # Will add -Dxyz to POSIX compiler command lines,
6783 # and /Dxyz to Microsoft Visual C++ command lines.
6784 env = Environment(CPPDEFINES='xyz')
6785 If $CPPDEFINES is a list, the values of the $CPPDEFPREFIX and
6787 $CPPDEFSUFFIX construction variables will be respectively prepended
6788 and appended to the beginning and end of each element in the list.
6789 If any element is a list or tuple, then the first item is the name
6790 being defined and the second item is its value:
6791 # Will add -DB=2 -DA to POSIX compiler command lines,
6793 # and /DB=2 /DA to Microsoft Visual C++ command lines.
6794 env = Environment(CPPDEFINES=[('B', 2), 'A'])
6795 If $CPPDEFINES is a dictionary, the values of the $CPPDEFPREFIX and
6797 $CPPDEFSUFFIX construction variables will be respectively prepended
6798 and appended to the beginning and end of each item from the
6799 dictionary. The key of each dictionary item is a name being defined
6800 to the dictionary item's corresponding value; if the value is None,
6801 then the name is defined without an explicit value. Note that the
6802 resulting flags are sorted by keyword to ensure that the order of
6803 the options on the command line is consistent each time scons is
6804 run.
6805 # Will add -DA -DB=2 to POSIX compiler command lines,
6807 # and /DA /DB=2 to Microsoft Visual C++ command lines.
6808 env = Environment(CPPDEFINES={'B':2, 'A':None})
6809 CPPDEFPREFIX
6811 The prefix used to specify preprocessor definitions on the C
6812 compiler command line. This will be prepended to the beginning of
6813 each definition in the $CPPDEFINES construction variable when the
6814 $_CPPDEFFLAGS variable is automatically generated.
6815 CPPDEFSUFFIX
6817 The suffix used to specify preprocessor definitions on the C
6818 compiler command line. This will be appended to the end of each
6819 definition in the $CPPDEFINES construction variable when the
6820 $_CPPDEFFLAGS variable is automatically generated.
6821 CPPFLAGS
6823 User-specified C preprocessor options. These will be included in
6824 any command that uses the C preprocessor, including not just
6825 compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
6826 $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
6827 $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
6828 compile a Fortran source file, and the $ASPPCOM command line used
6829 to assemble an assembly language source file, after first running
6830 each file through the C preprocessor. Note that this variable does
6831 not contain -I (or similar) include search path options that scons
6832 generates automatically from $CPPPATH. See $_CPPINCFLAGS, below,
6833 for the variable that expands to those options.
6834 _CPPINCFLAGS
6836 An automatically-generated construction variable containing the C
6837 preprocessor command-line options for specifying directories to be
6838 searched for include files. The value of $_CPPINCFLAGS is created
6839 by respectively prepending and appending $INCPREFIX and $INCSUFFIX
6840 to the beginning and end of each directory in $CPPPATH.
6841 CPPPATH
6843 The list of directories that the C preprocessor will search for
6844 include directories. The C/C++ implicit dependency scanner will
6845 search these directories for include files. Don't explicitly put
6846 include directory arguments in CCFLAGS or CXXFLAGS because the
6847 result will be non-portable and the directories will not be
6848 searched by the dependency scanner. Note: directory names in
6849 CPPPATH will be looked-up relative to the SConscript directory when
6850 they are used in a command. To force scons to look-up a directory
6851 relative to the root of the source tree use #:
6852 env = Environment(CPPPATH='#/include')
6854 The directory look-up can also be forced using the Dir() function:
6856 include = Dir('include')
6858 env = Environment(CPPPATH=include)
6859 The directory list will be added to command lines through the
6861 automatically-generated $_CPPINCFLAGS construction variable, which
6862 is constructed by respectively prepending and appending the value
6863 of the $INCPREFIX and $INCSUFFIX construction variables to the
6864 beginning and end of each directory in $CPPPATH. Any command lines
6865 you define that need the CPPPATH directory list should include
6866 $_CPPINCFLAGS:
6867 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
6869 CPPSUFFIXES
6871 The list of suffixes of files that will be scanned for C
6872 preprocessor implicit dependencies (#include lines). The default
6873 list is:
6874 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
6876 ".h", ".H", ".hxx", ".hpp", ".hh",
6877 ".F", ".fpp", ".FPP",
6878 ".m", ".mm",
6879 ".S", ".spp", ".SPP"]
6880 CXX
6882 The C++ compiler. See also $SHCXX for compiling to shared objects..
6883 CXXCOM
6885 The command line used to compile a C++ source file to an object
6886 file. Any options specified in the $CXXFLAGS and $CPPFLAGS
6887 construction variables are included on this command line. See also
6888 $SHCXXCOM for compiling to shared objects..
6889 CXXCOMSTR
6891 If set, the string displayed when a C++ source file is compiled to
6892 a (static) object file. If not set, then $CXXCOM (the command line)
6893 is displayed. See also $SHCXXCOMSTR for compiling to shared
6894 objects..
6895 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
6897 CXXFILESUFFIX
6899 The suffix for C++ source files. This is used by the internal
6900 CXXFile builder when generating C++ files from Lex (.ll) or YACC
6901 (.yy) input files. The default suffix is .cc. SCons also treats
6902 files with the suffixes .cpp, .cxx, .c++, and .C++ as C++ files,
6903 and files with .mm suffixes as Objective C++ files. On
6904 case-sensitive systems (Linux, UNIX, and other POSIX-alikes), SCons
6905 also treats .C (upper case) files as C++ files.
6906 CXXFLAGS
6908 General options that are passed to the C++ compiler. By default,
6909 this includes the value of $CCFLAGS, so that setting $CCFLAGS
6910 affects both C and C++ compilation. If you want to add C++-specific
6911 flags, you must set or override the value of $CXXFLAGS. See also
6912 $SHCXXFLAGS for compiling to shared objects..
6913 CXXVERSION
6915 The version number of the C++ compiler. This may or may not be set,
6916 depending on the specific C++ compiler being used.
6917 DC
6919 The D compiler to use. See also $SHDC for compiling to shared
6920 objects.
6921 DCOM
6923 The command line used to compile a D file to an object file. Any
6924 options specified in the $DFLAGS construction variable is included
6925 on this command line. See also $SHDCOM for compiling to shared
6926 objects.
6927 DCOMSTR
6929 If set, the string displayed when a D source file is compiled to a
6930 (static) object file. If not set, then $DCOM (the command line) is
6931 displayed. See also $SHDCOMSTR for compiling to shared objects.
6932 DDEBUG
6934 List of debug tags to enable when compiling.
6935 DDEBUGPREFIX
6937 DDEBUGPREFIX.
6938 DDEBUGSUFFIX
6940 DDEBUGSUFFIX.
6941 DESCRIPTION
6943 A long description of the project being packaged. This is included
6944 in the relevant section of the file that controls the packaging
6945 build.
6946 DESCRIPTION_lang
6948 A language-specific long description for the specified lang. This
6949 is used to populate a %description -l section of an RPM .spec file.
6950 DFILESUFFIX
6952 DFILESUFFIX.
6953 DFLAGPREFIX
6955 DFLAGPREFIX.
6956 DFLAGS
6958 General options that are passed to the D compiler.
6959 DFLAGSUFFIX
6961 DFLAGSUFFIX.
6962 DINCPREFIX
6964 DINCPREFIX.
6965 DINCSUFFIX
6967 DLIBFLAGSUFFIX.
6968 Dir
6970 A function that converts a string into a Dir instance relative to
6971 the target being built.
6972 Dirs
6974 A function that converts a list of strings into a list of Dir
6975 instances relative to the target being built.
6976 DLIB
6978 Name of the lib tool to use for D codes.
6979 DLIBCOM
6981 The command line to use when creating libraries.
6982 DLIBDIRPREFIX
6984 DLIBLINKPREFIX.
6985 DLIBDIRSUFFIX
6987 DLIBLINKSUFFIX.
6988 DLIBFLAGPREFIX
6990 DLIBFLAGPREFIX.
6991 DLIBFLAGSUFFIX
6993 DLIBFLAGSUFFIX.
6994 DLIBLINKPREFIX
6996 DLIBLINKPREFIX.
6997 DLIBLINKSUFFIX
6999 DLIBLINKSUFFIX.
7000 DLINK
7002 Name of the linker to use for linking systems including D sources.
7003 See also $SHDLINK for linking shared objects.
7004 DLINKCOM
7006 The command line to use when linking systems including D sources.
7007 See also $SHDLINKCOM for linking shared objects.
7008 DLINKFLAGPREFIX
7010 DLINKFLAGPREFIX.
7011 DLINKFLAGS
7013 List of linker flags. See also $SHDLINKFLAGS for linking shared
7014 objects.
7015 DLINKFLAGSUFFIX
7017 DLINKFLAGSUFFIX.
7018 DOCBOOK_DEFAULT_XSL_EPUB
7020 The default XSLT file for the DocbookEpub builder within the
7021 current environment, if no other XSLT gets specified via keyword.
7022 DOCBOOK_DEFAULT_XSL_HTML
7024 The default XSLT file for the DocbookHtml builder within the
7025 current environment, if no other XSLT gets specified via keyword.
7026 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
7028 The default XSLT file for the DocbookHtmlChunked builder within the
7029 current environment, if no other XSLT gets specified via keyword.
7030 DOCBOOK_DEFAULT_XSL_HTMLHELP
7032 The default XSLT file for the DocbookHtmlhelp builder within the
7033 current environment, if no other XSLT gets specified via keyword.
7034 DOCBOOK_DEFAULT_XSL_MAN
7036 The default XSLT file for the DocbookMan builder within the current
7037 environment, if no other XSLT gets specified via keyword.
7038 DOCBOOK_DEFAULT_XSL_PDF
7040 The default XSLT file for the DocbookPdf builder within the current
7041 environment, if no other XSLT gets specified via keyword.
7042 DOCBOOK_DEFAULT_XSL_SLIDESHTML
7044 The default XSLT file for the DocbookSlidesHtml builder within the
7045 current environment, if no other XSLT gets specified via keyword.
7046 DOCBOOK_DEFAULT_XSL_SLIDESPDF
7048 The default XSLT file for the DocbookSlidesPdf builder within the
7049 current environment, if no other XSLT gets specified via keyword.
7050 DOCBOOK_FOP
7052 The path to the PDF renderer fop or xep, if one of them is
7053 installed (fop gets checked first).
7054 DOCBOOK_FOPCOM
7056 The full command-line for the PDF renderer fop or xep.
7057 DOCBOOK_FOPCOMSTR
7059 The string displayed when a renderer like fop or xep is used to
7060 create PDF output from an XML file.
7061 DOCBOOK_FOPFLAGS
7063 Additonal command-line flags for the PDF renderer fop or xep.
7064 DOCBOOK_XMLLINT
7066 The path to the external executable xmllint, if it's installed.
7067 Note, that this is only used as last fallback for resolving
7068 XIncludes, if no lxml Python binding can be imported in the current
7069 system.
7070 DOCBOOK_XMLLINTCOM
7072 The full command-line for the external executable xmllint.
7073 DOCBOOK_XMLLINTCOMSTR
7075 The string displayed when xmllint is used to resolve XIncludes for
7076 a given XML file.
7077 DOCBOOK_XMLLINTFLAGS
7079 Additonal command-line flags for the external executable xmllint.
7080 DOCBOOK_XSLTPROC
7082 The path to the external executable xsltproc (or saxon, xalan), if
7083 one of them is installed. Note, that this is only used as last
7084 fallback for XSL transformations, if no lxml Python binding can be
7085 imported in the current system.
7086 DOCBOOK_XSLTPROCCOM
7088 The full command-line for the external executable xsltproc (or
7089 saxon, xalan).
7090 DOCBOOK_XSLTPROCCOMSTR
7092 The string displayed when xsltproc is used to transform an XML file
7093 via a given XSLT stylesheet.
7094 DOCBOOK_XSLTPROCFLAGS
7096 Additonal command-line flags for the external executable xsltproc
7097 (or saxon, xalan).
7098 DOCBOOK_XSLTPROCPARAMS
7100 Additonal parameters that are not intended for the XSLT processor
7101 executable, but the XSL processing itself. By default, they get
7102 appended at the end of the command line for saxon and saxon-xslt,
7103 respectively.
7104 DPATH
7106 List of paths to search for import modules.
7107 DRPATHPREFIX
7109 DRPATHPREFIX.
7110 DRPATHSUFFIX
7112 DRPATHSUFFIX.
7113 DSUFFIXES
7115 The list of suffixes of files that will be scanned for imported D
7116 package files. The default list is ['.d'].
7117 DVERPREFIX
7119 DVERPREFIX.
7120 DVERSIONS
7122 List of version tags to enable when compiling.
7123 DVERSUFFIX
7125 DVERSUFFIX.
7126 DVIPDF
7128 The TeX DVI file to PDF file converter.
7129 DVIPDFCOM
7131 The command line used to convert TeX DVI files into a PDF file.
7132 DVIPDFCOMSTR
7134 The string displayed when a TeX DVI file is converted into a PDF
7135 file. If this is not set, then $DVIPDFCOM (the command line) is
7136 displayed.
7137 DVIPDFFLAGS
7139 General options passed to the TeX DVI file to PDF file converter.
7140 DVIPS
7142 The TeX DVI file to PostScript converter.
7143 DVIPSFLAGS
7145 General options passed to the TeX DVI file to PostScript converter.
7146 ENV
7148 A dictionary of environment variables to use when invoking
7149 commands. When $ENV is used in a command all list values will be
7150 joined using the path separator and any other non-string values
7151 will simply be coerced to a string. Note that, by default, scons
7152 does not propagate the environment in force when you execute scons
7153 to the commands used to build target files. This is so that builds
7154 will be guaranteed repeatable regardless of the environment
7155 variables set at the time scons is invoked.
7156 If you want to propagate your environment variables to the commands
7158 executed to build target files, you must do so explicitly:
7159 import os
7161 env = Environment(ENV = os.environ)
7162 Note that you can choose only to propagate certain environment
7164 variables. A common example is the system PATH environment
7165 variable, so that scons uses the same utilities as the invoking
7166 shell (or other process):
7167 import os
7169 env = Environment(ENV = {'PATH' : os.environ['PATH']})
7170 ESCAPE
7172 A function that will be called to escape shell special characters
7173 in command lines. The function should take one argument: the
7174 command line string to escape; and should return the escaped
7175 command line.
7176 F03
7178 The Fortran 03 compiler. You should normally set the $FORTRAN
7179 variable, which specifies the default Fortran compiler for all
7180 Fortran versions. You only need to set $F03 if you need to use a
7181 specific compiler or compiler version for Fortran 03 files.
7182 F03COM
7184 The command line used to compile a Fortran 03 source file to an
7185 object file. You only need to set $F03COM if you need to use a
7186 specific command line for Fortran 03 files. You should normally set
7187 the $FORTRANCOM variable, which specifies the default command line
7188 for all Fortran versions.
7189 F03COMSTR
7191 If set, the string displayed when a Fortran 03 source file is
7192 compiled to an object file. If not set, then $F03COM or $FORTRANCOM
7193 (the command line) is displayed.
7194 F03FILESUFFIXES
7196 The list of file extensions for which the F03 dialect will be used.
7197 By default, this is ['.f03']
7198 F03FLAGS
7200 General user-specified options that are passed to the Fortran 03
7201 compiler. Note that this variable does not contain -I (or similar)
7202 include search path options that scons generates automatically from
7203 $F03PATH. See $_F03INCFLAGS below, for the variable that expands to
7204 those options. You only need to set $F03FLAGS if you need to define
7205 specific user options for Fortran 03 files. You should normally set
7206 the $FORTRANFLAGS variable, which specifies the user-specified
7207 options passed to the default Fortran compiler for all Fortran
7208 versions.
7209 _F03INCFLAGS
7211 An automatically-generated construction variable containing the
7212 Fortran 03 compiler command-line options for specifying directories
7213 to be searched for include files. The value of $_F03INCFLAGS is
7214 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7215 end of each directory in $F03PATH.
7216 F03PATH
7218 The list of directories that the Fortran 03 compiler will search
7219 for include directories. The implicit dependency scanner will
7220 search these directories for include files. Don't explicitly put
7221 include directory arguments in $F03FLAGS because the result will be
7222 non-portable and the directories will not be searched by the
7223 dependency scanner. Note: directory names in $F03PATH will be
7224 looked-up relative to the SConscript directory when they are used
7225 in a command. To force scons to look-up a directory relative to the
7226 root of the source tree use #: You only need to set $F03PATH if you
7227 need to define a specific include path for Fortran 03 files. You
7228 should normally set the $FORTRANPATH variable, which specifies the
7229 include path for the default Fortran compiler for all Fortran
7230 versions.
7231 env = Environment(F03PATH='#/include')
7233 The directory look-up can also be forced using the Dir() function:
7235 include = Dir('include')
7237 env = Environment(F03PATH=include)
7238 The directory list will be added to command lines through the
7240 automatically-generated $_F03INCFLAGS construction variable, which
7241 is constructed by appending the values of the $INCPREFIX and
7242 $INCSUFFIX construction variables to the beginning and end of each
7243 directory in $F03PATH. Any command lines you define that need the
7244 F03PATH directory list should include $_F03INCFLAGS:
7245 env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
7247 F03PPCOM
7249 The command line used to compile a Fortran 03 source file to an
7250 object file after first running the file through the C
7251 preprocessor. Any options specified in the $F03FLAGS and $CPPFLAGS
7252 construction variables are included on this command line. You only
7253 need to set $F03PPCOM if you need to use a specific C-preprocessor
7254 command line for Fortran 03 files. You should normally set the
7255 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7256 command line for all Fortran versions.
7257 F03PPCOMSTR
7259 If set, the string displayed when a Fortran 03 source file is
7260 compiled to an object file after first running the file through the
7261 C preprocessor. If not set, then $F03PPCOM or $FORTRANPPCOM (the
7262 command line) is displayed.
7263 F03PPFILESUFFIXES
7265 The list of file extensions for which the compilation +
7266 preprocessor pass for F03 dialect will be used. By default, this is
7267 empty.
7268 F08
7270 The Fortran 08 compiler. You should normally set the $FORTRAN
7271 variable, which specifies the default Fortran compiler for all
7272 Fortran versions. You only need to set $F08 if you need to use a
7273 specific compiler or compiler version for Fortran 08 files.
7274 F08COM
7276 The command line used to compile a Fortran 08 source file to an
7277 object file. You only need to set $F08COM if you need to use a
7278 specific command line for Fortran 08 files. You should normally set
7279 the $FORTRANCOM variable, which specifies the default command line
7280 for all Fortran versions.
7281 F08COMSTR
7283 If set, the string displayed when a Fortran 08 source file is
7284 compiled to an object file. If not set, then $F08COM or $FORTRANCOM
7285 (the command line) is displayed.
7286 F08FILESUFFIXES
7288 The list of file extensions for which the F08 dialect will be used.
7289 By default, this is ['.f08']
7290 F08FLAGS
7292 General user-specified options that are passed to the Fortran 08
7293 compiler. Note that this variable does not contain -I (or similar)
7294 include search path options that scons generates automatically from
7295 $F08PATH. See $_F08INCFLAGS below, for the variable that expands to
7296 those options. You only need to set $F08FLAGS if you need to define
7297 specific user options for Fortran 08 files. You should normally set
7298 the $FORTRANFLAGS variable, which specifies the user-specified
7299 options passed to the default Fortran compiler for all Fortran
7300 versions.
7301 _F08INCFLAGS
7303 An automatically-generated construction variable containing the
7304 Fortran 08 compiler command-line options for specifying directories
7305 to be searched for include files. The value of $_F08INCFLAGS is
7306 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7307 end of each directory in $F08PATH.
7308 F08PATH
7310 The list of directories that the Fortran 08 compiler will search
7311 for include directories. The implicit dependency scanner will
7312 search these directories for include files. Don't explicitly put
7313 include directory arguments in $F08FLAGS because the result will be
7314 non-portable and the directories will not be searched by the
7315 dependency scanner. Note: directory names in $F08PATH will be
7316 looked-up relative to the SConscript directory when they are used
7317 in a command. To force scons to look-up a directory relative to the
7318 root of the source tree use #: You only need to set $F08PATH if you
7319 need to define a specific include path for Fortran 08 files. You
7320 should normally set the $FORTRANPATH variable, which specifies the
7321 include path for the default Fortran compiler for all Fortran
7322 versions.
7323 env = Environment(F08PATH='#/include')
7325 The directory look-up can also be forced using the Dir() function:
7327 include = Dir('include')
7329 env = Environment(F08PATH=include)
7330 The directory list will be added to command lines through the
7332 automatically-generated $_F08INCFLAGS construction variable, which
7333 is constructed by appending the values of the $INCPREFIX and
7334 $INCSUFFIX construction variables to the beginning and end of each
7335 directory in $F08PATH. Any command lines you define that need the
7336 F08PATH directory list should include $_F08INCFLAGS:
7337 env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
7339 F08PPCOM
7341 The command line used to compile a Fortran 08 source file to an
7342 object file after first running the file through the C
7343 preprocessor. Any options specified in the $F08FLAGS and $CPPFLAGS
7344 construction variables are included on this command line. You only
7345 need to set $F08PPCOM if you need to use a specific C-preprocessor
7346 command line for Fortran 08 files. You should normally set the
7347 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7348 command line for all Fortran versions.
7349 F08PPCOMSTR
7351 If set, the string displayed when a Fortran 08 source file is
7352 compiled to an object file after first running the file through the
7353 C preprocessor. If not set, then $F08PPCOM or $FORTRANPPCOM (the
7354 command line) is displayed.
7355 F08PPFILESUFFIXES
7357 The list of file extensions for which the compilation +
7358 preprocessor pass for F08 dialect will be used. By default, this is
7359 empty.
7360 F77
7362 The Fortran 77 compiler. You should normally set the $FORTRAN
7363 variable, which specifies the default Fortran compiler for all
7364 Fortran versions. You only need to set $F77 if you need to use a
7365 specific compiler or compiler version for Fortran 77 files.
7366 F77COM
7368 The command line used to compile a Fortran 77 source file to an
7369 object file. You only need to set $F77COM if you need to use a
7370 specific command line for Fortran 77 files. You should normally set
7371 the $FORTRANCOM variable, which specifies the default command line
7372 for all Fortran versions.
7373 F77COMSTR
7375 If set, the string displayed when a Fortran 77 source file is
7376 compiled to an object file. If not set, then $F77COM or $FORTRANCOM
7377 (the command line) is displayed.
7378 F77FILESUFFIXES
7380 The list of file extensions for which the F77 dialect will be used.
7381 By default, this is ['.f77']
7382 F77FLAGS
7384 General user-specified options that are passed to the Fortran 77
7385 compiler. Note that this variable does not contain -I (or similar)
7386 include search path options that scons generates automatically from
7387 $F77PATH. See $_F77INCFLAGS below, for the variable that expands to
7388 those options. You only need to set $F77FLAGS if you need to define
7389 specific user options for Fortran 77 files. You should normally set
7390 the $FORTRANFLAGS variable, which specifies the user-specified
7391 options passed to the default Fortran compiler for all Fortran
7392 versions.
7393 _F77INCFLAGS
7395 An automatically-generated construction variable containing the
7396 Fortran 77 compiler command-line options for specifying directories
7397 to be searched for include files. The value of $_F77INCFLAGS is
7398 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7399 end of each directory in $F77PATH.
7400 F77PATH
7402 The list of directories that the Fortran 77 compiler will search
7403 for include directories. The implicit dependency scanner will
7404 search these directories for include files. Don't explicitly put
7405 include directory arguments in $F77FLAGS because the result will be
7406 non-portable and the directories will not be searched by the
7407 dependency scanner. Note: directory names in $F77PATH will be
7408 looked-up relative to the SConscript directory when they are used
7409 in a command. To force scons to look-up a directory relative to the
7410 root of the source tree use #: You only need to set $F77PATH if you
7411 need to define a specific include path for Fortran 77 files. You
7412 should normally set the $FORTRANPATH variable, which specifies the
7413 include path for the default Fortran compiler for all Fortran
7414 versions.
7415 env = Environment(F77PATH='#/include')
7417 The directory look-up can also be forced using the Dir() function:
7419 include = Dir('include')
7421 env = Environment(F77PATH=include)
7422 The directory list will be added to command lines through the
7424 automatically-generated $_F77INCFLAGS construction variable, which
7425 is constructed by appending the values of the $INCPREFIX and
7426 $INCSUFFIX construction variables to the beginning and end of each
7427 directory in $F77PATH. Any command lines you define that need the
7428 F77PATH directory list should include $_F77INCFLAGS:
7429 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
7431 F77PPCOM
7433 The command line used to compile a Fortran 77 source file to an
7434 object file after first running the file through the C
7435 preprocessor. Any options specified in the $F77FLAGS and $CPPFLAGS
7436 construction variables are included on this command line. You only
7437 need to set $F77PPCOM if you need to use a specific C-preprocessor
7438 command line for Fortran 77 files. You should normally set the
7439 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7440 command line for all Fortran versions.
7441 F77PPCOMSTR
7443 If set, the string displayed when a Fortran 77 source file is
7444 compiled to an object file after first running the file through the
7445 C preprocessor. If not set, then $F77PPCOM or $FORTRANPPCOM (the
7446 command line) is displayed.
7447 F77PPFILESUFFIXES
7449 The list of file extensions for which the compilation +
7450 preprocessor pass for F77 dialect will be used. By default, this is
7451 empty.
7452 F90
7454 The Fortran 90 compiler. You should normally set the $FORTRAN
7455 variable, which specifies the default Fortran compiler for all
7456 Fortran versions. You only need to set $F90 if you need to use a
7457 specific compiler or compiler version for Fortran 90 files.
7458 F90COM
7460 The command line used to compile a Fortran 90 source file to an
7461 object file. You only need to set $F90COM if you need to use a
7462 specific command line for Fortran 90 files. You should normally set
7463 the $FORTRANCOM variable, which specifies the default command line
7464 for all Fortran versions.
7465 F90COMSTR
7467 If set, the string displayed when a Fortran 90 source file is
7468 compiled to an object file. If not set, then $F90COM or $FORTRANCOM
7469 (the command line) is displayed.
7470 F90FILESUFFIXES
7472 The list of file extensions for which the F90 dialect will be used.
7473 By default, this is ['.f90']
7474 F90FLAGS
7476 General user-specified options that are passed to the Fortran 90
7477 compiler. Note that this variable does not contain -I (or similar)
7478 include search path options that scons generates automatically from
7479 $F90PATH. See $_F90INCFLAGS below, for the variable that expands to
7480 those options. You only need to set $F90FLAGS if you need to define
7481 specific user options for Fortran 90 files. You should normally set
7482 the $FORTRANFLAGS variable, which specifies the user-specified
7483 options passed to the default Fortran compiler for all Fortran
7484 versions.
7485 _F90INCFLAGS
7487 An automatically-generated construction variable containing the
7488 Fortran 90 compiler command-line options for specifying directories
7489 to be searched for include files. The value of $_F90INCFLAGS is
7490 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7491 end of each directory in $F90PATH.
7492 F90PATH
7494 The list of directories that the Fortran 90 compiler will search
7495 for include directories. The implicit dependency scanner will
7496 search these directories for include files. Don't explicitly put
7497 include directory arguments in $F90FLAGS because the result will be
7498 non-portable and the directories will not be searched by the
7499 dependency scanner. Note: directory names in $F90PATH will be
7500 looked-up relative to the SConscript directory when they are used
7501 in a command. To force scons to look-up a directory relative to the
7502 root of the source tree use #: You only need to set $F90PATH if you
7503 need to define a specific include path for Fortran 90 files. You
7504 should normally set the $FORTRANPATH variable, which specifies the
7505 include path for the default Fortran compiler for all Fortran
7506 versions.
7507 env = Environment(F90PATH='#/include')
7509 The directory look-up can also be forced using the Dir() function:
7511 include = Dir('include')
7513 env = Environment(F90PATH=include)
7514 The directory list will be added to command lines through the
7516 automatically-generated $_F90INCFLAGS construction variable, which
7517 is constructed by appending the values of the $INCPREFIX and
7518 $INCSUFFIX construction variables to the beginning and end of each
7519 directory in $F90PATH. Any command lines you define that need the
7520 F90PATH directory list should include $_F90INCFLAGS:
7521 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
7523 F90PPCOM
7525 The command line used to compile a Fortran 90 source file to an
7526 object file after first running the file through the C
7527 preprocessor. Any options specified in the $F90FLAGS and $CPPFLAGS
7528 construction variables are included on this command line. You only
7529 need to set $F90PPCOM if you need to use a specific C-preprocessor
7530 command line for Fortran 90 files. You should normally set the
7531 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7532 command line for all Fortran versions.
7533 F90PPCOMSTR
7535 If set, the string displayed when a Fortran 90 source file is
7536 compiled after first running the file through the C preprocessor.
7537 If not set, then $F90PPCOM or $FORTRANPPCOM (the command line) is
7538 displayed.
7539 F90PPFILESUFFIXES
7541 The list of file extensions for which the compilation +
7542 preprocessor pass for F90 dialect will be used. By default, this is
7543 empty.
7544 F95
7546 The Fortran 95 compiler. You should normally set the $FORTRAN
7547 variable, which specifies the default Fortran compiler for all
7548 Fortran versions. You only need to set $F95 if you need to use a
7549 specific compiler or compiler version for Fortran 95 files.
7550 F95COM
7552 The command line used to compile a Fortran 95 source file to an
7553 object file. You only need to set $F95COM if you need to use a
7554 specific command line for Fortran 95 files. You should normally set
7555 the $FORTRANCOM variable, which specifies the default command line
7556 for all Fortran versions.
7557 F95COMSTR
7559 If set, the string displayed when a Fortran 95 source file is
7560 compiled to an object file. If not set, then $F95COM or $FORTRANCOM
7561 (the command line) is displayed.
7562 F95FILESUFFIXES
7564 The list of file extensions for which the F95 dialect will be used.
7565 By default, this is ['.f95']
7566 F95FLAGS
7568 General user-specified options that are passed to the Fortran 95
7569 compiler. Note that this variable does not contain -I (or similar)
7570 include search path options that scons generates automatically from
7571 $F95PATH. See $_F95INCFLAGS below, for the variable that expands to
7572 those options. You only need to set $F95FLAGS if you need to define
7573 specific user options for Fortran 95 files. You should normally set
7574 the $FORTRANFLAGS variable, which specifies the user-specified
7575 options passed to the default Fortran compiler for all Fortran
7576 versions.
7577 _F95INCFLAGS
7579 An automatically-generated construction variable containing the
7580 Fortran 95 compiler command-line options for specifying directories
7581 to be searched for include files. The value of $_F95INCFLAGS is
7582 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7583 end of each directory in $F95PATH.
7584 F95PATH
7586 The list of directories that the Fortran 95 compiler will search
7587 for include directories. The implicit dependency scanner will
7588 search these directories for include files. Don't explicitly put
7589 include directory arguments in $F95FLAGS because the result will be
7590 non-portable and the directories will not be searched by the
7591 dependency scanner. Note: directory names in $F95PATH will be
7592 looked-up relative to the SConscript directory when they are used
7593 in a command. To force scons to look-up a directory relative to the
7594 root of the source tree use #: You only need to set $F95PATH if you
7595 need to define a specific include path for Fortran 95 files. You
7596 should normally set the $FORTRANPATH variable, which specifies the
7597 include path for the default Fortran compiler for all Fortran
7598 versions.
7599 env = Environment(F95PATH='#/include')
7601 The directory look-up can also be forced using the Dir() function:
7603 include = Dir('include')
7605 env = Environment(F95PATH=include)
7606 The directory list will be added to command lines through the
7608 automatically-generated $_F95INCFLAGS construction variable, which
7609 is constructed by appending the values of the $INCPREFIX and
7610 $INCSUFFIX construction variables to the beginning and end of each
7611 directory in $F95PATH. Any command lines you define that need the
7612 F95PATH directory list should include $_F95INCFLAGS:
7613 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
7615 F95PPCOM
7617 The command line used to compile a Fortran 95 source file to an
7618 object file after first running the file through the C
7619 preprocessor. Any options specified in the $F95FLAGS and $CPPFLAGS
7620 construction variables are included on this command line. You only
7621 need to set $F95PPCOM if you need to use a specific C-preprocessor
7622 command line for Fortran 95 files. You should normally set the
7623 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7624 command line for all Fortran versions.
7625 F95PPCOMSTR
7627 If set, the string displayed when a Fortran 95 source file is
7628 compiled to an object file after first running the file through the
7629 C preprocessor. If not set, then $F95PPCOM or $FORTRANPPCOM (the
7630 command line) is displayed.
7631 F95PPFILESUFFIXES
7633 The list of file extensions for which the compilation +
7634 preprocessor pass for F95 dialect will be used. By default, this is
7635 empty.
7636 File
7638 A function that converts a string into a File instance relative to
7639 the target being built.
7640 FORTRAN
7642 The default Fortran compiler for all versions of Fortran.
7643 FORTRANCOM
7645 The command line used to compile a Fortran source file to an object
7646 file. By default, any options specified in the $FORTRANFLAGS,
7647 $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
7648 construction variables are included on this command line.
7649 FORTRANCOMSTR
7651 If set, the string displayed when a Fortran source file is compiled
7652 to an object file. If not set, then $FORTRANCOM (the command line)
7653 is displayed.
7654 FORTRANFILESUFFIXES
7656 The list of file extensions for which the FORTRAN dialect will be
7657 used. By default, this is ['.f', '.for', '.ftn']
7658 FORTRANFLAGS
7660 General user-specified options that are passed to the Fortran
7661 compiler. Note that this variable does not contain -I (or similar)
7662 include or module search path options that scons generates
7663 automatically from $FORTRANPATH. See $_FORTRANINCFLAGS and
7664 $_FORTRANMODFLAG, below, for the variables that expand those
7665 options.
7666 _FORTRANINCFLAGS
7668 An automatically-generated construction variable containing the
7669 Fortran compiler command-line options for specifying directories to
7670 be searched for include files and module files. The value of
7671 $_FORTRANINCFLAGS is created by respectively prepending and
7672 appending $INCPREFIX and $INCSUFFIX to the beginning and end of
7673 each directory in $FORTRANPATH.
7674 FORTRANMODDIR
7676 Directory location where the Fortran compiler should place any
7677 module files it generates. This variable is empty, by default. Some
7678 Fortran compilers will internally append this directory in the
7679 search path for module files, as well.
7680 FORTRANMODDIRPREFIX
7682 The prefix used to specify a module directory on the Fortran
7683 compiler command line. This will be prepended to the beginning of
7684 the directory in the $FORTRANMODDIR construction variables when the
7685 $_FORTRANMODFLAG variables is automatically generated.
7686 FORTRANMODDIRSUFFIX
7688 The suffix used to specify a module directory on the Fortran
7689 compiler command line. This will be appended to the end of the
7690 directory in the $FORTRANMODDIR construction variables when the
7691 $_FORTRANMODFLAG variables is automatically generated.
7692 _FORTRANMODFLAG
7694 An automatically-generated construction variable containing the
7695 Fortran compiler command-line option for specifying the directory
7696 location where the Fortran compiler should place any module files
7697 that happen to get generated during compilation. The value of
7698 $_FORTRANMODFLAG is created by respectively prepending and
7699 appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the
7700 beginning and end of the directory in $FORTRANMODDIR.
7701 FORTRANMODPREFIX
7703 The module file prefix used by the Fortran compiler. SCons assumes
7704 that the Fortran compiler follows the quasi-standard naming
7705 convention for module files of module_name.mod. As a result, this
7706 variable is left empty, by default. For situations in which the
7707 compiler does not necessarily follow the normal convention, the
7708 user may use this variable. Its value will be appended to every
7709 module file name as scons attempts to resolve dependencies.
7710 FORTRANMODSUFFIX
7712 The module file suffix used by the Fortran compiler. SCons assumes
7713 that the Fortran compiler follows the quasi-standard naming
7714 convention for module files of module_name.mod. As a result, this
7715 variable is set to ".mod", by default. For situations in which the
7716 compiler does not necessarily follow the normal convention, the
7717 user may use this variable. Its value will be appended to every
7718 module file name as scons attempts to resolve dependencies.
7719 FORTRANPATH
7721 The list of directories that the Fortran compiler will search for
7722 include files and (for some compilers) module files. The Fortran
7723 implicit dependency scanner will search these directories for
7724 include files (but not module files since they are autogenerated
7725 and, as such, may not actually exist at the time the scan takes
7726 place). Don't explicitly put include directory arguments in
7727 FORTRANFLAGS because the result will be non-portable and the
7728 directories will not be searched by the dependency scanner. Note:
7729 directory names in FORTRANPATH will be looked-up relative to the
7730 SConscript directory when they are used in a command. To force
7731 scons to look-up a directory relative to the root of the source
7732 tree use #:
7733 env = Environment(FORTRANPATH='#/include')
7735 The directory look-up can also be forced using the Dir() function:
7737 include = Dir('include')
7739 env = Environment(FORTRANPATH=include)
7740 The directory list will be added to command lines through the
7742 automatically-generated $_FORTRANINCFLAGS construction variable,
7743 which is constructed by respectively prepending and appending the
7744 values of the $INCPREFIX and $INCSUFFIX construction variables to
7745 the beginning and end of each directory in $FORTRANPATH. Any
7746 command lines you define that need the FORTRANPATH directory list
7747 should include $_FORTRANINCFLAGS:
7748 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
7750 FORTRANPPCOM
7752 The command line used to compile a Fortran source file to an object
7753 file after first running the file through the C preprocessor. By
7754 default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
7755 $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction
7756 variables are included on this command line.
7757 FORTRANPPCOMSTR
7759 If set, the string displayed when a Fortran source file is compiled
7760 to an object file after first running the file through the C
7761 preprocessor. If not set, then $FORTRANPPCOM (the command line) is
7762 displayed.
7763 FORTRANPPFILESUFFIXES
7765 The list of file extensions for which the compilation +
7766 preprocessor pass for FORTRAN dialect will be used. By default,
7767 this is ['.fpp', '.FPP']
7768 FORTRANSUFFIXES
7770 The list of suffixes of files that will be scanned for Fortran
7771 implicit dependencies (INCLUDE lines and USE statements). The
7772 default list is:
7773 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
7775 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
7776 FRAMEWORKPATH
7778 On Mac OS X with gcc, a list containing the paths to search for
7779 frameworks. Used by the compiler to find framework-style includes
7780 like #include <Fmwk/Header.h>. Used by the linker to find
7781 user-specified frameworks when linking (see $FRAMEWORKS). For
7782 example:
7783 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
7785 will add
7788 ... -Fmyframeworkdir
7790 to the compiler and linker command lines.
7793 _FRAMEWORKPATH
7795 On Mac OS X with gcc, an automatically-generated construction
7796 variable containing the linker command-line options corresponding
7797 to $FRAMEWORKPATH.
7798 FRAMEWORKPATHPREFIX
7800 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH
7801 entries. (see $FRAMEWORKPATH). The default value is -F.
7802 FRAMEWORKPREFIX
7804 On Mac OS X with gcc, the prefix to be used for linking in
7805 frameworks (see $FRAMEWORKS). The default value is -framework.
7806 FRAMEWORKS
7808 On Mac OS X with gcc, a list of the framework names to be linked
7809 into a program or shared library or bundle. The default value is
7810 the empty list. For example:
7811 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
7813 _FRAMEWORKS
7816 On Mac OS X with gcc, an automatically-generated construction
7817 variable containing the linker command-line options for linking
7818 with FRAMEWORKS.
7819 FRAMEWORKSFLAGS
7821 On Mac OS X with gcc, general user-supplied frameworks options to
7822 be added at the end of a command line building a loadable module.
7823 (This has been largely superseded by the $FRAMEWORKPATH,
7824 $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS variables
7825 described above.)
7826 GS
7828 The Ghostscript program used, e.g. to convert PostScript to PDF
7829 files.
7830 GSCOM
7832 The full Ghostscript command line used for the conversion process.
7833 Its default value is “$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES”.
7834 GSCOMSTR
7836 The string displayed when Ghostscript is called for the conversion
7837 process. If this is not set (the default), then $GSCOM (the command
7838 line) is displayed.
7839 GSFLAGS
7841 General options passed to the Ghostscript program, when converting
7842 PostScript to PDF files for example. Its default value is
7843 “-dNOPAUSE -dBATCH -sDEVICE=pdfwrite”
7844 HOST_ARCH
7846 The name of the host hardware architecture used to create the
7847 Environment. If a platform is specified when creating the
7848 Environment, then that Platform's logic will handle setting this
7849 value. This value is immutable, and should not be changed by the
7850 user after the Environment is initialized. Currently only set for
7851 Win32.
7852 Sets the host architecture for the Visual C++ compiler. If not set,
7854 default to the detected host architecture: note that this may
7855 depend on the python you are using. This variable must be passed as
7856 an argument to the Environment() constructor; setting it later has
7857 no effect.
7858 Valid values are the same as for $TARGET_ARCH.
7860 This is currently only used on Windows, but in the future it may be
7862 used on other OSes as well.
7863 HOST_OS
7865 The name of the host operating system used to create the
7866 Environment. If a platform is specified when creating the
7867 Environment, then that Platform's logic will handle setting this
7868 value. This value is immutable, and should not be changed by the
7869 user after the Environment is initialized. Currently only set for
7870 Win32.
7871 IDLSUFFIXES
7873 The list of suffixes of files that will be scanned for IDL implicit
7874 dependencies (#include or import lines). The default list is:
7875 [".idl", ".IDL"]
7877 IMPLIBNOVERSIONSYMLINKS
7879 Used to override $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS
7880 when creating versioned import library for a shared
7881 library/loadable module. If not defined, then
7882 $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS is used to
7883 determine whether to disable symlink generation or not.
7884 IMPLIBPREFIX
7886 The prefix used for import library names. For example, cygwin uses
7887 import libraries (libfoo.dll.a) in pair with dynamic libraries
7888 (cygfoo.dll). The cyglink linker sets $IMPLIBPREFIX to 'lib' and
7889 $SHLIBPREFIX to 'cyg'.
7890 IMPLIBSUFFIX
7892 The suffix used for import library names. For example, cygwin uses
7893 import libraries (libfoo.dll.a) in pair with dynamic libraries
7894 (cygfoo.dll). The cyglink linker sets $IMPLIBSUFFIX to '.dll.a' and
7895 $SHLIBSUFFIX to '.dll'.
7896 IMPLIBVERSION
7898 Used to override $SHLIBVERSION/$LDMODULEVERSION when generating
7899 versioned import library for a shared library/loadable module. If
7900 undefined, the $SHLIBVERSION/$LDMODULEVERSION is used to determine
7901 the version of versioned import library.
7902 IMPLICIT_COMMAND_DEPENDENCIES
7904 Controls whether or not SCons will add implicit dependencies for
7905 the commands executed to build targets.
7906 By default, SCons will add to each target an implicit dependency on
7908 the command represented by the first argument of any command line
7909 it executes (which is typically the command itself). By setting
7910 such a dependency, SCons can determine that a target should be
7911 rebuilt if the command changes, such as when a compiler is upgraded
7912 to a new version. The specific file for the dependency is found by
7913 searching the PATH variable in the ENV dictionary in the
7914 construction environment used to execute the command. The default
7915 is the same as setting the construction variable
7916 $IMPLICIT_COMMAND_DEPENDENCIES to a True-like value (“true”, “yes”,
7917 or “1” - but not a number greater than one, as that has a different
7918 meaning).
7919 Action strings can be segmented by the use of an AND operator, &&.
7921 In a segemented string, each segment is a separate “command line”,
7922 these are run sequentially until one fails or the entire sequence
7923 has been executed. If an action string is segmented, then the
7924 selected behavior of $IMPLICIT_COMMAND_DEPENDENCIES is applied to
7925 each segment.
7926 If $IMPLICIT_COMMAND_DEPENDENCIES is set to a False-like value
7928 (“none”, “false”, “no”, “0”, etc.), then the implicit dependency
7929 will not be added to the targets built with that construction
7930 environment.
7931 If $IMPLICIT_COMMAND_DEPENDENCIES is set to “2” or higher, then
7933 that number of arguments in the command line will be scanned for
7934 relative or absolute paths. If any are present, they will be added
7935 as implicit dependencies to the targets built with that
7936 construction environment. The first argument in the command line
7937 will be searched for using the PATH variable in the ENV dictionary
7938 in the construction environment used to execute the command. The
7939 other arguments will only be found if they are absolute paths or
7940 valid paths relative to the working directory.
7941 If $IMPLICIT_COMMAND_DEPENDENCIES is set to “all”, then all
7943 arguments in the command line will be scanned for relative or
7944 absolute paths. If any are present, they will be added as implicit
7945 dependencies to the targets built with that construction
7946 environment. The first argument in the command line will be
7947 searched for using the PATH variable in the ENV dictionary in the
7948 construction environment used to execute the command. The other
7949 arguments will only be found if they are absolute paths or valid
7950 paths relative to the working directory.
7951 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
7953 INCPREFIX
7955 The prefix used to specify an include directory on the C compiler
7956 command line. This will be prepended to the beginning of each
7957 directory in the $CPPPATH and $FORTRANPATH construction variables
7958 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are
7959 automatically generated.
7960 INCSUFFIX
7962 The suffix used to specify an include directory on the C compiler
7963 command line. This will be appended to the end of each directory in
7964 the $CPPPATH and $FORTRANPATH construction variables when the
7965 $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically
7966 generated.
7967 INSTALL
7969 A function to be called to install a file into a destination file
7970 name. The default function copies the file into the destination
7971 (and sets the destination file's mode and permission bits to match
7972 the source file's). The function takes the following arguments:
7973 def install(dest, source, env):
7975 dest is the path name of the destination file. source is the path
7978 name of the source file. env is the construction environment (a
7979 dictionary of construction values) in force for this file
7980 installation.
7981 INSTALLSTR
7983 The string displayed when a file is installed into a destination
7984 file name. The default is:
7985 Install file: "$SOURCE" as "$TARGET"
7987 INTEL_C_COMPILER_VERSION
7989 Set by the "intelc" Tool to the major version number of the Intel C
7990 compiler selected for use.
7991 JAR
7993 The Java archive tool.
7994 JARCHDIR
7996 The directory to which the Java archive tool should change (using
7997 the -C option).
7998 JARCOM
8000 The command line used to call the Java archive tool.
8001 JARCOMSTR
8003 The string displayed when the Java archive tool is called If this
8004 is not set, then $JARCOM (the command line) is displayed.
8005 env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")
8007 JARFLAGS
8009 General options passed to the Java archive tool. By default this is
8010 set to cf to create the necessary jar file.
8011 JARSUFFIX
8013 The suffix for Java archives: .jar by default.
8014 JAVABOOTCLASSPATH
8016 Specifies the list of directories that will be added to the javac
8017 command line via the -bootclasspath option. The individual
8018 directory names will be separated by the operating system's path
8019 separate character (: on UNIX/Linux/POSIX, ; on Windows).
8020 JAVAC
8022 The Java compiler.
8023 JAVACCOM
8025 The command line used to compile a directory tree containing Java
8026 source files to corresponding Java class files. Any options
8027 specified in the $JAVACFLAGS construction variable are included on
8028 this command line.
8029 JAVACCOMSTR
8031 The string displayed when compiling a directory tree of Java source
8032 files to corresponding Java class files. If this is not set, then
8033 $JAVACCOM (the command line) is displayed.
8034 env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
8036 JAVACFLAGS
8039 General options that are passed to the Java compiler.
8040 JAVACLASSDIR
8042 The directory in which Java class files may be found. This is
8043 stripped from the beginning of any Java .class file names supplied
8044 to the JavaH builder.
8045 JAVACLASSPATH
8047 Specifies the list of directories that will be searched for Java
8048 .class file. The directories in this list will be added to the
8049 javac and javah command lines via the -classpath option. The
8050 individual directory names will be separated by the operating
8051 system's path separate character (: on UNIX/Linux/POSIX, ; on
8052 Windows).
8053 Note that this currently just adds the specified directory via the
8055 -classpath option. SCons does not currently search the
8056 $JAVACLASSPATH directories for dependency .class files.
8057 JAVACLASSSUFFIX
8059 The suffix for Java class files; .class by default.
8060 JAVAH
8062 The Java generator for C header and stub files.
8063 JAVAHCOM
8065 The command line used to generate C header and stub files from Java
8066 classes. Any options specified in the $JAVAHFLAGS construction
8067 variable are included on this command line.
8068 JAVAHCOMSTR
8070 The string displayed when C header and stub files are generated
8071 from Java classes. If this is not set, then $JAVAHCOM (the command
8072 line) is displayed.
8073 env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
8075 JAVAHFLAGS
8077 General options passed to the C header and stub file generator for
8078 Java classes.
8079 JAVAINCLUDES
8081 Include path for Java header files (such as jni.h)
8082 JAVASOURCEPATH
8084 Specifies the list of directories that will be searched for input
8085 .java file. The directories in this list will be added to the javac
8086 command line via the -sourcepath option. The individual directory
8087 names will be separated by the operating system's path separate
8088 character (: on UNIX/Linux/POSIX, ; on Windows).
8089 Note that this currently just adds the specified directory via the
8091 -sourcepath option. SCons does not currently search the
8092 $JAVASOURCEPATH directories for dependency .java files.
8093 JAVASUFFIX
8095 The suffix for Java files; .java by default.
8096 JAVAVERSION
8098 Specifies the Java version being used by the Java builder. This is
8099 not currently used to select one version of the Java compiler vs.
8100 another. Instead, you should set this to specify the version of
8101 Java supported by your javac compiler. The default is 1.4.
8102 This is sometimes necessary because Java 1.5 changed the file names
8104 that are created for nested anonymous inner classes, which can
8105 cause a mismatch with the files that SCons expects will be
8106 generated by the javac compiler. Setting $JAVAVERSION to 1.5 (or
8107 1.6, as appropriate) can make SCons realize that a Java 1.5 or 1.6
8108 build is actually up to date.
8109 LATEX
8111 The LaTeX structured formatter and typesetter.
8112 LATEXCOM
8114 The command line used to call the LaTeX structured formatter and
8115 typesetter.
8116 LATEXCOMSTR
8118 The string displayed when calling the LaTeX structured formatter
8119 and typesetter. If this is not set, then $LATEXCOM (the command
8120 line) is displayed.
8121 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
8123 LATEXFLAGS
8125 General options passed to the LaTeX structured formatter and
8126 typesetter.
8127 LATEXRETRIES
8129 The maximum number of times that LaTeX will be re-run if the .log
8130 generated by the $LATEXCOM command indicates that there are
8131 undefined references. The default is to try to resolve undefined
8132 references by re-running LaTeX up to three times.
8133 LATEXSUFFIXES
8135 The list of suffixes of files that will be scanned for LaTeX
8136 implicit dependencies (\include or \import files). The default list
8137 is:
8138 [".tex", ".ltx", ".latex"]
8140 LDMODULE
8142 The linker for building loadable modules. By default, this is the
8143 same as $SHLINK.
8144 LDMODULECOM
8146 The command line for building loadable modules. On Mac OS X, this
8147 uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
8148 On other systems, this is the same as $SHLINK.
8149 LDMODULECOMSTR
8151 If set, the string displayed when building loadable modules. If not
8152 set, then $LDMODULECOM (the command line) is displayed.
8153 LDMODULEEMITTER
8155 Contains the emitter specification for the LoadableModule builder.
8156 The manpage section "Builder Objects" contains general information
8157 on specifying emitters.
8158 LDMODULEFLAGS
8160 General user options passed to the linker for building loadable
8161 modules.
8162 LDMODULENOVERSIONSYMLINKS
8164 Instructs the LoadableModule builder to not automatically create
8165 symlinks for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS
8166 LDMODULEPREFIX
8168 The prefix used for loadable module file names. On Mac OS X, this
8169 is null; on other systems, this is the same as $SHLIBPREFIX.
8170 _LDMODULESONAME
8172 A macro that automatically generates loadable module's SONAME based
8173 on $TARGET, $LDMODULEVERSION and $LDMODULESUFFIX. Used by
8174 LoadableModule builder when the linker tool supports SONAME (e.g.
8175 gnulink).
8176 LDMODULESUFFIX
8178 The suffix used for loadable module file names. On Mac OS X, this
8179 is null; on other systems, this is the same as $SHLIBSUFFIX.
8180 LDMODULEVERSION
8182 When this construction variable is defined, a versioned loadable
8183 module is created by LoadableModule builder. This activates the
8184 $_LDMODULEVERSIONFLAGS and thus modifies the $LDMODULECOM as
8185 required, adds the version number to the library name, and creates
8186 the symlinks that are needed. $LDMODULEVERSION versions should
8187 exist in the same format as $SHLIBVERSION.
8188 _LDMODULEVERSIONFLAGS
8190 This macro automatically introduces extra flags to $LDMODULECOM
8191 when building versioned LoadableModule (that is when
8192 $LDMODULEVERSION is set). _LDMODULEVERSIONFLAGS usually adds
8193 $SHLIBVERSIONFLAGS and some extra dynamically generated options
8194 (such as -Wl,-soname=$_LDMODULESONAME). It is unused by plain
8195 (unversioned) loadable modules.
8196 LDMODULEVERSIONFLAGS
8198 Extra flags added to $LDMODULECOM when building versioned
8199 LoadableModule. These flags are only used when $LDMODULEVERSION is
8200 set.
8201 LEX
8203 The lexical analyzer generator.
8204 LEXCOM
8206 The command line used to call the lexical analyzer generator to
8207 generate a source file.
8208 LEXCOMSTR
8210 The string displayed when generating a source file using the
8211 lexical analyzer generator. If this is not set, then $LEXCOM (the
8212 command line) is displayed.
8213 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
8215 LEXFLAGS
8217 General options passed to the lexical analyzer generator.
8218 LEXUNISTD
8220 Used only on windows environments to set a lex flag to prevent
8221 'unistd.h' from being included. The default value is '--nounistd'.
8222 _LIBDIRFLAGS
8224 An automatically-generated construction variable containing the
8225 linker command-line options for specifying directories to be
8226 searched for library. The value of $_LIBDIRFLAGS is created by
8227 respectively prepending and appending $LIBDIRPREFIX and
8228 $LIBDIRSUFFIX to the beginning and end of each directory in
8229 $LIBPATH.
8230 LIBDIRPREFIX
8232 The prefix used to specify a library directory on the linker
8233 command line. This will be prepended to the beginning of each
8234 directory in the $LIBPATH construction variable when the
8235 $_LIBDIRFLAGS variable is automatically generated.
8236 LIBDIRSUFFIX
8238 The suffix used to specify a library directory on the linker
8239 command line. This will be appended to the end of each directory in
8240 the $LIBPATH construction variable when the $_LIBDIRFLAGS variable
8241 is automatically generated.
8242 LIBEMITTER
8244 Contains the emitter specification for the StaticLibrary builder.
8245 The manpage section "Builder Objects" contains general information
8246 on specifying emitters.
8247 _LIBFLAGS
8249 An automatically-generated construction variable containing the
8250 linker command-line options for specifying libraries to be linked
8251 with the resulting target. The value of $_LIBFLAGS is created by
8252 respectively prepending and appending $LIBLINKPREFIX and
8253 $LIBLINKSUFFIX to the beginning and end of each filename in $LIBS.
8254 LIBLINKPREFIX
8256 The prefix used to specify a library to link on the linker command
8257 line. This will be prepended to the beginning of each library in
8258 the $LIBS construction variable when the $_LIBFLAGS variable is
8259 automatically generated.
8260 LIBLINKSUFFIX
8262 The suffix used to specify a library to link on the linker command
8263 line. This will be appended to the end of each library in the $LIBS
8264 construction variable when the $_LIBFLAGS variable is automatically
8265 generated.
8266 LIBPATH
8268 The list of directories that will be searched for libraries. The
8269 implicit dependency scanner will search these directories for
8270 include files. Don't explicitly put include directory arguments in
8271 $LINKFLAGS or $SHLINKFLAGS because the result will be non-portable
8272 and the directories will not be searched by the dependency scanner.
8273 Note: directory names in LIBPATH will be looked-up relative to the
8274 SConscript directory when they are used in a command. To force
8275 scons to look-up a directory relative to the root of the source
8276 tree use #:
8277 env = Environment(LIBPATH='#/libs')
8279 The directory look-up can also be forced using the Dir() function:
8281 libs = Dir('libs')
8283 env = Environment(LIBPATH=libs)
8284 The directory list will be added to command lines through the
8286 automatically-generated $_LIBDIRFLAGS construction variable, which
8287 is constructed by respectively prepending and appending the values
8288 of the $LIBDIRPREFIX and $LIBDIRSUFFIX construction variables to
8289 the beginning and end of each directory in $LIBPATH. Any command
8290 lines you define that need the LIBPATH directory list should
8291 include $_LIBDIRFLAGS:
8292 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8294 LIBPREFIX
8296 The prefix used for (static) library file names. A default value is
8297 set for each platform (posix, win32, os2, etc.), but the value is
8298 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8299 etc.) to reflect the names of the libraries they create.
8300 LIBPREFIXES
8302 A list of all legal prefixes for library file names. When searching
8303 for library dependencies, SCons will look for files with these
8304 prefixes, the base library name, and suffixes in the $LIBSUFFIXES
8305 list.
8306 LIBS
8308 A list of one or more libraries that will be linked with any
8309 executable programs created by this environment.
8310 The library list will be added to command lines through the
8312 automatically-generated $_LIBFLAGS construction variable, which is
8313 constructed by respectively prepending and appending the values of
8314 the $LIBLINKPREFIX and $LIBLINKSUFFIX construction variables to the
8315 beginning and end of each filename in $LIBS. Any command lines you
8316 define that need the LIBS library list should include $_LIBFLAGS:
8317 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8319 If you add a File object to the $LIBS list, the name of that file
8321 will be added to $_LIBFLAGS, and thus the link line, as is, without
8322 $LIBLINKPREFIX or $LIBLINKSUFFIX. For example:
8323 env.Append(LIBS=File('/tmp/mylib.so'))
8325 In all cases, scons will add dependencies from the executable
8327 program to all the libraries in this list.
8328 LIBSUFFIX
8330 The suffix used for (static) library file names. A default value is
8331 set for each platform (posix, win32, os2, etc.), but the value is
8332 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8333 etc.) to reflect the names of the libraries they create.
8334 LIBSUFFIXES
8336 A list of all legal suffixes for library file names. When searching
8337 for library dependencies, SCons will look for files with prefixes,
8338 in the $LIBPREFIXES list, the base library name, and these
8339 suffixes.
8340 LICENSE
8342 The abbreviated name, preferably the SPDX code, of the license
8343 under which this project is released (GPL-3.0, LGPL-2.1,
8344 BSD-2-Clause etc.). See
8345 http://www.opensource.org/licenses/alphabetical for a list of
8346 license names and SPDX codes.
8347 LINESEPARATOR
8349 The separator used by the Substfile and Textfile builders. This
8350 value is used between sources when constructing the target. It
8351 defaults to the current system line separator.
8352 LINGUAS_FILE
8354 The $LINGUAS_FILE defines file(s) containing list of additional
8355 linguas to be processed by POInit, POUpdate or MOFiles builders. It
8356 also affects Translate builder. If the variable contains a string,
8357 it defines name of the list file. The $LINGUAS_FILE may be a list
8358 of file names as well. If $LINGUAS_FILE is set to True (or non-zero
8359 numeric value), the list will be read from default file named
8360 LINGUAS.
8361 LINK
8363 The linker. See also $SHLINK for linking shared objects.
8364 LINKCOM
8366 The command line used to link object files into an executable. See
8367 also $SHLINKCOM for linking shared objects.
8368 LINKCOMSTR
8370 If set, the string displayed when object files are linked into an
8371 executable. If not set, then $LINKCOM (the command line) is
8372 displayed. See also $SHLINKCOMSTR. for linking shared objects.
8373 env = Environment(LINKCOMSTR = "Linking $TARGET")
8375 LINKFLAGS
8377 General user options passed to the linker. Note that this variable
8378 should not contain -l (or similar) options for linking with the
8379 libraries listed in $LIBS, nor -L (or similar) library search path
8380 options that scons generates automatically from $LIBPATH. See
8381 $_LIBFLAGS above, for the variable that expands to library-link
8382 options, and $_LIBDIRFLAGS above, for the variable that expands to
8383 library search path options. See also $SHLINKFLAGS. for linking
8384 shared objects.
8385 M4
8387 The M4 macro preprocessor.
8388 M4COM
8390 The command line used to pass files through the M4 macro
8391 preprocessor.
8392 M4COMSTR
8394 The string displayed when a file is passed through the M4 macro
8395 preprocessor. If this is not set, then $M4COM (the command line) is
8396 displayed.
8397 M4FLAGS
8399 General options passed to the M4 macro preprocessor.
8400 MAKEINDEX
8402 The makeindex generator for the TeX formatter and typesetter and
8403 the LaTeX structured formatter and typesetter.
8404 MAKEINDEXCOM
8406 The command line used to call the makeindex generator for the TeX
8407 formatter and typesetter and the LaTeX structured formatter and
8408 typesetter.
8409 MAKEINDEXCOMSTR
8411 The string displayed when calling the makeindex generator for the
8412 TeX formatter and typesetter and the LaTeX structured formatter and
8413 typesetter. If this is not set, then $MAKEINDEXCOM (the command
8414 line) is displayed.
8415 MAKEINDEXFLAGS
8417 General options passed to the makeindex generator for the TeX
8418 formatter and typesetter and the LaTeX structured formatter and
8419 typesetter.
8420 MAXLINELENGTH
8422 The maximum number of characters allowed on an external command
8423 line. On Win32 systems, link lines longer than this many characters
8424 are linked via a temporary file name.
8425 MIDL
8427 The Microsoft IDL compiler.
8428 MIDLCOM
8430 The command line used to pass files to the Microsoft IDL compiler.
8431 MIDLCOMSTR
8433 The string displayed when the Microsoft IDL compiler is called. If
8434 this is not set, then $MIDLCOM (the command line) is displayed.
8435 MIDLFLAGS
8437 General options passed to the Microsoft IDL compiler.
8438 MOSUFFIX
8440 Suffix used for MO files (default: '.mo'). See msgfmt tool and
8441 MOFiles builder.
8442 MSGFMT
8444 Absolute path to msgfmt(1) binary, found by Detect(). See msgfmt
8445 tool and MOFiles builder.
8446 MSGFMTCOM
8448 Complete command line to run msgfmt(1) program. See msgfmt tool and
8449 MOFiles builder.
8450 MSGFMTCOMSTR
8452 String to display when msgfmt(1) is invoked (default: '', which
8453 means ``print $MSGFMTCOM''). See msgfmt tool and MOFiles builder.
8454 MSGFMTFLAGS
8456 Additional flags to msgfmt(1). See msgfmt tool and MOFiles builder.
8457 MSGINIT
8459 Path to msginit(1) program (found via Detect()). See msginit tool
8460 and POInit builder.
8461 MSGINITCOM
8463 Complete command line to run msginit(1) program. See msginit tool
8464 and POInit builder.
8465 MSGINITCOMSTR
8467 String to display when msginit(1) is invoked (default: '', which
8468 means ``print $MSGINITCOM''). See msginit tool and POInit builder.
8469 MSGINITFLAGS
8471 List of additional flags to msginit(1) (default: []). See msginit
8472 tool and POInit builder.
8473 _MSGINITLOCALE
8475 Internal ``macro''. Computes locale (language) name based on target
8476 filename (default: '${TARGET.filebase}').
8477 See msginit tool and POInit builder.
8479 MSGMERGE
8481 Absolute path to msgmerge(1) binary as found by Detect(). See
8482 msgmerge tool and POUpdate builder.
8483 MSGMERGECOM
8485 Complete command line to run msgmerge(1) command. See msgmerge tool
8486 and POUpdate builder.
8487 MSGMERGECOMSTR
8489 String to be displayed when msgmerge(1) is invoked (default: '',
8490 which means ``print $MSGMERGECOM''). See msgmerge tool and POUpdate
8491 builder.
8492 MSGMERGEFLAGS
8494 Additional flags to msgmerge(1) command. See msgmerge tool and
8495 POUpdate builder.
8496 MSSDK_DIR
8498 The directory containing the Microsoft SDK (either Platform SDK or
8499 Windows SDK) to be used for compilation.
8500 MSSDK_VERSION
8502 The version string of the Microsoft SDK (either Platform SDK or
8503 Windows SDK) to be used for compilation. Supported versions include
8504 6.1, 6.0A, 6.0, 2003R2 and 2003R1.
8505 MSVC_BATCH
8507 When set to any true value, specifies that SCons should batch
8508 compilation of object files when calling the Microsoft Visual C/C++
8509 compiler. All compilations of source files from the same source
8510 directory that generate target files in a same output directory and
8511 were configured in SCons using the same construction environment
8512 will be built in a single call to the compiler. Only source files
8513 that have changed since their object files were built will be
8514 passed to each compiler invocation (via the $CHANGED_SOURCES
8515 construction variable). Any compilations where the object (target)
8516 file base name (minus the .obj) does not match the source file base
8517 name will be compiled separately.
8518 MSVC_USE_SCRIPT
8520 Use a batch script to set up the Microsoft Visual C++ compiler.
8521 If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
8523 SCons will run that batch file instead of the auto-detected one,
8524 and extract the relevant variables from the result (typically
8525 %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can
8526 be useful to force the use of a compiler version that SCons does
8527 not detect.
8528 Setting $MSVC_USE_SCRIPT to None bypasses the Visual Studio
8530 autodetection entirely; use this if you are running SCons in a
8531 Visual Studio cmd window and importing the shell's environment
8532 variables - that is, if you are sure everything is set correctly
8533 already and you don't want SCons to change anything.
8534 $MSVC_USE_SCRIPT overrides $MSVC_VERSION and $TARGET_ARCH.
8537 MSVC_UWP_APP
8539 Build libraries for a Universal Windows Platform (UWP) Application.
8540 If $MSVC_UWP_APP is set, the Visual C++ environment will be set up
8542 to point to the Windows Store compatible libraries and Visual C++
8543 runtimes. In doing so, any libraries that are built will be able to
8544 be used in a UWP App and published to the Windows Store. This flag
8545 will only have an effect with Visual Studio 2015 or later. This
8546 variable must be passed as an argument to the Environment()
8547 constructor; setting it later has no effect.
8548 Valid values are '1' or '0'
8550 MSVC_VERSION
8552 Sets the preferred version of Microsoft Visual C/C++ to use.
8553 If $MSVC_VERSION is not set, SCons will (by default) select the
8555 latest version of Visual C/C++ installed on your system. If the
8556 specified version isn't installed, tool initialization will fail.
8557 This variable must be passed as an argument to the Environment
8558 constructor; setting it later has no effect.
8559 Valid values for Windows are 14.2, 14.1, 14.1Exp, 14.0, 14.0Exp,
8561 12.0, 12.0Exp, 11.0, 11.0Exp, 10.0, 10.0Exp, 9.0, 9.0Exp, 8.0,
8562 8.0Exp, 7.1, 7.0, and 6.0. Versions ending in Exp refer to
8563 "Express" or "Express for Desktop" editions.
8564 MSVS
8566 When the Microsoft Visual Studio tools are initialized, they set up
8567 this dictionary with the following keys:
8568 VERSION
8570 the version of MSVS being used (can be set via $MSVS_VERSION)
8571 VERSIONS
8573 the available versions of MSVS installed
8574 VCINSTALLDIR
8576 installed directory of Visual C++
8577 VSINSTALLDIR
8579 installed directory of Visual Studio
8580 FRAMEWORKDIR
8582 installed directory of the .NET framework
8583 FRAMEWORKVERSIONS
8585 list of installed versions of the .NET framework, sorted latest
8586 to oldest.
8587 FRAMEWORKVERSION
8589 latest installed version of the .NET framework
8590 FRAMEWORKSDKDIR
8592 installed location of the .NET SDK.
8593 PLATFORMSDKDIR
8595 installed location of the Platform SDK.
8596 PLATFORMSDK_MODULES
8598 dictionary of installed Platform SDK modules, where the
8599 dictionary keys are keywords for the various modules, and the
8600 values are 2-tuples where the first is the release date, and
8601 the second is the version number.
8602 If a value is not set, it was not available in the registry.
8604 MSVS_ARCH
8606 Sets the architecture for which the generated project(s) should
8607 build.
8608 The default value is x86. amd64 is also supported by SCons for
8610 most Visual Studio versions. Since Visual Studio 2015 arm is
8611 supported, and since Visual Studio 2017 arm64 is supported. Trying
8612 to set $MSVS_ARCH to an architecture that's not supported for a
8613 given Visual Studio version will generate an error.
8614 MSVS_PROJECT_GUID
8616 The string placed in a generated Microsoft Visual Studio project
8617 file as the value of the ProjectGUID attribute. There is no default
8618 value. If not defined, a new GUID is generated.
8619 MSVS_SCC_AUX_PATH
8621 The path name placed in a generated Microsoft Visual Studio project
8622 file as the value of the SccAuxPath attribute if the
8623 MSVS_SCC_PROVIDER construction variable is also set. There is no
8624 default value.
8625 MSVS_SCC_CONNECTION_ROOT
8627 The root path of projects in your SCC workspace, i.e the path under
8628 which all project and solution files will be generated. It is used
8629 as a reference path from which the relative paths of the generated
8630 Microsoft Visual Studio project and solution files are computed.
8631 The relative project file path is placed as the value of the
8632 SccLocalPath attribute of the project file and as the values of the
8633 SccProjectFilePathRelativizedFromConnection[i] (where [i] ranges
8634 from 0 to the number of projects in the solution) attributes of the
8635 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8636 Studio solution file. Similarly the relative solution file path is
8637 placed as the values of the SccLocalPath[i] (where [i] ranges from
8638 0 to the number of projects in the solution) attributes of the
8639 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8640 Studio solution file. This is used only if the MSVS_SCC_PROVIDER
8641 construction variable is also set. The default value is the current
8642 working directory.
8643 MSVS_SCC_PROJECT_NAME
8645 The project name placed in a generated Microsoft Visual Studio
8646 project file as the value of the SccProjectName attribute if the
8647 MSVS_SCC_PROVIDER construction variable is also set. In this case
8648 the string is also placed in the SccProjectName0 attribute of the
8649 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8650 Studio solution file. There is no default value.
8651 MSVS_SCC_PROVIDER
8653 The string placed in a generated Microsoft Visual Studio project
8654 file as the value of the SccProvider attribute. The string is also
8655 placed in the SccProvider0 attribute of the
8656 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8657 Studio solution file. There is no default value.
8658 MSVS_VERSION
8660 Sets the preferred version of Microsoft Visual Studio to use.
8661 If $MSVS_VERSION is not set, SCons will (by default) select the
8663 latest version of Visual Studio installed on your system. So, if
8664 you have version 6 and version 7 (MSVS .NET) installed, it will
8665 prefer version 7. You can override this by specifying the
8666 MSVS_VERSION variable in the Environment initialization, setting it
8667 to the appropriate version ('6.0' or '7.0', for example). If the
8668 specified version isn't installed, tool initialization will fail.
8669 This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is
8671 set and $MSVC_VERSION is not, $MSVC_VERSION will be set
8672 automatically to $MSVS_VERSION. If both are set to different
8673 values, scons will raise an error.
8674 MSVSBUILDCOM
8676 The build command line placed in a generated Microsoft Visual
8677 Studio project file. The default is to have Visual Studio invoke
8678 SCons with any specified build targets.
8679 MSVSCLEANCOM
8681 The clean command line placed in a generated Microsoft Visual
8682 Studio project file. The default is to have Visual Studio invoke
8683 SCons with the -c option to remove any specified targets.
8684 MSVSENCODING
8686 The encoding string placed in a generated Microsoft Visual Studio
8687 project file. The default is encoding Windows-1252.
8688 MSVSPROJECTCOM
8690 The action used to generate Microsoft Visual Studio project files.
8691 MSVSPROJECTSUFFIX
8693 The suffix used for Microsoft Visual Studio project (DSP) files.
8694 The default value is .vcproj when using Visual Studio version 7.x
8695 (.NET) or later version, and .dsp when using earlier versions of
8696 Visual Studio.
8697 MSVSREBUILDCOM
8699 The rebuild command line placed in a generated Microsoft Visual
8700 Studio project file. The default is to have Visual Studio invoke
8701 SCons with any specified rebuild targets.
8702 MSVSSCONS
8704 The SCons used in generated Microsoft Visual Studio project files.
8705 The default is the version of SCons being used to generate the
8706 project file.
8707 MSVSSCONSCOM
8709 The default SCons command used in generated Microsoft Visual Studio
8710 project files.
8711 MSVSSCONSCRIPT
8713 The sconscript file (that is, SConstruct or SConscript file) that
8714 will be invoked by Visual Studio project files (through the
8715 $MSVSSCONSCOM variable). The default is the same sconscript file
8716 that contains the call to MSVSProject to build the project file.
8717 MSVSSCONSFLAGS
8719 The SCons flags used in generated Microsoft Visual Studio project
8720 files.
8721 MSVSSOLUTIONCOM
8723 The action used to generate Microsoft Visual Studio solution files.
8724 MSVSSOLUTIONSUFFIX
8726 The suffix used for Microsoft Visual Studio solution (DSW) files.
8727 The default value is .sln when using Visual Studio version 7.x
8728 (.NET), and .dsw when using earlier versions of Visual Studio.
8729 MT
8731 The program used on Windows systems to embed manifests into DLLs
8732 and EXEs. See also $WINDOWS_EMBED_MANIFEST.
8733 MTEXECOM
8735 The Windows command line used to embed manifests into executables.
8736 See also $MTSHLIBCOM.
8737 MTFLAGS
8739 Flags passed to the $MT manifest embedding program (Windows only).
8740 MTSHLIBCOM
8742 The Windows command line used to embed manifests into shared
8743 libraries (DLLs). See also $MTEXECOM.
8744 MWCW_VERSION
8746 The version number of the MetroWerks CodeWarrior C compiler to be
8747 used.
8748 MWCW_VERSIONS
8750 A list of installed versions of the MetroWerks CodeWarrior C
8751 compiler on this system.
8752 NAME
8754 Specfies the name of the project to package.
8755 no_import_lib
8757 When set to non-zero, suppresses creation of a corresponding
8758 Windows static import lib by the SharedLibrary builder when used
8759 with MinGW, Microsoft Visual Studio or Metrowerks. This also
8760 suppresses creation of an export (.exp) file when using Microsoft
8761 Visual Studio.
8762 OBJPREFIX
8764 The prefix used for (static) object file names.
8765 OBJSUFFIX
8767 The suffix used for (static) object file names.
8768 PACKAGEROOT
8770 Specifies the directory where all files in resulting archive will
8771 be placed if applicable. The default value is "$NAME-$VERSION".
8772 PACKAGETYPE
8774 Selects the package type to build when using the Package builder.
8775 May be a string or list of strings. See the docuentation for the
8776 builder for the currently supported types.
8777 $PACKAGETYPE may be overridden with the --package-type command line
8780 option.
8781 PACKAGEVERSION
8783 The version of the package (not the underlying project). This is
8784 currently only used by the rpm packager and should reflect changes
8785 in the packaging, not the underlying project code itself.
8786 PCH
8788 The Microsoft Visual C++ precompiled header that will be used when
8789 compiling object files. This variable is ignored by tools other
8790 than Microsoft Visual C++. When this variable is defined SCons will
8791 add options to the compiler command line to cause it to use the
8792 precompiled header, and will also set up the dependencies for the
8793 PCH file. Example:
8794 env['PCH'] = 'StdAfx.pch'
8796 PCHCOM
8798 The command line used by the PCH builder to generated a precompiled
8799 header.
8800 PCHCOMSTR
8802 The string displayed when generating a precompiled header. If this
8803 is not set, then $PCHCOM (the command line) is displayed.
8804 PCHPDBFLAGS
8806 A construction variable that, when expanded, adds the /yD flag to
8807 the command line only if the $PDB construction variable is set.
8808 PCHSTOP
8810 This variable specifies how much of a source file is precompiled.
8811 This variable is ignored by tools other than Microsoft Visual C++,
8812 or when the PCH variable is not being used. When this variable is
8813 define it must be a string that is the name of the header that is
8814 included at the end of the precompiled portion of the source files,
8815 or the empty string if the "#pragma hrdstop" construct is being
8816 used:
8817 env['PCHSTOP'] = 'StdAfx.h'
8819 PDB
8821 The Microsoft Visual C++ PDB file that will store debugging
8822 information for object files, shared libraries, and programs. This
8823 variable is ignored by tools other than Microsoft Visual C++. When
8824 this variable is defined SCons will add options to the compiler and
8825 linker command line to cause them to generate external debugging
8826 information, and will also set up the dependencies for the PDB
8827 file. Example:
8828 env['PDB'] = 'hello.pdb'
8830 The Visual C++ compiler switch that SCons uses by default to
8832 generate PDB information is /Z7. This works correctly with parallel
8833 (-j) builds because it embeds the debug information in the
8834 intermediate object files, as opposed to sharing a single PDB file
8835 between multiple object files. This is also the only way to get
8836 debug information embedded into a static library. Using the /Zi
8837 instead may yield improved link-time performance, although parallel
8838 builds will no longer work. You can generate PDB files with the /Zi
8839 switch by overriding the default $CCPDBFLAGS variable; see the
8840 entry for that variable for specific examples.
8841 PDFCOM
8843 A deprecated synonym for $DVIPDFCOM.
8844 PDFLATEX
8846 The pdflatex utility.
8847 PDFLATEXCOM
8849 The command line used to call the pdflatex utility.
8850 PDFLATEXCOMSTR
8852 The string displayed when calling the pdflatex utility. If this is
8853 not set, then $PDFLATEXCOM (the command line) is displayed.
8854 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
8856 PDFLATEXFLAGS
8858 General options passed to the pdflatex utility.
8859 PDFPREFIX
8861 The prefix used for PDF file names.
8862 PDFSUFFIX
8864 The suffix used for PDF file names.
8865 PDFTEX
8867 The pdftex utility.
8868 PDFTEXCOM
8870 The command line used to call the pdftex utility.
8871 PDFTEXCOMSTR
8873 The string displayed when calling the pdftex utility. If this is
8874 not set, then $PDFTEXCOM (the command line) is displayed.
8875 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
8877 PDFTEXFLAGS
8879 General options passed to the pdftex utility.
8880 PKGCHK
8882 On Solaris systems, the package-checking program that will be used
8883 (along with $PKGINFO) to look for installed versions of the Sun PRO
8884 C++ compiler. The default is /usr/sbin/pgkchk.
8885 PKGINFO
8887 On Solaris systems, the package information program that will be
8888 used (along with $PKGCHK) to look for installed versions of the Sun
8889 PRO C++ compiler. The default is pkginfo.
8890 PLATFORM
8892 The name of the platform used to create the Environment. If no
8893 platform is specified when the Environment is created, scons
8894 autodetects the platform.
8895 env = Environment(tools = [])
8897 if env['PLATFORM'] == 'cygwin':
8898 Tool('mingw')(env)
8899 else:
8900 Tool('msvc')(env)
8901 POAUTOINIT
8903 The $POAUTOINIT variable, if set to True (on non-zero numeric
8904 value), let the msginit tool to automatically initialize missing PO
8905 files with msginit(1). This applies to both, POInit and POUpdate
8906 builders (and others that use any of them).
8907 POCREATE_ALIAS
8909 Common alias for all PO files created with POInit builder (default:
8910 'po-create'). See msginit tool and POInit builder.
8911 POSUFFIX
8913 Suffix used for PO files (default: '.po') See msginit tool and
8914 POInit builder.
8915 POTDOMAIN
8917 The $POTDOMAIN defines default domain, used to generate POT
8918 filename as $POTDOMAIN.pot when no POT file name is provided by the
8919 user. This applies to POTUpdate, POInit and POUpdate builders (and
8920 builders, that use them, e.g. Translate). Normally (if $POTDOMAIN
8921 is not defined), the builders use messages.pot as default POT file
8922 name.
8923 POTSUFFIX
8925 Suffix used for PO Template files (default: '.pot'). See xgettext
8926 tool and POTUpdate builder.
8927 POTUPDATE_ALIAS
8929 Name of the common phony target for all PO Templates created with
8930 POUpdate (default: 'pot-update'). See xgettext tool and POTUpdate
8931 builder.
8932 POUPDATE_ALIAS
8934 Common alias for all PO files being defined with POUpdate builder
8935 (default: 'po-update'). See msgmerge tool and POUpdate builder.
8936 PRINT_CMD_LINE_FUNC
8938 A Python function used to print the command lines as they are
8939 executed (assuming command printing is not disabled by the -q or -s
8940 options or their equivalents). The function should take four
8941 arguments: s, the command being executed (a string), target, the
8942 target being built (file node, list, or string name(s)), source,
8943 the source(s) used (file node, list, or string name(s)), and env,
8944 the environment being used.
8945 The function must do the printing itself. The default
8947 implementation, used if this variable is not set or is None, is:
8948 def print_cmd_line(s, target, source, env):
8950 sys.stdout.write(s + "\n")
8951 Here's an example of a more interesting function:
8953 def print_cmd_line(s, target, source, env):
8955 sys.stdout.write("Building %s -> %s...\n" %
8956 (' and '.join([str(x) for x in source]),
8957 ' and '.join([str(x) for x in target])))
8958 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
8959 env.Program('foo', 'foo.c')
8960 This just prints "Building targetname from sourcename..." instead
8962 of the actual commands. Such a function could also log the actual
8963 commands to a log file, for example.
8964 PROGEMITTER
8966 Contains the emitter specification for the Program builder. The
8967 manpage section "Builder Objects" contains general information on
8968 specifying emitters.
8969 PROGPREFIX
8971 The prefix used for executable file names.
8972 PROGSUFFIX
8974 The suffix used for executable file names.
8975 PSCOM
8977 The command line used to convert TeX DVI files into a PostScript
8978 file.
8979 PSCOMSTR
8981 The string displayed when a TeX DVI file is converted into a
8982 PostScript file. If this is not set, then $PSCOM (the command line)
8983 is displayed.
8984 PSPREFIX
8986 The prefix used for PostScript file names.
8987 PSSUFFIX
8989 The prefix used for PostScript file names.
8990 QT_AUTOSCAN
8992 Turn off scanning for mocable files. Use the Moc Builder to
8993 explicitly specify files to run moc on.
8994 QT_BINPATH
8996 The path where the qt binaries are installed. The default value is
8997 '$QTDIR/bin'.
8998 QT_CPPPATH
9000 The path where the qt header files are installed. The default value
9001 is '$QTDIR/include'. Note: If you set this variable to None, the
9002 tool won't change the $CPPPATH construction variable.
9003 QT_DEBUG
9005 Prints lots of debugging information while scanning for moc files.
9006 QT_LIB
9008 Default value is 'qt'. You may want to set this to 'qt-mt'. Note:
9009 If you set this variable to None, the tool won't change the $LIBS
9010 variable.
9011 QT_LIBPATH
9013 The path where the qt libraries are installed. The default value is
9014 '$QTDIR/lib'. Note: If you set this variable to None, the tool
9015 won't change the $LIBPATH construction variable.
9016 QT_MOC
9018 Default value is '$QT_BINPATH/moc'.
9019 QT_MOCCXXPREFIX
9021 Default value is ''. Prefix for moc output files, when source is a
9022 cxx file.
9023 QT_MOCCXXSUFFIX
9025 Default value is '.moc'. Suffix for moc output files, when source
9026 is a cxx file.
9027 QT_MOCFROMCXXCOM
9029 Command to generate a moc file from a cpp file.
9030 QT_MOCFROMCXXCOMSTR
9032 The string displayed when generating a moc file from a cpp file. If
9033 this is not set, then $QT_MOCFROMCXXCOM (the command line) is
9034 displayed.
9035 QT_MOCFROMCXXFLAGS
9037 Default value is '-i'. These flags are passed to moc, when moccing
9038 a C++ file.
9039 QT_MOCFROMHCOM
9041 Command to generate a moc file from a header.
9042 QT_MOCFROMHCOMSTR
9044 The string displayed when generating a moc file from a cpp file. If
9045 this is not set, then $QT_MOCFROMHCOM (the command line) is
9046 displayed.
9047 QT_MOCFROMHFLAGS
9049 Default value is ''. These flags are passed to moc, when moccing a
9050 header file.
9051 QT_MOCHPREFIX
9053 Default value is 'moc_'. Prefix for moc output files, when source
9054 is a header.
9055 QT_MOCHSUFFIX
9057 Default value is '$CXXFILESUFFIX'. Suffix for moc output files,
9058 when source is a header.
9059 QT_UIC
9061 Default value is '$QT_BINPATH/uic'.
9062 QT_UICCOM
9064 Command to generate header files from .ui files.
9065 QT_UICCOMSTR
9067 The string displayed when generating header files from .ui files.
9068 If this is not set, then $QT_UICCOM (the command line) is
9069 displayed.
9070 QT_UICDECLFLAGS
9072 Default value is ''. These flags are passed to uic, when creating a
9073 a h file from a .ui file.
9074 QT_UICDECLPREFIX
9076 Default value is ''. Prefix for uic generated header files.
9077 QT_UICDECLSUFFIX
9079 Default value is '.h'. Suffix for uic generated header files.
9080 QT_UICIMPLFLAGS
9082 Default value is ''. These flags are passed to uic, when creating a
9083 cxx file from a .ui file.
9084 QT_UICIMPLPREFIX
9086 Default value is 'uic_'. Prefix for uic generated implementation
9087 files.
9088 QT_UICIMPLSUFFIX
9090 Default value is '$CXXFILESUFFIX'. Suffix for uic generated
9091 implementation files.
9092 QT_UISUFFIX
9094 Default value is '.ui'. Suffix of designer input files.
9095 QTDIR
9097 The qt tool tries to take this from os.environ. It also initializes
9098 all QT_* construction variables listed below. (Note that all paths
9099 are constructed with python's os.path.join() method, but are listed
9100 here with the '/' separator for easier reading.) In addition, the
9101 construction environment variables $CPPPATH, $LIBPATH and $LIBS may
9102 be modified and the variables $PROGEMITTER, $SHLIBEMITTER and
9103 $LIBEMITTER are modified. Because the build-performance is affected
9104 when using this tool, you have to explicitly specify it at
9105 Environment creation:
9106 Environment(tools=['default','qt'])
9108 The qt tool supports the following operations:
9110 Automatic moc file generation from header files. You do not have
9113 to specify moc files explicitly, the tool does it for you. However,
9114 there are a few preconditions to do so: Your header file must have
9115 the same filebase as your implementation file and must stay in the
9116 same directory. It must have one of the suffixes .h, .hpp, .H,
9117 .hxx, .hh. You can turn off automatic moc file generation by
9118 setting QT_AUTOSCAN to 0. See also the corresponding Moc() builder
9119 method.
9120 Automatic moc file generation from cxx files. As stated in the qt
9123 documentation, include the moc file at the end of the cxx file.
9124 Note that you have to include the file, which is generated by the
9125 transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by
9126 default <basename>.moc. A warning is generated after building the
9127 moc file, if you do not include the correct file. If you are using
9128 VariantDir, you may need to specify duplicate=1. You can turn off
9129 automatic moc file generation by setting QT_AUTOSCAN to 0. See also
9130 the corresponding Moc builder method.
9131 Automatic handling of .ui files. The implementation files
9134 generated from .ui files are handled much the same as yacc or lex
9135 files. Each .ui file given as a source of Program, Library or
9136 SharedLibrary will generate three files, the declaration file, the
9137 implementation file and a moc file. Because there are also
9138 generated headers, you may need to specify duplicate=1 in calls to
9139 VariantDir. See also the corresponding Uic builder method.
9140 RANLIB
9142 The archive indexer.
9143 RANLIBCOM
9145 The command line used to index a static library archive.
9146 RANLIBCOMSTR
9148 The string displayed when a static library archive is indexed. If
9149 this is not set, then $RANLIBCOM (the command line) is displayed.
9150 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
9152 RANLIBFLAGS
9154 General options passed to the archive indexer.
9155 RC
9157 The resource compiler used to build a Microsoft Visual C++ resource
9158 file.
9159 RCCOM
9161 The command line used to build a Microsoft Visual C++ resource
9162 file.
9163 RCCOMSTR
9165 The string displayed when invoking the resource compiler to build a
9166 Microsoft Visual C++ resource file. If this is not set, then $RCCOM
9167 (the command line) is displayed.
9168 RCFLAGS
9170 The flags passed to the resource compiler by the RES builder.
9171 RCINCFLAGS
9173 An automatically-generated construction variable containing the
9174 command-line options for specifying directories to be searched by
9175 the resource compiler. The value of $RCINCFLAGS is created by
9176 respectively prepending and appending $RCINCPREFIX and $RCINCSUFFIX
9177 to the beginning and end of each directory in $CPPPATH.
9178 RCINCPREFIX
9180 The prefix (flag) used to specify an include directory on the
9181 resource compiler command line. This will be prepended to the
9182 beginning of each directory in the $CPPPATH construction variable
9183 when the $RCINCFLAGS variable is expanded.
9184 RCINCSUFFIX
9186 The suffix used to specify an include directory on the resource
9187 compiler command line. This will be appended to the end of each
9188 directory in the $CPPPATH construction variable when the
9189 $RCINCFLAGS variable is expanded.
9190 RDirs
9192 A function that converts a string into a list of Dir instances by
9193 searching the repositories.
9194 REGSVR
9196 The program used on Windows systems to register a newly-built DLL
9197 library whenever the SharedLibrary builder is passed a keyword
9198 argument of register=1.
9199 REGSVRCOM
9201 The command line used on Windows systems to register a newly-built
9202 DLL library whenever the SharedLibrary builder is passed a keyword
9203 argument of register=1.
9204 REGSVRCOMSTR
9206 The string displayed when registering a newly-built DLL file. If
9207 this is not set, then $REGSVRCOM (the command line) is displayed.
9208 REGSVRFLAGS
9210 Flags passed to the DLL registration program on Windows systems
9211 when a newly-built DLL library is registered. By default, this
9212 includes the /s that prevents dialog boxes from popping up and
9213 requiring user attention.
9214 RMIC
9216 The Java RMI stub compiler.
9217 RMICCOM
9219 The command line used to compile stub and skeleton class files from
9220 Java classes that contain RMI implementations. Any options
9221 specified in the $RMICFLAGS construction variable are included on
9222 this command line.
9223 RMICCOMSTR
9225 The string displayed when compiling stub and skeleton class files
9226 from Java classes that contain RMI implementations. If this is not
9227 set, then $RMICCOM (the command line) is displayed.
9228 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
9230 RMICFLAGS
9232 General options passed to the Java RMI stub compiler.
9233 RPATH
9235 A list of paths to search for shared libraries when running
9236 programs. Currently only used in the GNU (gnulink), IRIX (sgilink)
9237 and Sun (sunlink) linkers. Ignored on platforms and toolchains that
9238 don't support it. Note that the paths added to RPATH are not
9239 transformed by scons in any way: if you want an absolute path, you
9240 must make it absolute yourself.
9241 _RPATH
9243 An automatically-generated construction variable containing the
9244 rpath flags to be used when linking a program with shared
9245 libraries. The value of $_RPATH is created by respectively
9246 prepending $RPATHPREFIX and appending $RPATHSUFFIX to the beginning
9247 and end of each directory in $RPATH.
9248 RPATHPREFIX
9250 The prefix used to specify a directory to be searched for shared
9251 libraries when running programs. This will be prepended to the
9252 beginning of each directory in the $RPATH construction variable
9253 when the $_RPATH variable is automatically generated.
9254 RPATHSUFFIX
9256 The suffix used to specify a directory to be searched for shared
9257 libraries when running programs. This will be appended to the end
9258 of each directory in the $RPATH construction variable when the
9259 $_RPATH variable is automatically generated.
9260 RPCGEN
9262 The RPC protocol compiler.
9263 RPCGENCLIENTFLAGS
9265 Options passed to the RPC protocol compiler when generating client
9266 side stubs. These are in addition to any flags specified in the
9267 $RPCGENFLAGS construction variable.
9268 RPCGENFLAGS
9270 General options passed to the RPC protocol compiler.
9271 RPCGENHEADERFLAGS
9273 Options passed to the RPC protocol compiler when generating a
9274 header file. These are in addition to any flags specified in the
9275 $RPCGENFLAGS construction variable.
9276 RPCGENSERVICEFLAGS
9278 Options passed to the RPC protocol compiler when generating server
9279 side stubs. These are in addition to any flags specified in the
9280 $RPCGENFLAGS construction variable.
9281 RPCGENXDRFLAGS
9283 Options passed to the RPC protocol compiler when generating XDR
9284 routines. These are in addition to any flags specified in the
9285 $RPCGENFLAGS construction variable.
9286 SCANNERS
9288 A list of the available implicit dependency scanners. New file
9289 scanners may be added by appending to this list, although the more
9290 flexible approach is to associate scanners with a specific Builder.
9291 See the manpage sections "Builder Objects" and "Scanner Objects"
9292 for more information.
9293 SCONS_HOME
9295 The (optional) path to the SCons library directory, initialized
9296 from the external environment. If set, this is used to construct a
9297 shorter and more efficient search path in the $MSVSSCONS command
9298 line executed from Microsoft Visual Studio project files.
9299 SHCC
9301 The C compiler used for generating shared-library objects. See also
9302 $CC for compiling to static objects.
9303 SHCCCOM
9305 The command line used to compile a C source file to a
9306 shared-library object file. Any options specified in the $SHCFLAGS,
9307 $SHCCFLAGS and $CPPFLAGS construction variables are included on
9308 this command line. See also $CCCOM for compiling to static objects.
9309 SHCCCOMSTR
9311 If set, the string displayed when a C source file is compiled to a
9312 shared object file. If not set, then $SHCCCOM (the command line) is
9313 displayed. See also $CCCOMSTR for compiling to static objects.
9314 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
9316 SHCCFLAGS
9318 Options that are passed to the C and C++ compilers to generate
9319 shared-library objects. See also $CCFLAGS for compiling to static
9320 objects.
9321 SHCFLAGS
9323 Options that are passed to the C compiler (only; not C++) to
9324 generate shared-library objects. See also $CFLAGS for compiling to
9325 static objects.
9326 SHCXX
9328 The C++ compiler used for generating shared-library objects. See
9329 also $CXX for compiling to static objects.
9330 SHCXXCOM
9332 The command line used to compile a C++ source file to a
9333 shared-library object file. Any options specified in the
9334 $SHCXXFLAGS and $CPPFLAGS construction variables are included on
9335 this command line. See also $CXXCOM for compiling to static
9336 objects.
9337 SHCXXCOMSTR
9339 If set, the string displayed when a C++ source file is compiled to
9340 a shared object file. If not set, then $SHCXXCOM (the command line)
9341 is displayed. See also $CXXCOMSTR for compiling to static objects.
9342 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
9344 SHCXXFLAGS
9346 Options that are passed to the C++ compiler to generate
9347 shared-library objects. See also $CXXFLAGS for compiling to static
9348 objects.
9349 SHDC
9351 The name of the compiler to use when compiling D source destined to
9352 be in a shared objects. See also $DC for compiling to static
9353 objects.
9354 SHDCOM
9356 The command line to use when compiling code to be part of shared
9357 objects. See also $DCOM for compiling to static objects.
9358 SHDCOMSTR
9360 If set, the string displayed when a D source file is compiled to a
9361 (shared) object file. If not set, then $SHDCOM (the command line)
9362 is displayed. See also $DCOMSTR for compiling to static objects.
9363 SHDLIBVERSIONFLAGS
9365 Extra flags added to $SHDLINKCOM when building versioned
9366 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
9367 SHDLINK
9369 The linker to use when creating shared objects for code bases
9370 include D sources. See also $DLINK for linking static objects.
9371 SHDLINKCOM
9373 The command line to use when generating shared objects. See also
9374 $DLINKCOM for linking static objects.
9375 SHDLINKFLAGS
9377 The list of flags to use when generating a shared object. See also
9378 $DLINKFLAGS for linking static objects.
9379 SHELL
9381 A string naming the shell program that will be passed to the $SPAWN
9382 function. See the $SPAWN construction variable for more
9383 information.
9384 SHF03
9386 The Fortran 03 compiler used for generating shared-library objects.
9387 You should normally set the $SHFORTRAN variable, which specifies
9388 the default Fortran compiler for all Fortran versions. You only
9389 need to set $SHF03 if you need to use a specific compiler or
9390 compiler version for Fortran 03 files.
9391 SHF03COM
9393 The command line used to compile a Fortran 03 source file to a
9394 shared-library object file. You only need to set $SHF03COM if you
9395 need to use a specific command line for Fortran 03 files. You
9396 should normally set the $SHFORTRANCOM variable, which specifies the
9397 default command line for all Fortran versions.
9398 SHF03COMSTR
9400 If set, the string displayed when a Fortran 03 source file is
9401 compiled to a shared-library object file. If not set, then
9402 $SHF03COM or $SHFORTRANCOM (the command line) is displayed.
9403 SHF03FLAGS
9405 Options that are passed to the Fortran 03 compiler to generated
9406 shared-library objects. You only need to set $SHF03FLAGS if you
9407 need to define specific user options for Fortran 03 files. You
9408 should normally set the $SHFORTRANFLAGS variable, which specifies
9409 the user-specified options passed to the default Fortran compiler
9410 for all Fortran versions.
9411 SHF03PPCOM
9413 The command line used to compile a Fortran 03 source file to a
9414 shared-library object file after first running the file through the
9415 C preprocessor. Any options specified in the $SHF03FLAGS and
9416 $CPPFLAGS construction variables are included on this command line.
9417 You only need to set $SHF03PPCOM if you need to use a specific
9418 C-preprocessor command line for Fortran 03 files. You should
9419 normally set the $SHFORTRANPPCOM variable, which specifies the
9420 default C-preprocessor command line for all Fortran versions.
9421 SHF03PPCOMSTR
9423 If set, the string displayed when a Fortran 03 source file is
9424 compiled to a shared-library object file after first running the
9425 file through the C preprocessor. If not set, then $SHF03PPCOM or
9426 $SHFORTRANPPCOM (the command line) is displayed.
9427 SHF08
9429 The Fortran 08 compiler used for generating shared-library objects.
9430 You should normally set the $SHFORTRAN variable, which specifies
9431 the default Fortran compiler for all Fortran versions. You only
9432 need to set $SHF08 if you need to use a specific compiler or
9433 compiler version for Fortran 08 files.
9434 SHF08COM
9436 The command line used to compile a Fortran 08 source file to a
9437 shared-library object file. You only need to set $SHF08COM if you
9438 need to use a specific command line for Fortran 08 files. You
9439 should normally set the $SHFORTRANCOM variable, which specifies the
9440 default command line for all Fortran versions.
9441 SHF08COMSTR
9443 If set, the string displayed when a Fortran 08 source file is
9444 compiled to a shared-library object file. If not set, then
9445 $SHF08COM or $SHFORTRANCOM (the command line) is displayed.
9446 SHF08FLAGS
9448 Options that are passed to the Fortran 08 compiler to generated
9449 shared-library objects. You only need to set $SHF08FLAGS if you
9450 need to define specific user options for Fortran 08 files. You
9451 should normally set the $SHFORTRANFLAGS variable, which specifies
9452 the user-specified options passed to the default Fortran compiler
9453 for all Fortran versions.
9454 SHF08PPCOM
9456 The command line used to compile a Fortran 08 source file to a
9457 shared-library object file after first running the file through the
9458 C preprocessor. Any options specified in the $SHF08FLAGS and
9459 $CPPFLAGS construction variables are included on this command line.
9460 You only need to set $SHF08PPCOM if you need to use a specific
9461 C-preprocessor command line for Fortran 08 files. You should
9462 normally set the $SHFORTRANPPCOM variable, which specifies the
9463 default C-preprocessor command line for all Fortran versions.
9464 SHF08PPCOMSTR
9466 If set, the string displayed when a Fortran 08 source file is
9467 compiled to a shared-library object file after first running the
9468 file through the C preprocessor. If not set, then $SHF08PPCOM or
9469 $SHFORTRANPPCOM (the command line) is displayed.
9470 SHF77
9472 The Fortran 77 compiler used for generating shared-library objects.
9473 You should normally set the $SHFORTRAN variable, which specifies
9474 the default Fortran compiler for all Fortran versions. You only
9475 need to set $SHF77 if you need to use a specific compiler or
9476 compiler version for Fortran 77 files.
9477 SHF77COM
9479 The command line used to compile a Fortran 77 source file to a
9480 shared-library object file. You only need to set $SHF77COM if you
9481 need to use a specific command line for Fortran 77 files. You
9482 should normally set the $SHFORTRANCOM variable, which specifies the
9483 default command line for all Fortran versions.
9484 SHF77COMSTR
9486 If set, the string displayed when a Fortran 77 source file is
9487 compiled to a shared-library object file. If not set, then
9488 $SHF77COM or $SHFORTRANCOM (the command line) is displayed.
9489 SHF77FLAGS
9491 Options that are passed to the Fortran 77 compiler to generated
9492 shared-library objects. You only need to set $SHF77FLAGS if you
9493 need to define specific user options for Fortran 77 files. You
9494 should normally set the $SHFORTRANFLAGS variable, which specifies
9495 the user-specified options passed to the default Fortran compiler
9496 for all Fortran versions.
9497 SHF77PPCOM
9499 The command line used to compile a Fortran 77 source file to a
9500 shared-library object file after first running the file through the
9501 C preprocessor. Any options specified in the $SHF77FLAGS and
9502 $CPPFLAGS construction variables are included on this command line.
9503 You only need to set $SHF77PPCOM if you need to use a specific
9504 C-preprocessor command line for Fortran 77 files. You should
9505 normally set the $SHFORTRANPPCOM variable, which specifies the
9506 default C-preprocessor command line for all Fortran versions.
9507 SHF77PPCOMSTR
9509 If set, the string displayed when a Fortran 77 source file is
9510 compiled to a shared-library object file after first running the
9511 file through the C preprocessor. If not set, then $SHF77PPCOM or
9512 $SHFORTRANPPCOM (the command line) is displayed.
9513 SHF90
9515 The Fortran 90 compiler used for generating shared-library objects.
9516 You should normally set the $SHFORTRAN variable, which specifies
9517 the default Fortran compiler for all Fortran versions. You only
9518 need to set $SHF90 if you need to use a specific compiler or
9519 compiler version for Fortran 90 files.
9520 SHF90COM
9522 The command line used to compile a Fortran 90 source file to a
9523 shared-library object file. You only need to set $SHF90COM if you
9524 need to use a specific command line for Fortran 90 files. You
9525 should normally set the $SHFORTRANCOM variable, which specifies the
9526 default command line for all Fortran versions.
9527 SHF90COMSTR
9529 If set, the string displayed when a Fortran 90 source file is
9530 compiled to a shared-library object file. If not set, then
9531 $SHF90COM or $SHFORTRANCOM (the command line) is displayed.
9532 SHF90FLAGS
9534 Options that are passed to the Fortran 90 compiler to generated
9535 shared-library objects. You only need to set $SHF90FLAGS if you
9536 need to define specific user options for Fortran 90 files. You
9537 should normally set the $SHFORTRANFLAGS variable, which specifies
9538 the user-specified options passed to the default Fortran compiler
9539 for all Fortran versions.
9540 SHF90PPCOM
9542 The command line used to compile a Fortran 90 source file to a
9543 shared-library object file after first running the file through the
9544 C preprocessor. Any options specified in the $SHF90FLAGS and
9545 $CPPFLAGS construction variables are included on this command line.
9546 You only need to set $SHF90PPCOM if you need to use a specific
9547 C-preprocessor command line for Fortran 90 files. You should
9548 normally set the $SHFORTRANPPCOM variable, which specifies the
9549 default C-preprocessor command line for all Fortran versions.
9550 SHF90PPCOMSTR
9552 If set, the string displayed when a Fortran 90 source file is
9553 compiled to a shared-library object file after first running the
9554 file through the C preprocessor. If not set, then $SHF90PPCOM or
9555 $SHFORTRANPPCOM (the command line) is displayed.
9556 SHF95
9558 The Fortran 95 compiler used for generating shared-library objects.
9559 You should normally set the $SHFORTRAN variable, which specifies
9560 the default Fortran compiler for all Fortran versions. You only
9561 need to set $SHF95 if you need to use a specific compiler or
9562 compiler version for Fortran 95 files.
9563 SHF95COM
9565 The command line used to compile a Fortran 95 source file to a
9566 shared-library object file. You only need to set $SHF95COM if you
9567 need to use a specific command line for Fortran 95 files. You
9568 should normally set the $SHFORTRANCOM variable, which specifies the
9569 default command line for all Fortran versions.
9570 SHF95COMSTR
9572 If set, the string displayed when a Fortran 95 source file is
9573 compiled to a shared-library object file. If not set, then
9574 $SHF95COM or $SHFORTRANCOM (the command line) is displayed.
9575 SHF95FLAGS
9577 Options that are passed to the Fortran 95 compiler to generated
9578 shared-library objects. You only need to set $SHF95FLAGS if you
9579 need to define specific user options for Fortran 95 files. You
9580 should normally set the $SHFORTRANFLAGS variable, which specifies
9581 the user-specified options passed to the default Fortran compiler
9582 for all Fortran versions.
9583 SHF95PPCOM
9585 The command line used to compile a Fortran 95 source file to a
9586 shared-library object file after first running the file through the
9587 C preprocessor. Any options specified in the $SHF95FLAGS and
9588 $CPPFLAGS construction variables are included on this command line.
9589 You only need to set $SHF95PPCOM if you need to use a specific
9590 C-preprocessor command line for Fortran 95 files. You should
9591 normally set the $SHFORTRANPPCOM variable, which specifies the
9592 default C-preprocessor command line for all Fortran versions.
9593 SHF95PPCOMSTR
9595 If set, the string displayed when a Fortran 95 source file is
9596 compiled to a shared-library object file after first running the
9597 file through the C preprocessor. If not set, then $SHF95PPCOM or
9598 $SHFORTRANPPCOM (the command line) is displayed.
9599 SHFORTRAN
9601 The default Fortran compiler used for generating shared-library
9602 objects.
9603 SHFORTRANCOM
9605 The command line used to compile a Fortran source file to a
9606 shared-library object file.
9607 SHFORTRANCOMSTR
9609 If set, the string displayed when a Fortran source file is compiled
9610 to a shared-library object file. If not set, then $SHFORTRANCOM
9611 (the command line) is displayed.
9612 SHFORTRANFLAGS
9614 Options that are passed to the Fortran compiler to generate
9615 shared-library objects.
9616 SHFORTRANPPCOM
9618 The command line used to compile a Fortran source file to a
9619 shared-library object file after first running the file through the
9620 C preprocessor. Any options specified in the $SHFORTRANFLAGS and
9621 $CPPFLAGS construction variables are included on this command line.
9622 SHFORTRANPPCOMSTR
9624 If set, the string displayed when a Fortran source file is compiled
9625 to a shared-library object file after first running the file
9626 through the C preprocessor. If not set, then $SHFORTRANPPCOM (the
9627 command line) is displayed.
9628 SHLIBEMITTER
9630 Contains the emitter specification for the SharedLibrary builder.
9631 The manpage section "Builder Objects" contains general information
9632 on specifying emitters.
9633 SHLIBNOVERSIONSYMLINKS
9635 Instructs the SharedLibrary builder to not create symlinks for
9636 versioned shared libraries.
9637 SHLIBPREFIX
9639 The prefix used for shared library file names.
9640 _SHLIBSONAME
9642 A macro that automatically generates shared library's SONAME based
9643 on $TARGET, $SHLIBVERSION and $SHLIBSUFFIX. Used by SharedLibrary
9644 builder when the linker tool supports SONAME (e.g. gnulink).
9645 SHLIBSUFFIX
9647 The suffix used for shared library file names.
9648 SHLIBVERSION
9650 When this construction variable is defined, a versioned shared
9651 library is created by the SharedLibrary builder. This activates the
9652 $_SHLIBVERSIONFLAGS and thus modifies the $SHLINKCOM as required,
9653 adds the version number to the library name, and creates the
9654 symlinks that are needed. $SHLIBVERSION versions should exist as
9655 alpha-numeric, decimal-delimited values as defined by the regular
9656 expression "\w+[\.\w+]*". Example $SHLIBVERSION values include '1',
9657 '1.2.3', and '1.2.gitaa412c8b'.
9658 _SHLIBVERSIONFLAGS
9660 This macro automatically introduces extra flags to $SHLINKCOM when
9661 building versioned SharedLibrary (that is when $SHLIBVERSION is
9662 set). _SHLIBVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS and some
9663 extra dynamically generated options (such as
9664 -Wl,-soname=$_SHLIBSONAME. It is unused by "plain" (unversioned)
9665 shared libraries.
9666 SHLIBVERSIONFLAGS
9668 Extra flags added to $SHLINKCOM when building versioned
9669 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
9670 SHLINK
9672 The linker for programs that use shared libraries. See also $LINK
9673 for linking static objects.
9674 SHLINKCOM
9676 The command line used to link programs using shared libraries. See
9677 also $LINKCOM for linking static objects.
9678 SHLINKCOMSTR
9680 The string displayed when programs using shared libraries are
9681 linked. If this is not set, then $SHLINKCOM (the command line) is
9682 displayed. See also $LINKCOMSTR for linking static objects.
9683 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
9685 SHLINKFLAGS
9687 General user options passed to the linker for programs using shared
9688 libraries. Note that this variable should not contain -l (or
9689 similar) options for linking with the libraries listed in $LIBS,
9690 nor -L (or similar) include search path options that scons
9691 generates automatically from $LIBPATH. See $_LIBFLAGS above, for
9692 the variable that expands to library-link options, and
9693 $_LIBDIRFLAGS above, for the variable that expands to library
9694 search path options. See also $LINKFLAGS for linking static
9695 objects.
9696 SHOBJPREFIX
9698 The prefix used for shared object file names.
9699 SHOBJSUFFIX
9701 The suffix used for shared object file names.
9702 SONAME
9704 Variable used to hard-code SONAME for versioned shared
9705 library/loadable module.
9706 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
9708 The variable is used, for example, by gnulink linker tool.
9710 SOURCE
9712 A reserved variable name that may not be set or used in a
9713 construction environment. (See the manpage section "Variable
9714 Substitution" for more information).
9715 SOURCE_URL
9717 The URL (web address) of the location from which the project was
9718 retrieved. This is used to fill in the Source: field in the
9719 controlling information for Ipkg and RPM packages.
9720 SOURCES
9722 A reserved variable name that may not be set or used in a
9723 construction environment. (See the manpage section "Variable
9724 Substitution" for more information).
9725 SOVERSION
9727 This will construct the SONAME using on the base library name (test
9728 in the example below) and use specified SOVERSION to create SONAME.
9729 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
9731 The variable is used, for example, by gnulink linker tool.
9733 In the example above SONAME would be libtest.so.2 which would be a
9735 symlink and point to libtest.so.0.1.2
9736 SPAWN
9738 A command interpreter function that will be called to execute
9739 command line strings. The function must expect the following
9740 arguments:
9741 def spawn(shell, escape, cmd, args, env):
9743 sh is a string naming the shell program to use. escape is a
9746 function that can be called to escape shell special characters in
9747 the command line. cmd is the path to the command to be executed.
9748 args is the arguments to the command. env is a dictionary of the
9749 environment variables in which the command should be executed.
9750 STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME
9752 When this variable is true, static objects and shared objects are
9753 assumed to be the same; that is, SCons does not check for linking
9754 static objects into a shared library.
9755 SUBST_DICT
9757 The dictionary used by the Substfile or Textfile builders for
9758 substitution values. It can be anything acceptable to the dict()
9759 constructor, so in addition to a dictionary, lists of tuples are
9760 also acceptable.
9761 SUBSTFILEPREFIX
9763 The prefix used for Substfile file names, an empty string by
9764 default.
9765 SUBSTFILESUFFIX
9767 The suffix used for Substfile file names, an empty string by
9768 default.
9769 SUMMARY
9771 A short summary of what the project is about. This is used to fill
9772 in the Summary: field in the controlling information for Ipkg and
9773 RPM packages, and as the Description: field in MSI packages.
9774 SWIG
9776 The scripting language wrapper and interface generator.
9777 SWIGCFILESUFFIX
9779 The suffix that will be used for intermediate C source files
9780 generated by the scripting language wrapper and interface
9781 generator. The default value is _wrap$CFILESUFFIX. By default, this
9782 value is used whenever the -c++ option is not specified as part of
9783 the $SWIGFLAGS construction variable.
9784 SWIGCOM
9786 The command line used to call the scripting language wrapper and
9787 interface generator.
9788 SWIGCOMSTR
9790 The string displayed when calling the scripting language wrapper
9791 and interface generator. If this is not set, then $SWIGCOM (the
9792 command line) is displayed.
9793 SWIGCXXFILESUFFIX
9795 The suffix that will be used for intermediate C++ source files
9796 generated by the scripting language wrapper and interface
9797 generator. The default value is _wrap$CFILESUFFIX. By default, this
9798 value is used whenever the -c++ option is specified as part of the
9799 $SWIGFLAGS construction variable.
9800 SWIGDIRECTORSUFFIX
9802 The suffix that will be used for intermediate C++ header files
9803 generated by the scripting language wrapper and interface
9804 generator. These are only generated for C++ code when the SWIG
9805 'directors' feature is turned on. The default value is _wrap.h.
9806 SWIGFLAGS
9808 General options passed to the scripting language wrapper and
9809 interface generator. This is where you should set -python, -perl5,
9810 -tcl, or whatever other options you want to specify to SWIG. If you
9811 set the -c++ option in this variable, scons will, by default,
9812 generate a C++ intermediate source file with the extension that is
9813 specified as the $CXXFILESUFFIX variable.
9814 _SWIGINCFLAGS
9816 An automatically-generated construction variable containing the
9817 SWIG command-line options for specifying directories to be searched
9818 for included files. The value of $_SWIGINCFLAGS is created by
9819 respectively prepending and appending $SWIGINCPREFIX and
9820 $SWIGINCSUFFIX to the beginning and end of each directory in
9821 $SWIGPATH.
9822 SWIGINCPREFIX
9824 The prefix used to specify an include directory on the SWIG command
9825 line. This will be prepended to the beginning of each directory in
9826 the $SWIGPATH construction variable when the $_SWIGINCFLAGS
9827 variable is automatically generated.
9828 SWIGINCSUFFIX
9830 The suffix used to specify an include directory on the SWIG command
9831 line. This will be appended to the end of each directory in the
9832 $SWIGPATH construction variable when the $_SWIGINCFLAGS variable is
9833 automatically generated.
9834 SWIGOUTDIR
9836 Specifies the output directory in which the scripting language
9837 wrapper and interface generator should place generated
9838 language-specific files. This will be used by SCons to identify the
9839 files that will be generated by the swig call, and translated into
9840 the swig -outdir option on the command line.
9841 SWIGPATH
9843 The list of directories that the scripting language wrapper and
9844 interface generate will search for included files. The SWIG
9845 implicit dependency scanner will search these directories for
9846 include files. The default value is an empty list.
9847 Don't explicitly put include directory arguments in SWIGFLAGS; the
9849 result will be non-portable and the directories will not be
9850 searched by the dependency scanner. Note: directory names in
9851 SWIGPATH will be looked-up relative to the SConscript directory
9852 when they are used in a command. To force scons to look-up a
9853 directory relative to the root of the source tree use #:
9854 env = Environment(SWIGPATH='#/include')
9856 The directory look-up can also be forced using the Dir() function:
9858 include = Dir('include')
9860 env = Environment(SWIGPATH=include)
9861 The directory list will be added to command lines through the
9863 automatically-generated $_SWIGINCFLAGS construction variable, which
9864 is constructed by respectively prepending and appending the values
9865 of the $SWIGINCPREFIX and $SWIGINCSUFFIX construction variables to
9866 the beginning and end of each directory in $SWIGPATH. Any command
9867 lines you define that need the SWIGPATH directory list should
9868 include $_SWIGINCFLAGS:
9869 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
9871 SWIGVERSION
9873 The version number of the SWIG tool.
9874 TAR
9876 The tar archiver.
9877 TARCOM
9879 The command line used to call the tar archiver.
9880 TARCOMSTR
9882 The string displayed when archiving files using the tar archiver.
9883 If this is not set, then $TARCOM (the command line) is displayed.
9884 env = Environment(TARCOMSTR = "Archiving $TARGET")
9886 TARFLAGS
9888 General options passed to the tar archiver.
9889 TARGET
9891 A reserved variable name that may not be set or used in a
9892 construction environment. (See the manpage section "Variable
9893 Substitution" for more information).
9894 TARGET_ARCH
9896 The name of the target hardware architecture for the compiled
9897 objects created by this Environment. This defaults to the value of
9898 HOST_ARCH, and the user can override it. Currently only set for
9899 Win32.
9900 Sets the target architecture for the Visual C++ compiler (i.e. the
9902 arch of the binaries generated by the compiler). If not set,
9903 default to $HOST_ARCH, or, if that is unset, to the architecture of
9904 the running machine's OS (note that the python build or
9905 architecture has no effect). This variable must be passed as an
9906 argument to the Environment() constructor; setting it later has no
9907 effect. This is currently only used on Windows, but in the future
9908 it will be used on other OSes as well. If this is set and
9909 $MSVC_VERSION is not set, this will search for all installed MSVC's
9910 that support the $TARGET_ARCH, selecting the latest version for
9911 use.
9912 On Windows, valid target values are x86, arm, i386 for 32-bit
9914 targets and amd64, arm64, em64t, x86_64 and ia64 (Itanium) for
9915 64-bit targets. Note that not all target architectures are
9916 supported for all Visual Studio / MSVC versions. Check the relevant
9917 Microsoft documentation.
9918 For example, if you want to compile 64-bit binaries, you would set
9920 TARGET_ARCH='x86_64' in your SCons environment.
9921 TARGET_OS
9923 The name of the target operating system for the compiled objects
9924 created by this Environment. This defaults to the value of HOST_OS,
9925 and the user can override it. Currently only set for Win32.
9926 TARGETS
9928 A reserved variable name that may not be set or used in a
9929 construction environment. (See the manpage section "Variable
9930 Substitution" for more information).
9931 TARSUFFIX
9933 The suffix used for tar file names.
9934 TEMPFILEARGJOIN
9936 The string (or character) to be used to join the arguments passed
9937 to TEMPFILE when command line exceeds the limit set by
9938 $MAXLINELENGTH. The default value is a space. However for MSVC,
9939 MSLINK the default is a line seperator characters as defined by
9940 os.linesep. Note this value is used literally and not expanded by
9941 the subst logic.
9942 TEMPFILEDIR
9944 The directory to create the tempfile in.
9945 TEMPFILEPREFIX
9947 The prefix for a temporary file used to store lines lines longer
9948 than $MAXLINELENGTH as operations which call out to a shell will
9949 fail if the line is too long, which particularly impacts linking.
9950 The default is '@', which works for the Microsoft and GNU
9951 toolchains on Windows. Set this appropriately for other toolchains,
9952 for example '-@' for the diab compiler or '-via' for ARM toolchain.
9953 TEMPFILESUFFIX
9955 The suffix used for the temporary file name used for long command
9956 lines. The name should include the dot ('.') if one is wanted as it
9957 will not be added automatically. The default is '.lnk'.
9958 TEX
9960 The TeX formatter and typesetter.
9961 TEXCOM
9963 The command line used to call the TeX formatter and typesetter.
9964 TEXCOMSTR
9966 The string displayed when calling the TeX formatter and typesetter.
9967 If this is not set, then $TEXCOM (the command line) is displayed.
9968 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
9970 TEXFLAGS
9972 General options passed to the TeX formatter and typesetter.
9973 TEXINPUTS
9975 List of directories that the LaTeX program will search for include
9976 directories. The LaTeX implicit dependency scanner will search
9977 these directories for \include and \import files.
9978 TEXTFILEPREFIX
9980 The prefix used for Textfile file names, an empty string by
9981 default.
9982 TEXTFILESUFFIX
9984 The suffix used for Textfile file names; .txt by default.
9985 TOOLS
9987 A list of the names of the Tool specifications that are part of
9988 this construction environment.
9989 UNCHANGED_SOURCES
9991 A reserved variable name that may not be set or used in a
9992 construction environment. (See the manpage section "Variable
9993 Substitution" for more information).
9994 UNCHANGED_TARGETS
9996 A reserved variable name that may not be set or used in a
9997 construction environment. (See the manpage section "Variable
9998 Substitution" for more information).
9999 VENDOR
10001 The person or organization who supply the packaged software. This
10002 is used to fill in the Vendor: field in the controlling information
10003 for RPM packages, and the Manufacturer: field in the controlling
10004 information for MSI packages.
10005 VERSION
10007 The version of the project, specified as a string.
10008 VSWHERE
10010 Specify the location of vswhere.exe.
10011 The vswhere.exe executable is distributed with Microsoft Visual
10013 Studio and Build Tools since the 2017 edition, but is also
10014 available standalone. It provides full information about
10015 installations of 2017 and later editions. With the -legacy
10016 argument, vswhere.exe can detect installations of the 2010 through
10017 2015 editions with limited data returned. If VSWHERE is set, SCons
10018 will use that location.
10019 Otherwise SCons will look in the following locations and set
10021 VSWHERE to the path of the first vswhere.exe located.
10022 • %ProgramFiles(x86)%\Microsoft Visual Studio\Installer
10024 • %ProgramFiles%\Microsoft Visual Studio\Installer
10026 • %ChocolateyInstall%\bin
10028 Note that VSWHERE must be set at the same time or prior to any of
10030 msvc, msvs , and/or mslink Tool being initialized. Either set it as
10031 follows
10032 env = Environment(VSWHERE='c:/my/path/to/vswhere')
10034 or if your construction environment is created specifying an empty
10036 tools list (or a list of tools which omits all of default, msvs,
10037 msvc, and mslink), and also before env.Tool is called to
10038 ininitialize any of those tools:
10039 env = Environment(tools=[])
10041 env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
10042 env.Tool('msvc')
10043 env.Tool('mslink')
10044 env.Tool('msvs')
10045 WIN32_INSERT_DEF
10049 A deprecated synonym for $WINDOWS_INSERT_DEF.
10050 WIN32DEFPREFIX
10052 A deprecated synonym for $WINDOWSDEFPREFIX.
10053 WIN32DEFSUFFIX
10055 A deprecated synonym for $WINDOWSDEFSUFFIX.
10056 WIN32EXPPREFIX
10058 A deprecated synonym for $WINDOWSEXPSUFFIX.
10059 WIN32EXPSUFFIX
10061 A deprecated synonym for $WINDOWSEXPSUFFIX.
10062 WINDOWS_EMBED_MANIFEST
10064 Set this variable to True or 1 to embed the compiler-generated
10065 manifest (normally ${TARGET}.manifest) into all Windows exes and
10066 DLLs built with this environment, as a resource during their link
10067 step. This is done using $MT and $MTEXECOM and $MTSHLIBCOM.
10068 WINDOWS_INSERT_DEF
10070 When this is set to true, a library build of a Windows shared
10071 library (.dll file) will also build a corresponding .def file at
10072 the same time, if a .def file is not already listed as a build
10073 target. The default is 0 (do not build a .def file).
10074 WINDOWS_INSERT_MANIFEST
10076 When this is set to true, scons will be aware of the .manifest
10077 files generated by Microsoft Visua C/C++ 8.
10078 WINDOWSDEFPREFIX
10080 The prefix used for Windows .def file names.
10081 WINDOWSDEFSUFFIX
10083 The suffix used for Windows .def file names.
10084 WINDOWSEXPPREFIX
10086 The prefix used for Windows .exp file names.
10087 WINDOWSEXPSUFFIX
10089 The suffix used for Windows .exp file names.
10090 WINDOWSPROGMANIFESTPREFIX
10092 The prefix used for executable program .manifest files generated by
10093 Microsoft Visual C/C++.
10094 WINDOWSPROGMANIFESTSUFFIX
10096 The suffix used for executable program .manifest files generated by
10097 Microsoft Visual C/C++.
10098 WINDOWSSHLIBMANIFESTPREFIX
10100 The prefix used for shared library .manifest files generated by
10101 Microsoft Visual C/C++.
10102 WINDOWSSHLIBMANIFESTSUFFIX
10104 The suffix used for shared library .manifest files generated by
10105 Microsoft Visual C/C++.
10106 X_IPK_DEPENDS
10108 This is used to fill in the Depends: field in the controlling
10109 information for Ipkg packages.
10110 X_IPK_DESCRIPTION
10112 This is used to fill in the Description: field in the controlling
10113 information for Ipkg packages. The default value is
10114 $SUMMARY\n$DESCRIPTION
10115 X_IPK_MAINTAINER
10117 This is used to fill in the Maintainer: field in the controlling
10118 information for Ipkg packages.
10119 X_IPK_PRIORITY
10121 This is used to fill in the Priority: field in the controlling
10122 information for Ipkg packages.
10123 X_IPK_SECTION
10125 This is used to fill in the Section: field in the controlling
10126 information for Ipkg packages.
10127 X_MSI_LANGUAGE
10129 This is used to fill in the Language: attribute in the controlling
10130 information for MSI packages.
10131 X_MSI_LICENSE_TEXT
10133 The text of the software license in RTF format. Carriage return
10134 characters will be replaced with the RTF equivalent \\par.
10135 X_MSI_UPGRADE_CODE
10137 TODO
10138 X_RPM_AUTOREQPROV
10140 This is used to fill in the AutoReqProv: field in the RPM .spec
10141 file.
10142 X_RPM_BUILD
10144 internal, but overridable
10145 X_RPM_BUILDREQUIRES
10147 This is used to fill in the BuildRequires: field in the RPM .spec
10148 file. Note this should only be used on a host managed by rpm as the
10149 dependencies will not be resolvable at build time otherwise.
10150 X_RPM_BUILDROOT
10152 internal, but overridable
10153 X_RPM_CLEAN
10155 internal, but overridable
10156 X_RPM_CONFLICTS
10158 This is used to fill in the Conflicts: field in the RPM .spec file.
10159 X_RPM_DEFATTR
10161 This value is used as the default attributes for the files in the
10162 RPM package. The default value is (-,root,root).
10163 X_RPM_DISTRIBUTION
10165 This is used to fill in the Distribution: field in the RPM .spec
10166 file.
10167 X_RPM_EPOCH
10169 This is used to fill in the Epoch: field in the RPM .spec file.
10170 X_RPM_EXCLUDEARCH
10172 This is used to fill in the ExcludeArch: field in the RPM .spec
10173 file.
10174 X_RPM_EXLUSIVEARCH
10176 This is used to fill in the ExclusiveArch: field in the RPM .spec
10177 file.
10178 X_RPM_EXTRADEFS
10180 A list used to supply extra defintions or flags to be added to the
10181 RPM .spec file. Each item is added as-is with a carriage return
10182 appended. This is useful if some specific RPM feature not otherwise
10183 anticipated by SCons needs to be turned on or off. Note if this
10184 variable is omitted, SCons will by default supply the value
10185 '%global debug_package %{nil}' to disable debug package generation.
10186 To enable debug package generation, include this variable set
10187 either to None, or to a custom list that does not include the
10188 default line. Added in version 3.1.
10189 env.Package(
10191 NAME="foo",
10192 ...
10193 X_RPM_EXTRADEFS=[
10194 "%define _unpackaged_files_terminate_build 0"
10195 "%define _missing_doc_files_terminate_build 0"
10196 ],
10197 ...
10198 )
10199 X_RPM_GROUP
10201 This is used to fill in the Group: field in the RPM .spec file.
10202 X_RPM_GROUP_lang
10204 This is used to fill in the Group(lang): field in the RPM .spec
10205 file. Note that lang is not literal and should be replaced by the
10206 appropriate language code.
10207 X_RPM_ICON
10209 This is used to fill in the Icon: field in the RPM .spec file.
10210 X_RPM_INSTALL
10212 internal, but overridable
10213 X_RPM_PACKAGER
10215 This is used to fill in the Packager: field in the RPM .spec file.
10216 X_RPM_POSTINSTALL
10218 This is used to fill in the %post: section in the RPM .spec file.
10219 X_RPM_POSTUNINSTALL
10221 This is used to fill in the %postun: section in the RPM .spec file.
10222 X_RPM_PREFIX
10224 This is used to fill in the Prefix: field in the RPM .spec file.
10225 X_RPM_PREINSTALL
10227 This is used to fill in the %pre: section in the RPM .spec file.
10228 X_RPM_PREP
10230 internal, but overridable
10231 X_RPM_PREUNINSTALL
10233 This is used to fill in the %preun: section in the RPM .spec file.
10234 X_RPM_PROVIDES
10236 This is used to fill in the Provides: field in the RPM .spec file.
10237 X_RPM_REQUIRES
10239 This is used to fill in the Requires: field in the RPM .spec file.
10240 X_RPM_SERIAL
10242 This is used to fill in the Serial: field in the RPM .spec file.
10243 X_RPM_URL
10245 This is used to fill in the Url: field in the RPM .spec file.
10246 XGETTEXT
10248 Path to xgettext(1) program (found via Detect()). See xgettext tool
10249 and POTUpdate builder.
10250 XGETTEXTCOM
10252 Complete xgettext command line. See xgettext tool and POTUpdate
10253 builder.
10254 XGETTEXTCOMSTR
10256 A string that is shown when xgettext(1) command is invoked
10257 (default: '', which means "print $XGETTEXTCOM"). See xgettext tool
10258 and POTUpdate builder.
10259 _XGETTEXTDOMAIN
10261 Internal "macro". Generates xgettext domain name form source and
10262 target (default: '${TARGET.filebase}').
10263 XGETTEXTFLAGS
10265 Additional flags to xgettext(1). See xgettext tool and POTUpdate
10266 builder.
10267 XGETTEXTFROM
10269 Name of file containing list of xgettext(1)'s source files.
10270 Autotools' users know this as POTFILES.in so they will in most
10271 cases set XGETTEXTFROM="POTFILES.in" here. The $XGETTEXTFROM files
10272 have same syntax and semantics as the well known GNU POTFILES.in.
10273 See xgettext tool and POTUpdate builder.
10274 _XGETTEXTFROMFLAGS
10276 Internal "macro". Genrates list of -D<dir> flags from the
10277 $XGETTEXTPATH list.
10278 XGETTEXTFROMPREFIX
10280 This flag is used to add single $XGETTEXTFROM file to xgettext(1)'s
10281 commandline (default: '-f').
10282 XGETTEXTFROMSUFFIX
10284 (default: '')
10285 XGETTEXTPATH
10287 List of directories, there xgettext(1) will look for source files
10288 (default: []).
10289 Note
10291 This variable works only together with $XGETTEXTFROM
10292 See also xgettext tool and POTUpdate builder.
10293 _XGETTEXTPATHFLAGS
10295 Internal "macro". Generates list of -f<file> flags from
10296 $XGETTEXTFROM.
10297 XGETTEXTPATHPREFIX
10299 This flag is used to add single search path to xgettext(1)'s
10300 commandline (default: '-D').
10301 XGETTEXTPATHSUFFIX
10303 (default: '')
10304 YACC
10306 The parser generator.
10307 YACCCOM
10309 The command line used to call the parser generator to generate a
10310 source file.
10311 YACCCOMSTR
10313 The string displayed when generating a source file using the parser
10314 generator. If this is not set, then $YACCCOM (the command line) is
10315 displayed.
10316 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
10318 YACCFLAGS
10320 General options passed to the parser generator. If $YACCFLAGS
10321 contains a -d option, SCons assumes that the call will also create
10322 a .h file (if the yacc source file ends in a .y suffix) or a .hpp
10323 file (if the yacc source file ends in a .yy suffix)
10324 YACCHFILESUFFIX
10326 The suffix of the C header file generated by the parser generator
10327 when the -d option is used. Note that setting this variable does
10328 not cause the parser generator to generate a header file with the
10329 specified suffix, it exists to allow you to specify what suffix the
10330 parser generator will use of its own accord. The default value is
10331 .h.
10332 YACCHXXFILESUFFIX
10334 The suffix of the C++ header file generated by the parser generator
10335 when the -d option is used. Note that setting this variable does
10336 not cause the parser generator to generate a header file with the
10337 specified suffix, it exists to allow you to specify what suffix the
10338 parser generator will use of its own accord. The default value is
10339 .hpp, except on Mac OS X, where the default is ${TARGET.suffix}.h.
10340 because the default bison parser generator just appends .h to the
10341 name of the generated C++ file.
10342 YACCVCGFILESUFFIX
10344 The suffix of the file containing the VCG grammar automaton
10345 definition when the --graph= option is used. Note that setting this
10346 variable does not cause the parser generator to generate a VCG file
10347 with the specified suffix, it exists to allow you to specify what
10348 suffix the parser generator will use of its own accord. The default
10349 value is .vcg.
10350 ZIP
10352 The zip compression and file packaging utility.
10353 ZIP_OVERRIDE_TIMESTAMP
10355 An optional timestamp which overrides the last modification time of
10356 the file when stored inside the Zip archive. This is a tuple of six
10357 values: Year (>= 1980) Month (one-based) Day of month (one-based)
10358 Hours (zero-based) Minutes (zero-based) Seconds (zero-based)
10359 ZIPCOM
10361 The command line used to call the zip utility, or the internal
10362 Python function used to create a zip archive.
10363 ZIPCOMPRESSION
10365 The compression flag from the Python zipfile module used by the
10366 internal Python function to control whether the zip archive is
10367 compressed or not. The default value is zipfile.ZIP_DEFLATED, which
10368 creates a compressed zip archive. This value has no effect if the
10369 zipfile module is unavailable.
10370 ZIPCOMSTR
10372 The string displayed when archiving files using the zip utility. If
10373 this is not set, then $ZIPCOM (the command line or internal Python
10374 function) is displayed.
10375 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
10377 ZIPFLAGS
10379 General options passed to the zip utility.
10380 ZIPROOT
10382 An optional zip root directory (default empty). The filenames
10383 stored in the zip file will be relative to this directory, if
10384 given. Otherwise the filenames are relative to the current
10385 directory of the command. For instance:
10386 env = Environment()
10388 env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
10389 will produce a zip file foo.zip containing a file with the name
10391 subdir2/file1 rather than subdir1/subdir2/file1.
10392 ZIPSUFFIX
10394 The suffix used for zip file names.
10395 Configure Contexts
10397 SCons supports a configure context, an integrated mechanism similar to
10398 the various AC_CHECK macros in GNU Autoconf for testing the existence
10399 of external items needed for the build, such as C header files,
10400 libraries, etc. The mechanism is portable across platforms.
10401 scons does not maintain an explicit cache of the tested values (this is
10403 different than Autoconf), but uses its normal dependency tracking to
10404 keep the checked values up to date. However, users may override this
10405 behaviour with the --config command line option.
10406 Configure(env, [custom_tests, conf_dir, log_file, config_h, clean,
10408 help]), env.Configure([custom_tests, conf_dir, log_file, config_h,
10409 clean, help])
10410 Create a configure context, which tracks information discovered
10411 while running tests. The context includes a local construction
10412 environment (available as context.env) which is used when running
10413 the tests and which can be updated with the check results. Only one
10414 context may be active at a time (since 4.0, scons will raise an
10415 exception on an attempt to create a new context when there is an
10416 active context), but a new context can be created after the active
10417 one is completed. For the global function form, the required env
10418 describes the initial values for the context's local construction
10419 environment; for the construction environment method form the
10420 instance provides the values.
10421 custom_tests specifies a dictionary containing custom tests (see
10423 the section on custom tests below). The default value is None,
10424 meaning no custom tests are added to the configure context.
10425 conf_dir specifies a directory where the test cases are built. This
10428 directory is not used for building normal targets. The default
10429 value is “#/.sconf_temp”.
10430 log_file specifies a file which collects the output from commands
10433 that are executed to check for the existence of header files,
10434 libraries, etc. The default is “#/config.log”. If you are using the
10435 VariantDir function, you may want to specify a subdirectory under
10436 your variant directory.
10437 config_h specifies a C header file where the results of tests will
10440 be written. The results will consist of lines like #define
10441 HAVE_STDIO_H, #define HAVE_LIBM, etc. Customarily, the name chosen
10442 is “config.h”. The default is to not write a config_h file. You can
10443 specify the same config_h file in multiple calls to Configure, in
10444 which case SCons will concatenate all results in the specified
10445 file. Note that SCons uses its normal dependency checking to decide
10446 if it's necessary to rebuild the specified config_h file. This
10447 means that the file is not necessarily re-built each time scons is
10448 run, but is only rebuilt if its contents will have changed and some
10449 target that depends on the config_h file is being built.
10450 The clean and help arguments can be used to suppress execution of
10452 the configuration tests when the -c/--clean or -H/-h/--help options
10453 are used, respectively. The default behavior is always to execute
10454 configure context tests, since the results of the tests may affect
10455 the list of targets to be cleaned or the help text. If the
10456 configure tests do not affect these, then you may add the
10457 clean=False or help=False arguments (or both) to avoid unnecessary
10458 test execution.
10459 SConf.Finish(context), context.Finish()
10461 This method must be called after configuration is done. Though
10462 required, this is not enforced except if Configure is called again
10463 while there is still an active context, in which case an exception
10464 is raised. Finish returns the environment as modified during the
10465 course of running the configuration checks. After this method is
10466 called, no further checks can be performed with this configuration
10467 context. However, you can create a new configure context to perform
10468 additional checks.
10469 Example of a typical Configure usage:
10471 env = Environment()
10473 conf = Configure(env)
10474 if not conf.CheckCHeader("math.h"):
10475 print("We really need math.h!")
10476 Exit(1)
10477 if conf.CheckLibWithHeader("qt", "qapp.h", "c++", "QApplication qapp(0,0);"):
10478 # do stuff for qt - usage, e.g.
10479 conf.env.Append(CPPDEFINES="WITH_QT")
10480 env = conf.Finish()
10481 A configure context has the following predefined methods which can be
10483 used to perform checks. Where language is a required or optional
10484 parameter, the choice can currently be C or C++. The spellings accepted
10485 for C are “C” or “c”; for C++ the value can be “CXX”, “cxx”, “C++” or
10486 “c++”.
10487 SConf.CheckHeader(context, header, [include_quotes, language]),
10489 context.CheckHeader(header, [include_quotes, language])
10490 Checks if header is usable in the specified language. header may
10491 be a list, in which case the last item in the list is the header
10492 file to be checked, and the previous list items are header files
10493 whose #include lines should precede the header line being checked
10494 for. The optional argument include_quotes must be a two character
10495 string, where the first character denotes the opening quote and the
10496 second character denotes the closing quote. By default, both
10497 characters are " (double quote). The optional argument language
10498 should be either C or C++ and selects the compiler to be used for
10499 the check. Returns a boolean indicating success or failure.
10500 SConf.CheckCHeader(context, header, [include_quotes]),
10502 context.CheckCHeader(header, [include_quotes])
10503 This is a wrapper around SConf.CheckHeader which checks if header
10504 is usable in the C language. header may be a list, in which case
10505 the last item in the list is the header file to be checked, and the
10506 previous list items are header files whose #include lines should
10507 precede the header line being checked for. The optional argument
10508 include_quotes must be a two character string, where the first
10509 character denotes the opening quote and the second character
10510 denotes the closing quote. By default, both characters are "
10511 (double quote). Returns a boolean indicating success or failure.
10512 SConf.CheckCXXHeader(context, header, [include_quotes]),
10514 context.CheckCXXHeader(header, [include_quotes])
10515 This is a wrapper around SConf.CheckHeader which checks if header
10516 is usable in the C++ language. header may be a list, in which case
10517 the last item in the list is the header file to be checked, and the
10518 previous list items are header files whose #include lines should
10519 precede the header line being checked for. The optional argument
10520 include_quotes must be a two character string, where the first
10521 character denotes the opening quote and the second character
10522 denotes the closing quote. By default, both characters are "
10523 (double quote). Returns a boolean indicating success or failure.
10524 SConf.CheckFunc(context, function_name, [header, language]),
10526 context.CheckFunc(function_name, [header, language])
10527 Checks if the specified C or C++ library function is available
10528 based on the context's local environment settings (that is, using
10529 the values of CFLAGS, CPPFLAGS, LIBS or other relevant construction
10530 variables).
10531 function_name is the name of the function to check for. The
10534 optional header argument is a string that will be placed at the top
10535 of the test file that will be compiled to check if the function
10536 exists; the default is:
10537 #ifdef __cplusplus
10539 extern "C"
10540 #endif
10541 char function_name();
10542 Returns an empty string on success, a string containing an error
10544 message on failure.
10545 SConf.CheckLib(context, [library, symbol, header, language,
10547 autoadd=True]), context.CheckLib([library, symbol, header, language,
10548 autoadd=True])
10549 Checks if library provides symbol. If autoadd is true (the default)
10550 and the library provides the specified symbol, appends the library
10551 to the LIBS construction variable library may also be None (the
10552 default), in which case symbol is checked with the current LIBS
10553 variable, or a list of library names, in which case each library in
10554 the list will be checked for symbol. If symbol is not set or is
10555 None, then SConf.CheckLib just checks if you can link against the
10556 specified library. Note though it is legal syntax, it would not be
10557 very useful to call this method with library and symbol both
10558 omitted or None. Returns a boolean indicating success or failure.
10559 SConf.CheckLibWithHeader(context, library, header, language, [call,
10561 autoadd=True]), context.CheckLibWithHeader(library, header, language,
10562 [call, autoadd=True])
10563 Provides a more sophisticated way to check against libraries then
10564 the SConf.CheckLib call. library specifies the library or a list
10565 of libraries to check. header specifies a header to check for.
10566 header may be a list, in which case the last item in the list is
10567 the header file to be checked, and the previous list items are
10568 header files whose #include lines should precede the header line
10569 being checked for. call can be any valid expression (with a
10570 trailing ';'). If call is not set, the default simply checks that
10571 you can link against the specified library. autoadd (default true)
10572 specifies whether to add the library to the environment if the
10573 check succeeds. Returns a boolean indicating success or failure.
10574 SConf.CheckType(context, type_name, [includes, language]),
10576 context.CheckType(type_name, [includes, language])
10577 Checks for the existence of a type defined by typedef. type_name
10578 specifies the typedef name to check for. includes is a string
10579 containing one or more #include lines that will be inserted into
10580 the program that will be run to test for the existence of the type.
10581 Example:
10582 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
10584 Returns an empty string on success, a string containing an error
10586 message on failure.
10587 SConf.CheckCC(context), context.CheckCC()
10589 Checks whether the C compiler (as defined by the CC construction
10590 variable) works by trying to compile a small source file. Returns a
10591 boolean indicating success or failure.
10592 By default, SCons only detects if there is a program with the
10594 correct name, not if it is a functioning compiler.
10595 This uses the exact same command as the one used by the object
10597 builder for C source files, so it can be used to detect if a
10598 particular compiler flag works or not.
10599 SConf.CheckCXX(context), context.CheckCXX()
10601 Checks whether the C++ compiler (as defined by the CXX construction
10602 variable) works by trying to compile a small source file. By
10603 default, SCons only detects if there is a program with the correct
10604 name, not if it is a functioning compiler. Returns a boolean
10605 indicating success or failure.
10606 This uses the exact same command as the one used by the object
10608 builder for C++ source files, so it can be used to detect if a
10609 particular compiler flag works or not.
10610 SConf.CheckSHCC(context), context.CheckSHCC()
10612 Checks whether the shared-object C compiler (as defined by the SHCC
10613 construction variable) works by trying to compile a small source
10614 file. By default, SCons only detects if there is a program with the
10615 correct name, not if it is a functioning compiler. Returns a
10616 boolean indicating success or failure.
10617 This uses the exact same command as the one used by the object
10619 builder for C source file, so it can be used to detect if a
10620 particular compiler flag works or not. This does not check whether
10621 the object code can be used to build a shared library, only that
10622 the compilation (not link) succeeds.
10623 SConf.CheckSHCXX(context), context.CheckSHCXX()
10625 Checks whether the shared-object C++ compiler (as defined by the
10626 SHCXX construction variable) works by trying to compile a small
10627 source file. By default, SCons only detects if there is a program
10628 with the correct name, not if it is a functioning compiler. Returns
10629 a boolean indicating success or failure.
10630 This uses the exact same command as the one used by the object
10632 builder for C++ source files, so it can be used to detect if a
10633 particular compiler flag works or not. This does not check whether
10634 the object code can be used to build a shared library, only that
10635 the compilation (not link) succeeds.
10636 SConf.CheckTypeSize(context, type_name, [header, language, expect]),
10638 context.CheckTypeSize(type_name, [header, language, expect])
10639 Checks for the size of a type defined by typedef. type_name
10640 specifies the typedef name to check for. The optional header
10641 argument is a string that will be placed at the top of the test
10642 file that will be compiled to check if the type exists; the default
10643 is empty. If the optional expect, is supplied, it should be an
10644 integer size; CheckTypeSize will fail unless type_name is actually
10645 that size. Returns the size in bytes, or zero if the type was not
10646 found (or if the size did not match expect).
10647 For example,
10649 CheckTypeSize('short', expect=2)
10651 will return the size 2 only if short is actually two bytes.
10653 SConf.CheckDeclaration(context, symbol, [includes, language]),
10655 context.CheckDeclaration(symbol, [includes, language])
10656 Checks if the specified symbol is declared. includes is a string
10657 containing one or more #include lines that will be inserted into
10658 the program that will be run to test for the existence of the
10659 symbol. Returns a boolean indicating success or failure.
10660 SConf.Define(context, symbol, [value, comment]), context.Define(symbol,
10662 [value, comment])
10663 This function does not check for anything, but defines a
10664 preprocessor symbol that will be added to the configuration header
10665 file. It is the equivalent of AC_DEFINE, and defines the symbol
10666 name with the optional value and the optional comment comment.
10667 Define Examples:
10669 env = Environment()
10671 conf = Configure(env)
10672 # Puts the following line in the config header file:
10674 # #define A_SYMBOL
10675 conf.Define("A_SYMBOL")
10676 # Puts the following line in the config header file:
10678 # #define A_SYMBOL 1
10679 conf.Define("A_SYMBOL", 1)
10680 Be careful about quoting string values, though:
10682 env = Environment()
10684 conf = Configure(env)
10685 # Puts the following line in the config header file:
10687 # #define A_SYMBOL YA
10688 conf.Define("A_SYMBOL", "YA")
10689 # Puts the following line in the config header file:
10691 # #define A_SYMBOL "YA"
10692 conf.Define("A_SYMBOL", '"YA"')
10693 For comment:
10695 env = Environment()
10697 conf = Configure(env)
10698 # Puts the following lines in the config header file:
10700 # /* Set to 1 if you have a symbol */
10701 # #define A_SYMBOL 1
10702 conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol")
10703 You can define your own custom checks in addition to the predefined
10705 checks. You pass a dictionary of these to the Configure function as the
10706 custom_tests argument. This dictionary maps the names of the checks to
10707 the user defined Python callables (either Python functions or class
10708 instances implementing a __call__ method). Each custom check will be
10709 called with a first argument of a CheckContext, instance followed by
10710 the arguments, which must be supplied by the user of the check. A
10711 CheckContext instance defines the following methods:
10712 context.Message(text)
10714 Displays a message, as an indicator of progess. text will be
10715 displayed, e.g. Checking for library X.... Usually called before
10716 the check is started.
10717 context.Result(res)
10719 Displays a “result” message, as an indicator of progress. res can
10720 be either an integer or a string. If an integer, displays yes (if
10721 res evaluates True) or no (if res evaluates False). If a string, it
10722 is displayed as-is. Usually called after the check has completed.
10723 context.TryCompile(text, extension='')
10725 Checks if a file with the specified extension (e.g. '.c')
10726 containing text can be compiled using the environment's Object
10727 builder. Returns a boolean indicating success or failure.
10728 context.TryLink(text, extension='')
10730 Checks, if a file with the specified extension (e.g. '.c')
10731 containing text can be compiled using the environment's Program
10732 builder. Returns a boolean indicating success or failure.
10733 context.TryRun(text, extension='')
10735 Checks if a file with the specified extension (e.g. '.c')
10736 containing text can be compiled using the environment's Program
10737 builder. On success, the program is run. If the program executes
10738 successfully (that is, its return status is 0), a tuple (1,
10739 outputStr) is returned, where outputStr is the standard output of
10740 the program. If the program fails execution (its return status is
10741 non-zero), then (0, '') is returned.
10742 context.TryAction(action, [text, extension=''])
10744 Checks if the specified action with an optional source file
10745 (contents text, extension extension) can be executed. action may
10746 be anything which can be converted to a scons Action. On success,
10747 (1, outputStr) is returned, where outputStr is the content of the
10748 target file. On failure (0, '') is returned.
10749 context.TryBuild(builder[, text, extension=''])
10751 Low level implementation for testing specific builds; the methods
10752 above are based on this method. Given the Builder instance builder
10753 and the optional text of a source file with optional extension,
10754 returns a boolean indicating success or failure. In addition,
10755 context.lastTarget is set to the build target node if the build was
10756 successful.
10757 Example of implementing and using custom tests:
10759 def CheckQt(context, qtdir):
10761 context.Message( 'Checking for qt ...' )
10762 lastLIBS = context.env['LIBS']
10763 lastLIBPATH = context.env['LIBPATH']
10764 lastCPPPATH= context.env['CPPPATH']
10765 context.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include')
10766 ret = context.TryLink("""
10767 #include <qapp.h>
10768 int main(int argc, char **argv) {
10769 QApplication qapp(argc, argv);
10770 return 0;
10771 }
10772 """)
10773 if not ret:
10774 context.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
10775 context.Result( ret )
10776 return ret
10777 env = Environment()
10779 conf = Configure(env, custom_tests={'CheckQt': CheckQt})
10780 if not conf.CheckQt('/usr/lib/qt'):
10781 print('We really need qt!')
10782 Exit(1)
10783 env = conf.Finish()
10784 Command-Line Construction Variables
10786 Often when building software, some variables need to be specified at
10787 build time. For example, libraries needed for the build may be in
10788 non-standard locations, or site-specific compiler options may need to
10789 be passed to the compiler. SCons provides a Variables object to
10790 support overriding construction variables with values obtained from
10791 various sources, often from the command line:
10792 scons VARIABLE=foo
10794 The variable values can also be specified in a configuration file or an
10796 SConscript file.
10797 To obtain the object for manipulating values, call the Variables
10799 function:
10800 Variables([files, [args]])
10802 If files is a file or list of files, those are executed as Python
10803 scripts, and the values of (global) Python variables set in those
10804 files are added as construction variables in the Default
10805 Environment. If no files are specified, or the files argument is
10806 None, then no files will be read (supplying None is necessary if
10807 there are no files but you want to specify args as a positional
10808 argument).
10809 The following example file contents could be used to set an
10811 alternative C compiler:
10812 CC = 'my_cc'
10814 If args is specified, it is a dictionary of values that will
10816 override anything read from files. This is primarily intended to
10817 pass the ARGUMENTS dictionary that holds variables specified on the
10818 command line. Example:
10819 vars = Variables('custom.py')
10821 vars = Variables('overrides.py', ARGUMENTS)
10822 vars = Variables(None, {FOO:'expansion', BAR:7})
10823 Calling Variables with no arguments is equivalent to:
10825 vars = Variables(files=None, args=ARGUMENTS)
10827 Note that since the variables are eventually added as construction
10829 variables, you should choose variable names which do not
10830 unintentionally change pre-defined construction variables that your
10831 project will make use of (see the section called “Construction
10832 Variables”).
10833 Variables objects have the following methods:
10835 vars.Add(key, [help, default, validator, converter])
10837 Add a customizable construction variable to the Variables object.
10838 key is the name of the variable. help is the help text for the
10839 variable. default is the default value of the variable; if the
10840 default value is None and there is no explicit value specified, the
10841 construction variable will not be added to the construction
10842 environment. If set, validator is called to validate the value of
10843 the variable. A function supplied as a validator shall accept
10844 arguments: key, value, and env. The recommended way to handle an
10845 invalid value is to raise an exception (see example below). If set,
10846 converter is called to convert the value before putting it in the
10847 environment, and should take either a value, or the value and
10848 environment, as parameters. The converter function must return a
10849 value, which will be converted into a string before being validated
10850 by the validator (if any) and then added to the construction
10851 environment.
10852 Examples:
10854 vars.Add('CC', help='The C compiler')
10856 def valid_color(key, val, env):
10858 if not val in ['red', 'blue', 'yellow']:
10859 raise Exception("Invalid color value '%s'" % val)
10860 vars.Add('COLOR', validator=valid_color)
10862 vars.AddVariables(args)
10864 A convenience method that adds multiple customizable construction
10865 variables to a Variables object in one call; equivalent to calling
10866 Add multiple times. The args are tuples (or lists) that contain the
10867 arguments for an individual call to the Add method. Since tuples
10868 are not Python mappings, the arguments cannot use the keyword form,
10869 but rather are positional arguments as documented for Add: a
10870 required name, the rest optional but must be in the specified in
10871 order if used.
10872 opt.AddVariables(
10874 ("debug", "", 0),
10875 ("CC", "The C compiler"),
10876 ("VALIDATE", "An option for testing validation", "notset", validator, None),
10877 )
10878 vars.Update(env, [args])
10880 Update a construction environment env with the customized
10881 construction variables . Any specified variables that are not
10882 configured for the Variables object will be saved and may be
10883 retrieved using the UnknownVariables method, below.
10884 Normally this method is not called directly, but rather invoked
10886 indirectly by passing the Variables object to the Environment
10887 function:
10888 env = Environment(variables=vars)
10890 vars.UnknownVariables()
10892 Returns a dictionary containing any variables that were specified
10893 either in the files or the dictionary with which the Variables
10894 object was initialized, but for which the Variables object was not
10895 configured.
10896 env = Environment(variables=vars)
10898 for key, value in vars.UnknownVariables():
10899 print("unknown variable: %s=%s" % (key, value))
10900 vars.Save(filename, env)
10902 Save the currently set variables into a script file named by
10903 filename that can be used on the next invocation to automatically
10904 load the current settings. This method combined with the Variables
10905 method can be used to support caching of variables between runs.
10906 env = Environment()
10908 vars = Variables(['variables.cache', 'custom.py'])
10909 vars.Add(...)
10910 vars.Update(env)
10911 vars.Save('variables.cache', env)
10912 vars.GenerateHelpText(env, [sort])
10914 Generate help text documenting the customizable construction
10915 variables, suitable for passing in to the Help function. env is
10916 the construction environment that will be used to get the actual
10917 values of the customizable variables. If the (optional) value of
10918 sort is callable, it is used as a comparison function to determine
10919 how to sort the added variables. This function must accept two
10920 arguments, compare them, and return a negative integer if the first
10921 is less-than the second, zero for equality, or a positive integer
10922 for greater-than. Optionally a Boolean value of True for sort will
10923 cause a standard alphabetical sort to be performed.
10924 Help(vars.GenerateHelpText(env))
10926 def cmp(a, b):
10928 return (a > b) - (a < b)
10929 Help(vars.GenerateHelpText(env, sort=cmp))
10931 vars.FormatVariableHelpText(env, opt, help, default, actual)
10933 Returns a formatted string containing the printable help text for
10934 one option. It is normally not called directly, but is called by
10935 the GenerateHelpText method to create the returned help text. It
10936 may be overridden with your own function that takes the arguments
10937 specified above and returns a string of help text formatted to your
10938 liking. Note that GenerateHelpText will not put any blank lines or
10939 extra characters in between the entries, so you must add those
10940 characters to the returned string if you want the entries
10941 separated.
10942 def my_format(env, opt, help, default, actual):
10944 fmt = "\n%s: default=%s actual=%s (%s)\n"
10945 return fmt % (opt, default, actual, help)
10946 vars.FormatVariableHelpText = my_format
10947 To make it more convenient to work with customizable Variables, scons
10949 provides a number of functions that make it easy to set up various
10950 types of Variables. Each of these return a tuple ready to be passed to
10951 the Add or AddVariables method:
10952 BoolVariable(key, help, default)
10954 Returns a tuple of arguments to set up a Boolean option. The option
10955 will use the specified name key, have a default value of default,
10956 and help will form the descriptive part of the help text. The
10957 option will interpret the values y, yes, t, true, 1, on and all as
10958 true, and the values n, no, f, false, 0, off and none as false.
10959 EnumVariable(key, help, default, allowed_values, [map, ignorecase])
10961 Returns a tuple of arguments to set up an option whose value may be
10962 one of a specified list of legal enumerated values. The option will
10963 use the specified name key, have a default value of default, and
10964 help will form the descriptive part of the help text. The option
10965 will only support those values in the allowed_values list. The
10966 optional map argument is a dictionary that can be used to convert
10967 input values into specific legal values in the allowed_values list.
10968 If the value of ignore_case is 0 (the default), then the values are
10969 case-sensitive. If the value of ignore_case is 1, then values will
10970 be matched case-insensitively. If the value of ignore_case is 2,
10971 then values will be matched case-insensitively, and all input
10972 values will be converted to lower case.
10973 ListVariable(key, help, default, names, [map])
10975 Returns a tuple of arguments to set up an option whose value may be
10976 one or more of a specified list of legal enumerated values. The
10977 option will use the specified name key, have a default value of
10978 default, and help will form the descriptive part of the help text.
10979 The option will only accept the values “all”, “none”, or the values
10980 in the names list. More than one value may be specified, separated
10981 by commas. The default may be a string of comma-separated default
10982 values, or a list of the default values. The optional map argument
10983 is a dictionary that can be used to convert input values into
10984 specific legal values in the names list. (Note that the additional
10985 values accepted through the use of a map are not reflected in the
10986 generated help message).
10987 PackageVariable(key, help, default)
10989 Returns a tuple of arguments to set up an option whose value is a
10990 path name of a package that may be enabled, disabled or given an
10991 explicit path name. The option will use the specified name key,
10992 have a default value of default, and help will form the descriptive
10993 part of the help text. The option will support the values yes,
10994 true, on, enable or search, in which case the specified default
10995 will be used, or the option may be set to an arbitrary string
10996 (typically the path name to a package that is being enabled). The
10997 option will also support the values no, false, off or disable to
10998 disable use of the specified option.
10999 PathVariable(key, help, default, [validator])
11001 Returns a tuple of arguments to set up an option whose value is
11002 expected to be a path name. The option will use the specified name
11003 key, have a default value of default, and help will form the
11004 descriptive part of the help text. An additional validator may be
11005 specified that will be called to verify that the specified path is
11006 acceptable. SCons supplies the following ready-made validators:
11007 PathVariable.PathExists
11009 Verify that the specified path exists (this the default
11010 behavior if no validator is supplied).
11011 PathVariable.PathIsFile
11013 Verify that the specified path exists and is a regular file.
11014 PathVariable.PathIsDir
11016 Verify that the specified path exists and is a directory.
11017 PathVariable.PathIsDirCreate
11019 Verify that the specified path exists and is a directory; if it
11020 does not exist, create the directory.
11021 PathVariable.PathAccept
11023 Accept the specific path name argument without validation,
11024 suitable for when you want your users to be able to specify a
11025 directory path that will be created as part of the build
11026 process, for example.
11027 You may supply your own validator function, which must accept three
11029 arguments (key, the name of the variable to be set; val, the
11030 specified value being checked; and env, the construction
11031 environment) and should raise an exception if the specified value
11032 is not acceptable.
11033 These functions make it convenient to create a number of variables with
11035 consistent behavior in a single call to the AddVariables method:
11036 vars.AddVariables(
11038 BoolVariable(
11039 "warnings",
11040 help="compilation with -Wall and similar",
11041 default=1,
11042 ),
11043 EnumVariable(
11044 "debug",
11045 help="debug output and symbols",
11046 default="no",
11047 allowed_values=("yes", "no", "full"),
11048 map={},
11049 ignorecase=0, # case sensitive
11050 ),
11051 ListVariable(
11052 "shared",
11053 help="libraries to build as shared libraries",
11054 default="all",
11055 names=list_of_libs,
11056 ),
11057 PackageVariable(
11058 "x11",
11059 help="use X11 installed here (yes = search some places)",
11060 default="yes",
11061 ),
11062 PathVariable(
11063 "qtdir",
11064 help="where the root of Qt is installed",
11065 default=qtdir),
11066 PathVariable(
11067 "foopath",
11068 help="where the foo library is installed",
11069 default=foopath,
11070 validator=PathVariable.PathIsDir,
11071 ),
11072 )
11073 File and Directory Nodes
11075 The File and Dir functions/methods return File and Directory Nodes,
11076 respectively. Such nodes are Python objects with several user-visible
11077 attributes and methods that are often useful to access in SConscript
11078 files:
11079 n.path
11081 The build path of the given file or directory. This path is
11082 relative to the top-level directory (where the SConstruct file is
11083 found). The build path is the same as the source path if
11084 variant_dir is not being used.
11085 n.abspath
11087 The absolute build path of the given file or directory.
11088 n.srcnode()
11090 The srcnode method returns another File or Directory Node
11091 representing the source path of the given File or Directory Node.
11092 For example:
11094 # Get the current build dir's path, relative to top.
11096 Dir('.').path
11097 # Current dir's absolute path
11098 Dir('.').abspath
11099 # Next line is always '.', because it is the top dir's path relative to itself.
11100 Dir('#.').path
11101 File('foo.c').srcnode().path # source path of the given source file.
11102 # Builders also return File objects:
11104 foo = env.Program('foo.c')
11105 print("foo will be built in", foo.path)
11106 File and Directory Node objects have methods to create File and
11108 Directory Nodes relative to the original Node.
11109 If the object is a Directory Node, these methods will place the the new
11111 Node within the directory the Node represents:
11112 d.Dir(name)
11114 Returns a directory Node for a subdirectory of d named name.
11115 d.File(name)
11117 Returns a file Node for a file within d named name.
11118 d.Entry(name)
11120 Returns an unresolved Node within d named name.
11121 If the object is a File Node, these methods will place the the new Node
11123 in the same directory as the one the Node represents:
11124 f.Dir(name)
11126 Returns a directory named name within the parent directory of f.
11127 f.File(name)
11129 Returns a file named name within the parent directory of f.
11130 f.Entry(name)
11132 Returns an unresolved Node named name within the parent directory
11133 of f.
11134 For example:
11136 # Get a Node for a file within a directory
11138 incl = Dir('include')
11139 f = incl.File('header.h')
11140 # Get a Node for a subdirectory within a directory
11142 dist = Dir('project-3.2.1')
11143 src = dist.Dir('src')
11144 # Get a Node for a file in the same directory
11146 cfile = File('sample.c')
11147 hfile = cfile.File('sample.h')
11148 # Combined example
11150 docs = Dir('docs')
11151 html = docs.Dir('html')
11152 index = html.File('index.html')
11153 css = index.File('app.css')
11154
11156 Builder Objects
11157 scons can be extended to build different types of targets by adding new
11158 Builder objects to a construction environment. In general, you should
11159 only need to add a new Builder object when you want to build a new type
11160 of file or other external target. If you just want to invoke a
11161 different compiler or other tool to build Program, Object, Library, or
11162 any other type of output file for which scons already has an existing
11163 Builder, it is generally much easier to use those existing Builders in
11164 a construction environment that sets the appropriate construction
11165 variables (CC, LINK, etc.).
11166 Builder objects are created using the Builder factory function. The
11168 Builder function accepts the following keyword arguments:
11169 action
11171 The command line string used to build the target from the source.
11172 action can also be: a list of strings representing the command to
11173 be executed and its arguments (suitable for enclosing white space
11174 in an argument), a dictionary mapping source file name suffixes to
11175 any combination of command line strings (if the builder should
11176 accept multiple source file extensions), a Python function; an
11177 Action object (see the next section); or a list of any of the
11178 above.
11179 An action function takes three arguments:
11181 source - a list of source nodes;.
11182 target - a list of target nodes;.
11183 env - the construction environment.
11184 The action and generator arguments must not both be used for the
11185 same Builder.
11186 prefix
11188 The prefix that will be prepended to the target file name. prefix
11189 may be:
11190 • a string
11192 • a callable object - a function or other callable that takes two
11194 arguments (a construction environment and a list of sources)
11195 and returns a prefix
11196 • a dictionary - specifies a mapping from a specific source
11198 suffix (of the first source specified) to a corresponding
11199 target prefix. Both the source suffix and target prefix
11200 specifications may use environment variable substitution, and
11201 the target prefix (the 'value' entries in the dictionary) may
11202 also be a callable object. The default target prefix may be
11203 indicated by a dictionary entry with a key value of None.
11204 b = Builder("build_it < $SOURCE > $TARGET",
11206 prefix = "file-")
11207 def gen_prefix(env, sources):
11209 return "file-" + env['PLATFORM'] + '-'
11210 b = Builder("build_it < $SOURCE > $TARGET",
11211 prefix = gen_prefix)
11212 b = Builder("build_it < $SOURCE > $TARGET",
11214 suffix = { None: "file-",
11215 "$SRC_SFX_A": gen_prefix })
11216 suffix
11218 The suffix that will be appended to the target file name. This may
11219 be specified in the same manner as the prefix above. If the suffix
11220 is a string, then scons will append a '.' to the beginning of the
11221 suffix if it's not already there. The string returned by callable
11222 object (or obtained from the dictionary) is untouched and must
11223 append its own '.' to the beginning if one is desired.
11224 b = Builder("build_it < $SOURCE > $TARGET"
11226 suffix = "-file")
11227 def gen_suffix(env, sources):
11229 return "." + env['PLATFORM'] + "-file"
11230 b = Builder("build_it < $SOURCE > $TARGET",
11231 suffix = gen_suffix)
11232 b = Builder("build_it < $SOURCE > $TARGET",
11234 suffix = { None: ".sfx1",
11235 "$SRC_SFX_A": gen_suffix })
11236 ensure_suffix
11238 When set to any true value, causes scons to add the target suffix
11239 specified by the suffix keyword to any target strings that have a
11240 different suffix. (The default behavior is to leave untouched any
11241 target file name that looks like it already has any suffix.)
11242 b1 = Builder("build_it < $SOURCE > $TARGET"
11244 suffix = ".out")
11245 b2 = Builder("build_it < $SOURCE > $TARGET"
11246 suffix = ".out",
11247 ensure_suffix)
11248 env = Environment()
11249 env['BUILDERS']['B1'] = b1
11250 env['BUILDERS']['B2'] = b2
11251 # Builds "foo.txt" because ensure_suffix is not set.
11253 env.B1('foo.txt', 'foo.in')
11254 # Builds "bar.txt.out" because ensure_suffix is set.
11256 env.B2('bar.txt', 'bar.in')
11257 src_suffix
11259 The expected source file name suffix. This may be a string or a
11260 list of strings.
11261 target_scanner
11263 A Scanner object that will be invoked to find implicit dependencies
11264 for this target file. This keyword argument should be used for
11265 Scanner objects that find implicit dependencies based only on the
11266 target file and the construction environment, not for implicit
11267 dependencies based on source files. See the section called “Scanner
11268 Objects” for information about creating Scanner objects.
11269 source_scanner
11271 A Scanner object that will be invoked to find implicit dependencies
11272 in any source files used to build this target file. This is where
11273 you would specify a scanner to find things like #include lines in
11274 source files. The pre-built DirScanner Scanner object may be used
11275 to indicate that this Builder should scan directory trees for
11276 on-disk changes to files that scons does not know about from other
11277 Builder or function calls. See the section called “Scanner Objects”
11278 for information about creating your own Scanner objects.
11279 target_factory
11281 A factory function that the Builder will use to turn any targets
11282 specified as strings into SCons Nodes. By default, SCons assumes
11283 that all targets are files. Other useful target_factory values
11284 include Dir, for when a Builder creates a directory target, and
11285 Entry, for when a Builder can create either a file or directory
11286 target.
11287 Example:
11289 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
11291 env = Environment()
11292 env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder})
11293 env.MakeDirectory('new_directory', [])
11294 Note that the call to this MakeDirectory Builder needs to specify
11296 an empty source list to make the string represent the builder's
11297 target; without that, it would assume the argument is the source,
11298 and would try to deduce the target name from it, which in the
11299 absence of an automatically-added prefix or suffix would lead to a
11300 matching target and source name and a circular dependency.
11301 source_factory
11303 A factory function that the Builder will use to turn any sources
11304 specified as strings into SCons Nodes. By default, SCons assumes
11305 that all source are files. Other useful source_factory values
11306 include Dir, for when a Builder uses a directory as a source, and
11307 Entry, for when a Builder can use files or directories (or both) as
11308 sources.
11309 Example:
11311 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
11313 env = Environment()
11314 env.Append(BUILDERS={'Collect': CollectBuilder})
11315 env.Collect('archive', ['directory_name', 'file_name'])
11316 emitter
11318 A function or list of functions to manipulate the target and source
11319 lists before dependencies are established and the target(s) are
11320 actually built. emitter can also be a string containing a
11321 construction variable to expand to an emitter function or list of
11322 functions, or a dictionary mapping source file suffixes to emitter
11323 functions. (Only the suffix of the first source file is used to
11324 select the actual emitter function from an emitter dictionary.)
11325 An emitter function takes three arguments:
11327 source - a list of source nodes.
11328 target - a list of target nodes.
11329 env - the construction environment.
11330 An emitter must return a tuple containing two lists, the list of
11331 targets to be built by this builder, and the list of sources for
11332 this builder.
11333 Example:
11335 def e(target, source, env):
11337 return (target + ['foo.foo'], source + ['foo.src'])
11338 # Simple association of an emitter function with a Builder.
11340 b = Builder("my_build < $TARGET > $SOURCE",
11341 emitter = e)
11342 def e2(target, source, env):
11344 return (target + ['bar.foo'], source + ['bar.src'])
11345 # Simple association of a list of emitter functions with a Builder.
11347 b = Builder("my_build < $TARGET > $SOURCE",
11348 emitter = [e, e2])
11349 # Calling an emitter function through a construction variable.
11351 env = Environment(MY_EMITTER=e)
11352 b = Builder("my_build < $TARGET > $SOURCE",
11353 emitter='$MY_EMITTER')
11354 # Calling a list of emitter functions through a construction variable.
11356 env = Environment(EMITTER_LIST=[e, e2])
11357 b = Builder("my_build < $TARGET > $SOURCE",
11358 emitter='$EMITTER_LIST')
11359 # Associating multiple emitters with different file
11361 # suffixes using a dictionary.
11362 def e_suf1(target, source, env):
11363 return (target + ['another_target_file'], source)
11364 def e_suf2(target, source, env):
11365 return (target, source + ['another_source_file'])
11366 b = Builder("my_build < $TARGET > $SOURCE",
11367 emitter={'.suf1' : e_suf1,
11368 '.suf2' : e_suf2})
11369 multi
11371 Specifies whether this builder is allowed to be called multiple
11372 times for the same target file(s). The default is 0, which means
11373 the builder can not be called multiple times for the same target
11374 file(s). Calling a builder multiple times for the same target
11375 simply adds additional source files to the target; it is not
11376 allowed to change the environment associated with the target,
11377 specify additional environment overrides, or associate a different
11378 builder with the target.
11379 env
11381 A construction environment that can be used to fetch source code
11382 using this Builder. (Note that this environment is not used for
11383 normal builds of normal target files, which use the environment
11384 that was used to call the Builder for the target file.)
11385 generator
11387 A function that returns a list of actions that will be executed to
11388 build the target(s) from the source(s). The returned action(s) may
11389 be an Action object, or anything that can be converted into an
11390 Action object (see the next section).
11391 The generator function takes four arguments:
11393 source - A list of source nodes;.
11394 target - A list of target nodes;.
11395 env - the construction environment.
11396 for_signature -
11397 A Boolean value that specifies
11398 whether the generator is being called
11399 for generating a build signature
11400 (as opposed to actually executing the command).
11401 Example:
11402 def g(source, target, env, for_signature):
11404 return [["gcc", "-c", "-o"] + target + source]
11405 b = Builder(generator=g)
11407 The generator and action arguments must not both be used for the
11409 same Builder.
11410 src_builder
11412 Specifies a builder to use when a source file name suffix does not
11413 match any of the suffixes of the builder. Using this argument
11414 produces a multi-stage builder.
11415 single_source
11417 Specifies that this builder expects exactly one source file per
11418 call. Giving more than one source file without target files results
11419 in implicitly calling the builder multiple times (once for each
11420 source given). Giving multiple source files together with target
11421 files results in a UserError exception.
11422 source_ext_match
11424 When the specified action argument is a dictionary, the default
11425 behavior when a builder is passed multiple source files is to make
11426 sure that the extensions of all the source files match. If it is
11427 legal for this builder to be called with a list of source files
11428 with different extensions, this check can be suppressed by setting
11429 source_ext_match to None or some other non-true value. When
11430 source_ext_match is disable, scons will use the suffix of the first
11431 specified source file to select the appropriate action from the
11432 action dictionary.
11433 In the following example, the setting of source_ext_match prevents
11435 scons from exiting with an error due to the mismatched suffixes of
11436 foo.in and foo.extra.
11437 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
11439 source_ext_match = None)
11440 env = Environment(BUILDERS={'MyBuild':b})
11442 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
11443 env
11445 A construction environment that can be used to fetch source code
11446 using this Builder. (Note that this environment is not used for
11447 normal builds of normal target files, which use the environment
11448 that was used to call the Builder for the target file.)
11449 b = Builder(action="build < $SOURCE > $TARGET")
11451 env = Environment(BUILDERS={'MyBuild' : b})
11452 env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy')
11453 chdir
11455 A directory from which scons will execute the action(s) specified
11456 for this Builder. If the chdir argument is a string or a directory
11457 Node, scons will change to the specified directory. If the chdir is
11458 not a string or Node and is non-zero, then scons will change to the
11459 target file's directory.
11460 Note that scons will not automatically modify its expansion of
11462 construction variables like $TARGET and $SOURCE when using the
11463 chdir keyword argument--that is, the expanded file names will still
11464 be relative to the top-level directory containing the SConstruct
11465 file, and consequently incorrect relative to the chdir directory.
11466 Builders created using chdir keyword argument, will need to use
11467 construction variable expansions like ${TARGET.file} and
11468 ${SOURCE.file} to use just the filename portion of the targets and
11469 source.
11470 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
11472 chdir=1)
11473 env = Environment(BUILDERS={'MyBuild' : b})
11474 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
11475 Warning
11477 Python only keeps one current directory location even if there
11478 are multiple threads. This means that use of the chdir argument
11479 will not work with the SCons -j option, because individual
11480 worker threads spawned by SCons interfere with each other when
11481 they start changing directory.
11482 Any additional keyword arguments supplied when a Builder object is
11484 created (that is, when the Builder function is called) will be set in
11485 the executing construction environment when the Builder object is
11486 called. The canonical example here would be to set a construction
11487 variable to the repository of a source code system.
11488 Any additional keyword arguments supplied when a Builder object is
11490 called will only be associated with the target created by that
11491 particular Builder call (and any other files built as a result of the
11492 call).
11493 These extra keyword arguments are passed to the following functions:
11495 command generator functions, function Actions, and emitter functions.
11496 Action Objects
11498 The Builder function will turn its action keyword argument into an
11499 appropriate internal Action object, as will the Command function. You
11500 can also explicitly create Action objects for passing to Builder, or
11501 other functions that take actions as arguments, by calling the Action
11502 factory function. This may more efficient when multiple Builder objects
11503 need to do the same thing rather than letting each of those Builder
11504 objects create a separate Action object. It also allows more flexible
11505 configuration of an Action object. For example, to control the message
11506 printed when the action is taken you need to create the action object
11507 using Action.
11508 The Action factory function returns an appropriate object for the
11510 action represented by the type of the action argument (the first
11511 positional parmeter):
11512 • If the action argument is already an Action object, the object is
11514 simply returned.
11515 • If the action argument is a string, a command-line Action is
11517 returned. If such a string begins with @, it indicates printing of
11518 the command line is to be suppressed. If the string begins with -
11519 (hyphen), it indicates the exit status from the specified command
11520 is to be ignored, allowing execution to continue even if the
11521 command reports failure:
11522 Action('$CC -c -o $TARGET $SOURCES')
11524 # Doesn't print the line being executed.
11526 Action('@build $TARGET $SOURCES')
11527 # Ignores return value
11529 Action('-build $TARGET $SOURCES')
11530 • If the action argument is a list, then a list of Action objects is
11532 returned. An Action object is created as necessary for each element
11533 in the list. If an element within the list is itself a list, the
11534 internal list is taken as the command and arguments to be executed
11535 via the command line. This allows white space to be enclosed in an
11536 argument rather than taken as a separator by defining a command in
11537 a list within a list:
11538 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
11540 • If the action argument is a Python function, a function Action is
11542 returned. The Python function must accept three keyword arguments:
11543 target -
11544 a Node object representing the target file.
11545 source -
11546 a Node object representing the source file.
11547 env -
11548 the construction environment used for building the target
11549 file.
11550 The target and source arguments may be lists of Node objects if
11551 there is more than one target file or source file. The actual
11552 target and source file name(s) may be retrieved from their Node
11553 objects via the built-in Python str function:
11554 target_file_name = str(target)
11556 source_file_names = [str(x) for x in source]
11557 The function should return 0 or None to indicate a successful build
11559 of the target file(s). The function may raise an exception or
11560 return a non-zero exit status to indicate an unsuccessful build.
11561 def build_it(target=None, source=None, env=None):
11563 # build the target from the source
11564 return 0
11565 a = Action(build_it)
11567 • If the action argument is not one of the above types, None is
11569 returned.
11570 As usual the environment method form env.Action will expand
11572 construction variables in any argument strings, including the action
11573 argument, at the time it is called, using the construction variables in
11574 the construction environment through which it was called. The global
11575 function form Action delays variable expansion until the Action object
11576 is actually used.
11577 The optional second argument to Action is used to control the output
11579 which is printed when the Action is actually performed. If this
11580 parameter is omitted, or if the value is an empty string, a default
11581 output depending on the type of the action is used. For example, a
11582 command-line action will print the executed command. The following
11583 argument types are accepted:
11584 • If the output argument is a function, the function will be called
11586 to obtain a string describing the action being executed. The
11587 function must accept these three keyword arguments:
11588 source -
11589 a Node object representing the source file.
11590 target -
11591 a Node object representing the target file.
11592 env - the construction environment.
11593 The target and source arguments may be lists of Node objects if
11594 there is more than one target file or source file.
11595 • If the output argument is a string, substitution is performed on
11597 the string before it is printed. The string typically contains
11598 variables, notably $TARGET(S) and $SOURCE(S), or consists of just a
11599 single variable, which is optionally defined somewhere else. SCons
11600 itself heavily uses the latter variant.
11601 • If the argument is None, output is suppressed entirely.
11603 Instead of using a positional argument, the cmdstr keyword argument may
11605 be used to specify the output string, or the strfunction keyword
11606 argument may be used to specify a function to return the output string,
11607 Use cmdstr=None to suppress output.
11608 Examples:
11610 def build_it(target, source, env):
11612 # build the target from the source
11613 return 0
11614 def string_it(target, source, env):
11616 return "building '%s' from '%s'" % (target[0], source[0])
11617 # Use a positional argument.
11619 f = Action(build_it, string_it)
11620 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
11621 # Alternatively, use a keyword argument.
11623 f = Action(build_it, strfunction=string_it)
11624 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
11625 # You can provide a configurable variable.
11627 l = Action(build_it, '$STRINGIT')
11628 Any additional positional arguments, if present, may either be
11630 construction variables or lists of construction variables whose values
11631 will be included in the signature of the Action when deciding whether a
11632 target should be rebuilt because the action changed. Such variables may
11633 also be specified using the varlist keyword parameter; both positional
11634 and keyword forms may be present, and will be combined. This is
11635 necessary whenever you want a target to be rebuilt when a specific
11636 construction variable changes. This is not often needed for a string
11637 action, as the expanded variables will normally be part of the command
11638 line, but may be needed if a Python function action uses the value of a
11639 construction variable when generating the command line.
11640 def build_it(target, source, env):
11642 # build the target from the 'XXX' construction variable
11643 with open(target[0], 'w') as f:
11644 f.write(env['XXX'])
11645 return 0
11646 # Use positional arguments.
11648 a = Action(build_it, '$STRINGIT', ['XXX'])
11649 # Alternatively, use a keyword argument.
11651 a = Action(build_it, varlist=['XXX'])
11652 The Action factory function can be passed the following optional
11654 keyword arguments to modify the Action object's behavior:
11655 chdir
11657 Specifies that scons will execute the action after changing to the
11658 specified directory. If the chdir argument is a string or a
11659 directory Node, scons will change to the specified directory. If
11660 the chdir argument is not a string or Node and is non-zero, then
11661 scons will change to the target file's directory.
11662 Note that scons will not automatically modify its expansion of
11664 construction variables like $TARGET and $SOURCE when using the
11665 chdir keyword argument--that is, the expanded file names will still
11666 be relative to the top-level directory containing the SConstruct
11667 file, and consequently incorrect relative to the chdir directory.
11668 Builders created using chdir keyword argument, will need to use
11669 construction variable expansions like ${TARGET.file} and
11670 ${SOURCE.file} to use just the filename portion of the targets and
11671 source. Example:
11672 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
11674 chdir=1)
11675 exitstatfunc
11677 A function that is passed the exit status (or return value) from
11678 the specified action and can return an arbitrary or modified value.
11679 This can be used, for example, to specify that an Action object's
11680 return value should be ignored under special conditions and SCons
11681 should, therefore, consider that the action always succeeds.
11682 Example:
11683 def always_succeed(s):
11685 # Always return 0, which indicates success.
11686 return 0
11687 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
11689 exitstatfunc=always_succeed)
11690 batch_key
11692 Specifies that the Action can create multiple target files by
11693 processing multiple independent source files simultaneously. (The
11694 canonical example is "batch compilation" of multiple object files
11695 by passing multiple source files to a single invocation of a
11696 compiler such as Microsoft's Visual C / C++ compiler.) If the
11697 batch_key argument evaluates True and is not a callable object, the
11698 configured Action object will cause scons to collect all targets
11699 built with the Action object and configured with the same
11700 construction environment into single invocations of the Action
11701 object's command line or function. Command lines will typically
11702 want to use the $CHANGED_SOURCES construction variable (and
11703 possibly $CHANGED_TARGETS as well) to only pass to the command line
11704 those sources that have actually changed since their targets were
11705 built. Example:
11706 a = Action('build $CHANGED_SOURCES', batch_key=True)
11708 The batch_key argument may also be a callable function that returns
11710 a key that will be used to identify different "batches" of target
11711 files to be collected for batch building. A batch_key function must
11712 accept the following arguments:
11713 action - The action object.
11714 env -
11715 The construction environment configured for the target.
11716 target -
11717 The list of targets for a particular configured action.
11718 source -
11719 The list of source for a particular configured action.
11720 The returned key should typically be a tuple of values derived from
11721 the arguments, using any appropriate logic to decide how multiple
11722 invocations should be batched. For example, a batch_key function
11723 may decide to return the value of a specific construction variable
11724 from the env argument which will cause scons to batch-build targets
11725 with matching values of that variable, or perhaps return the Python
11726 id() of the entire construction environment, in which case scons
11727 will batch-build all targets configured with the same construction
11728 environment. Returning None indicates that the particular target
11729 should not be part of any batched build, but instead will be built
11730 by a separate invocation of action's command or function. Example:
11731 def batch_key(action, env, target, source):
11733 tdir = target[0].dir
11734 if tdir.name == 'special':
11735 # Don't batch-build any target
11736 # in the special/ subdirectory.
11737 return None
11738 return (id(action), id(env), tdir)
11739 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
11740 Miscellaneous Action Functions
11742 scons supplies a number of functions that arrange for various common
11743 file and directory manipulations to be performed. These are similar in
11744 concept to "tasks" in the Ant build tool, although the implementation
11745 is slightly different. These functions do not actually perform the
11746 specified action at the time the function is called, but rather are
11747 factory functions which return an Action object that can be executed at
11748 the appropriate time.
11749 In practice, there are two natural ways that these Action Functions are
11751 intended to be used.
11752 First, if you need to perform the action at the time the SConscript
11754 file is being read, you can use the Execute global function to do so:
11755 Execute(Touch('file'))
11757 Second, you can use these functions to supply Actions in a list for use
11759 by the env.Command method. This can allow you to perform more
11760 complicated sequences of file manipulation without relying on
11761 platform-specific external commands:
11762 env = Environment(TMPBUILD='/tmp/builddir')
11764 env.Command(
11765 target='foo.out',
11766 source='foo.in',
11767 action=[
11768 Mkdir('$TMPBUILD'),
11769 Copy('$TMPBUILD', '${SOURCE.dir}'),
11770 "cd $TMPBUILD && make",
11771 Delete('$TMPBUILD'),
11772 ],
11773 )
11774 Chmod(dest, mode)
11776 Returns an Action object that changes the permissions on the
11777 specified dest file or directory to the specified mode which can be
11778 octal or string, similar to the bash command. Examples:
11779 Execute(Chmod('file', 0o755))
11781 env.Command('foo.out', 'foo.in',
11783 [Copy('$TARGET', '$SOURCE'),
11784 Chmod('$TARGET', 0o755)])
11785 Execute(Chmod('file', "ugo+w"))
11787 env.Command('foo.out', 'foo.in',
11789 [Copy('$TARGET', '$SOURCE'),
11790 Chmod('$TARGET', "ugo+w")])
11791 Copy(dest, src)
11793 Returns an Action object that will copy the src source file or
11794 directory to the dest destination file or directory. Examples:
11795 Execute(Copy('foo.output', 'foo.input'))
11797 env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE'))
11799 Delete(entry, [must_exist])
11801 Returns an Action that deletes the specified entry, which may be a
11802 file or a directory tree. If a directory is specified, the entire
11803 directory tree will be removed. If the must_exist flag is set to a
11804 true value, then a Python error will be raised if the specified
11805 entry does not exist; the default is false, that is, the Action
11806 will silently do nothing if the entry does not exist. Examples:
11807 Execute(Delete('/tmp/buildroot'))
11809 env.Command(
11811 'foo.out',
11812 'foo.in',
11813 action=[
11814 Delete('${TARGET.dir}'),
11815 MyBuildAction,
11816 ],
11817 )
11818 Execute(Delete('file_that_must_exist', must_exist=True))
11820 Mkdir(dir)
11822 Returns an Action that creates the specified directory dir.
11823 Examples:
11824 Execute(Mkdir('/tmp/outputdir'))
11826 env.Command(
11828 'foo.out',
11829 'foo.in',
11830 action=[
11831 Mkdir('/tmp/builddir'),
11832 Copy('/tmp/builddir/foo.in', '$SOURCE'),
11833 "cd /tmp/builddir && make",
11834 Copy('$TARGET', '/tmp/builddir/foo.out'),
11835 ],
11836 )
11837 Move(dest, src)
11839 Returns an Action that moves the specified src file or directory to
11840 the specified dest file or directory. Examples:
11841 Execute(Move('file.destination', 'file.source'))
11843 env.Command(
11845 'output_file',
11846 'input_file',
11847 action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')],
11848 )
11849 Touch(file)
11851 Returns an Action that updates the modification time on the
11852 specified file. Examples:
11853 Execute(Touch('file_to_be_touched'))
11855 env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')])
11857 Variable Substitution
11859 Before executing a command, scons performs variable substitution on the
11860 string that makes up the action part of the builder. Variables to be
11861 interpolated are indicated in the string with a leading $, to
11862 distinguish them from plain text which is not to be substituted. The
11863 name may be surrounded by curly braces (${}) to separate the name from
11864 surrounding characters if necessary. Curly braces are required when you
11865 use Python list subscripting/slicing notation on a variable to select
11866 one or more items from a list, or access a variable's special
11867 attributes, or use Python expression substitution.
11868 Besides regular construction variables, scons provides the following
11870 special variables for use in expanding commands:
11871 $CHANGED_SOURCES
11873 The file names of all sources of the build command that have
11874 changed since the target was last built.
11875 $CHANGED_TARGETS
11877 The file names of all targets that would be built from sources that
11878 have changed since the target was last built.
11879 $SOURCE
11881 The file name of the source of the build command, or the file name
11882 of the first source if multiple sources are being built.
11883 $SOURCES
11885 The file names of the sources of the build command.
11886 $TARGET
11888 The file name of the target being built, or the file name of the
11889 first target if multiple targets are being built.
11890 $TARGETS
11892 The file names of all targets being built.
11893 $UNCHANGED_SOURCES
11895 The file names of all sources of the build command that have not
11896 changed since the target was last built.
11897 $UNCHANGED_TARGETS
11899 The file names of all targets that would be built from sources that
11900 have not changed since the target was last built.
11901 These names are reserved and may not be assigned to or used as
11903 construction variables.
11904 For example, the following builder call:
11906 env = Environment(CC='cc')
11908 env.Command(
11909 target=['foo'],
11910 source=['foo.c', 'bar.c'],
11911 action='@echo $CC -c -o $TARGET $SOURCES'
11912 )
11913 would produce the following output:
11915 cc -c -o foo foo.c bar.c
11917 In the previous example, a string ${SOURCES[1]} would expand to: bar.c.
11919 A variable name may have the following modifiers appended within the
11921 enclosing curly braces to access properties of the interpolated string.
11922 These are known as special attributes.
11923 base -
11924 The base path of the file name,
11925 including the directory path
11926 but excluding any suffix.
11927 dir - The name of the directory in which the file exists.
11929 file - The file name, minus any directory portion.
11930 filebase - Like file but minus its suffix.
11931 suffix - Just the file suffix.
11932 abspath - The absolute path name of the file.
11933 posix -
11934 The path with directories separated by forward slashes
11935 (/).
11936 Sometimes necessary on Windows systems
11937 when a path references a file on other (POSIX) systems.
11938 windows -
11940 The path with directories separated by backslashes
11941 (\\).
11942 Sometimes necessary on POSIX-style systems
11943 when a path references a file on other (Windows) systems.
11944 win32 is a (deprecated) synonym for
11945 windows.
11946 srcpath -
11948 The directory and file name to the source file linked to this
11949 file through
11950 VariantDir().
11951 If this file isn't linked,
11952 it just returns the directory and filename unchanged.
11953 srcdir -
11955 The directory containing the source file linked to this file
11956 through
11957 VariantDir().
11958 If this file isn't linked,
11959 it just returns the directory part of the filename.
11960 rsrcpath -
11962 The directory and file name to the source file linked to this
11963 file through
11964 VariantDir().
11965 If the file does not exist locally but exists in a Repository,
11966 the path in the Repository is returned.
11967 If this file isn't linked, it just returns the
11968 directory and filename unchanged.
11969 rsrcdir -
11971 The Repository directory containing the source file linked to
11972 this file through
11973 VariantDir().
11974 If this file isn't linked,
11975 it just returns the directory part of the filename.
11976 For example, the specified target will expand as follows for the
11979 corresponding modifiers:
11980 $TARGET => sub/dir/file.x
11982 ${TARGET.base} => sub/dir/file
11983 ${TARGET.dir} => sub/dir
11984 ${TARGET.file} => file.x
11985 ${TARGET.filebase} => file
11986 ${TARGET.suffix} => .x
11987 ${TARGET.abspath} => /top/dir/sub/dir/file.x
11988 SConscript('src/SConscript', variant_dir='sub/dir')
11990 $SOURCE => sub/dir/file.x
11991 ${SOURCE.srcpath} => src/file.x
11992 ${SOURCE.srcdir} => src
11993 Repository('/usr/repository')
11995 $SOURCE => sub/dir/file.x
11996 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
11997 ${SOURCE.rsrcdir} => /usr/repository/src
11998 Some modifiers can be combined, like ${TARGET.srcpath.base),
12000 ${TARGET.file.suffix}, etc.
12001 The curly brace notation may also be used to enclose a Python
12003 expression to be evaluated. See the section called “Python Code
12004 Substitution” below for a description.
12005 A variable name may also be a Python function associated with a
12007 construction variable in the environment. The function should accept
12008 four arguments:
12009 target - a list of target nodes
12010 source - a list of source nodes
12011 env - the construction environment
12012 for_signature -
12013 a Boolean value that specifies
12014 whether the function is being called
12015 for generating a build signature.
12016 SCons will insert whatever the called function returns into the
12019 expanded string:
12020 def foo(target, source, env, for_signature):
12022 return "bar"
12023 # Will expand $BAR to "bar baz"
12025 env=Environment(FOO=foo, BAR="$FOO baz")
12026 As a reminder, this evaluation happens when $BAR is actually used in a
12028 builder action. The value of env['BAR'] will be exactly as it was set:
12029 "$FOO baz".
12030 You can use this feature to pass arguments to a Python function by
12032 creating a callable class that stores one or more arguments in an
12033 object, and then uses them when the __call__() method is called. Note
12034 that in this case, the entire variable expansion must be enclosed by
12035 curly braces so that the arguments will be associated with the
12036 instantiation of the class:
12037 class foo:
12039 def __init__(self, arg):
12040 self.arg = arg
12041 def __call__(self, target, source, env, for_signature):
12043 return self.arg + " bar"
12044 # Will expand $BAR to "my argument bar baz"
12046 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
12047 The special pseudo-variables $( and $) may be used to surround parts of
12049 a command line that may change without causing a rebuild--that is,
12050 which are not included in the signature of target files built with this
12051 command. All text between $( and $) will be removed from the command
12052 line before it is added to file signatures, and the $( and $) will be
12053 removed before the command is executed. For example, the command line:
12054 echo Last build occurred $( $TODAY $). > $TARGET
12056 would execute the command:
12058 echo Last build occurred $TODAY. > $TARGET
12060 but the command signature added to any target files would be:
12062 echo Last build occurred . > $TARGET
12064 Python Code Substitution
12066 If a substitutable expression using the notation ${something} does not
12067 appear to match one of the other substitution patterns, it is evaluated
12068 as a Python expression. This uses Python's eval function, with the
12069 globals parameter set to the current environment's set of construction
12070 variables, and the result substituted in. So in the following case:
12071 env.Command(
12073 'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET"
12074 )
12075 the command executed will be either
12077 echo FOO > foo.out
12079 or
12081 echo BAR > foo.out
12083 according to the current value of env['COND'] when the command is
12085 executed. The evaluation takes place when the target is being built,
12086 not when the SConscript is being read. So if env['COND'] is changed
12087 later in the SConscript, the final value will be used.
12088 Here's a more complete example. Note that all of COND, FOO, and BAR are
12090 construction variables, and their values are substituted into the final
12091 command. FOO is a list, so its elements are interpolated separated by
12092 spaces.
12093 env=Environment()
12095 env['COND'] = 1
12096 env['FOO'] = ['foo1', 'foo2']
12097 env['BAR'] = 'barbar'
12098 env.Command(
12099 'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} > $TARGET"
12100 )
12101 will execute:
12103 echo foo1 foo2 > foo.out
12105 In point of fact, Python expression evaluation is how the special
12107 attributes are substituted: they are simply attributes of the Python
12108 objects that represent $TARGET, $SOURCES, etc., which SCons passes to
12109 eval which returns the value.
12110 SCons uses the following rules when converting construction variables
12112 into command lines:
12113 string
12115 When the value is a string it is interpreted as a space delimited
12116 list of command line arguments.
12117 list
12119 When the value is a list it is interpreted as a list of command
12120 line arguments. Each element of the list is converted to a string.
12121 other
12123 Anything that is not a list or string is converted to a string and
12124 interpreted as a single command line argument.
12125 newline
12127 Newline characters (\n) delimit lines. The newline parsing is done
12128 after all other parsing, so it is not possible for arguments (e.g.
12129 file names) to contain embedded newline characters.
12130 Note
12132 Use of the Python eval function is considered to have security
12133 implications, since, depending on input sources, arbitrary
12134 unchecked strings of code can be executed by the Python
12135 interpreter. Although SCons makes use of it in a somewhat
12136 restricted context, you should be aware of this issue when using
12137 the ${python-expression-for-subst} form.
12138 Scanner Objects
12140 You can use the Scanner function to define objects to scan new file
12141 types for implicit dependencies. The Scanner function accepts the
12142 following arguments:
12143 function
12145 This can be either:
12146 • a Python function that will process the Node (file) and return
12148 a list of File Nodes representing the implicit dependencies
12149 (file names) found in the contents.
12150 • a dictionary that maps keys (typically the file suffix, but see
12152 below for more discussion) to other Scanners that should be
12153 called.
12154 If the argument is a Python function, the function must accept
12156 three required arguments and an optional fourth:
12157 node -
12158 The internal SCons node representing the file.
12159 Use str(node)
12160 to fetch the name of the file, and
12161 node.get_contents()
12162 to fetch the contents of the file as bytes or
12163 node.get_text_contents()
12164 to fetch the contents as text.
12165 Note that the file is
12166 not
12167 guaranteed to exist before the scanner is called,
12168 so the scanner function should check that
12169 if there's any chance that the scanned file
12170 might not exist
12171 (for example, if it's built from other files).
12172 env - The construction environment for the scan.
12174 path -
12175 A tuple (or list)
12176 of directories that can be searched
12177 for files.
12178 This will usually be the tuple returned by the
12179 path_function
12180 argument (see below).
12181 arg -
12183 The argument supplied when the scanner was created, if any
12184 (default None.
12185 name
12188 The name of the Scanner. This is mainly used to identify the
12189 Scanner internally. The default value is "NONE".
12190 argument
12192 An optional argument that, if specified, will be passed to the
12193 scanner function (described above) and the path function (specified
12194 below).
12195 skeys
12197 An optional list that can be used to determine which scanner should
12198 be used for a given Node. In the usual case of scanning for file
12199 names, this argument will be a list of suffixes for the different
12200 file types that this Scanner knows how to scan. If the argument is
12201 a string, then it will be expanded into a list by the current
12202 environment.
12203 path_function
12205 A Python function that takes four or five arguments: a construction
12206 environment, a Node for the directory containing the SConscript
12207 file in which the first target was defined, a list of target nodes,
12208 a list of source nodes, and an optional argument supplied when the
12209 scanner was created. The path_function returns a tuple of
12210 directories that can be searched for files to be returned by this
12211 Scanner object. (Note that the FindPathDirs function can be used to
12212 return a ready-made path_function for a given construction variable
12213 name, instead of having to write your own function from scratch.)
12214 node_class
12216 The class of Node that should be returned by this Scanner object.
12217 Any strings or other objects returned by the scanner function that
12218 are not of this class will be run through the function supplied by
12219 the node_factory argument.
12220 node_factory
12222 A Python function that will take a string or other object and turn
12223 it into the appropriate class of Node to be returned by this
12224 Scanner object.
12225 scan_check
12227 An optional Python function that takes two arguments, a Node (file)
12228 and a construction environment, and returns whether the Node
12229 should, in fact, be scanned for dependencies. This check can be
12230 used to eliminate unnecessary calls to the scanner function when,
12231 for example, the underlying file represented by a Node does not yet
12232 exist.
12233 recursive
12235 An optional flag that specifies whether this scanner should be
12236 re-invoked on the dependency files returned by the scanner. When
12237 this flag is not set, the Node subsystem will only invoke the
12238 scanner on the file being scanned, and not (for example) also on
12239 the files specified by the #include lines in the file being
12240 scanned. recursive may be a callable function, in which case it
12241 will be called with a list of Nodes found and should return a list
12242 of Nodes that should be scanned recursively; this can be used to
12243 select a specific subset of Nodes for additional scanning.
12244 Note that scons has a global SourceFileScanner object that is used by
12246 the Object, SharedObject and StaticObject builders to decide which
12247 scanner should be used for different file extensions. You can use the
12248 SourceFileScanner.add_scanner() method to add your own Scanner object
12249 to the SCons infrastructure that builds target programs or libraries
12250 from a list of source files of different types:
12251 def xyz_scan(node, env, path):
12253 contents = node.get_text_contents()
12254 # Scan the contents and return the included files.
12255 XYZScanner = Scanner(xyz_scan)
12257 SourceFileScanner.add_scanner('.xyz', XYZScanner)
12259 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
12261
12263 scons and its configuration files are very portable, due largely to its
12264 implementation in Python. There are, however, a few portability issues
12265 waiting to trap the unwary.
12266 .C file suffix
12268 scons handles the upper-case .C file suffix differently, depending on
12269 the capabilities of the underlying system. On a case-sensitive system
12270 such as Linux or UNIX, scons treats a file with a .C suffix as a C++
12271 source file. On a case-insensitive system such as Windows, scons treats
12272 a file with a .C suffix as a C source file.
12273 Fortran file suffixes
12275 scons handles upper-case Fortran file suffixes differently depending on
12276 the capabilities of the underlying system. On a case-sensitive system
12277 such as Linux or UNIX, scons treats a file with a .F as a Fortran
12278 source file that is to be first run through the standard C
12279 preprocessor, while the lower-case version is not. This matches the
12280 convention of gfortran, which may also be followed by other Fortran
12281 compilers. This also applies to other naming variants, .FOR, .FTN,
12282 .F90, .F95, .F03 and .F08; files suffixed with .FPP and .fpp are both
12283 run through the preprocessor, as indicated by the pp part of the name.
12284 On a case-insensitive system such as Windows, scons treats a file with
12285 a .F suffix as a Fortran source file that should not be run through the
12286 C preprocessor.
12287 Run through the C preprocessor here means that a different set of
12289 construction variables will be applied in constructed commands, for
12290 example $FORTRANPPCOM and $FORTRANPPCOMSTR instead of $FORTRANCOM and
12291 $FORTRANCOMSTR. See the Fortran-related construction variables for more
12292 details.
12293 Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
12295 Cygwin supplies a set of tools and utilities that let users work on a
12296 Windows system using a more POSIX-like environment. The Cygwin tools,
12297 including Cygwin Python, do this, in part, by sharing an ability to
12298 interpret UNIX-like path names. For example, the Cygwin tools will
12299 internally translate a Cygwin path name like /cygdrive/c/mydir to an
12300 equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
12301 Versions of Python that are built for native Windows execution, such as
12303 the python.org and ActiveState versions, do not have the Cygwin path
12304 name semantics. This means that using a native Windows version of
12305 Python to build compiled programs using Cygwin tools (such as gcc,
12306 bison and flex) may yield unpredictable results. "Mixing and matching"
12307 in this way can be made to work, but it requires careful attention to
12308 the use of path names in your SConscript files.
12309 In practice, users can sidestep the issue by adopting the following
12311 rules: When using gcc, use the Cygwin-supplied Python interpreter to
12312 run scons; when using Microsoft Visual C/C++ (or some other Windows
12313 compiler) use the python.org or Microsoft Store or ActiveState version
12314 of Python to run scons.
12315 Windows: scons.bat file
12317 On Windows systems, scons is executed via a wrapper scons.bat file.
12318 This has (at least) two ramifications:
12319 First, Windows command-line users that want to use variable assignment
12321 on the command line may have to put double quotes around the
12322 assignments:
12323 scons "FOO=BAR" "BAZ=BLEH"
12325 Second, the Cygwin shell does not recognize this file as being the same
12327 as an scons command issued at the command-line prompt. You can work
12328 around this either by executing scons.bat from the Cygwin command line,
12329 or by creating a wrapper shell script named scons.
12330 MinGW
12332 The MinGW bin directory must be in your PATH environment variable or
12333 the ['ENV']['PATH'] construction variable for scons to detect and use
12334 the MinGW tools. When running under the native Windows Python
12335 interpreter, scons will prefer the MinGW tools over the Cygwin tools,
12336 if they are both installed, regardless of the order of the bin
12337 directories in the PATH variable. If you have both MSVC and MinGW
12338 installed and you want to use MinGW instead of MSVC, then you must
12339 explicitly tell scons to use MinGW by passing tools=['mingw'] to the
12340 Environment function, because scons will prefer the MSVC tools over the
12341 MinGW tools.
12342
12344 In general, scons is not controlled by environment variables set in the
12345 shell used to invoke it, leaving it up to the SConscript file author to
12346 import those if desired. However the following variables are imported
12347 by scons itself if set:
12348 SCONS_LIB_DIR
12350 Specifies the directory that contains the scons Python module
12351 directory. Normally scons can deduce this, but in some
12352 circumstances, such as working with a source release, it may be
12353 necessary to specify (for example,
12354 /home/aroach/scons-src-0.01/src/engine).
12355 SCONSFLAGS
12357 A string of options that will be used by scons in addition to those
12358 passed on the command line.
12359 SCONS_CACHE_MSVC_CONFIG
12361 (Windows only). If set, save the shell environment variables
12362 generated when setting up the Microsoft Visual C++ compiler (and/or
12363 Build Tools) to a file to give these settings, which are expensive
12364 to generate, persistence across scons invocations. Use of this
12365 option is primarily intended to aid performance in tightly
12366 controlled Continuous Integration setups.
12367 If set to a True-like value ("1", "true" or "True") will cache to a
12369 file named .scons_msvc_cache in the user's home directory. If set
12370 to a pathname, will use that pathname for the cache.
12371 Note: use this cache with caution as it might be somewhat fragile:
12373 while each major toolset version (e.g. Visual Studio 2017 vs 2019)
12374 and architecture pair will get separate cache entries, if toolset
12375 updates cause a change to settings within a given release series,
12376 scons will not detect the change and will reuse old settings.
12377 Remove the cache file in case of problems with this. scons will
12378 ignore failures reading or writing the file and will silently
12379 revert to non-cached behavior in such cases.
12380 Available since scons 3.1 (experimental).
12382
12384 The SCons User Guide at
12385 https://scons.org/doc/production/HTML/scons-user.html
12386 The SCons Design Document (old)
12388 The SCons Cookbook at
12390 https://scons-cookbook.readthedocs.io
12391 for examples of how to solve various problems with SCons.
12392 SCons source code
12395 on GitHub[2]
12396 The SCons API Reference
12399 https://scons.org/doc/production/HTML/scons-api/index.html
12400 (for internal details)
12401
12404 Originally: Steven Knight knight@baldmt.com and Anthony Roach
12405 aroach@electriceyeball.com.
12406 Since 2010: The SCons Development Team scons-dev@scons.org.
12408
12410 SCons Development Team
12411 Author.
12412 The SCons Development Team
12414
12416 Copyright © 2004 - 2021 The SCons Foundation
12417
12419 1. LLVM specification
12420 https://clang.llvm.org/docs/JSONCompilationDatabase.html
12421 2. on GitHub
12423 https://github.com/SCons/scons
12424SCons 4.1.0 version 4.1.0<pubdate>2004 - 2021</pubdate> SCONS(1)