1SCONS(1) SCons 4.4.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,
17 automatic dependency scanning, and a database of information about
18 previous builds so details do not have to be recalculated each run.
19 scons requires Python 3.6 or later to run; there should be no other
21 dependencies or requirements. unless the experimental Ninja tool is
22 used.
23 Support for Python 3.5 is removed since SCons 4.3.0. The CPython
24 project has retired 3.5: https://www.python.org/dev/peps/pep-0478.
25 You set up an SCons build system by writing a script that describes
27 things to build (targets), and, if necessary, the rules to build those
28 files (actions). SCons comes with a collection of Builder methods
29 which apply premade actions for building many common software
30 components such as executable programs, object files and libraries, so
31 that for many software projects, only the targets and input files
32 (sources) need be specified in a call to a builder. SCons thus can
33 operate at a level of abstraction above that of pure filenames. For
34 example if you specify a library target named "foo", SCons keeps track
35 of the actual operating system dependent filename (such as libfoo.so on
36 a GNU/Linux system), and how to refer to that library in later
37 construction steps that want to use it, so you don't have to specify
38 that precise information yourself. SCons can also scan automatically
39 for dependency information, such as header files included by source
40 code files (for example, #include preprocessor directives in C or C++
41 files), so these implicit dependencies do not have to be specified
42 manually. SCons supports the ability to define new scanners to support
43 additional input file types.
44 Information about files involved in the build, including a
46 cryptographic hash of the contents, is cached for later reuse. By
47 default this hash (the content signature) is used to determine if a
48 file has changed since the last build, but this can be controlled by
49 selecting an appropriate Decider function. Implicit dependency files
50 are also part of out-of-date computation. The scanned implicit
51 dependency information can optionally be cached and used to speed up
52 future builds. A hash of each executed build action (the build
53 signature is cached, so that changes to build instructions (changing
54 flags, etc.) or to the build tools themselves (new version) can also
55 trigger a rebuild.
56 When invoked, scons looks for a file named SConstruct in the current
58 directory and reads the build configuration from that file (other names
59 are allowed, see the section called “SConscript Files” for more
60 information). The SConstruct file may specify subsidiary configuration
61 files by calling the SConscript function. By convention, these
62 subsidiary files are named SConscript, although any name may be used.
63 As a result of this naming convention, the term SConscript files is
64 used to refer generically to the complete set of configuration files
65 for a project (including the SConstruct file), regardless of the actual
66 file names or number of such files.
67 Before reading the SConscript files, scons looks for a directory named
69 site_scons in various system directories and in the directory
70 containing the SConstruct file or, if specified, the directory from the
71 --site-dir option instead, and prepends the ones it finds to the Python
72 module search path (sys.path), thus allowing modules in such
73 directories to be imported in the normal Python way in SConscript
74 files. For each found site directory, (1) if it contains a file
75 site_init.py that file is evaluated, and (2) if it contains a directory
76 site_tools the path to that directory is prepended to the default
77 toolpath. See the --site-dir and --no-site-dir options for details on
78 default paths and controlling the site directories.
79 SConscript files are written in the Python programming language,
81 although it is normally not necessary to be a Python programmer to use
82 scons effectively. SConscript files are invoked in a context that makes
83 the facilities described in this manual page available in their local
84 namespace without any special steps. Standard Python scripting
85 capabilities such as flow control, data manipulation, and imported
86 Python libraries are available to use to handle complicated build
87 situations. Other Python files can be made a part of the build system,
88 but they do not automatically have the SCons context and need to import
89 it if they need access (described later).
90 scons reads and executes all of the included SConscript files before it
92 begins building any targets. To make this clear, scons prints the
93 following messages about what it is doing:
94 $ scons foo.out
96 scons: Reading SConscript files ...
97 scons: done reading SConscript files.
98 scons: Building targets ...
99 cp foo.in foo.out
100 scons: done building targets.
101 $
102 The status messages (lines beginning with the scons: tag) may be
104 suppressed using the -Q option.
105 To assure reproducible builds, SCons uses a restricted execution
107 environment for running external commands used to build targets, rather
108 then propagating the full environment in effect at the time scons was
109 called. This helps avoid problems like picking up accidental settings,
110 temporary debug values that are no longer needed, or one developer
111 having different settings than another (or than the CI/CD pipeline).
112 Environment variables that are needed for proper operation of such
113 commands need to be set explicitly, which can be done either by
114 assigning the desired values, or by picking values individually out of
115 environment variables using the Python os.environ dictionary. The
116 execution environment for a given construction environment is contained
117 in its $ENV construction variable. A few environment variables are
118 picked up automatically - see the section called “ENVIRONMENT”).
119 In particular, if the compiler or other commands that you want to use
121 to build your target files are not in standard system locations, scons
122 will not find them unless you explicitly include the locations into the
123 PATH element of the execution environment. One example approach is to
124 extract the entire PATH environment variable and set that into the
125 execution environment:
126 import os
128 env = Environment(ENV={'PATH': os.environ['PATH']})
129 Similarly, if the commands use specific external environment variables
131 that scons does not recognize, they can be propagated into the
132 execution environment:
133 import os
135 env = Environment(
137 ENV={
138 'PATH': os.environ['PATH'],
139 'ANDROID_HOME': os.environ['ANDROID_HOME'],
140 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME'],
141 }
142 )
143 Or you may explicitly propagate the invoking user's complete external
145 environment:
146 import os
148 env = Environment(ENV=os.environ.copy())
149 This comes at the expense of making your build dependent on the user's
151 environment being set correctly, but it may be more convenient for many
152 configurations. It should not cause problems if done in a build setup
153 which tightly controls how the environment is set up before invoking
154 scons, as in many continuous integration setups.
155 scons is normally executed in a top-level directory containing an
157 SConstruct file. When scons is invoked, the command line (including the
158 contents of the SCONSFLAGS environment variable, if set) is processed.
159 Command-line options (see the section called “OPTIONS”) are consumed.
160 Any variable argument assignments are collected, and remaining
161 arguments are taken as targets to build.
162 Values of variables to be passed to the SConscript files may be
164 specified on the command line:
165 scons debug=1
167 These variables are available through the ARGUMENTS dictionary, and can
169 be used in the SConscript files to modify the build in any way:
170 if ARGUMENTS.get('debug', 0):
172 env = Environment(CCFLAGS='-g')
173 else:
174 env = Environment()
175 The command-line variable arguments are also available in the ARGLIST
177 list, indexed by their order on the command line. This allows you to
178 process them in order rather than by name, if necessary. Each ARGLIST
179 entry is a tuple containing (argname, argvalue).
180 See the section called “Command-Line Construction Variables” for more
182 information.
183 scons can maintain a cache of target (derived) files that can be shared
185 between multiple builds. When derived-file caching is enabled in an
186 SConscript file, any target files built by scons will be copied to the
187 cache. If an up-to-date target file is found in the cache, it will be
188 retrieved from the cache instead of being rebuilt locally. Caching
189 behavior may be disabled and controlled in other ways by the
190 --cache-force, --cache-disable, --cache-readonly, and --cache-show
191 command-line options. The --random option is useful to prevent multiple
192 builds from trying to update the cache simultaneously.
193 By default, scons searches for known programming tools on various
195 systems and initializes itself based on what is found. On Windows
196 systems which identify as win32, scons searches in order for the
197 Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler
198 tools, and the PharLap ETS compiler. On Windows system which identify
199 as cygwin (that is, if scons is invoked from a cygwin shell), the order
200 changes to prefer the GCC toolchain over the MSVC tools. On OS/2
201 systems, scons searches in order for the OS/2 compiler, the GCC tool
202 chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX,
203 Hewlett Packard HP-UX, and Oracle Solaris systems, scons searches for
204 the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools
205 respectively) and the GCC tool chain. On all other platforms, including
206 POSIX (Linux and UNIX) platforms, scons searches in order for the GCC
207 tool chain, and the Intel compiler tools. These default values may be
208 overridden by appropriate setting of construction variables.
209 Target Selection
211 SCons acts on the selected targets, whether the requested operation is
212 build, no-exec or clean. Targets are selected as follows:
213 1. Targets specified on the command line. These may be files,
215 directories, or phony targets defined using the Alias function.
216 Directory targets are scanned by scons for any targets that may be
217 found with a destination in or under that directory. The targets
218 listed on the command line are made available in the
219 COMMAND_LINE_TARGETS list.
220 2. If no targets are specified on the command line, scons will select
222 those targets specified in the SConscript files via calls to the
223 Default function. These are known as the default targets, and are
224 made available in the DEFAULT_TARGETS list.
225 3. If no targets are selected by the previous steps, scons selects the
227 current directory for scanning, unless command-line options which
228 affect the target scan are detected (-C, -D, -u, -U). Since targets
229 thus selected were not the result of user instructions, this target
230 list is not made available for direct inspection; use the
231 --debug=explain option if they need to be examined.
232 4. scons always adds to the selected targets any intermediate targets
234 which are necessary to build the specified ones. For example, if
235 constructing a shared library or dll from C source files, scons
236 will also build the object files which will make up the library.
237 To ignore the default targets specified through calls to Default and
239 instead build all target files in or below the current directory
240 specify the current directory (.) as a command-line target:
241 scons .
243 To build all target files, including any files outside of the current
245 directory, supply a command-line target of the root directory (on POSIX
246 systems):
247 scons /
249 or the path name(s) of the volume(s) in which all the targets should be
251 built (on Windows systems):
252 scons C:\ D:\
254 A subset of a hierarchical tree may be built by remaining at the
256 top-level directory (where the SConstruct file lives) and specifying
257 the subdirectory as the target to build:
258 scons src/subdir
260 or by changing directory and invoking scons with the -u option, which
262 traverses up the directory hierarchy until it finds the SConstruct
263 file, and then builds targets relatively to the current subdirectory
264 (see also the related -D and -U options):
265 cd src/subdir
267 scons -u .
268 In all cases, more files may be built than are requested, as scons
270 needs to make sure any dependent files are built.
271 Specifying "cleanup" targets in SConscript files is usually not
273 necessary. The -c flag removes all selected targets:
274 scons -c .
276 to remove all target files in or under the current directory, or:
278 scons -c build export
280 to remove target files under build and export.
282 Additional files or directories to remove can be specified using the
284 Clean function in the SConscript files. Conversely, targets that would
285 normally be removed by the -c invocation can be retained by calling the
286 NoClean function with those targets.
287 scons supports building multiple targets in parallel via a -j option
289 that takes, as its argument, the number of simultaneous tasks that may
290 be spawned:
291 scons -j 4
293 builds four targets in parallel, for example.
295
297 In general, scons supports the same command-line options as GNU Make
298 and many of those supported by cons.
299 -b
301 Ignored for compatibility with non-GNU versions of Make
302 -c, --clean, --remove
304 Set clean mode. Clean up by removing the selected targets, well as
305 any files or directories associated with a selected target through
306 calls to the Clean function. Will not remove any targets which are
307 marked for preservation through calls to the NoClean function.
308 While clean mode removes targets rather than building them, work
310 which is done directly in Python code in SConscript files will
311 still be carried out. If it is important to avoid some such work
312 from taking place in clean mode, it should be protected. An
313 SConscript file can determine which mode is active by querying
314 GetOption, as in the call if GetOption("clean"):
315 --cache-debug=file
317 Write debug information about derived-file caching to the specified
318 file. If file is a hyphen (-), the debug information is printed to
319 the standard output. The printed messages describe what
320 signature-file names are being looked for in, retrieved from, or
321 written to the derived-file cache specified by CacheDir.
322 --cache-disable, --no-cache
324 Disable derived-file caching. scons will neither retrieve files
325 from the cache nor copy files to the cache. This option can be used
326 to temporarily disable the cache without modifying the build
327 scripts.
328 --cache-force, --cache-populate
330 When using CacheDir, populate a derived-file cache by copying any
331 already-existing, up-to-date derived files to the cache, in
332 addition to files built by this invocation. This is useful to
333 populate a new cache with all the current derived files, or to add
334 to the cache any derived files recently built with caching disabled
335 via the --cache-disable option.
336 --cache-readonly
338 Use the derived-file cache, if enabled, to retrieve files, but do
339 not not update the cache with any files actually built during this
340 invocation.
341 --cache-show
343 When using a derived-file cache show the command that would have
344 been executed to build the file (or the corresponding *COMSTR
345 contents if set) even if the file is retrieved from cache. Without
346 this option, scons shows a cache retrieval message if the file is
347 fetched from cache. This allows producing consistent output for
348 build logs, regardless of whether a target file was rebuilt or
349 retrieved from the cache.
350 --config=mode
352 Control how the Configure call should use or generate the results
353 of configuration tests. mode should be one of the following
354 choices:
355 auto
357 SCons will use its normal dependency mechanisms to decide if a
358 test must be rebuilt or not. This saves time by not running the
359 same configuration tests every time you invoke scons, but will
360 overlook changes in system header files or external commands
361 (such as compilers) if you don't specify those dependecies
362 explicitly. This is the default behavior.
363 force
365 If this mode is specified, all configuration tests will be
366 re-run regardless of whether the cached results are out of
367 date. This can be used to explicitly force the configuration
368 tests to be updated in response to an otherwise unconfigured
369 change in a system header file or compiler.
370 cache
372 If this mode is specified, no configuration tests will be rerun
373 and all results will be taken from cache. scons will report an
374 error if --config=cache is specified and a necessary test does
375 not have any results in the cache.
376 -C directory, --directory=directory
379 Run as if scons was started in directory instead of the current
380 working directory. That is, change directory before searching for
381 the SConstruct, Sconstruct, sconstruct, SConstruct.py,
382 Sconstruct.py or sconstruct.py file or doing anything else. When
383 multiple -C options are given, each subsequent non-absolute -C
384 directory is interpreted relative to the preceding one. This option
385 is similar to using -f directory/SConstruct, but -f does not search
386 for any of the predefined SConstruct names in the specified
387 directory. See also options -u, -U and -D to change the SConstruct
388 search behavior when this option is used.
389 -D
391 Works exactly the same way as the -u option except for the way
392 default targets are handled. When this option is used and no
393 targets are specified on the command line, all default targets are
394 built, whether or not they are below the current directory.
395 --debug=type[,type...]
397 Debug the build process. type specifies the kind of debugging info
398 to emit. Multiple types may be specified, separated by commas. The
399 following types are recognized:
400 action-timestamps
402 Prints additional time profiling information. For each command,
403 shows the absolute start and end times. This may be useful in
404 debugging parallel builds. Implies the --debug=time option.
405 Available since scons 3.1.
407 count
409 Print how many objects are created of the various classes used
410 internally by SCons before and after reading the SConscript
411 files and before and after building targets. This is not
412 supported when SCons is executed with the Python -O (optimized)
413 option or when the SCons modules have been compiled with
414 optimization (that is, when executing from *.pyo files).
415 duplicate
417 Print a line for each unlink/relink (or copy) of a variant file
418 from its source file. Includes debugging info for unlinking
419 stale variant files, as well as unlinking old targets before
420 building them.
421 explain
423 Print an explanation of why scons is deciding to (re-)build the
424 targets it selects for building.
425 findlibs
427 Instruct the scanner that searches for libraries to print a
428 message about each potential library name it is searching for,
429 and about the actual libraries it finds.
430 includes
432 Print the include tree after each top-level target is built.
433 This is generally used to find out what files are included by
434 the sources of a given derived file:
435 $ scons --debug=includes foo.o
437 memoizer
439 Prints a summary of hits and misses using the Memoizer, an
440 internal subsystem that counts how often SCons uses cached
441 values in memory instead of recomputing them each time they're
442 needed.
443 memory
445 Prints how much memory SCons uses before and after reading the
446 SConscript files and before and after building targets.
447 objects
449 Prints a list of the various objects of the various classes
450 used internally by SCons.
451 pdb
453 Re-run scons under the control of the pdb Python debugger.
454 prepare
456 Print a line each time any target (internal or external) is
457 prepared for building. scons prints this for each target it
458 considers, even if that target is up to date (see also
459 --debug=explain). This can help debug problems with targets
460 that aren't being built; it shows whether scons is at least
461 considering them or not.
462 presub
464 Print the raw command line used to build each target before the
465 construction environment variables are substituted. Also shows
466 which targets are being built by this command. Output looks
467 something like this:
468 $ scons --debug=presub
470 Building myprog.o with action(s):
471 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
472 ...
473 stacktrace
475 Prints an internal Python stack trace when encountering an
476 otherwise unexplained error.
477 time
479 Prints various time profiling information:
480 • The time spent executing each individual build command
482 • The total build time (time SCons ran from beginning to end)
484 • The total time spent reading and executing SConscript files
486 • The total time SCons itself spent running (that is, not
488 counting reading and executing SConscript files)
489 • The total time spent executing all build commands
491 • The elapsed wall-clock time spent executing those build
493 commands
494 • The time spent processing each file passed to the
496 SConscript function
497 (When scons is executed without the -j option, the elapsed
499 wall-clock time will typically be slightly longer than the
500 total time spent executing all the build commands, due to the
501 SCons processing that takes place in between executing each
502 command. When scons is executed with the -j option, and your
503 build configuration allows good parallelization, the elapsed
504 wall-clock time should be significantly smaller than the total
505 time spent executing all the build commands, since multiple
506 build commands and intervening SCons processing should take
507 place in parallel.)
508 --diskcheck=type
511 Enable specific checks for whether or not there is a file on disk
512 where the SCons configuration expects a directory (or vice versa)
513 when searching for source and include files. type can be an
514 available diskcheck type or the special tokens all or none. A
515 comma-separated string can be used to select multiple checks. The
516 default setting is all.
517 Current available checks are:
519 match
521 to check that files and directories on disk match SCons'
522 expected configuration.
523 Disabling some or all of these checks can provide a performance
525 boost for large configurations, or when the configuration will
526 check for files and/or directories across networked or shared file
527 systems, at the slight increased risk of an incorrect build or of
528 not handling errors gracefully.
529 --duplicate=ORDER
531 There are three ways to duplicate files in a build tree: hard
532 links, soft (symbolic) links and copies. The default policy is to
533 prefer hard links to soft links to copies. You can specify a
534 different policy with this option. ORDER must be one of
535 hard-soft-copy (the default), soft-hard-copy, hard-copy, soft-copy
536 or copy. SCons will attempt to duplicate files using the
537 mechanisms in the specified order.
538 --enable-virtualenv
540 Import virtualenv-related variables to SCons.
541 --experimental=feature
543 Enable experimental features and/or tools. feature can be an
544 available feature name or the special tokens all or none. A
545 comma-separated string can be used to select multiple features. The
546 default setting is none.
547 Current available features are: ninja.
549 Caution
551 No Support offered for any features or tools enabled by this
552 flag.
553 Available since scons 4.2.
554 -f file, --file=file, --makefile=file, --sconstruct=file
556 Use file as the initial SConscript file. Multiple -f options may be
557 specified, in which case scons will read all of the specified
558 files.
559 -h, --help
561 Print a local help message for this project, if one is defined in
562 the SConscript files (see the Help function), plus a line that
563 refers to the standard SCons help message. If no local help message
564 is defined, prints the standard SCons help message (as for the -H
565 option) plus help for any local options defined through AddOption.
566 Exits after displaying the appropriate message.
567 Note that use of this option requires SCons to process the
569 SConscript files, so syntax errors may cause the help message not
570 to be displayed.
571 --hash-chunksize=KILOBYTES
573 Set the block size used when computing content signatures to
574 KILOBYTES. This value determines the size of the chunks which are
575 read in at once when computing signature hashes. Files below that
576 size are fully stored in memory before performing the signature
577 computation while bigger files are read in block-by-block. A huge
578 block-size leads to high memory consumption while a very small
579 block-size slows down the build considerably.
580 The default value is to use a chunk size of 64 kilobytes, which
582 should be appropriate for most uses.
583 Available since scons 4.2.
585 --hash-format=ALGORITHM
587 Set the hashing algorithm used by SCons to ALGORITHM. This value
588 determines the hashing algorithm used in generating content
589 signatures or CacheDir keys.
590 The supported list of values are: md5, sha1, and sha256. However,
592 the Python interpreter used to run SCons must have the
593 corresponding support available in the hashlib module to use the
594 specified algorithm.
595 Specifying this value changes the name of the SConsign database.
597 For example, --hash-format=sha256 will create a SConsign database
598 with name .sconsign_sha256.dblite.
599 If this option is not specified, a the first supported hash format
601 found is selected. Typically this is MD5, however, if you are on a
602 FIPS-compliant system and using a version of Python less than 3.9,
603 SHA1 or SHA256 will be chosen as the default. Python 3.9 and
604 onwards clients will always default to MD5, even in FIPS mode,
605 unless otherwise specified with the --hash-format option.
606 For MD5 databases (either explicitly specified with
608 --hash-format=md5 or defaulted), the SConsign database
609 is.sconsign.dblite. The newer SHA1 and SHA256 selections meanwhile
610 store their databases to .sconsign_algorithmname.dblite
611 Available since scons 4.2.
613 -H, --help-options
615 Print the standard help message about SCons command-line options
616 and exit.
617 -i, --ignore-errors
619 Ignore all errors from commands executed to rebuild files.
620 -I directory, --include-dir=directory
622 Specifies a directory to search for imported Python modules. If
623 several -I options are used, the directories are searched in the
624 order specified.
625 --ignore-virtualenv
627 Suppress importing virtualenv-related variables to SCons.
628 --implicit-cache
630 Cache implicit dependencies. This causes scons to use the implicit
631 (scanned) dependencies from the last time it was run instead of
632 scanning the files for implicit dependencies. This can
633 significantly speed up SCons, but with the following limitations:
634 scons will not detect changes to implicit dependency search paths
636 (e.g. $CPPPATH, $LIBPATH) that would ordinarily cause different
637 versions of same-named files to be used.
638 scons will miss changes in the implicit dependencies in cases where
640 a new implicit dependency is added earlier in the implicit
641 dependency search path (e.g. $CPPPATH, $LIBPATH) than a current
642 implicit dependency with the same name.
643 --implicit-deps-changed
645 Forces SCons to ignore the cached implicit dependencies. This
646 causes the implicit dependencies to be rescanned and recached. This
647 implies --implicit-cache.
648 --implicit-deps-unchanged
650 Force SCons to ignore changes in the implicit dependencies. This
651 causes cached implicit dependencies to always be used. This implies
652 --implicit-cache.
653 --install-sandbox=sandbox_path
655 When using the Install builders, prepend sandbox_path to the
656 installation paths such that all installed files will be placed
657 under that directory. This option is unavailable if one of Install,
658 InstallAs or InstallVersionedLib is not used in the SConscript
659 files.
660 --interactive
662 Starts SCons in interactive mode. The SConscript files are read
663 once and a scons>>> prompt is printed. Targets may now be rebuilt
664 by typing commands at interactive prompt without having to re-read
665 the SConscript files and re-initialize the dependency graph from
666 scratch.
667 SCons interactive mode supports the following commands:
669 build [OPTIONS] [TARGETS] ...
671 Builds the specified TARGETS (and their dependencies) with the
672 specified SCons command-line OPTIONS. b and scons are synonyms
673 for build.
674 The following SCons command-line options affect the build
676 command:
677 --cache-debug=FILE
679 --cache-disable, --no-cache
680 --cache-force, --cache-populate
681 --cache-readonly
682 --cache-show
683 --debug=TYPE
684 -i, --ignore-errors
685 -j N, --jobs=N
686 -k, --keep-going
687 -n, --no-exec, --just-print, --dry-run, --recon
688 -Q
689 -s, --silent, --quiet
690 --taskmastertrace=FILE
691 --tree=OPTIONS
692 Any other SCons command-line options that are specified do not
694 cause errors but have no effect on the build command (mainly
695 because they affect how the SConscript files are read, which
696 only happens once at the beginning of interactive mode).
697 clean [OPTIONS] [TARGETS] ...
699 Cleans the specified TARGETS (and their dependencies) with the
700 specified OPTIONS. c is a synonym. This command is itself a
701 synonym for build --clean
702 exit
704 Exits SCons interactive mode. You can also exit by terminating
705 input (Ctrl+D UNIX or Linux systems, (Ctrl+Z on Windows
706 systems).
707 help [COMMAND]
709 Provides a help message about the commands available in SCons
710 interactive mode. If COMMAND is specified, h and ? are
711 synonyms.
712 shell [COMMANDLINE]
714 Executes the specified COMMANDLINE in a subshell. If no
715 COMMANDLINE is specified, executes the interactive command
716 interpreter specified in the SHELL environment variable (on
717 UNIX and Linux systems) or the COMSPEC environment variable (on
718 Windows systems). sh and ! are synonyms.
719 version
721 Prints SCons version information.
722 An empty line repeats the last typed command. Command-line editing
724 can be used if the readline module is available.
725 $ scons --interactive
727 scons: Reading SConscript files ...
728 scons: done reading SConscript files.
729 scons>>> build -n prog
730 scons>>> exit
731 -j N, --jobs=N
733 Specifies the maximum number of comcurrent jobs (commands) to run.
734 If there is more than one -j option, the last one is effective.
735 -k, --keep-going
737 Continue as much as possible after an error. The target that failed
738 and those that depend on it will not be remade, but other targets
739 specified on the command line will still be processed.
740 -m
742 Ignored for compatibility with non-GNU versions of Make.
743 --max-drift=SECONDS
745 Set the maximum expected drift in the modification time of files to
746 SECONDS. This value determines how long a file must be unmodified
747 before its cached content signature will be used instead of
748 calculating a new content signature (hash) of the file's contents.
749 The default value is 2 days, which means a file must have a
750 modification time of at least two days ago in order to have its
751 cached content signature used. A negative value means to never
752 cache the content signature and to ignore the cached value if there
753 already is one. A value of 0 means to always use the cached
754 signature, no matter how old the file is.
755 --md5-chunksize=KILOBYTES
757 A deprecated synonym for --hash-chunksize.
758 Deprecated since scons 4.2.
760 -n, --no-exec, --just-print, --dry-run, --recon
762 Set no execute mode. Print the commands that would be executed to
763 build any out-of-date target files, but do not execute the
764 commands.
765 The output is a best effort, as SCons cannot always precisely
767 determine what would be built. For example, if a file is generated
768 by a builder action that is later used in the build, that file is
769 not available to scan for dependencies on an unbuilt tree, or may
770 contain out of date information in a built tree.
771 Work which is done directly in Python code in SConscript files, as
773 opposed to work done by builder actions during the build phase,
774 will still be carried out. If it is important to avoid some such
775 work from taking place in no execute mode, it should be protected.
776 An SConscript file can determine which mode is active by querying
777 GetOption, as in the call if GetOption("no_exec"):
778 --no-site-dir
780 Prevents the automatic addition of the standard site_scons dirs to
781 sys.path. Also prevents loading the site_scons/site_init.py modules
782 if they exist, and prevents adding their site_scons/site_tools dirs
783 to the toolpath.
784 --package-type=type
786 The type or types of package to create when using the Package
787 builder. In the case of multiple types, type should be a
788 comma-separated string; SCons will try to build for all of those
789 packages. Note this option is only available if the packaging tool
790 has been enabled.
791 --profile=file
793 Run SCons under the Python profiler and save the results in the
794 specified file. The results may be analyzed using the Python pstats
795 module.
796 -q, --question
798 Do not run any commands, or print anything. Just return an exit
799 status that is zero if the specified targets are already up to
800 date, non-zero otherwise.
801 -Q
803 Quiets SCons status messages about reading SConscript files,
804 building targets and entering directories. Commands that are
805 executed to rebuild target files are still printed.
806 --random
808 Build dependencies in a random order. This is useful when building
809 multiple trees simultaneously with caching enabled, to prevent
810 multiple builds from simultaneously trying to build or retrieve the
811 same target files.
812 -s, --silent, --quiet
814 Silent. Do not print commands that are executed to rebuild target
815 files. Also suppresses SCons status messages.
816 -S, --no-keep-going, --stop
818 Ignored for compatibility with GNU Make
819 --site-dir=path
821 Use a specific path as the site directory rather than searching the
822 list of default site directories. This directory will be prepended
823 to sys.path, the module path/site_init.py will be loaded if it
824 exists, and path/site_tools will be added to the default toolpath.
825 The default set of site directories searched when --site-dir is not
827 specified depends on the system platform, as follows. Users or
828 system administrators can tune site-specific or project-specific
829 SCons behavior by setting up a site directory in one or more of
830 these locations. Directories are examined in the order given, from
831 most generic ("system" directories) to most specific (in the
832 current project), so the last-executed site_init.py file is the
833 most specific one, giving it the chance to override everything
834 else), and the directories are prepended to the paths, again so the
835 last directory examined comes first in the resulting path.
836 Windows:
838 %ALLUSERSPROFILE%/scons/site_scons
840 %LOCALAPPDATA%/scons/site_scons
841 %APPDATA%/scons/site_scons
842 %USERPROFILE%/.scons/site_scons
843 ./site_scons
844 Note earlier versions of the documentation listed a different
846 path for the "system" site directory, this path is still
847 checked but its use is discouraged:
848 %ALLUSERSPROFILE%/Application Data/scons/site_scons
850 Mac OS X:
852 /Library/Application Support/SCons/site_scons
854 /opt/local/share/scons/site_scons (for MacPorts)
855 /sw/share/scons/site_scons (for Fink)
856 $HOME/Library/Application Support/SCons/site_scons
857 $HOME/.scons/site_scons
858 ./site_scons
859 Solaris:
861 /opt/sfw/scons/site_scons
863 /usr/share/scons/site_scons
864 $HOME/.scons/site_scons
865 ./site_scons
866 Linux, HPUX, and other Posix-like systems:
868 /usr/share/scons/site_scons
870 $HOME/.scons/site_scons
871 ./site_scons
872 --stack-size=KILOBYTES
874 Set the size stack used to run threads to KILOBYTES. This value
875 determines the stack size of the threads used to run jobs. These
876 threads execute the actions of the builders for the nodes that are
877 out-of-date. This option has no effect unless the number of
878 concurrent build jobs is larger than one (as set by -j N or
879 --jobs=N on the command line or SetOption in a script).
880 Using a stack size that is too small may cause stack overflow
882 errors. This usually shows up as segmentation faults that cause
883 scons to abort before building anything. Using a stack size that is
884 too large will cause scons to use more memory than required and may
885 slow down the entire build process. The default value is to use a
886 stack size of 256 kilobytes, which should be appropriate for most
887 uses. You should not need to increase this value unless you
888 encounter stack overflow errors.
889 -t, --touch
891 Ignored for compatibility with GNU Make. (Touching a file to make
892 it appear up-to-date is unnecessary when using scons.)
893 --taskmastertrace=file
895 Prints trace information to the specified file about how the
896 internal Taskmaster object evaluates and controls the order in
897 which Nodes are built. A file name of - may be used to specify the
898 standard output.
899 --tree=type[,type...]
901 Prints a tree of the dependencies after each top-level target is
902 built. This prints out some or all of the tree, in various formats,
903 depending on the type specified:
904 all
906 Print the entire dependency tree after each top-level target is
907 built. This prints out the complete dependency tree, including
908 implicit dependencies and ignored dependencies.
909 derived
911 Restricts the tree output to only derived (target) files, not
912 source files.
913 linedraw
915 Draw the tree output using Unicode line-drawing characters
916 instead of plain ASCII text. This option acts as a modifier to
917 the selected type(s). If specified alone, without any type, it
918 behaves as if all had been specified.
919 Available since scons 4.0.
921 status
923 Prints status information for each displayed node.
924 prune
926 Prunes the tree to avoid repeating dependency information for
927 nodes that have already been displayed. Any node that has
928 already been displayed will have its name printed in [square
929 brackets], as an indication that the dependencies for that node
930 can be found by searching for the relevant output higher up in
931 the tree.
932 Multiple type choices may be specified, separated by commas:
934 # Prints only derived files, with status information:
936 scons --tree=derived,status
937 # Prints all dependencies of target, with status information
939 # and pruning dependencies of already-visited Nodes:
940 scons --tree=all,prune,status target
941 -u, --up, --search-up
943 Walks up the directory structure until an SConstruct, Sconstruct,
944 sconstruct, SConstruct.py, Sconstruct.py or sconstruct.py file is
945 found, and uses that as the top of the directory tree. If no
946 targets are specified on the command line, only targets at or below
947 the current directory will be built.
948 -U
950 Works exactly the same way as the -u option except for the way
951 default targets are handled. When this option is used and no
952 targets are specified on the command line, all default targets that
953 are defined in the SConscript(s) in the current directory are
954 built, regardless of what directory the resultant targets end up
955 in.
956 -v, --version
958 Print the scons version, copyright information, list of authors,
959 and any other relevant information. Then exit.
960 -w, --print-directory
962 Print a message containing the working directory before and after
963 other processing.
964 --no-print-directory
966 Turn off -w, even if it was turned on implicitly.
967 --warn=type, --warn=no-type
969 Enable or disable (with the prefix "no-") warnings (--warning is a
970 synonym). type specifies the type of warnings to be enabled or
971 disabled:
972 all
974 All warnings.
975 cache-version
977 Warnings about the derived-file cache directory specified by
978 CacheDir not using the latest configuration information. These
979 warnings are enabled by default.
980 cache-write-error
982 Warnings about errors trying to write a copy of a built file to
983 a specified derived-file cache specified by CacheDir. These
984 warnings are disabled by default.
985 corrupt-sconsign
987 Warnings about unfamiliar signature data in .sconsign files.
988 These warnings are enabled by default.
989 dependency
991 Warnings about dependencies. These warnings are disabled by
992 default.
993 deprecated
995 Warnings about use of currently deprecated features. These
996 warnings are enabled by default. Not all deprecation warnings
997 can be disabled with the --warn=no-deprecated option as some
998 deprecated features which are late in the deprecation cycle may
999 have been designated as mandatory warnings, and these will
1000 still display. Warnings for certain deprecated features may
1001 also be enabled or disabled individually; see below.
1002 duplicate-environment
1004 Warnings about attempts to specify a build of a target with two
1005 different construction environments that use the same action.
1006 These warnings are enabled by default.
1007 fortran-cxx-mix
1009 Warnings about linking Fortran and C++ object files in a single
1010 executable, which can yield unpredictable behavior with some
1011 compilers.
1012 future-deprecated
1014 Warnings about features that will be deprecated in the future.
1015 Such warnings are disabled by default. Enabling future
1016 deprecation warnings is recommended for projects that
1017 redistribute SCons configurations for other users to build, so
1018 that the project can be warned as soon as possible about
1019 to-be-deprecated features that may require changes to the
1020 configuration.
1021 link
1023 Warnings about link steps.
1024 misleading-keywords
1026 Warnings about the use of two commonly misspelled keywords
1027 targets and sources to Builder calls. The correct spelling is
1028 the singular form, even though target and source can themselves
1029 refer to lists of names or nodes.
1030 tool-qt-deprecated
1032 Warnings about the qt tool being deprecated. These warnings are
1033 disabled by default for the first phase of deprecation. Enable
1034 to be reminded about use of this tool module. Available since
1035 SCons 4.3.
1036 missing-sconscript
1038 Warnings about missing SConscript files. These warnings are
1039 enabled by default.
1040 no-object-count
1042 Warnings about the --debug=object feature not working when
1043 scons is run with the Python -O option or from optimized Python
1044 (.pyo) modules.
1045 no-parallel-support
1047 Warnings about the version of Python not being able to support
1048 parallel builds when the -j option is used. These warnings are
1049 enabled by default.
1050 python-version
1052 Warnings about running SCons with a deprecated version of
1053 Python. These warnings are enabled by default.
1054 reserved-variable
1056 Warnings about attempts to set the reserved construction
1057 variable names $CHANGED_SOURCES, $CHANGED_TARGETS, $TARGET,
1058 $TARGETS, $SOURCE, $SOURCES, $UNCHANGED_SOURCES or
1059 $UNCHANGED_TARGETS. These warnings are disabled by default.
1060 stack-size
1062 Warnings about requests to set the stack size that could not be
1063 honored. These warnings are enabled by default.
1064 target_not_build
1066 Warnings about a build rule not building the expected targets.
1067 These warnings are disabled by default.
1068 -Y repository, --repository=repository, --srcdir=repository
1071 Search the specified repository for any input and target files not
1072 found in the local directory hierarchy. Multiple -Y options may be
1073 specified, in which case the repositories are searched in the order
1074 specified.
1075
1077 SConscript Files
1078 The build configuration is described by one or more files, known as
1079 SConscript files. There must be at least one file for a valid build
1080 (scons will quit if it does not find one). scons by default looks for
1081 this file by the name SConstruct in the directory from which you run
1082 scons, though if necessary, also looks for alternative file names
1083 Sconstruct, sconstruct, SConstruct.py, Sconstruct.py and sconstruct.py
1084 in that order. A different file name (which can include a pathname
1085 part) may be specified via the -f option. Except for the SConstruct
1086 file, these files are not searched for automatically; you add
1087 additional configuration files to the build by calling the SConscript
1088 function. This allows parts of the build to be conditionally included
1089 or excluded at run-time depending on how scons is invoked.
1090 Each SConscript file in a build configuration is invoked independently
1092 in a separate context. This provides necessary isolation so that
1093 different parts of the build don't accidentally step on each other. You
1094 have to be explicit about sharing information, by using the Export
1095 function or the exports argument to the SConscript function, as well as
1096 the Return function in a called SConscript file, and comsume shared
1097 information by using the Import function.
1098 The following sections describe the various SCons facilities that can
1100 be used in SConscript files. Quick links:
1101 Construction Environments
1102 Tools
1103 Builder Methods
1104 Methods and Functions to do Things
1105 SConscript Variables
1106 Construction Variables
1107 Configure Contexts
1108 Command-Line Construction Variables
1109 Node Objects
1110 Construction Environments
1112 A Construction Environment is the basic means by which you communicate
1113 build information to SCons. A new construction environment is created
1114 using the Environment function:
1115 env = Environment()
1117 Construction environment attributes called Construction Variables may
1119 be set either by specifying them as keyword arguments when the object
1120 is created or by assigning them a value after the object is created.
1121 These two are nominally equivalent:
1122 env = Environment(FOO='foo')
1124 env['FOO'] = 'foo'
1125 Note that certain settings which affect tool detection are referenced
1127 only when the tools are initializided, so you either need either to
1128 supply them as part of the call to Environment, or defer tool
1129 initialization. For example, initializing the Microsoft Visual C++
1130 version you wish to use:
1131 # initializes msvc to v14.1
1133 env = Environment(MSVC_VERSION="14.1")
1134 env = Environment()
1136 # msvc tool was initialized to default, does not reinitialize
1137 env['MSVC_VERSION'] = "14.1"
1138 env = Environment(tools=[])
1140 env['MSVC_VERSION'] = "14.1"
1141 # msvc tool initialization was deferred, so will pick up new value
1142 env.Tool('default')
1143 As a convenience, construction variables may also be set or modified by
1145 the parse_flags keyword argument during object creation, which has the
1146 effect of the env.MergeFlags method being applied to the argument value
1147 after all other processing is completed. This is useful either if the
1148 exact content of the flags is unknown (for example, read from a control
1149 file) or if the flags need to be distributed to a number of
1150 construction variables. env.ParseFlags describes how these arguments
1151 are distributed to construction variables.
1152 env = Environment(parse_flags='-Iinclude -DEBUG -lm')
1154 This example adds 'include' to the $CPPPATH construction variable,
1156 'EBUG' to $CPPDEFINES, and 'm' to $LIBS.
1157 An existing construction environment can be duplicated by calling the
1159 env.Clone method. Without arguments, it will be a copy with the same
1160 settings. Otherwise, env.Clone takes the same arguments as Environment,
1161 and uses the arguments to create a modified copy.
1162 SCons provides a special construction environment called the Default
1164 Environment. The default environment is used only for global functions,
1165 that is, construction activities called without the context of a
1166 regular construction environment. See DefaultEnvironment for more
1167 information.
1168 By default, a new construction environment is initialized with a set of
1170 builder methods and construction variables that are appropriate for the
1171 current platform. The optional platform keyword argument may be used to
1172 specify that the construction environment should be initialized for a
1173 different platform:
1174 env = Environment(platform='cygwin')
1176 Specifying a platform initializes the appropriate construction
1178 variables in the environment to use and generate file names with
1179 prefixes and suffixes appropriate for that platform.
1180 Note that the win32 platform adds the SystemDrive and SystemRoot
1182 variables from the user's external environment to the construction
1183 environment's ENV dictionary. This is so that any executed commands
1184 that use sockets to connect with other systems will work on Windows
1185 systems.
1186 The platform argument may be a string value representing one of the
1188 pre-defined platforms (aix, cygwin, darwin, hpux, irix, os2, posix,
1189 sunos or win32), or it may be be a callable platform object returned by
1190 a call to Platform selecting a pre-defined platform, or it may be a
1191 user-supplied callable, in which case the Environment method will call
1192 it to update the new construction environment:
1193 def my_platform(env):
1195 env['VAR'] = 'xyzzy'
1196 env = Environment(platform=my_platform)
1198 Note that supplying a non-default platform or custom fuction for
1200 initialization may bypass settings that should happen for the host
1201 system and should be used with care. It is most useful in the case
1202 where the platform is an alternative for the one that would be
1203 auto-detected, such as platform="cygwin" on a system which would
1204 otherwise identify as win32.
1205 The optional tools and toolpath keyword arguments affect the way tools
1207 available to the environment are initialized. See the section called
1208 “Tools” for details.
1209 The optional variables keyword argument allows passing a Variables
1211 object which will be used in the initialization of the construction
1212 environment See the section called “Command-Line Construction
1213 Variables” for details.
1214 Tools
1216 SCons has a large number of predefined tool modules (more properly,
1217 tool specification modules) which are used to help initialize the
1218 construction environment. An SCons tool is only responsible for setup.
1219 For example, if an SConscript file declares the need to construct an
1220 object file from a C-language source file by calling the Object
1221 builder, then a tool representing an available C compiler needs to have
1222 run first, to set up that builder and all the construction variables it
1223 needs in the associated construction environment; the tool itself is
1224 not called in the process of the build. Normally this happens invisibly
1225 as scons has per-platform lists of default tools, and it steps through
1226 those tools, calling the ones which are actually applicable, skipping
1227 those where necessary programs are not installed on the build system,
1228 or other preconditions are not met.
1229 A specific set of tools with which to initialize an environment when
1231 creating it may be specified using the optional keyword argument tools,
1232 which takes a list of tool names. This is useful to override the
1233 defaults, to specify non-default built-in tools, and to supply added
1234 tools:
1235 env = Environment(tools=['msvc', 'lex'])
1237 Tools can also be directly called by using the Tool method (see below).
1239 The tools argument overrides the default tool list, it does not add to
1241 it, so be sure to include all the tools you need. For example if you
1242 are building a c/c++ program you must specify a tool for at least a
1243 compiler and a linker, as in tools=['clang', 'link']. The tool name
1244 'default' can be used to retain the default list.
1245 If no tools argument is specified, or if tools includes 'default', then
1247 scons will auto-detect usable tools, using the execution environment
1248 value of PATH (that is, env['ENV']['PATH'] - the external evironment
1249 PATH from os.environ is not used) for looking up any backing programs,
1250 and the platform name in effect to determine the default tools for that
1251 platform. Changing the PATH variable after the construction environment
1252 is constructed will not cause the tools to be re-detected.
1253 Additional tools can be added, see the Extending SCons section and
1255 specifically Tool Modules.
1256 SCons supports the following tool specifications out of the box:
1258 386asm
1260 Sets construction variables for the 386ASM assembler for the Phar
1261 Lap ETS embedded operating system.
1262 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1264 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1266 aixc++
1268 Sets construction variables for the IMB xlc / Visual Age C++
1269 compiler.
1270 Sets: $CXX, $CXXVERSION, $SHCXX, $SHOBJSUFFIX.
1272 aixcc
1274 Sets construction variables for the IBM xlc / Visual Age C
1275 compiler.
1276 Sets: $CC, $CCVERSION, $SHCC.
1278 aixf77
1280 Sets construction variables for the IBM Visual Age f77 Fortran
1281 compiler.
1282 Sets: $F77, $SHF77.
1284 aixlink
1286 Sets construction variables for the IBM Visual Age linker.
1287 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1289 applelink
1291 Sets construction variables for the Apple linker (similar to the
1292 GNU linker).
1293 Sets: $APPLELINK_COMPATIBILITY_VERSION, $APPLELINK_CURRENT_VERSION,
1295 $APPLELINK_NO_COMPATIBILITY_VERSION, $APPLELINK_NO_CURRENT_VERSION,
1296 $FRAMEWORKPATHPREFIX, $LDMODULECOM, $LDMODULEFLAGS,
1297 $LDMODULEPREFIX, $LDMODULESUFFIX, $LINKCOM, $SHLINKCOM,
1298 $SHLINKFLAGS, $_APPLELINK_COMPATIBILITY_VERSION,
1299 $_APPLELINK_CURRENT_VERSION, $_FRAMEWORKPATH, $_FRAMEWORKS.
1300 Uses: $FRAMEWORKSFLAGS.
1302 ar
1304 Sets construction variables for the ar library archiver.
1305 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $RANLIB,
1307 $RANLIBCOM, $RANLIBFLAGS.
1308 as
1310 Sets construction variables for the as assembler.
1311 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1313 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1315 bcc32
1317 Sets construction variables for the bcc32 compiler.
1318 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1320 $CPPDEFSUFFIX, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS,
1321 $SHCFLAGS, $SHOBJSUFFIX.
1322 Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS.
1324 cc
1326 Sets construction variables for generic POSIX C compilers.
1327 Sets: $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CFILESUFFIX, $CFLAGS,
1329 $CPPDEFPREFIX, $CPPDEFSUFFIX, $FRAMEWORKPATH, $FRAMEWORKS,
1330 $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS,
1331 $SHOBJSUFFIX.
1332 Uses: $CCCOMSTR, $PLATFORM, $SHCCCOMSTR.
1334 clang
1336 Set construction variables for the Clang C compiler.
1337 Sets: $CC, $CCDEPFLAGS, $CCVERSION, $SHCCFLAGS.
1339 clangxx
1341 Set construction variables for the Clang C++ compiler.
1342 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX,
1344 $STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME.
1345 compilation_db
1347 Sets up CompilationDatabase builder which generates a clang tooling
1348 compatible compilation database.
1349 Sets: $COMPILATIONDB_COMSTR, $COMPILATIONDB_PATH_FILTER,
1351 $COMPILATIONDB_USE_ABSPATH.
1352 cvf
1354 Sets construction variables for the Compaq Visual Fortran compiler.
1355 Sets: $FORTRAN, $FORTRANCOM, $FORTRANMODDIR, $FORTRANMODDIRPREFIX,
1357 $FORTRANMODDIRSUFFIX, $FORTRANPPCOM, $OBJSUFFIX, $SHFORTRANCOM,
1358 $SHFORTRANPPCOM.
1359 Uses: $CPPFLAGS, $FORTRANFLAGS, $SHFORTRANFLAGS, $_CPPDEFFLAGS,
1361 $_FORTRANINCFLAGS, $_FORTRANMODFLAG.
1362 cXX
1364 Sets construction variables for generic POSIX C++ compilers.
1365 Sets: $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX,
1367 $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJSUFFIX, $SHCXX, $SHCXXCOM,
1368 $SHCXXFLAGS, $SHOBJSUFFIX.
1369 Uses: $CXXCOMSTR, $SHCXXCOMSTR.
1371 cyglink
1373 Set construction variables for cygwin linker/loader.
1374 Sets: $IMPLIBPREFIX, $IMPLIBSUFFIX, $LDMODULEVERSIONFLAGS,
1376 $LINKFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBPREFIX, $SHLIBSUFFIX,
1377 $SHLIBVERSIONFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1378 $_LDMODULEVERSIONFLAGS, $_SHLIBVERSIONFLAGS.
1379 default
1381 Sets construction variables for a default list of Tool modules. Use
1382 default in the tools list to retain the original defaults, since
1383 the tools parameter is treated as a literal statement of the tools
1384 to be made available in that construction environment, not an
1385 addition.
1386 The list of tools selected by default is not static, but is
1388 dependent both on the platform and on the software installed on the
1389 platform. Some tools will not initialize if an underlying command
1390 is not found, and some tools are selected from a list of choices on
1391 a first-found basis. The finished tool list can be examined by
1392 inspecting the $TOOLS construction variable in the construction
1393 environment.
1394 On all platforms, the tools from the following list are selected if
1396 their respective conditions are met: filesystem;, wix, lex, yacc,
1397 rpcgen, swig, jar, javac, javah, rmic, dvipdf, dvips, gs, tex,
1398 latex, pdflatex, pdftex, tar, zip, textfile.
1399 On Linux systems, the default tools list selects (first-found): a C
1401 compiler from gcc, intelc, icc, cc; a C++ compiler from g++,
1402 intelc, icc, cXX; an assembler from gas, nasm, masm; a linker from
1403 gnulink, ilink; a Fortran compiler from gfortran, g77, ifort, ifl,
1404 f95, f90, f77; and a static archiver ar. It also selects all found
1405 from the list m4 rpm.
1406 On Windows systems, the default tools list selects (first-found): a
1408 C compiler from msvc, mingw, gcc, intelc, icl, icc, cc, bcc32; a
1409 C++ compiler from msvc, intelc, icc, g++, cXX, bcc32; an assembler
1410 from masm, nasm, gas, 386asm; a linker from mslink, gnulink, ilink,
1411 linkloc, ilink32; a Fortran compiler from gfortran, g77, ifl, cvf,
1412 f95, f90, fortran; and a static archiver from mslib, ar, tlib; It
1413 also selects all found from the list msvs, midl.
1414 On MacOS systems, the default tools list selects (first-found): a C
1416 compiler from gcc, cc; a C++ compiler from g++, cXX; an assembler
1417 as; a linker from applelink, gnulink; a Fortran compiler from
1418 gfortran, f95, f90, g77; and a static archiver ar. It also selects
1419 all found from the list m4, rpm.
1420 Default lists for other platforms can be found by examining the
1422 scons source code (see SCons/Tool/__init__.py).
1423 dmd
1425 Sets construction variables for D language compiler DMD.
1426 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1428 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1429 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1430 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1431 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1432 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1433 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1434 $SHDLINKCOM, $SHDLINKFLAGS.
1435 docbook
1437 This tool tries to make working with Docbook in SCons a little
1438 easier. It provides several toolchains for creating different
1439 output formats, like HTML or PDF. Contained in the package is a
1440 distribution of the Docbook XSL stylesheets as of version 1.76.1.
1441 As long as you don't specify your own stylesheets for
1442 customization, these official versions are picked as
1443 default...which should reduce the inevitable setup hassles for you.
1444 Implicit dependencies to images and XIncludes are detected
1446 automatically if you meet the HTML requirements. The additional
1447 stylesheet utils/xmldepend.xsl by Paul DuBois is used for this
1448 purpose.
1449 Note, that there is no support for XML catalog resolving offered!
1451 This tool calls the XSLT processors and PDF renderers with the
1452 stylesheets you specified, that's it. The rest lies in your hands
1453 and you still have to know what you're doing when resolving names
1454 via a catalog.
1455 For activating the tool "docbook", you have to add its name to the
1457 Environment constructor, like this
1458 env = Environment(tools=['docbook'])
1460 On its startup, the docbook tool tries to find a required xsltproc
1462 processor, and a PDF renderer, e.g. fop. So make sure that these
1463 are added to your system's environment PATH and can be called
1464 directly without specifying their full path.
1465 For the most basic processing of Docbook to HTML, you need to have
1467 installed
1468 • the Python lxml binding to libxml2, or
1470 • a standalone XSLT processor, currently detected are xsltproc,
1472 saxon, saxon-xslt and xalan.
1473 Rendering to PDF requires you to have one of the applications fop
1475 or xep installed.
1476 Creating a HTML or PDF document is very simple and straightforward.
1478 Say
1479 env = Environment(tools=['docbook'])
1481 env.DocbookHtml('manual.html', 'manual.xml')
1482 env.DocbookPdf('manual.pdf', 'manual.xml')
1483 to get both outputs from your XML source manual.xml. As a shortcut,
1485 you can give the stem of the filenames alone, like this:
1486 env = Environment(tools=['docbook'])
1488 env.DocbookHtml('manual')
1489 env.DocbookPdf('manual')
1490 and get the same result. Target and source lists are also
1492 supported:
1493 env = Environment(tools=['docbook'])
1495 env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])
1496 or even
1498 env = Environment(tools=['docbook'])
1500 env.DocbookHtml(['manual','reference'])
1501 Important
1504 Whenever you leave out the list of sources, you may not specify
1505 a file extension! The Tool uses the given names as file stems,
1506 and adds the suffixes for target and source files accordingly.
1507 The rules given above are valid for the Builders DocbookHtml,
1508 DocbookPdf, DocbookEpub, DocbookSlidesPdf and DocbookXInclude. For
1509 the DocbookMan transformation you can specify a target name, but
1510 the actual output names are automatically set from the refname
1511 entries in your XML source.
1512 The Builders DocbookHtmlChunked, DocbookHtmlhelp and
1514 DocbookSlidesHtml are special, in that:
1515 1. they create a large set of files, where the exact names and
1517 their number depend on the content of the source file, and
1518 2. the main target is always named index.html, i.e. the output
1520 name for the XSL transformation is not picked up by the
1521 stylesheets.
1522 As a result, there is simply no use in specifying a target HTML
1524 name. So the basic syntax for these builders is always:
1525 env = Environment(tools=['docbook'])
1527 env.DocbookHtmlhelp('manual')
1528 If you want to use a specific XSL file, you can set the additional
1530 xsl parameter to your Builder call as follows:
1531 env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl')
1533 Since this may get tedious if you always use the same local naming
1535 for your customized XSL files, e.g. html.xsl for HTML and pdf.xsl
1536 for PDF output, a set of variables for setting the default XSL name
1537 is provided. These are:
1538 DOCBOOK_DEFAULT_XSL_HTML
1540 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
1541 DOCBOOK_DEFAULT_XSL_HTMLHELP
1542 DOCBOOK_DEFAULT_XSL_PDF
1543 DOCBOOK_DEFAULT_XSL_EPUB
1544 DOCBOOK_DEFAULT_XSL_MAN
1545 DOCBOOK_DEFAULT_XSL_SLIDESPDF
1546 DOCBOOK_DEFAULT_XSL_SLIDESHTML
1547 and you can set them when constructing your environment:
1549 env = Environment(
1551 tools=['docbook'],
1552 DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
1553 DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl',
1554 )
1555 env.DocbookHtml('manual') # now uses html.xsl
1556 Sets: $DOCBOOK_DEFAULT_XSL_EPUB, $DOCBOOK_DEFAULT_XSL_HTML,
1558 $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED, $DOCBOOK_DEFAULT_XSL_HTMLHELP,
1559 $DOCBOOK_DEFAULT_XSL_MAN, $DOCBOOK_DEFAULT_XSL_PDF,
1560 $DOCBOOK_DEFAULT_XSL_SLIDESHTML, $DOCBOOK_DEFAULT_XSL_SLIDESPDF,
1561 $DOCBOOK_FOP, $DOCBOOK_FOPCOM, $DOCBOOK_FOPFLAGS, $DOCBOOK_XMLLINT,
1562 $DOCBOOK_XMLLINTCOM, $DOCBOOK_XMLLINTFLAGS, $DOCBOOK_XSLTPROC,
1563 $DOCBOOK_XSLTPROCCOM, $DOCBOOK_XSLTPROCFLAGS,
1564 $DOCBOOK_XSLTPROCPARAMS.
1565 Uses: $DOCBOOK_FOPCOMSTR, $DOCBOOK_XMLLINTCOMSTR,
1567 $DOCBOOK_XSLTPROCCOMSTR.
1568 dvi
1570 Attaches the DVI builder to the construction environment.
1571 dvipdf
1573 Sets construction variables for the dvipdf utility.
1574 Sets: $DVIPDF, $DVIPDFCOM, $DVIPDFFLAGS.
1576 Uses: $DVIPDFCOMSTR.
1578 dvips
1580 Sets construction variables for the dvips utility.
1581 Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX.
1583 Uses: $PSCOMSTR.
1585 f03
1587 Set construction variables for generic POSIX Fortran 03 compilers.
1588 Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM,
1590 $SHF03FLAGS, $SHF03PPCOM, $_F03INCFLAGS.
1591 Uses: $F03COMSTR, $F03PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF03COMSTR,
1593 $SHF03PPCOMSTR.
1594 f08
1596 Set construction variables for generic POSIX Fortran 08 compilers.
1597 Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM,
1599 $SHF08FLAGS, $SHF08PPCOM, $_F08INCFLAGS.
1600 Uses: $F08COMSTR, $F08PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF08COMSTR,
1602 $SHF08PPCOMSTR.
1603 f77
1605 Set construction variables for generic POSIX Fortran 77 compilers.
1606 Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM,
1608 $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHF77,
1609 $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM,
1610 $SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS.
1611 Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMMONFLAGS,
1613 $FORTRANCOMSTR, $FORTRANFLAGS, $FORTRANPPCOMSTR, $SHF77COMSTR,
1614 $SHF77PPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANFLAGS,
1615 $SHFORTRANPPCOMSTR.
1616 f90
1618 Set construction variables for generic POSIX Fortran 90 compilers.
1619 Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM,
1621 $SHF90FLAGS, $SHF90PPCOM, $_F90INCFLAGS.
1622 Uses: $F90COMSTR, $F90PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF90COMSTR,
1624 $SHF90PPCOMSTR.
1625 f95
1627 Set construction variables for generic POSIX Fortran 95 compilers.
1628 Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM,
1630 $SHF95FLAGS, $SHF95PPCOM, $_F95INCFLAGS.
1631 Uses: $F95COMSTR, $F95PPCOMSTR, $FORTRANCOMMONFLAGS, $SHF95COMSTR,
1633 $SHF95PPCOMSTR.
1634 fortran
1636 Set construction variables for generic POSIX Fortran compilers.
1637 Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN,
1639 $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM.
1640 Uses: $CPPFLAGS, $FORTRANCOMSTR, $FORTRANPPCOMSTR,
1642 $SHFORTRANCOMSTR, $SHFORTRANPPCOMSTR, $_CPPDEFFLAGS.
1643 g++
1645 Set construction variables for the g++ C++ compiler.
1646 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX.
1648 g77
1650 Set construction variables for the g77 Fortran compiler.
1651 Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77PPCOM,
1653 $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHF77,
1654 $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM,
1655 $SHFORTRANFLAGS, $SHFORTRANPPCOM.
1656 Uses: $F77FLAGS, $FORTRANCOMMONFLAGS, $FORTRANFLAGS.
1658 gas
1660 Sets construction variables for the gas assembler. Calls the as
1661 tool.
1662 Sets: $AS.
1664 gcc
1666 Set construction variables for the gcc C compiler.
1667 Sets: $CC, $CCDEPFLAGS, $CCVERSION, $SHCCFLAGS.
1669 gdc
1671 Sets construction variables for the D language compiler GDC.
1672 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1674 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1675 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1676 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1677 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1678 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1679 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1680 $SHDLINKCOM, $SHDLINKFLAGS.
1681 gettext
1683 This is actually a toolset, which supports internationalization and
1684 localization of software being constructed with SCons. The toolset
1685 loads following tools:
1686 • xgettext - to extract internationalized messages from source
1690 code to POT file(s),
1691 • msginit - may be optionally used to initialize PO files,
1693 • msgmerge - to update PO files, that already contain translated
1695 messages,
1696 • msgfmt - to compile textual PO file to binary installable MO
1698 file.
1699 When you enable gettext, it internally loads all abovementioned
1701 tools, so you're encouraged to see their individual documentation.
1702 Each of the above tools provides its own builder(s) which may be
1704 used to perform particular activities related to software
1705 internationalization. You may be however interested in top-level
1706 Translate builder.
1707 To use gettext tools add 'gettext' tool to your environment:
1709 env = Environment( tools = ['default', 'gettext'] )
1711 gfortran
1713 Sets construction variables for the GNU Fortran compiler. Calls the
1714 fortran Tool module to set variables.
1715 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1717 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1718 gnulink
1720 Set construction variables for GNU linker/loader.
1721 Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX,
1723 $SHLIBVERSIONFLAGS, $SHLINKFLAGS, $_LDMODULESONAME, $_SHLIBSONAME.
1724 gs
1726 This Tool sets the required construction variables for working with
1727 the Ghostscript software. It also registers an appropriate Action
1728 with the PDF Builder, such that the conversion from PS/EPS to PDF
1729 happens automatically for the TeX/LaTeX toolchain. Finally, it adds
1730 an explicit Gs Builder for Ghostscript to the environment.
1731 Sets: $GS, $GSCOM, $GSFLAGS.
1733 Uses: $GSCOMSTR.
1735 hpc++
1737 Set construction variables for the compilers aCC on HP/UX systems.
1738 hpcc
1740 Set construction variables for aCC compilers on HP/UX systems.
1741 Calls the cXX tool for additional variables.
1742 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS.
1744 hplink
1746 Sets construction variables for the linker on HP/UX systems.
1747 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1749 icc
1751 Sets construction variables for the icc compiler on OS/2 systems.
1752 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1754 $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX.
1755 Uses: $CCFLAGS, $CFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1757 icl
1759 Sets construction variables for the Intel C/C++ compiler. Calls the
1760 intelc Tool module to set its variables.
1761 ifl
1763 Sets construction variables for the Intel Fortran compiler.
1764 Sets: $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHFORTRANCOM,
1766 $SHFORTRANPPCOM.
1767 Uses: $CPPFLAGS, $FORTRANFLAGS, $_CPPDEFFLAGS, $_FORTRANINCFLAGS.
1769 ifort
1771 Sets construction variables for newer versions of the Intel Fortran
1772 compiler for Linux.
1773 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1775 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1776 ilink
1778 Sets construction variables for the ilink linker on OS/2 systems.
1779 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1781 $LINK, $LINKCOM, $LINKFLAGS.
1782 ilink32
1784 Sets construction variables for the Borland ilink32 linker.
1785 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1787 $LINK, $LINKCOM, $LINKFLAGS.
1788 install
1790 Sets construction variables for file and directory installation.
1791 Sets: $INSTALL, $INSTALLSTR.
1793 intelc
1795 Sets construction variables for the Intel C/C++ compiler (Linux and
1796 Windows, version 7 and later). Calls the gcc or msvc (on Linux and
1797 Windows, respectively) tool to set underlying variables.
1798 Sets: $AR, $CC, $CXX, $INTEL_C_COMPILER_VERSION, $LINK.
1800 jar
1802 Sets construction variables for the jar utility.
1803 Sets: $JAR, $JARCOM, $JARFLAGS, $JARSUFFIX.
1805 Uses: $JARCOMSTR.
1807 javac
1809 Sets construction variables for the javac compiler.
1810 Sets: $JAVABOOTCLASSPATH, $JAVAC, $JAVACCOM, $JAVACFLAGS,
1812 $JAVACLASSPATH, $JAVACLASSSUFFIX, $JAVAINCLUDES, $JAVASOURCEPATH,
1813 $JAVASUFFIX.
1814 Uses: $JAVACCOMSTR.
1816 javah
1818 Sets construction variables for the javah tool.
1819 Sets: $JAVACLASSSUFFIX, $JAVAH, $JAVAHCOM, $JAVAHFLAGS.
1821 Uses: $JAVACLASSPATH, $JAVAHCOMSTR.
1823 latex
1825 Sets construction variables for the latex utility.
1826 Sets: $LATEX, $LATEXCOM, $LATEXFLAGS.
1828 Uses: $LATEXCOMSTR.
1830 ldc
1832 Sets construction variables for the D language compiler LDC2.
1833 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1835 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1836 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1837 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1838 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1839 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1840 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1841 $SHDLINKCOM, $SHDLINKFLAGS.
1842 lex
1844 Sets construction variables for the lex lexical analyser.
1845 Sets: $LEX, $LEXCOM, $LEXFLAGS, $LEXUNISTD.
1847 Uses: $LEXCOMSTR, $LEXFLAGS, $LEX_HEADER_FILE, $LEX_TABLES_FILE.
1849 link
1851 Sets construction variables for generic POSIX linkers. This is a
1852 "smart" linker tool which selects a compiler to complete the
1853 linking based on the types of source files.
1854 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS,
1856 $LDMODULENOVERSIONSYMLINKS, $LDMODULEPREFIX, $LDMODULESUFFIX,
1857 $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREFIX,
1858 $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM,
1859 $LINKFLAGS, $SHLIBSUFFIX, $SHLINK, $SHLINKCOM, $SHLINKFLAGS,
1860 $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS.
1861 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $SHLINKCOMSTR.
1863 linkloc
1865 Sets construction variables for the LinkLoc linker for the Phar Lap
1866 ETS embedded operating system.
1867 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1869 $LINK, $LINKCOM, $LINKFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
1870 Uses: $LINKCOMSTR, $SHLINKCOMSTR.
1872 m4
1874 Sets construction variables for the m4 macro processor.
1875 Sets: $M4, $M4COM, $M4FLAGS.
1877 Uses: $M4COMSTR.
1879 masm
1881 Sets construction variables for the Microsoft assembler.
1882 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1884 Uses: $ASCOMSTR, $ASPPCOMSTR, $CPPFLAGS, $_CPPDEFFLAGS,
1886 $_CPPINCFLAGS.
1887 midl
1889 Sets construction variables for the Microsoft IDL compiler.
1890 Sets: $MIDL, $MIDLCOM, $MIDLFLAGS.
1892 Uses: $MIDLCOMSTR.
1894 mingw
1896 Sets construction variables for MinGW (Minimal Gnu on Windows).
1897 Sets: $AS, $CC, $CXX, $LDMODULECOM, $LIBPREFIX, $LIBSUFFIX,
1899 $OBJSUFFIX, $RC, $RCCOM, $RCFLAGS, $RCINCFLAGS, $RCINCPREFIX,
1900 $RCINCSUFFIX, $SHCCFLAGS, $SHCXXFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1901 $SHOBJSUFFIX, $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX.
1902 Uses: $RCCOMSTR, $SHLINKCOMSTR.
1904 msgfmt
1906 This scons tool is a part of scons gettext toolset. It provides
1907 scons interface to msgfmt(1) command, which generates binary
1908 message catalog (MO) from a textual translation description (PO).
1909 Sets: $MOSUFFIX, $MSGFMT, $MSGFMTCOM, $MSGFMTCOMSTR, $MSGFMTFLAGS,
1911 $POSUFFIX.
1912 Uses: $LINGUAS_FILE.
1914 msginit
1916 This scons tool is a part of scons gettext toolset. It provides
1917 scons interface to msginit(1) program, which creates new PO file,
1918 initializing the meta information with values from user's
1919 environment (or options).
1920 Sets: $MSGINIT, $MSGINITCOM, $MSGINITCOMSTR, $MSGINITFLAGS,
1922 $POAUTOINIT, $POCREATE_ALIAS, $POSUFFIX, $POTSUFFIX,
1923 $_MSGINITLOCALE.
1924 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1926 msgmerge
1928 This scons tool is a part of scons gettext toolset. It provides
1929 scons interface to msgmerge(1) command, which merges two Uniform
1930 style .po files together.
1931 Sets: $MSGMERGE, $MSGMERGECOM, $MSGMERGECOMSTR, $MSGMERGEFLAGS,
1933 $POSUFFIX, $POTSUFFIX, $POUPDATE_ALIAS.
1934 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1936 mslib
1938 Sets construction variables for the Microsoft mslib library
1939 archiver.
1940 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
1942 Uses: $ARCOMSTR.
1944 mslink
1946 Sets construction variables for the Microsoft linker.
1947 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX,
1949 $LDMODULESUFFIX, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
1950 $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $REGSVR, $REGSVRCOM,
1951 $REGSVRFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS, $WINDOWSDEFPREFIX,
1952 $WINDOWSDEFSUFFIX, $WINDOWSEXPPREFIX, $WINDOWSEXPSUFFIX,
1953 $WINDOWSPROGMANIFESTPREFIX, $WINDOWSPROGMANIFESTSUFFIX,
1954 $WINDOWSSHLIBMANIFESTPREFIX, $WINDOWSSHLIBMANIFESTSUFFIX,
1955 $WINDOWS_INSERT_DEF.
1956 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $REGSVRCOMSTR, $SHLINKCOMSTR.
1958 mssdk
1960 Sets variables for Microsoft Platform SDK and/or Windows SDK. Note
1961 that unlike most other Tool modules, mssdk does not set
1962 construction variables, but sets the environment variables in the
1963 environment SCons uses to execute the Microsoft toolchain:
1964 %INCLUDE%, %LIB%, %LIBPATH% and %PATH%.
1965 Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION.
1967 msvc
1969 Sets construction variables for the Microsoft Visual C/C++
1970 compiler.
1971 Sets: $BUILDERS, $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS, $CCPCHFLAGS,
1973 $CCPDBFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1974 $CXX, $CXXCOM, $CXXFILESUFFIX, $CXXFLAGS, $INCPREFIX, $INCSUFFIX,
1975 $OBJPREFIX, $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM,
1976 $RCFLAGS, $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHCXX,
1977 $SHCXXCOM, $SHCXXFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.
1978 Uses: $CCCOMSTR, $CXXCOMSTR, $MSVC_NOTFOUND_POLICY, $PCH, $PCHSTOP,
1980 $PDB, $SHCCCOMSTR, $SHCXXCOMSTR.
1981 msvs
1983 Sets construction variables for Microsoft Visual Studio.
1984 Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM,
1986 $MSVSREBUILDCOM, $MSVSSCONS, $MSVSSCONSCOM, $MSVSSCONSCRIPT,
1987 $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM.
1988 mwcc
1990 Sets construction variables for the Metrowerks CodeWarrior
1991 compiler.
1992 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1994 $CXX, $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX,
1995 $MWCW_VERSION, $MWCW_VERSIONS, $SHCC, $SHCCCOM, $SHCCFLAGS,
1996 $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS.
1997 Uses: $CCCOMSTR, $CXXCOMSTR, $SHCCCOMSTR, $SHCXXCOMSTR.
1999 mwld
2001 Sets construction variables for the Metrowerks CodeWarrior linker.
2002 Sets: $AR, $ARCOM, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
2004 $LIBLINKSUFFIX, $LINK, $LINKCOM, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
2005 nasm
2007 Sets construction variables for the nasm Netwide Assembler.
2008 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
2010 Uses: $ASCOMSTR, $ASPPCOMSTR.
2012 ninja
2014 Sets up the Ninja builder, which generates a ninja build file, and
2015 then optionally runs ninja.
2016 Note
2018 This is an experimental feature. This functionality is subject
2019 to change and/or removal without a deprecation cycle.
2020 Sets: $IMPLICIT_COMMAND_DEPENDENCIES, $NINJA_ALIAS_NAME,
2021 $NINJA_CMD_ARGS, $NINJA_COMPDB_EXPAND, $NINJA_DEPFILE_PARSE_FORMAT,
2022 $NINJA_DIR, $NINJA_DISABLE_AUTO_RUN, $NINJA_ENV_VAR_CACHE,
2023 $NINJA_FILE_NAME, $NINJA_FORCE_SCONS_BUILD,
2024 $NINJA_GENERATED_SOURCE_ALIAS_NAME,
2025 $NINJA_GENERATED_SOURCE_SUFFIXES, $NINJA_MSVC_DEPS_PREFIX,
2026 $NINJA_POOL, $NINJA_REGENERATE_DEPS,
2027 $NINJA_SCONS_DAEMON_KEEP_ALIVE, $NINJA_SCONS_DAEMON_PORT,
2028 $NINJA_SYNTAX, $_NINJA_REGENERATE_DEPS_FUNC.
2029 Uses: $AR, $ARCOM, $ARFLAGS, $CC, $CCCOM, $CCDEPFLAGS, $CCFLAGS,
2031 $CXX, $CXXCOM, $ESCAPE, $LINK, $LINKCOM, $PLATFORM,
2032 $PRINT_CMD_LINE_FUNC, $PROGSUFFIX, $RANLIB, $RANLIBCOM, $SHCCCOM,
2033 $SHCXXCOM, $SHLINK, $SHLINKCOM.
2034 packaging
2036 Sets construction variables for the Package Builder. If this tool
2037 is enabled, the --package-type command-line option is also enabled.
2038 pdf
2040 Sets construction variables for the Portable Document Format
2041 builder.
2042 Sets: $PDFPREFIX, $PDFSUFFIX.
2044 pdflatex
2046 Sets construction variables for the pdflatex utility.
2047 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS.
2049 Uses: $PDFLATEXCOMSTR.
2051 pdftex
2053 Sets construction variables for the pdftex utility.
2054 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS,
2056 $PDFTEX, $PDFTEXCOM, $PDFTEXFLAGS.
2057 Uses: $PDFLATEXCOMSTR, $PDFTEXCOMSTR.
2059 python
2061 Loads the Python source scanner into the invoking environment. When
2062 loaded, the scanner will attempt to find implicit dependencies for
2063 any Python source files in the list of sources provided to an
2064 Action that uses this environment.
2065 Available since scons 4.0..
2067 qt
2069 Sets construction variables for building Qt3 applications.
2070 Note
2072 This tool is only suitable for building targeted to Qt3, which
2073 is obsolete (the tool is deprecated since 4.3). There are
2074 contributed tools for Qt4 and Qt5, see
2075 https://github.com/SCons/scons-contrib[1]. Qt4 has also passed
2076 end of life for standard support (in Dec 2015).
2077 Note paths for these construction variables are assembled using the
2078 os.path.join method so they will have the appropriate separator at
2079 runtime, but are listed here in the various entries only with the
2080 '/' separator for simplicity.
2081 In addition, the construction variables $CPPPATH, $LIBPATH and
2083 $LIBS may be modified and the variables $PROGEMITTER, $SHLIBEMITTER
2084 and $LIBEMITTER are modified. Because the build-performance is
2085 affected when using this tool, you have to explicitly specify it at
2086 Environment creation:
2087 Environment(tools=['default','qt'])
2089 The qt tool supports the following operations:
2091 Automatic moc file generation from header files. You do not have
2094 to specify moc files explicitly, the tool does it for you. However,
2095 there are a few preconditions to do so: Your header file must have
2096 the same filebase as your implementation file and must stay in the
2097 same directory. It must have one of the suffixes .h, .hpp, .H,
2098 .hxx, .hh. You can turn off automatic moc file generation by
2099 setting $QT_AUTOSCAN to False. See also the corresponding Moc
2100 Builder.
2101 Automatic moc file generation from C++ files. As described in the
2104 Qt documentation, include the moc file at the end of the C++ file.
2105 Note that you have to include the file, which is generated by the
2106 transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by
2107 default <basename>.mo. A warning is generated after building the
2108 moc file if you do not include the correct file. If you are using
2109 VariantDir, you may need to specify duplicate=True. You can turn
2110 off automatic moc file generation by setting $QT_AUTOSCAN to False.
2111 See also the corresponding Moc Builder.
2112 Automatic handling of .ui files. The implementation files
2115 generated from .ui files are handled much the same as yacc or lex
2116 files. Each .ui file given as a source of Program, Library or
2117 SharedLibrary will generate three files: the declaration file, the
2118 implementation file and a moc file. Because there are also
2119 generated headers, you may need to specify duplicate=True in calls
2120 to VariantDir. See also the corresponding Uic Builder.
2121 Sets: $QTDIR, $QT_AUTOSCAN, $QT_BINPATH, $QT_CPPPATH, $QT_LIB,
2123 $QT_LIBPATH, $QT_MOC, $QT_MOCCXXPREFIX, $QT_MOCCXXSUFFIX,
2124 $QT_MOCFROMCXXCOM, $QT_MOCFROMCXXFLAGS, $QT_MOCFROMHCOM,
2125 $QT_MOCFROMHFLAGS, $QT_MOCHPREFIX, $QT_MOCHSUFFIX, $QT_UIC,
2126 $QT_UICCOM, $QT_UICDECLFLAGS, $QT_UICDECLPREFIX, $QT_UICDECLSUFFIX,
2127 $QT_UICIMPLFLAGS, $QT_UICIMPLPREFIX, $QT_UICIMPLSUFFIX,
2128 $QT_UISUFFIX.
2129 Uses: $QTDIR.
2131 rmic
2133 Sets construction variables for the rmic utility.
2134 Sets: $JAVACLASSSUFFIX, $RMIC, $RMICCOM, $RMICFLAGS.
2136 Uses: $RMICCOMSTR.
2138 rpcgen
2140 Sets construction variables for building with RPCGEN.
2141 Sets: $RPCGEN, $RPCGENCLIENTFLAGS, $RPCGENFLAGS,
2143 $RPCGENHEADERFLAGS, $RPCGENSERVICEFLAGS, $RPCGENXDRFLAGS.
2144 sgiar
2146 Sets construction variables for the SGI library archiver.
2147 Sets: $AR, $ARCOMSTR, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $SHLINK,
2149 $SHLINKFLAGS.
2150 Uses: $ARCOMSTR, $SHLINKCOMSTR.
2152 sgic++
2154 Sets construction variables for the SGI C++ compiler.
2155 Sets: $CXX, $CXXFLAGS, $SHCXX, $SHOBJSUFFIX.
2157 sgicc
2159 Sets construction variables for the SGI C compiler.
2160 Sets: $CXX, $SHOBJSUFFIX.
2162 sgilink
2164 Sets construction variables for the SGI linker.
2165 Sets: $LINK, $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2167 sunar
2169 Sets construction variables for the Sun library archiver.
2170 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2172 Uses: $ARCOMSTR.
2174 sunc++
2176 Sets construction variables for the Sun C++ compiler.
2177 Sets: $CXX, $CXXVERSION, $SHCXX, $SHCXXFLAGS, $SHOBJPREFIX,
2179 $SHOBJSUFFIX.
2180 suncc
2182 Sets construction variables for the Sun C compiler.
2183 Sets: $CXX, $SHCCFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.
2185 sunf77
2187 Set construction variables for the Sun f77 Fortran compiler.
2188 Sets: $F77, $FORTRAN, $SHF77, $SHF77FLAGS, $SHFORTRAN,
2190 $SHFORTRANFLAGS.
2191 sunf90
2193 Set construction variables for the Sun f90 Fortran compiler.
2194 Sets: $F90, $FORTRAN, $SHF90, $SHF90FLAGS, $SHFORTRAN,
2196 $SHFORTRANFLAGS.
2197 sunf95
2199 Set construction variables for the Sun f95 Fortran compiler.
2200 Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN,
2202 $SHFORTRANFLAGS.
2203 sunlink
2205 Sets construction variables for the Sun linker.
2206 Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2208 swig
2210 Sets construction variables for the SWIG interface compiler.
2211 Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX,
2213 $SWIGDIRECTORSUFFIX, $SWIGFLAGS, $SWIGINCPREFIX, $SWIGINCSUFFIX,
2214 $SWIGPATH, $SWIGVERSION, $_SWIGINCFLAGS.
2215 Uses: $SWIGCOMSTR.
2217 tar
2219 Sets construction variables for the tar archiver.
2220 Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX.
2222 Uses: $TARCOMSTR.
2224 tex
2226 Sets construction variables for the TeX formatter and typesetter.
2227 Sets: $BIBTEX, $BIBTEXCOM, $BIBTEXFLAGS, $LATEX, $LATEXCOM,
2229 $LATEXFLAGS, $MAKEINDEX, $MAKEINDEXCOM, $MAKEINDEXFLAGS, $TEX,
2230 $TEXCOM, $TEXFLAGS.
2231 Uses: $BIBTEXCOMSTR, $LATEXCOMSTR, $MAKEINDEXCOMSTR, $TEXCOMSTR.
2233 textfile
2235 Set construction variables for the Textfile and Substfile builders.
2236 Sets: $LINESEPARATOR, $SUBSTFILEPREFIX, $SUBSTFILESUFFIX,
2238 $TEXTFILEPREFIX, $TEXTFILESUFFIX.
2239 Uses: $SUBST_DICT.
2241 tlib
2243 Sets construction variables for the Borlan tib library archiver.
2244 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2246 Uses: $ARCOMSTR.
2248 xgettext
2250 This scons tool is a part of scons gettext toolset. It provides
2251 scons interface to xgettext(1) program, which extracts
2252 internationalized messages from source code. The tool provides
2253 POTUpdate builder to make PO Template files.
2254 Sets: $POTSUFFIX, $POTUPDATE_ALIAS, $XGETTEXTCOM, $XGETTEXTCOMSTR,
2256 $XGETTEXTFLAGS, $XGETTEXTFROM, $XGETTEXTFROMPREFIX,
2257 $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPATHPREFIX,
2258 $XGETTEXTPATHSUFFIX, $_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS,
2259 $_XGETTEXTPATHFLAGS.
2260 Uses: $POTDOMAIN.
2262 yacc
2264 Sets construction variables for the yacc parse generator.
2265 Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX,
2267 $YACCHXXFILESUFFIX, $YACCVCGFILESUFFIX.
2268 Uses: $YACCCOMSTR, $YACCFLAGS, $YACC_GRAPH_FILE, $YACC_HEADER_FILE.
2270 zip
2272 Sets construction variables for the zip archiver.
2273 Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX.
2275 Uses: $ZIPCOMSTR.
2277 Builder Methods
2279 You tell SCons what to build by calling Builders, functions which take
2280 particular action(s) to produce target(s) of a particular type
2281 (conventionally hinted at by the builder name, e.g. Program) from the
2282 specified source files. A builder call is a declaration: SCons enters
2283 the specified relationship into its internal dependency node graph, and
2284 only later makes the decision on whether anything is actually built,
2285 since this depends on command-line options, target selection rules, and
2286 whether the target(s) are out of date with respect to the sources.
2287 SCons provides a number of builders, and you can also write your own
2289 (see Builder Objects). Builders are created dynamically at run-time,
2290 often (though not always) by tools which determine whether the external
2291 dependencies for the builder are satisfied, and which perform the
2292 necessary setup (see Tools). Builders are attached to a construction
2293 environment as methods. The available builder methods are registered as
2294 key-value pairs in the $BUILDERS attribute of the construction
2295 environment, so the available builders can be examined. This example
2296 displays them for debugging purposes:
2297 env = Environment()
2299 print("Builders:", list(env['BUILDERS']))
2300 Builder methods take two required arguments: target and source. The
2302 target and source arguments can be specified either as positional
2303 arguments, in which case target comes first, or as keyword arguments,
2304 using target= and source=. Although both arguments are nominally
2305 required, if there is a single source and the target can be inferred
2306 the target argument can be omitted (see below). Builder methods also
2307 take a variety of keyword arguments, described below.
2308 Because long lists of file names can lead to a lot of quoting in a
2310 builder call, SCons supplies a Split global function and a same-named
2311 environment method that splits a single string into a list, using
2312 strings of white-space characters as the delimiter (similar to the
2313 Python string split method, but succeeds even if the input isn't a
2314 string).
2315 The following are equivalent examples of calling the Program builder
2317 method:
2318 env.Program('bar', ['bar.c', 'foo.c'])
2320 env.Program('bar', Split('bar.c foo.c'))
2321 env.Program('bar', env.Split('bar.c foo.c'))
2322 env.Program(source=['bar.c', 'foo.c'], target='bar')
2323 env.Program(target='bar', source=Split('bar.c foo.c'))
2324 env.Program(target='bar', source=env.Split('bar.c foo.c'))
2325 env.Program('bar', source='bar.c foo.c'.split())
2326 Sources and targets can be specified as a scalar or as a list, composed
2328 of either strings or nodes (more on nodes below). When specifying path
2329 strings, Python follows the POSIX pathname convention: if a string
2330 begins with the operating system pathname separator (on Windows both
2331 the slash and backslash separator are accepted, and any leading drive
2332 specifier is ignored for the determination) it is considered an
2333 absolute path, otherwise it is a relative path. If the path string
2334 contains no separator characters, it is searched for as a file in the
2335 current directory. If it contains separator characters, the search
2336 follows down from the starting point, which is the top of the directory
2337 tree for an absolute path and the current directory for a relative
2338 path. The "current directory" in this context is the directory of the
2339 SConscript file currently being processed.
2340 SCons also recognizes a third way to specify path strings: if the
2342 string begins with the # character it is top-relative - it works like a
2343 relative path but the search follows down from the directory containing
2344 the top-level SConstruct rather than from the current directory. The #
2345 can optionally be followed by a pathname separator, which is ignored if
2346 found in that position. Top-relative paths only work in places where
2347 scons will interpret the path (see some examples below). To be used in
2348 other contexts the string will need to be converted to a relative or
2349 absolute path first.
2350 Examples:
2352 # The comments describing the targets that will be built
2354 # assume these calls are in a SConscript file in the
2355 # a subdirectory named "subdir".
2356 # Builds the program "subdir/foo" from "subdir/foo.c":
2358 env.Program('foo', 'foo.c')
2359 # Builds the program "/tmp/bar" from "subdir/bar.c":
2361 env.Program('/tmp/bar', 'bar.c')
2362 # An initial '#' or '#/' are equivalent; the following
2364 # calls build the programs "foo" and "bar" (in the
2365 # top-level SConstruct directory) from "subdir/foo.c" and
2366 # "subdir/bar.c", respectively:
2367 env.Program('#foo', 'foo.c')
2368 env.Program('#/bar', 'bar.c')
2369 # Builds the program "other/foo" (relative to the top-level
2371 # SConstruct directory) from "subdir/foo.c":
2372 env.Program('#other/foo', 'foo.c')
2373 # This will not work, only SCons interfaces understand '#',
2375 # os.path.exists is pure Python:
2376 if os.path.exists('#inc/foo.h'):
2377 env.Append(CPPPATH='#inc')
2378 When the target shares the same base name as the source and only the
2380 suffix varies, and if the builder method has a suffix defined for the
2381 target file type, then the target argument may be omitted completely,
2382 and scons will deduce the target file name from the source file name.
2383 The following examples all build the executable program bar (on POSIX
2384 systems) or bar.exe (on Windows systems) from the bar.c source file:
2385 env.Program(target='bar', source='bar.c')
2387 env.Program('bar', source='bar.c')
2388 env.Program(source='bar.c')
2389 env.Program('bar.c')
2390 The optional srcdir keyword argument specifies that all source file
2392 strings that are not absolute paths or top-relative paths shall be
2393 interpreted relative to the specified srcdir. The following example
2394 will build the build/prog (or build/prog.exe on Windows) program from
2395 the files src/f1.c and src/f2.c:
2396 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
2398 The optional parse_flags keyword argument causes behavior similar to
2400 the env.MergeFlags method, where the argument value is broken into
2401 individual settings and merged into the appropriate construction
2402 variables.
2403 env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
2405 This example adds 'include' to the $CPPPATH construction variable,
2407 'EBUG' to $CPPDEFINES, and 'm' to $LIBS.
2408 The optional chdir keyword argument specifies that the Builder's
2410 action(s) should be executed after changing directory. If the chdir
2411 argument is a path string or a directory Node, scons will change to the
2412 specified directory. If the chdir is not a string or Node and evaluates
2413 true, then scons will change to the target file's directory.
2414 Warning
2416 Python only keeps one current directory location even if there are
2417 multiple threads. This means that use of the chdir argument will
2418 not work with the SCons -j option, because individual worker
2419 threads spawned by SCons interfere with each other when they start
2420 changing directory.
2421 # scons will change to the "sub" subdirectory
2423 # before executing the "cp" command.
2424 env.Command(
2425 target='sub/dir/foo.out',
2426 source='sub/dir/foo.in',
2427 action="cp dir/foo.in dir/foo.out",
2428 chdir='sub',
2429 )
2430 # Because chdir is not a string, scons will change to the
2432 # target's directory ("sub/dir") before executing the
2433 # "cp" command.
2434 env.Command('sub/dir/foo.out', 'sub/dir/foo.in', "cp foo.in foo.out", chdir=True)
2435 Note that SCons will not automatically modify its expansion of
2437 construction variables like $TARGET and $SOURCE when using the chdir
2438 keyword argument--that is, the expanded file names will still be
2439 relative to the top-level directory where the SConstruct was found, and
2440 consequently incorrect relative to the chdir directory. If you use the
2441 chdir keyword argument, you will typically need to supply a different
2442 command line using expansions like ${TARGET.file} and ${SOURCE.file} to
2443 use just the filename portion of the target and source.
2444 Keyword arguments that are not specifically recognized are treated as
2446 construction variable overrides, which replace or add those variables
2447 on a limited basis. These overrides will only be in effect when
2448 building the target of the builder call, and will not affect other
2449 parts of the build. For example, if you want to specify some libraries
2450 needed by just one program:
2451 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
2453 or generate a shared library with a non-standard suffix:
2455 env.SharedLibrary(
2457 target='word',
2458 source='word.cpp',
2459 SHLIBSUFFIX='.ocx',
2460 LIBSUFFIXES=['.ocx'],
2461 )
2462 Note that both the $SHLIBSUFFIX and $LIBSUFFIXES construction variables
2464 must be set if you want scons to search automatically for dependencies
2465 on the non-standard library names; see the descriptions of these
2466 variables for more information.
2467 Although the builder methods defined by scons are, in fact, methods of
2469 a construction environment object, many may also be called without an
2470 explicit environment:
2471 Program('hello', 'hello.c')
2473 SharedLibrary('word', 'word.cpp')
2474 If called this way, the builder will internally use the Default
2476 Environment that consists of the tools and values that scons has
2477 determined are appropriate for the local system.
2478 Builder methods that can be called without an explicit environment
2480 (indicated in the listing of builders below without a leading env.) may
2481 be called from custom Python modules that you import into an SConscript
2482 file by adding the following to the Python module:
2483 from SCons.Script import *
2485 A builder may add additional targets beyond those requested if an
2487 attached Emitter chooses to do so (see the section called “Builder
2488 Objects” for more information. $PROGEMITTER is an example). For
2489 example, the GNU linker takes a command-line argument -Map=mapfile,
2490 which causes it to produce a linker map file in addition to the
2491 executable file actually being linked. If the Program builder's emitter
2492 is configured to add this mapfile if the option is set, then two
2493 targets will be returned when you only provided for one.
2494 For this reason, builder methods always return a NodeList, a list-like
2496 object whose elements are Nodes. Nodes are the internal representation
2497 of build targets or sources (see the section called “Node Objects” for
2498 more information). The returned NodeList object can be passed to other
2499 builder methods as source(s) or to other SCons functions or methods
2500 where a path string would normally be accepted.
2501 For example, to add a specific preprocessor define when compiling one
2503 specific object file but not the others:
2504 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2506 env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])
2507 Using a Node as in this example makes for a more portable build by
2509 avoiding having to specify a platform-specific object suffix when
2510 calling the Program builder method.
2511 The NodeList object is also convenient to pass to the Default function,
2513 for the same reason of avoiding a platform-specific name:
2514 tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"])
2516 Default(tgt)
2517 Builder calls will automatically "flatten" lists passed as source and
2519 target, so they are free to contain elements which are themselves
2520 lists, such as bar_obj_list returned by the StaticObject call. If you
2521 need to manipulate a list of lists returned by builders directly in
2522 Python code, you can either build a new list by hand:
2523 foo = Object('foo.c')
2525 bar = Object('bar.c')
2526 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2527 for obj in objects:
2528 print(str(obj))
2529 Or you can use the Flatten function supplied by SCons to create a list
2531 containing just the Nodes, which may be more convenient:
2532 foo = Object('foo.c')
2534 bar = Object('bar.c')
2535 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2536 for obj in objects:
2537 print(str(obj))
2538 Since builder calls return a list-like object, not an actual Python
2540 list, it is not appropriate to use the Python add operator (+ or +=) to
2541 append builder results to a Python list. Because the list and the
2542 object are different types, Python will not update the original list in
2543 place, but will instead create a new NodeList object containing the
2544 concatenation of the list elements and the builder results. This will
2545 cause problems for any other Python variables in your SCons
2546 configuration that still hold on to a reference to the original list.
2547 Instead, use the Python list extend method to make sure the list is
2548 updated in-place. Example:
2549 object_files = []
2551 # Do NOT use += here:
2553 # object_files += Object('bar.c')
2554 #
2555 # It will not update the object_files list in place.
2556 #
2557 # Instead, use the list extend method:
2558 object_files.extend(Object('bar.c'))
2559 The path name for a Node's file may be used by passing the Node to
2561 Python's builtin str function:
2562 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2564 print("The path to bar_obj is:", str(bar_obj_list[0]))
2565 Note that because the Builder call returns a NodeList, you have to
2567 access the first element in the list (bar_obj_list[0] in the example)
2568 to get at the Node that actually represents the object file.
2569 When trying to handle errors that may occur in a builder method,
2571 consider that the corresponding Action is executed at a different time
2572 than the SConscript file statement calling the builder. It is not
2573 useful to wrap a builder call in a try block, since success in the
2574 builder call is not the same as the builder itself succeeding. If
2575 necessary, a Builder's Action should be coded to exit with a useful
2576 exception message indicating the problem in the SConscript files -
2577 programmatically recovering from build errors is rarely useful.
2578 The following builder methods are predefined in the SCons core software
2580 distribution. Depending on the setup of a particular construction
2581 environment and on the type and software installation status of the
2582 underlying system, not all builders may be available in that
2583 construction environment. Since the function calling signature is the
2584 same for all builders:
2585 Buildername(target, source, [key=val, ...])
2587 it is omitted in this listing for brevity.
2589 CFile(), env.CFile()
2591 Builds a C source file given a lex (.l) or yacc (.y) input file.
2592 The suffix specified by the $CFILESUFFIX construction variable (.c
2593 by default) is automatically added to the target if it is not
2594 already present. Example:
2595 # builds foo.c
2597 env.CFile(target = 'foo.c', source = 'foo.l')
2598 # builds bar.c
2599 env.CFile(target = 'bar', source = 'bar.y')
2600 Command(), env.Command()
2602 The Command "Builder" is actually a function that looks like a
2603 Builder, but takes a required third argument, which is the action
2604 to take to construct the target from the source, used for "one-off"
2605 builds where a full builder is not needed. Thus it does not follow
2606 the builder calling rules described at the start of this section.
2607 See instead the Command function description for the calling syntax
2608 and details.
2609 CompilationDatabase(), env.CompilationDatabase()
2611 CompilationDatabase is a special builder which adds a target to
2613 create a JSON formatted compilation database compatible with clang
2614 tooling (see the LLVM specification[2]). This database is suitable
2615 for consumption by various tools and editors who can use it to
2616 obtain build and dependency information which otherwise would be
2617 internal to SCons. The builder does not require any source files to
2618 be specified, rather it arranges to emit information about all of
2619 the C, C++ and assembler source/output pairs identified in the
2620 build that are not excluded by the optional filter
2621 $COMPILATIONDB_PATH_FILTER. The target is subject to the usual
2622 SCons target selection rules.
2623 If called with no arguments, the builder will default to a target
2625 name of compile_commands.json.
2626 If called with a single positional argument, scons will "deduce"
2628 the target name from that source argument, giving it the same name,
2629 and then ignore the source. This is the usual way to call the
2630 builder if a non-default target name is wanted.
2631 If called with either the target= or source= keyword arguments, the
2633 value of the argument is taken as the target name. If called with
2634 both, the target= value is used and source= is ignored. If called
2635 with multiple sources, the source list will be ignored, since there
2636 is no way to deduce what the intent was; in this case the default
2637 target name will be used.
2638 Note
2640 You must load the compilation_db tool prior to specifying any
2641 part of your build or some source/output files will not show up
2642 in the compilation database.
2643 Available since scons 4.0.
2644 CXXFile(), env.CXXFile()
2646 Builds a C++ source file given a lex (.ll) or yacc (.yy) input
2647 file. The suffix specified by the $CXXFILESUFFIX construction
2648 variable (.cc by default) is automatically added to the target if
2649 it is not already present. Example:
2650 # builds foo.cc
2652 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
2653 # builds bar.cc
2654 env.CXXFile(target = 'bar', source = 'bar.yy')
2655 DocbookEpub(), env.DocbookEpub()
2657 A pseudo-Builder, providing a Docbook toolchain for EPUB output.
2658 env = Environment(tools=['docbook'])
2660 env.DocbookEpub('manual.epub', 'manual.xml')
2661 or simply
2663 env = Environment(tools=['docbook'])
2665 env.DocbookEpub('manual')
2666 DocbookHtml(), env.DocbookHtml()
2668 A pseudo-Builder, providing a Docbook toolchain for HTML output.
2669 env = Environment(tools=['docbook'])
2671 env.DocbookHtml('manual.html', 'manual.xml')
2672 or simply
2674 env = Environment(tools=['docbook'])
2676 env.DocbookHtml('manual')
2677 DocbookHtmlChunked(), env.DocbookHtmlChunked()
2679 A pseudo-Builder providing a Docbook toolchain for chunked HTML
2680 output. It supports the base.dir parameter. The chunkfast.xsl file
2681 (requires "EXSLT") is used as the default stylesheet. Basic syntax:
2682 env = Environment(tools=['docbook'])
2684 env.DocbookHtmlChunked('manual')
2685 where manual.xml is the input file.
2687 If you use the root.filename parameter in your own stylesheets you
2689 have to specify the new target name. This ensures that the
2690 dependencies get correct, especially for the cleanup via “scons
2691 -c”:
2692 env = Environment(tools=['docbook'])
2694 env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
2695 Some basic support for the base.dir parameter is provided. You can
2697 add the base_dir keyword to your Builder call, and the given prefix
2698 gets prepended to all the created filenames:
2699 env = Environment(tools=['docbook'])
2701 env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
2702 Make sure that you don't forget the trailing slash for the base
2704 folder, else your files get renamed only!
2705 DocbookHtmlhelp(), env.DocbookHtmlhelp()
2707 A pseudo-Builder, providing a Docbook toolchain for HTMLHELP
2708 output. Its basic syntax is:
2709 env = Environment(tools=['docbook'])
2711 env.DocbookHtmlhelp('manual')
2712 where manual.xml is the input file.
2714 If you use the root.filename parameter in your own stylesheets you
2716 have to specify the new target name. This ensures that the
2717 dependencies get correct, especially for the cleanup via “scons
2718 -c”:
2719 env = Environment(tools=['docbook'])
2721 env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
2722 Some basic support for the base.dir parameter is provided. You can
2724 add the base_dir keyword to your Builder call, and the given prefix
2725 gets prepended to all the created filenames:
2726 env = Environment(tools=['docbook'])
2728 env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
2729 Make sure that you don't forget the trailing slash for the base
2731 folder, else your files get renamed only!
2732 DocbookMan(), env.DocbookMan()
2734 A pseudo-Builder, providing a Docbook toolchain for Man page
2735 output. Its basic syntax is:
2736 env = Environment(tools=['docbook'])
2738 env.DocbookMan('manual')
2739 where manual.xml is the input file. Note, that you can specify a
2741 target name, but the actual output names are automatically set from
2742 the refname entries in your XML source.
2743 DocbookPdf(), env.DocbookPdf()
2745 A pseudo-Builder, providing a Docbook toolchain for PDF output.
2746 env = Environment(tools=['docbook'])
2748 env.DocbookPdf('manual.pdf', 'manual.xml')
2749 or simply
2751 env = Environment(tools=['docbook'])
2753 env.DocbookPdf('manual')
2754 DocbookSlidesHtml(), env.DocbookSlidesHtml()
2756 A pseudo-Builder, providing a Docbook toolchain for HTML slides
2757 output.
2758 env = Environment(tools=['docbook'])
2760 env.DocbookSlidesHtml('manual')
2761 If you use the titlefoil.html parameter in your own stylesheets you
2763 have to give the new target name. This ensures that the
2764 dependencies get correct, especially for the cleanup via “scons
2765 -c”:
2766 env = Environment(tools=['docbook'])
2768 env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
2769 Some basic support for the base.dir parameter is provided. You can
2771 add the base_dir keyword to your Builder call, and the given prefix
2772 gets prepended to all the created filenames:
2773 env = Environment(tools=['docbook'])
2775 env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
2776 Make sure that you don't forget the trailing slash for the base
2778 folder, else your files get renamed only!
2779 DocbookSlidesPdf(), env.DocbookSlidesPdf()
2781 A pseudo-Builder, providing a Docbook toolchain for PDF slides
2782 output.
2783 env = Environment(tools=['docbook'])
2785 env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
2786 or simply
2788 env = Environment(tools=['docbook'])
2790 env.DocbookSlidesPdf('manual')
2791 DocbookXInclude(), env.DocbookXInclude()
2793 A pseudo-Builder, for resolving XIncludes in a separate processing
2794 step.
2795 env = Environment(tools=['docbook'])
2797 env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
2798 DocbookXslt(), env.DocbookXslt()
2800 A pseudo-Builder, applying a given XSL transformation to the input
2801 file.
2802 env = Environment(tools=['docbook'])
2804 env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
2805 Note, that this builder requires the xsl parameter to be set.
2807 DVI(), env.DVI()
2809 Builds a .dvi file from a .tex, .ltx or .latex input file. If the
2810 source file suffix is .tex, scons will examine the contents of the
2811 file; if the string \documentclass or \documentstyle is found, the
2812 file is assumed to be a LaTeX file and the target is built by
2813 invoking the $LATEXCOM command line; otherwise, the $TEXCOM command
2814 line is used. If the file is a LaTeX file, the DVI builder method
2815 will also examine the contents of the .aux file and invoke the
2816 $BIBTEX command line if the string bibdata is found, start
2817 $MAKEINDEX to generate an index if a .ind file is found and will
2818 examine the contents .log file and re-run the $LATEXCOM command if
2819 the log file says it is necessary.
2820 The suffix .dvi (hard-coded within TeX itself) is automatically
2822 added to the target if it is not already present. Examples:
2823 # builds from aaa.tex
2825 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
2826 # builds bbb.dvi
2827 env.DVI(target = 'bbb', source = 'bbb.ltx')
2828 # builds from ccc.latex
2829 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
2830 Gs(), env.Gs()
2832 A Builder for explicitly calling the gs executable. Depending on
2833 the underlying OS, the different names gs, gsos2 and gswin32c are
2834 tried.
2835 env = Environment(tools=['gs'])
2837 env.Gs(
2838 'cover.jpg',
2839 'scons-scons.pdf',
2840 GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q',
2841 )
2842 Install(), env.Install()
2844 Installs one or more source files or directories in the specified
2845 target, which must be a directory. The names of the specified
2846 source files or directories remain the same within the destination
2847 directory. The sources may be given as a string or as a node
2848 returned by a builder.
2849 env.Install(target='/usr/local/bin', source=['foo', 'bar'])
2851 Note that if target paths chosen for the Install builder (and the
2853 related InstallAs and InstallVersionedLib builders) are outside the
2854 project tree, such as in the example above, they may not be
2855 selected for "building" by default, since in the absence of other
2856 instructions scons builds targets that are underneath the top
2857 directory (the directory that contains the SConstruct file, usually
2858 the current directory). Use command line targets or the Default
2859 function in this case.
2860 If the --install-sandbox command line option is given, the target
2862 directory will be prefixed by the directory path specified. This is
2863 useful to test installs without installing to a "live" location in
2864 the system.
2865 See also FindInstalledFiles. For more thoughts on installation, see
2867 the User Guide (particularly the section on Command-Line Targets
2868 and the chapters on Installing Files and on Alias Targets).
2869 InstallAs(), env.InstallAs()
2871 Installs one or more source files or directories to specific names,
2872 allowing changing a file or directory name as part of the
2873 installation. It is an error if the target and source arguments
2874 list different numbers of files or directories.
2875 env.InstallAs(target='/usr/local/bin/foo',
2877 source='foo_debug')
2878 env.InstallAs(target=['../lib/libfoo.a', '../lib/libbar.a'],
2879 source=['libFOO.a', 'libBAR.a'])
2880 See the note under Install.
2882 InstallVersionedLib(), env.InstallVersionedLib()
2884 Installs a versioned shared library. The symlinks appropriate to
2885 the architecture will be generated based on symlinks of the source
2886 library.
2887 env.InstallVersionedLib(target='/usr/local/bin/foo',
2889 source='libxyz.1.5.2.so')
2890 See the note under Install.
2892 Jar(), env.Jar()
2894 Builds a Java archive (.jar) file from the specified list of
2895 sources. Any directories in the source list will be searched for
2896 .class files). Any .java files in the source list will be compiled
2897 to .class files by calling the Java Builder.
2898 If the $JARCHDIR value is set, the jar command will change to the
2900 specified directory using the -C option. If $JARCHDIR is not set
2901 explicitly, SCons will use the top of any subdirectory tree in
2902 which Java .class were built by the Java Builder.
2903 If the contents any of the source files begin with the string
2905 Manifest-Version, the file is assumed to be a manifest and is
2906 passed to the jar command with the m option set.
2907 env.Jar(target = 'foo.jar', source = 'classes')
2909 env.Jar(target = 'bar.jar',
2911 source = ['bar1.java', 'bar2.java'])
2912 Java(), env.Java()
2914 Builds one or more Java class files. The sources may be any
2915 combination of explicit .java files, or directory trees which will
2916 be scanned for .java files.
2917 SCons will parse each source .java file to find the classes
2919 (including inner classes) defined within that file, and from that
2920 figure out the target .class files that will be created. The class
2921 files will be placed underneath the specified target directory.
2922 SCons will also search each Java file for the Java package name,
2924 which it assumes can be found on a line beginning with the string
2925 package in the first column; the resulting .class files will be
2926 placed in a directory reflecting the specified package name. For
2927 example, the file Foo.java defining a single public Foo class and
2928 containing a package name of sub.dir will generate a corresponding
2929 sub/dir/Foo.class class file.
2930 Examples:
2932 env.Java(target = 'classes', source = 'src')
2934 env.Java(target = 'classes', source = ['src1', 'src2'])
2935 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
2936 Java source files can use the native encoding for the underlying
2939 OS. Since SCons compiles in simple ASCII mode by default, the
2940 compiler will generate warnings about unmappable characters, which
2941 may lead to errors as the file is processed further. In this case,
2942 the user must specify the LANG environment variable to tell the
2943 compiler what encoding is used. For portibility, it's best if the
2944 encoding is hard-coded so that the compile will work if it is done
2945 on a system with a different encoding.
2946 env = Environment()
2948 env['ENV']['LANG'] = 'en_GB.UTF-8'
2949 JavaH(), env.JavaH()
2952 Builds C header and source files for implementing Java native
2953 methods. The target can be either a directory in which the header
2954 files will be written, or a header file name which will contain all
2955 of the definitions. The source can be the names of .class files,
2956 the names of .java files to be compiled into .class files by
2957 calling the Java builder method, or the objects returned from the
2958 Java builder method.
2959 If the construction variable $JAVACLASSDIR is set, either in the
2961 environment or in the call to the JavaH builder method itself, then
2962 the value of the variable will be stripped from the beginning of
2963 any .class file names.
2964 Examples:
2966 # builds java_native.h
2968 classes = env.Java(target="classdir", source="src")
2969 env.JavaH(target="java_native.h", source=classes)
2970 # builds include/package_foo.h and include/package_bar.h
2972 env.JavaH(target="include", source=["package/foo.class", "package/bar.class"])
2973 # builds export/foo.h and export/bar.h
2975 env.JavaH(
2976 target="export",
2977 source=["classes/foo.class", "classes/bar.class"],
2978 JAVACLASSDIR="classes",
2979 )
2980 Note
2982 Java versions starting with 10.0 no longer use the javah
2983 command for generating JNI headers/sources, and indeed have
2984 removed the command entirely (see Java Enhancement Proposal JEP
2985 313[3]), making this tool harder to use for that purpose.
2986 SCons may autodiscover a javah belonging to an older release if
2987 there are multiple Java versions on the system, which will lead
2988 to incorrect results. To use with a newer Java, override the
2989 default values of $JAVAH (to contain the path to the javac) and
2990 $JAVAHFLAGS (to contain at least a -h flag) and note that
2991 generating headers with javac requires supplying source .java
2992 files only, not .class files.
2993 Library(), env.Library()
2995 A synonym for the StaticLibrary builder method.
2996 LoadableModule(), env.LoadableModule()
2998 On most systems, this is the same as SharedLibrary. On Mac OS X
2999 (Darwin) platforms, this creates a loadable module bundle.
3000 M4(), env.M4()
3002 Builds an output file from an M4 input file. This uses a default
3003 $M4FLAGS value of -E, which considers all warnings to be fatal and
3004 stops on the first warning when using the GNU version of m4.
3005 Example:
3006 env.M4(target = 'foo.c', source = 'foo.c.m4')
3008 Moc(), env.Moc()
3010 Builds an output file from a moc input file. moc input files are
3011 either header files or C++ files. This builder is only available
3012 after using the tool qt. See the $QTDIR variable for more
3013 information. Example:
3014 env.Moc('foo.h') # generates moc_foo.cc
3016 env.Moc('foo.cpp') # generates foo.moc
3017 MOFiles(), env.MOFiles()
3019 This builder belongs to msgfmt tool. The builder compiles PO files
3020 to MO files.
3021 Example 1. Create pl.mo and en.mo by compiling pl.po and en.po:
3024 # ...
3026 env.MOFiles(['pl', 'en'])
3027 Example 2. Compile files for languages defined in LINGUAS file:
3030 # ...
3032 env.MOFiles(LINGUAS_FILE = 1)
3033 Example 3. Create pl.mo and en.mo by compiling pl.po and en.po plus
3036 files for languages defined in LINGUAS file:
3037 # ...
3039 env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
3040 Example 4. Compile files for languages defined in LINGUAS file
3043 (another version):
3044 # ...
3046 env['LINGUAS_FILE'] = 1
3047 env.MOFiles()
3048 MSVSProject(), env.MSVSProject()
3050 Builds a Microsoft Visual Studio project file, and by default
3051 builds a solution file as well.
3052 This builds a Visual Studio project file, based on the version of
3054 Visual Studio that is configured (either the latest installed
3055 version, or the version specified by $MSVS_VERSION in the
3056 Environment constructor). For Visual Studio 6, it will generate a
3057 .dsp file. For Visual Studio 7, 8, and 9, it will generate a
3058 .vcproj file. For Visual Studio 10 and later, it will generate a
3059 .vcxproj file.
3060 By default, this also generates a solution file for the specified
3062 project, a .dsw file for Visual Studio 6 or a .sln file for Visual
3063 Studio 7 and later. This behavior may be disabled by specifying
3064 auto_build_solution=0 when you call MSVSProject, in which case you
3065 presumably want to build the solution file(s) by calling the
3066 MSVSSolution Builder (see below).
3067 The MSVSProject builder takes several lists of filenames to be
3069 placed into the project file. These are currently limited to srcs,
3070 incs, localincs, resources, and misc. These are pretty
3071 self-explanatory, but it should be noted that these lists are added
3072 to the $SOURCES construction variable as strings, NOT as SCons File
3073 Nodes. This is because they represent file names to be added to the
3074 project file, not the source files used to build the project file.
3075 The above filename lists are all optional, although at least one
3077 must be specified for the resulting project file to be non-empty.
3078 In addition to the above lists of values, the following values may
3080 be specified:
3081 target
3083 The name of the target .dsp or .vcproj file. The correct suffix
3084 for the version of Visual Studio must be used, but the
3085 $MSVSPROJECTSUFFIX construction variable will be defined to the
3086 correct value (see example below).
3087 variant
3089 The name of this particular variant. For Visual Studio 7
3090 projects, this can also be a list of variant names. These are
3091 typically things like "Debug" or "Release", but really can be
3092 anything you want. For Visual Studio 7 projects, they may also
3093 specify a target platform separated from the variant name by a
3094 | (vertical pipe) character: Debug|Xbox. The default target
3095 platform is Win32. Multiple calls to MSVSProject with different
3096 variants are allowed; all variants will be added to the project
3097 file with their appropriate build targets and sources.
3098 cmdargs
3100 Additional command line arguments for the different variants.
3101 The number of cmdargs entries must match the number of variant
3102 entries, or be empty (not specified). If you give only one, it
3103 will automatically be propagated to all variants.
3104 cppdefines
3106 Preprocessor definitions for the different variants. The number
3107 of cppdefines entries must match the number of variant entries,
3108 or be empty (not specified). If you give only one, it will
3109 automatically be propagated to all variants. If you don't give
3110 this parameter, SCons will use the invoking environment's
3111 CPPDEFINES entry for all variants.
3112 cppflags
3114 Compiler flags for the different variants. If a /std:c++ flag
3115 is found then /Zc:__cplusplus is appended to the flags if not
3116 already found, this ensures that intellisense uses the /std:c++
3117 switch. The number of cppflags entries must match the number of
3118 variant entries, or be empty (not specified). If you give only
3119 one, it will automatically be propagated to all variants. If
3120 you don't give this parameter, SCons will combine the invoking
3121 environment's CCFLAGS, CXXFLAGS, CPPFLAGS entries for all
3122 variants.
3123 cpppaths
3125 Compiler include paths for the different variants. The number
3126 of cpppaths entries must match the number of variant entries,
3127 or be empty (not specified). If you give only one, it will
3128 automatically be propagated to all variants. If you don't give
3129 this parameter, SCons will use the invoking environment's
3130 CPPPATH entry for all variants.
3131 buildtarget
3133 An optional string, node, or list of strings or nodes (one per
3134 build variant), to tell the Visual Studio debugger what output
3135 target to use in what build variant. The number of buildtarget
3136 entries must match the number of variant entries.
3137 runfile
3139 The name of the file that Visual Studio 7 and later will run
3140 and debug. This appears as the value of the Output field in the
3141 resulting Visual Studio project file. If this is not specified,
3142 the default is the same as the specified buildtarget value.
3143 Note that because SCons always executes its build commands from the
3145 directory in which the SConstruct file is located, if you generate
3146 a project file in a different directory than the SConstruct
3147 directory, users will not be able to double-click on the file name
3148 in compilation error messages displayed in the Visual Studio
3149 console output window. This can be remedied by adding the Visual
3150 C/C++ /FC compiler option to the $CCFLAGS variable so that the
3151 compiler will print the full path name of any files that cause
3152 compilation errors.
3153 Example usage:
3155 barsrcs = ['bar.cpp']
3157 barincs = ['bar.h']
3158 barlocalincs = ['StdAfx.h']
3159 barresources = ['bar.rc','resource.h']
3160 barmisc = ['bar_readme.txt']
3161 dll = env.SharedLibrary(target='bar.dll',
3163 source=barsrcs)
3164 buildtarget = [s for s in dll if str(s).endswith('dll')]
3165 env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
3166 srcs=barsrcs,
3167 incs=barincs,
3168 localincs=barlocalincs,
3169 resources=barresources,
3170 misc=barmisc,
3171 buildtarget=buildtarget,
3172 variant='Release')
3173 Starting with version 2.4 of SCons it is also possible to specify
3176 the optional argument DebugSettings, which creates files for
3177 debugging under Visual Studio:
3178 DebugSettings
3180 A dictionary of debug settings that get written to the
3181 .vcproj.user or the .vcxproj.user file, depending on the
3182 version installed. As it is done for cmdargs (see above), you
3183 can specify a DebugSettings dictionary per variant. If you give
3184 only one, it will be propagated to all variants.
3185 Currently, only Visual Studio v9.0 and Visual Studio version v11
3187 are implemented, for other versions no file is generated. To
3188 generate the user file, you just need to add a DebugSettings
3189 dictionary to the environment with the right parameters for your
3190 MSVS version. If the dictionary is empty, or does not contain any
3191 good value, no file will be generated.
3192 Following is a more contrived example, involving the setup of a
3194 project for variants and DebugSettings:
3195 # Assuming you store your defaults in a file
3197 vars = Variables('variables.py')
3198 msvcver = vars.args.get('vc', '9')
3199 # Check command args to force one Microsoft Visual Studio version
3201 if msvcver == '9' or msvcver == '11':
3202 env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False)
3203 else:
3204 env = Environment()
3205 AddOption('--userfile', action='store_true', dest='userfile', default=False,
3207 help="Create Visual Studio Project user file")
3208 #
3210 # 1. Configure your Debug Setting dictionary with options you want in the list
3211 # of allowed options, for instance if you want to create a user file to launch
3212 # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
3213 #
3214 V9DebugSettings = {
3215 'Command':'c:\\myapp\\using\\thisdll.exe',
3216 'WorkingDirectory': 'c:\\myapp\\using\\',
3217 'CommandArguments': '-p password',
3218 # 'Attach':'false',
3219 # 'DebuggerType':'3',
3220 # 'Remote':'1',
3221 # 'RemoteMachine': None,
3222 # 'RemoteCommand': None,
3223 # 'HttpUrl': None,
3224 # 'PDBPath': None,
3225 # 'SQLDebugging': None,
3226 # 'Environment': '',
3227 # 'EnvironmentMerge':'true',
3228 # 'DebuggerFlavor': None,
3229 # 'MPIRunCommand': None,
3230 # 'MPIRunArguments': None,
3231 # 'MPIRunWorkingDirectory': None,
3232 # 'ApplicationCommand': None,
3233 # 'ApplicationArguments': None,
3234 # 'ShimCommand': None,
3235 # 'MPIAcceptMode': None,
3236 # 'MPIAcceptFilter': None,
3237 }
3238 #
3240 # 2. Because there are a lot of different options depending on the Microsoft
3241 # Visual Studio version, if you use more than one version you have to
3242 # define a dictionary per version, for instance if you want to create a user
3243 # file to launch a specific application for testing your dll with Microsoft
3244 # Visual Studio 2012 (v11):
3245 #
3246 V10DebugSettings = {
3247 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
3248 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
3249 'LocalDebuggerCommandArguments': '-p password',
3250 # 'LocalDebuggerEnvironment': None,
3251 # 'DebuggerFlavor': 'WindowsLocalDebugger',
3252 # 'LocalDebuggerAttach': None,
3253 # 'LocalDebuggerDebuggerType': None,
3254 # 'LocalDebuggerMergeEnvironment': None,
3255 # 'LocalDebuggerSQLDebugging': None,
3256 # 'RemoteDebuggerCommand': None,
3257 # 'RemoteDebuggerCommandArguments': None,
3258 # 'RemoteDebuggerWorkingDirectory': None,
3259 # 'RemoteDebuggerServerName': None,
3260 # 'RemoteDebuggerConnection': None,
3261 # 'RemoteDebuggerDebuggerType': None,
3262 # 'RemoteDebuggerAttach': None,
3263 # 'RemoteDebuggerSQLDebugging': None,
3264 # 'DeploymentDirectory': None,
3265 # 'AdditionalFiles': None,
3266 # 'RemoteDebuggerDeployDebugCppRuntime': None,
3267 # 'WebBrowserDebuggerHttpUrl': None,
3268 # 'WebBrowserDebuggerDebuggerType': None,
3269 # 'WebServiceDebuggerHttpUrl': None,
3270 # 'WebServiceDebuggerDebuggerType': None,
3271 # 'WebServiceDebuggerSQLDebugging': None,
3272 }
3273 #
3275 # 3. Select the dictionary you want depending on the version of visual Studio
3276 # Files you want to generate.
3277 #
3278 if not env.GetOption('userfile'):
3279 dbgSettings = None
3280 elif env.get('MSVC_VERSION', None) == '9.0':
3281 dbgSettings = V9DebugSettings
3282 elif env.get('MSVC_VERSION', None) == '11.0':
3283 dbgSettings = V10DebugSettings
3284 else:
3285 dbgSettings = None
3286 #
3288 # 4. Add the dictionary to the DebugSettings keyword.
3289 #
3290 barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
3291 barincs = ['targetver.h']
3292 barlocalincs = ['StdAfx.h']
3293 barresources = ['bar.rc','resource.h']
3294 barmisc = ['ReadMe.txt']
3295 dll = env.SharedLibrary(target='bar.dll',
3297 source=barsrcs)
3298 env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
3300 srcs=barsrcs,
3301 incs=barincs,
3302 localincs=barlocalincs,
3303 resources=barresources,
3304 misc=barmisc,
3305 buildtarget=[dll[0]] * 2,
3306 variant=('Debug|Win32', 'Release|Win32'),
3307 cmdargs='vc=%s' % msvcver,
3308 DebugSettings=(dbgSettings, {}))
3309 MSVSSolution(), env.MSVSSolution()
3312 Builds a Microsoft Visual Studio solution file.
3313 This builds a Visual Studio solution file, based on the version of
3315 Visual Studio that is configured (either the latest installed
3316 version, or the version specified by $MSVS_VERSION in the
3317 construction environment). For Visual Studio 6, it will generate a
3318 .dsw file. For Visual Studio 7 (.NET), it will generate a .sln
3319 file.
3320 The following values must be specified:
3322 target
3324 The name of the target .dsw or .sln file. The correct suffix
3325 for the version of Visual Studio must be used, but the value
3326 $MSVSSOLUTIONSUFFIX will be defined to the correct value (see
3327 example below).
3328 variant
3330 The name of this particular variant, or a list of variant names
3331 (the latter is only supported for MSVS 7 solutions). These are
3332 typically things like "Debug" or "Release", but really can be
3333 anything you want. For MSVS 7 they may also specify target
3334 platform, like this "Debug|Xbox". Default platform is Win32.
3335 projects
3337 A list of project file names, or Project nodes returned by
3338 calls to the MSVSProject Builder, to be placed into the
3339 solution file. It should be noted that these file names are NOT
3340 added to the $SOURCES environment variable in form of files,
3341 but rather as strings. This is because they represent file
3342 names to be added to the solution file, not the source files
3343 used to build the solution file.
3344 Example Usage:
3346 env.MSVSSolution(
3348 target="Bar" + env["MSVSSOLUTIONSUFFIX"],
3349 projects=["bar" + env["MSVSPROJECTSUFFIX"]],
3350 variant="Release",
3351 )
3352 Ninja(), env.Ninja()
3355 A special builder which adds a target to create a Ninja build file.
3356 The builder does not require any source files to be specified.
3357 Note
3359 This is an experimental feature. To enable it you must use one
3360 of the following methods
3361 # On the command line
3363 --experimental=ninja
3364 # Or in your SConstruct
3366 SetOption('experimental', 'ninja')
3367 This functionality is subject to change and/or removal without
3370 deprecation cycle.
3371 To use this tool you need to install the Python ninja package,
3373 as the tool by default depends on being able to do an import of
3374 the package This can be done via:
3375 python -m pip install ninja
3377 If called with no arguments, the builder will default to a target
3379 name of ninja.build.
3380 If called with a single positional argument, scons will "deduce"
3382 the target name from that source argument, giving it the same name,
3383 and then ignore the source. This is the usual way to call the
3384 builder if a non-default target name is wanted.
3385 If called with either the target= or source= keyword arguments, the
3387 value of the argument is taken as the target name. If called with
3388 both, the target= value is used and source= is ignored. If called
3389 with multiple sources, the source list will be ignored, since there
3390 is no way to deduce what the intent was; in this case the default
3391 target name will be used.
3392 Available since scons 4.2.
3395 Object(), env.Object()
3397 A synonym for the StaticObject builder method.
3398 Package(), env.Package()
3400 Builds software distribution packages. A package is a container
3401 format which includes files to install along with metadata.
3402 Packaging is optional, and must be enabled by specifying the
3403 packaging tool. For example:
3404 env = Environment(tools=['default', 'packaging'])
3406 SCons can build packages in a number of well known packaging
3409 formats. The target package type may be selected with the the
3410 $PACKAGETYPE construction variable or the --package-type command
3411 line option. The package type may be a list, in which case SCons
3412 will attempt to build packages for each type in the list. Example:
3413 env.Package(PACKAGETYPE=['src_zip', 'src_targz'], ...other args...)
3415 The currently supported packagers are:
3417 ┌───────────┬────────────────────────────┐
3419 │msi │ Microsoft Installer │
3420 │ │ package │
3421 ├───────────┼────────────────────────────┤
3422 │rpm │ RPM Package Manger package │
3423 ├───────────┼────────────────────────────┤
3424 │ipkg │ Itsy Package Management │
3425 │ │ package │
3426 ├───────────┼────────────────────────────┤
3427 │tarbz2 │ bzip2-compressed tar file │
3428 ├───────────┼────────────────────────────┤
3429 │targz │ gzip-compressed tar file │
3430 ├───────────┼────────────────────────────┤
3431 │tarxz │ xz-compressed tar file │
3432 ├───────────┼────────────────────────────┤
3433 │zip │ zip file │
3434 ├───────────┼────────────────────────────┤
3435 │src_tarbz2 │ bzip2-compressed tar file │
3436 │ │ suitable as source to │
3437 │ │ another packager │
3438 ├───────────┼────────────────────────────┤
3439 │src_targz │ gzip-compressed tar file │
3440 │ │ suitable as source to │
3441 │ │ another packager │
3442 ├───────────┼────────────────────────────┤
3443 │src_tarxz │ xz-compressed tar file │
3444 │ │ suitable as source to │
3445 │ │ another packager │
3446 ├───────────┼────────────────────────────┤
3447 │src_zip │ zip file suitable as │
3448 │ │ source to another packager │
3449 └───────────┴────────────────────────────┘
3450 The file list to include in the package may be specified with the
3451 source keyword argument. If omitted, the FindInstalledFiles
3452 function is called behind the scenes to select all files that have
3453 an Install, InstallAs or InstallVersionedLib Builder attached. If
3454 the target keyword argument is omitted, the target name(s) will be
3455 deduced from the package type(s).
3456 The metadata comes partly from attributes of the files to be
3458 packaged, and partly from packaging tags. Tags can be passed as
3459 keyword arguments to the Package builder call, and may also be
3460 attached to files (or more accurately, Nodes representing files)
3461 with the Tag function. Some package-level tags are mandatory, and
3462 will lead to errors if omitted. The mandatory tags vary depending
3463 on the package type.
3464 While packaging, the builder uses a temporary location named by the
3466 value of the $PACKAGEROOT variable - the package sources are copied
3467 there before packaging.
3468 Packaging example:
3470 env = Environment(tools=["default", "packaging"])
3472 env.Install("/bin/", "my_program")
3473 env.Package(
3474 NAME="foo",
3475 VERSION="1.2.3",
3476 PACKAGEVERSION=0,
3477 PACKAGETYPE="rpm",
3478 LICENSE="gpl",
3479 SUMMARY="balalalalal",
3480 DESCRIPTION="this should be really really long",
3481 X_RPM_GROUP="Application/fu",
3482 SOURCE_URL="https://foo.org/foo-1.2.3.tar.gz",
3483 )
3484 In this example, the target /bin/my_program created by the Install
3486 call would not be built by default since it is not under the
3487 project top directory. However, since no source is specified to the
3488 Package builder, it is selected for packaging by the default
3489 sources rule. Since packaging is done using $PACKAGEROOT, no write
3490 is actually done to the system's /bin directory, and the target
3491 will be selected since after rebasing to underneath $PACKAGEROOT it
3492 is now under the top directory of the project.
3493 PCH(), env.PCH()
3495 Builds a Microsoft Visual C++ precompiled header. Calling this
3496 builder returns a list of two targets: the PCH as the first
3497 element, and the object file as the second element. Normally the
3498 object file is ignored. This builder is only provided when
3499 Microsoft Visual C++ is being used as the compiler. The PCH builder
3500 is generally used in conjunction with the $PCH construction
3501 variable to force object files to use the precompiled header:
3502 env['PCH'] = env.PCH('StdAfx.cpp')[0]
3504 PDF(), env.PDF()
3506 Builds a .pdf file from a .dvi input file (or, by extension, a
3507 .tex, .ltx, or .latex input file). The suffix specified by the
3508 $PDFSUFFIX construction variable (.pdf by default) is added
3509 automatically to the target if it is not already present. Example:
3510 # builds from aaa.tex
3512 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
3513 # builds bbb.pdf from bbb.dvi
3514 env.PDF(target = 'bbb', source = 'bbb.dvi')
3515 POInit(), env.POInit()
3517 This builder belongs to msginit tool. The builder initializes
3518 missing PO file(s) if $POAUTOINIT is set. If $POAUTOINIT is not set
3519 (default), POInit prints instruction for user (that is supposed to
3520 be a translator), telling how the PO file should be initialized. In
3521 normal projects you should not use POInit and use POUpdate instead.
3522 POUpdate chooses intelligently between msgmerge(1) and msginit(1).
3523 POInit always uses msginit(1) and should be regarded as builder for
3524 special purposes or for temporary use (e.g. for quick, one time
3525 initialization of a bunch of PO files) or for tests.
3526 Target nodes defined through POInit are not built by default
3528 (they're Ignored from '.' node) but are added to special Alias
3529 ('po-create' by default). The alias name may be changed through the
3530 $POCREATE_ALIAS construction variable. All PO files defined through
3531 POInit may be easily initialized by scons po-create.
3532 Example 1. Initialize en.po and pl.po from messages.pot:
3535 # ...
3537 env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
3538 Example 2. Initialize en.po and pl.po from foo.pot:
3541 # ...
3543 env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
3544 Example 3. Initialize en.po and pl.po from foo.pot but using
3547 $POTDOMAIN construction variable:
3548 # ...
3550 env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
3551 Example 4. Initialize PO files for languages defined in LINGUAS
3554 file. The files will be initialized from template messages.pot:
3555 # ...
3557 env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3558 Example 5. Initialize en.po and pl.pl PO files plus files for
3561 languages defined in LINGUAS file. The files will be initialized
3562 from template messages.pot:
3563 # ...
3565 env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
3566 Example 6. You may preconfigure your environment first, and then
3569 initialize PO files:
3570 # ...
3572 env['POAUTOINIT'] = 1
3573 env['LINGUAS_FILE'] = 1
3574 env['POTDOMAIN'] = 'foo'
3575 env.POInit()
3576 which has same efect as:
3578 # ...
3580 env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
3581 PostScript(), env.PostScript()
3583 Builds a .ps file from a .dvi input file (or, by extension, a .tex,
3584 .ltx, or .latex input file). The suffix specified by the $PSSUFFIX
3585 construction variable (.ps by default) is added automatically to
3586 the target if it is not already present. Example:
3587 # builds from aaa.tex
3589 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
3590 # builds bbb.ps from bbb.dvi
3591 env.PostScript(target = 'bbb', source = 'bbb.dvi')
3592 POTUpdate(), env.POTUpdate()
3594 The builder belongs to xgettext tool. The builder updates target
3595 POT file if exists or creates one if it doesn't. The node is not
3596 built by default (i.e. it is Ignored from '.'), but only on demand
3597 (i.e. when given POT file is required or when special alias is
3598 invoked). This builder adds its targe node (messages.pot, say) to a
3599 special alias (pot-update by default, see $POTUPDATE_ALIAS) so you
3600 can update/create them easily with scons pot-update. The file is
3601 not written until there is no real change in internationalized
3602 messages (or in comments that enter POT file).
3603 Note
3606 You may see xgettext(1) being invoked by the xgettext tool even
3607 if there is no real change in internationalized messages (so
3608 the POT file is not being updated). This happens every time a
3609 source file has changed. In such case we invoke xgettext(1) and
3610 compare its output with the content of POT file to decide
3611 whether the file should be updated or not.
3612 Example 1. Let's create po/ directory and place following
3615 SConstruct script there:
3616 # SConstruct in 'po/' subdir
3618 env = Environment( tools = ['default', 'xgettext'] )
3619 env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
3620 env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
3621 Then invoke scons few times:
3623 user@host:$ scons # Does not create foo.pot nor bar.pot
3625 user@host:$ scons foo.pot # Updates or creates foo.pot
3626 user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
3627 user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
3628 the results shall be as the comments above say.
3630 Example 2. The POTUpdate builder may be used with no target
3633 specified, in which case default target messages.pot will be used.
3634 The default target may also be overridden by setting $POTDOMAIN
3635 construction variable or providing it as an override to POTUpdate
3636 builder:
3637 # SConstruct script
3640 env = Environment( tools = ['default', 'xgettext'] )
3641 env['POTDOMAIN'] = "foo"
3642 env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
3643 env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
3644 Example 3. The sources may be specified within separate file, for
3647 example POTFILES.in:
3648 # POTFILES.in in 'po/' subdirectory
3651 ../a.cpp
3652 ../b.cpp
3653 # end of file
3654 The name of the file (POTFILES.in) containing the list of sources
3656 is provided via $XGETTEXTFROM:
3657 # SConstruct file in 'po/' subdirectory
3660 env = Environment( tools = ['default', 'xgettext'] )
3661 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
3662 Example 4. You may use $XGETTEXTPATH to define source search path.
3665 Assume, for example, that you have files a.cpp, b.cpp,
3666 po/SConstruct, po/POTFILES.in. Then your POT-related files could
3667 look as below:
3668 # POTFILES.in in 'po/' subdirectory
3670 a.cpp
3671 b.cpp
3672 # end of file
3673 # SConstruct file in 'po/' subdirectory
3675 env = Environment( tools = ['default', 'xgettext'] )
3676 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
3677 Example 5. Multiple search directories may be defined within a
3680 list, i.e. XGETTEXTPATH = ['dir1', 'dir2', ...]. The order in the
3681 list determines the search order of source files. The path to the
3682 first file found is used.
3683 Let's create 0/1/po/SConstruct script:
3685 # SConstruct file in '0/1/po/' subdirectory
3687 env = Environment( tools = ['default', 'xgettext'] )
3688 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
3689 and 0/1/po/POTFILES.in:
3691 # POTFILES.in in '0/1/po/' subdirectory
3693 a.cpp
3694 # end of file
3695 Write two *.cpp files, the first one is 0/a.cpp:
3697 /* 0/a.cpp */
3699 gettext("Hello from ../../a.cpp")
3700 and the second is 0/1/a.cpp:
3702 /* 0/1/a.cpp */
3704 gettext("Hello from ../a.cpp")
3705 then run scons. You'll obtain 0/1/po/messages.pot with the message
3707 "Hello from ../a.cpp". When you reverse order in $XGETTEXTFOM, i.e.
3708 when you write SConscript as
3709 # SConstruct file in '0/1/po/' subdirectory
3711 env = Environment( tools = ['default', 'xgettext'] )
3712 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
3713 then the messages.pot will contain msgid "Hello from ../../a.cpp"
3715 line and not msgid "Hello from ../a.cpp".
3716 POUpdate(), env.POUpdate()
3718 The builder belongs to msgmerge tool. The builder updates PO files
3719 with msgmerge(1), or initializes missing PO files as described in
3720 documentation of msginit tool and POInit builder (see also
3721 $POAUTOINIT). Note, that POUpdate does not add its targets to
3722 po-create alias as POInit does.
3723 Target nodes defined through POUpdate are not built by default
3725 (they're Ignored from '.' node). Instead, they are added
3726 automatically to special Alias ('po-update' by default). The alias
3727 name may be changed through the $POUPDATE_ALIAS construction
3728 variable. You can easily update PO files in your project by scons
3729 po-update.
3730 Example 1. Update en.po and pl.po from messages.pot template (see
3733 also $POTDOMAIN), assuming that the later one exists or there is
3734 rule to build it (see POTUpdate):
3735 # ...
3737 env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
3738 Example 2. Update en.po and pl.po from foo.pot template:
3741 # ...
3743 env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
3744 Example 3. Update en.po and pl.po from foo.pot (another version):
3747 # ...
3749 env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
3750 Example 4. Update files for languages defined in LINGUAS file. The
3753 files are updated from messages.pot template:
3754 # ...
3756 env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3757 Example 5. Same as above, but update from foo.pot template:
3760 # ...
3762 env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
3763 Example 6. Update en.po and pl.po plus files for languages defined
3766 in LINGUAS file. The files are updated from messages.pot template:
3767 # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
3769 env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
3770 Example 7. Use $POAUTOINIT to automatically initialize PO file if
3773 it doesn't exist:
3774 # ...
3776 env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
3777 Example 8. Update PO files for languages defined in LINGUAS file.
3780 The files are updated from foo.pot template. All necessary settings
3781 are pre-configured via environment.
3782 # ...
3784 env['POAUTOINIT'] = 1
3785 env['LINGUAS_FILE'] = 1
3786 env['POTDOMAIN'] = 'foo'
3787 env.POUpdate()
3788 Program(), env.Program()
3790 Builds an executable given one or more object files or C, C++, D,
3791 or Fortran source files. If any C, C++, D or Fortran source files
3792 are specified, then they will be automatically compiled to object
3793 files using the Object builder method; see that builder method's
3794 description for a list of legal source file suffixes and how they
3795 are interpreted. The target executable file prefix, specified by
3796 the $PROGPREFIX construction variable (nothing by default), and
3797 suffix, specified by the $PROGSUFFIX construction variable (by
3798 default, .exe on Windows systems, nothing on POSIX systems), are
3799 automatically added to the target if not already present. Example:
3800 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
3802 ProgramAllAtOnce(), env.ProgramAllAtOnce()
3804 Builds an executable from D sources without first creating
3805 individual objects for each file.
3806 D sources can be compiled file-by-file as C and C++ source are, and
3808 D is integrated into the scons Object and Program builders for this
3809 model of build. D codes can though do whole source meta-programming
3810 (some of the testing frameworks do this). For this it is imperative
3811 that all sources are compiled and linked in a single call to the D
3812 compiler. This builder serves that purpose.
3813 env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
3815 This command will compile the modules mod_a, mod_b, and mod_c in a
3818 single compilation process without first creating object files for
3819 the modules. Some of the D compilers will create executable.o
3820 others will not.
3821 RES(), env.RES()
3823 Builds a Microsoft Visual C++ resource file. This builder method is
3824 only provided when Microsoft Visual C++ or MinGW is being used as
3825 the compiler. The .res (or .o for MinGW) suffix is added to the
3826 target name if no other suffix is given. The source file is scanned
3827 for implicit dependencies as though it were a C file. Example:
3828 env.RES('resource.rc')
3830 RMIC(), env.RMIC()
3832 Builds stub and skeleton class files for remote objects from Java
3833 .class files. The target is a directory relative to which the stub
3834 and skeleton class files will be written. The source can be the
3835 names of .class files, or the objects return from the Java builder
3836 method.
3837 If the construction variable $JAVACLASSDIR is set, either in the
3839 environment or in the call to the RMIC builder method itself, then
3840 the value of the variable will be stripped from the beginning of
3841 any .class file names.
3842 classes = env.Java(target = 'classdir', source = 'src')
3844 env.RMIC(target = 'outdir1', source = classes)
3845 env.RMIC(target = 'outdir2',
3847 source = ['package/foo.class', 'package/bar.class'])
3848 env.RMIC(target = 'outdir3',
3850 source = ['classes/foo.class', 'classes/bar.class'],
3851 JAVACLASSDIR = 'classes')
3852 RPCGenClient(), env.RPCGenClient()
3854 Generates an RPC client stub (_clnt.c) file from a specified RPC
3855 (.x) source file. Because rpcgen only builds output files in the
3856 local directory, the command will be executed in the source file's
3857 directory by default.
3858 # Builds src/rpcif_clnt.c
3860 env.RPCGenClient('src/rpcif.x')
3861 RPCGenHeader(), env.RPCGenHeader()
3863 Generates an RPC header (.h) file from a specified RPC (.x) source
3864 file. Because rpcgen only builds output files in the local
3865 directory, the command will be executed in the source file's
3866 directory by default.
3867 # Builds src/rpcif.h
3869 env.RPCGenHeader('src/rpcif.x')
3870 RPCGenService(), env.RPCGenService()
3872 Generates an RPC server-skeleton (_svc.c) file from a specified RPC
3873 (.x) source file. Because rpcgen only builds output files in the
3874 local directory, the command will be executed in the source file's
3875 directory by default.
3876 # Builds src/rpcif_svc.c
3878 env.RPCGenClient('src/rpcif.x')
3879 RPCGenXDR(), env.RPCGenXDR()
3881 Generates an RPC XDR routine (_xdr.c) file from a specified RPC
3882 (.x) source file. Because rpcgen only builds output files in the
3883 local directory, the command will be executed in the source file's
3884 directory by default.
3885 # Builds src/rpcif_xdr.c
3887 env.RPCGenClient('src/rpcif.x')
3888 SharedLibrary(), env.SharedLibrary()
3890 Builds a shared library (.so on a POSIX system, .dll on Windows)
3891 given one or more object files or C, C++, D or Fortran source
3892 files. If any source files are given, then they will be
3893 automatically compiled to object files. The target library file
3894 prefix, specified by the $SHLIBPREFIX construction variable (by
3895 default, lib on POSIX systems, nothing on Windows systems), and
3896 suffix, specified by the $SHLIBSUFFIX construction variable (by
3897 default, .dll on Windows systems, .so on POSIX systems), are
3898 automatically added to the target if not already present. Example:
3899 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
3901 On Windows systems, the SharedLibrary builder method will always
3903 build an import library (.lib) in addition to the shared library
3904 (.dll), adding a .lib library with the same basename if there is
3905 not already a .lib file explicitly listed in the targets.
3906 On Cygwin systems, the SharedLibrary builder method will always
3908 build an import library (.dll.a) in addition to the shared library
3909 (.dll), adding a .dll.a library with the same basename if there is
3910 not already a .dll.a file explicitly listed in the targets.
3911 Any object files listed in the source must have been built for a
3913 shared library (that is, using the SharedObject builder method).
3914 scons will raise an error if there is any mismatch.
3915 On some platforms, there is a distinction between a shared library
3917 (loaded automatically by the system to resolve external references)
3918 and a loadable module (explicitly loaded by user action). For
3919 maximum portability, use the LoadableModule builder for the latter.
3920 When the $SHLIBVERSION construction variable is defined, a
3922 versioned shared library is created. This modifies $SHLINKFLAGS as
3923 required, adds the version number to the library name, and creates
3924 any symbolic links that are needed.
3925 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
3927 On a POSIX system, versions with a single token create exactly one
3929 symlink: libbar.so.6 would have symlink libbar.so only. On a POSIX
3930 system, versions with two or more tokens create exactly two
3931 symlinks: libbar.so.2.3.1 would have symlinks libbar.so and
3932 libbar.so.2; on a Darwin (OSX) system the library would be
3933 libbar.2.3.1.dylib and the link would be libbar.dylib.
3934 On Windows systems, specifying register=1 will cause the .dll to be
3936 registered after it is built. The command that is run is determined
3937 by the $REGSVR construction variable (regsvr32 by default), and the
3938 flags passed are determined by $REGSVRFLAGS. By default,
3939 $REGSVRFLAGS includes the /s option, to prevent dialogs from
3940 popping up and requiring user attention when it is run. If you
3941 change $REGSVRFLAGS, be sure to include the /s option. For example,
3942 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
3944 will register bar.dll as a COM object when it is done linking it.
3946 SharedObject(), env.SharedObject()
3948 Builds an object file intended for inclusion in a shared library.
3949 Source files must have one of the same set of extensions specified
3950 above for the StaticObject builder method. On some platforms
3951 building a shared object requires additional compiler option (e.g.
3952 -fPIC for gcc) in addition to those needed to build a normal
3953 (static) object, but on some platforms there is no difference
3954 between a shared object and a normal (static) one. When there is a
3955 difference, SCons will only allow shared objects to be linked into
3956 a shared library, and will use a different suffix for shared
3957 objects. On platforms where there is no difference, SCons will
3958 allow both normal (static) and shared objects to be linked into a
3959 shared library, and will use the same suffix for shared and normal
3960 (static) objects. The target object file prefix, specified by the
3961 $SHOBJPREFIX construction variable (by default, the same as
3962 $OBJPREFIX), and suffix, specified by the $SHOBJSUFFIX construction
3963 variable, are automatically added to the target if not already
3964 present. Examples:
3965 env.SharedObject(target='ddd', source='ddd.c')
3967 env.SharedObject(target='eee.o', source='eee.cpp')
3968 env.SharedObject(target='fff.obj', source='fff.for')
3969 Note that the source files will be scanned according to the suffix
3971 mappings in the SourceFileScanner object. See the manpage section
3972 "Scanner Objects" for more information.
3973 StaticLibrary(), env.StaticLibrary()
3975 Builds a static library given one or more object files or C, C++, D
3976 or Fortran source files. If any source files are given, then they
3977 will be automatically compiled to object files. The static library
3978 file prefix, specified by the $LIBPREFIX construction variable (by
3979 default, lib on POSIX systems, nothing on Windows systems), and
3980 suffix, specified by the $LIBSUFFIX construction variable (by
3981 default, .lib on Windows systems, .a on POSIX systems), are
3982 automatically added to the target if not already present. Example:
3983 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
3985 Any object files listed in the source must have been built for a
3987 static library (that is, using the StaticObject builder method).
3988 scons will raise an error if there is any mismatch.
3989 StaticObject(), env.StaticObject()
3991 Builds a static object file from one or more C, C++, D, or Fortran
3992 source files. Source files must have one of the following
3993 extensions:
3994 .asm assembly language file
3996 .ASM assembly language file
3997 .c C file
3998 .C Windows: C file
3999 POSIX: C++ file
4000 .cc C++ file
4001 .cpp C++ file
4002 .cxx C++ file
4003 .cxx C++ file
4004 .c++ C++ file
4005 .C++ C++ file
4006 .d D file
4007 .f Fortran file
4008 .F Windows: Fortran file
4009 POSIX: Fortran file + C pre-processor
4010 .for Fortran file
4011 .FOR Fortran file
4012 .fpp Fortran file + C pre-processor
4013 .FPP Fortran file + C pre-processor
4014 .m Object C file
4015 .mm Object C++ file
4016 .s assembly language file
4017 .S Windows: assembly language file
4018 ARM: CodeSourcery Sourcery Lite
4019 .sx assembly language file + C pre-processor
4020 POSIX: assembly language file + C pre-processor
4021 .spp assembly language file + C pre-processor
4022 .SPP assembly language file + C pre-processor
4023 The target object file prefix, specified by the $OBJPREFIX
4025 construction variable (nothing by default), and suffix, specified
4026 by the $OBJSUFFIX construction variable (.obj on Windows systems,
4027 .o on POSIX systems), are automatically added to the target if not
4028 already present. Examples:
4029 env.StaticObject(target='aaa', source='aaa.c')
4031 env.StaticObject(target='bbb.o', source='bbb.c++')
4032 env.StaticObject(target='ccc.obj', source='ccc.f')
4033 Note that the source files will be scanned according to the suffix
4035 mappings in the SourceFileScanner object. See the manpage section
4036 "Scanner Objects" for more information.
4037 Substfile(), env.Substfile()
4039 The Substfile builder creates a single text file from a template
4040 consisting of a file or set of files (or nodes), replacing text
4041 using the $SUBST_DICT construction variable (if set). If a set,
4042 they are concatenated into the target file using the value of the
4043 $LINESEPARATOR construction variable as a separator between
4044 contents; the separator is not emitted after the contents of the
4045 last file. Nested lists of source files are flattened. See also
4046 Textfile.
4047 If a single source file name is specified and has a .in suffix, the
4049 suffix is stripped and the remainder of the name is used as the
4050 default target name.
4051 The prefix and suffix specified by the $SUBSTFILEPREFIX and
4053 $SUBSTFILESUFFIX construction variables (an empty string by default
4054 in both cases) are automatically added to the target if they are
4055 not already present.
4056 If a construction variable named $SUBST_DICT is present, it may be
4058 either a Python dictionary or a sequence of (key, value) tuples. If
4059 it is a dictionary it is converted into a list of tuples with
4060 unspecified order, so if one key is a prefix of another key or if
4061 one substitution could be further expanded by another subsitition,
4062 it is unpredictable whether the expansion will occur.
4063 Any occurrences of a key in the source are replaced by the
4065 corresponding value, which may be a Python callable function or a
4066 string. If the value is a callable, it is called with no arguments
4067 to get a string. Strings are subst-expanded and the result replaces
4068 the key.
4069 env = Environment(tools=['default'])
4071 env['prefix'] = '/usr/bin'
4073 script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
4074 env.Substfile('script.in', SUBST_DICT=script_dict)
4075 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
4077 env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict)
4078 # UNPREDICTABLE - one key is a prefix of another
4080 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
4081 env.Substfile('foo.in', SUBST_DICT=bad_foo)
4082 # PREDICTABLE - keys are applied longest first
4084 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
4085 env.Substfile('foo.in', SUBST_DICT=good_foo)
4086 # UNPREDICTABLE - one substitution could be futher expanded
4088 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
4089 env.Substfile('bar.in', SUBST_DICT=bad_bar)
4090 # PREDICTABLE - substitutions are expanded in order
4092 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
4093 env.Substfile('bar.in', SUBST_DICT=good_bar)
4094 # the SUBST_DICT may be in common (and not an override)
4096 substutions = {}
4097 subst = Environment(tools=['textfile'], SUBST_DICT=substitutions)
4098 substitutions['@foo@'] = 'foo'
4099 subst['SUBST_DICT']['@bar@'] = 'bar'
4100 subst.Substfile(
4101 'pgm1.c',
4102 [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"],
4103 )
4104 subst.Substfile(
4105 'pgm2.c',
4106 [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"],
4107 )
4108 Tar(), env.Tar()
4111 Builds a tar archive of the specified files and/or directories.
4112 Unlike most builder methods, the Tar builder method may be called
4113 multiple times for a given target; each additional call adds to the
4114 list of entries that will be built into the archive. Any source
4115 directories will be scanned for changes to any on-disk files,
4116 regardless of whether or not scons knows about them from other
4117 Builder or function calls.
4118 env.Tar('src.tar', 'src')
4120 # Create the stuff.tar file.
4122 env.Tar('stuff', ['subdir1', 'subdir2'])
4123 # Also add "another" to the stuff.tar file.
4124 env.Tar('stuff', 'another')
4125 # Set TARFLAGS to create a gzip-filtered archive.
4127 env = Environment(TARFLAGS = '-c -z')
4128 env.Tar('foo.tar.gz', 'foo')
4129 # Also set the suffix to .tgz.
4131 env = Environment(TARFLAGS = '-c -z',
4132 TARSUFFIX = '.tgz')
4133 env.Tar('foo')
4134 Textfile(), env.Textfile()
4136 The Textfile builder generates a single text file from a template
4137 consisting of a list of strings, replacing text using the
4138 $SUBST_DICT construction variable (if set) - see Substfile for a
4139 description of replacement. The strings will be separated in the
4140 target file using the value of the $LINESEPARATOR construction
4141 variable; the line separator is not emitted after the last string.
4142 Nested lists of source strings are flattened. Source strings need
4143 not literally be Python strings: they can be Nodes or Python
4144 objects that convert cleanly to Value nodes
4145 The prefix and suffix specified by the $TEXTFILEPREFIX and
4147 $TEXTFILESUFFIX construction variables (by default an empty string
4148 and .txt, respectively) are automatically added to the target if
4149 they are not already present. Examples:
4150 # builds/writes foo.txt
4152 env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller'])
4153 # builds/writes bar.txt
4155 env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*')
4156 # nested lists are flattened automatically
4158 env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei'])
4159 # files may be used as input by wraping them in File()
4161 env.Textfile(
4162 target='concat', # concatenate files with a marker between
4163 source=[File('concat1'), File('concat2')],
4164 LINESEPARATOR='====================\n',
4165 )
4166 Results:
4168 foo.txt
4170 Goethe
4172 42
4173 Schiller
4174 bar.txt
4176 lalala|*tanteratei
4178 blob.txt
4180 lalala
4182 Goethe
4183 42
4184 Schiller
4185 tanteratei
4186 Translate(), env.Translate()
4188 This pseudo-builder belongs to gettext toolset. The builder
4189 extracts internationalized messages from source files, updates POT
4190 template (if necessary) and then updates PO translations (if
4191 necessary). If $POAUTOINIT is set, missing PO files will be
4192 automatically created (i.e. without translator person
4193 intervention). The variables $LINGUAS_FILE and $POTDOMAIN are taken
4194 into acount too. All other construction variables used by
4195 POTUpdate, and POUpdate work here too.
4196 Example 1. The simplest way is to specify input files and output
4199 languages inline in a SCons script when invoking Translate
4200 # SConscript in 'po/' directory
4202 env = Environment( tools = ["default", "gettext"] )
4203 env['POAUTOINIT'] = 1
4204 env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
4205 Example 2. If you wish, you may also stick to conventional style
4208 known from autotools, i.e. using POTFILES.in and LINGUAS files
4209 # LINGUAS
4211 en pl
4212 #end
4213 # POTFILES.in
4215 a.cpp
4216 b.cpp
4217 # end
4218 # SConscript
4220 env = Environment( tools = ["default", "gettext"] )
4221 env['POAUTOINIT'] = 1
4222 env['XGETTEXTPATH'] = ['../']
4223 env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
4224 The last approach is perhaps the recommended one. It allows easily
4226 split internationalization/localization onto separate SCons
4227 scripts, where a script in source tree is responsible for
4228 translations (from sources to PO files) and script(s) under variant
4229 directories are responsible for compilation of PO to MO files to
4230 and for installation of MO files. The "gluing factor" synchronizing
4231 these two scripts is then the content of LINGUAS file. Note, that
4232 the updated POT and PO files are usually going to be committed back
4233 to the repository, so they must be updated within the source
4234 directory (and not in variant directories). Additionaly, the file
4235 listing of po/ directory contains LINGUAS file, so the source tree
4236 looks familiar to translators, and they may work with the project
4237 in their usual way.
4238 Example 3. Let's prepare a development tree as below
4241 project/
4243 + SConstruct
4244 + build/
4245 + src/
4246 + po/
4247 + SConscript
4248 + SConscript.i18n
4249 + POTFILES.in
4250 + LINGUAS
4251 with build being variant directory. Write the top-level SConstruct
4253 script as follows
4254 # SConstruct
4256 env = Environment( tools = ["default", "gettext"] )
4257 VariantDir('build', 'src', duplicate = 0)
4258 env['POAUTOINIT'] = 1
4259 SConscript('src/po/SConscript.i18n', exports = 'env')
4260 SConscript('build/po/SConscript', exports = 'env')
4261 the src/po/SConscript.i18n as
4263 # src/po/SConscript.i18n
4265 Import('env')
4266 env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
4267 and the src/po/SConscript
4269 # src/po/SConscript
4271 Import('env')
4272 env.MOFiles(LINGUAS_FILE = 1)
4273 Such setup produces POT and PO files under source tree in src/po/
4275 and binary MO files under variant tree in build/po/. This way the
4276 POT and PO files are separated from other output files, which must
4277 not be committed back to source repositories (e.g. MO files).
4278 Note
4281 In above example, the PO files are not updated, nor created
4282 automatically when you issue scons '.' command. The files must
4283 be updated (created) by hand via scons po-update and then MO
4284 files can be compiled by running scons '.'.
4285 TypeLibrary(), env.TypeLibrary()
4287 Builds a Windows type library (.tlb) file from an input IDL file
4288 (.idl). In addition, it will build the associated interface stub
4289 and proxy source files, naming them according to the base name of
4290 the .idl file. For example,
4291 env.TypeLibrary(source="foo.idl")
4293 Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c files.
4295 Uic(), env.Uic()
4297 Builds a header file, an implementation file and a moc file from an
4298 ui file. and returns the corresponding nodes in the that order.
4299 This builder is only available after using the tool qt. Note: you
4300 can specify .ui files directly as source files to the Program,
4301 Library and SharedLibrary builders without using this builder.
4302 Using this builder lets you override the standard naming
4303 conventions (be careful: prefixes are always prepended to names of
4304 built files; if you don't want prefixes, you may set them to ``).
4305 See the $QTDIR variable for more information. Example:
4306 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
4308 env.Uic(
4309 target=Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
4310 source='foo.ui'
4311 ) # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
4312 Zip(), env.Zip()
4314 Builds a zip archive of the specified files and/or directories.
4315 Unlike most builder methods, the Zip builder method may be called
4316 multiple times for a given target; each additional call adds to the
4317 list of entries that will be built into the archive. Any source
4318 directories will be scanned for changes to any on-disk files,
4319 regardless of whether or not scons knows about them from other
4320 Builder or function calls.
4321 env.Zip('src.zip', 'src')
4323 # Create the stuff.zip file.
4325 env.Zip('stuff', ['subdir1', 'subdir2'])
4326 # Also add "another" to the stuff.tar file.
4327 env.Zip('stuff', 'another')
4328 All targets of builder methods automatically depend on their sources.
4330 An explicit dependency can be specified using the env.Depends method of
4331 a construction environment (see below).
4332 In addition, scons automatically scans source files for various
4334 programming languages, so the dependencies do not need to be specified
4335 explicitly. By default, SCons can C source files, C++ source files,
4336 Fortran source files with .F (POSIX systems only), .fpp, or .FPP file
4337 extensions, and assembly language files with .S (POSIX systems only),
4338 .spp, or .SPP files extensions for C preprocessor dependencies. SCons
4339 also has default support for scanning D source files, You can also
4340 write your own Scanners to add support for additional source file
4341 types. These can be added to the default Scanner object used by the
4342 Object, StaticObject and SharedObject Builders by adding them to the
4343 SourceFileScanner object. See the section called “Scanner Objects” for
4344 more information about defining your own Scanner objects and using the
4345 SourceFileScanner object.
4346 Methods and Functions To Do Things
4348 In addition to Builder methods, scons provides a number of other
4349 construction environment methods and global functions to manipulate the
4350 build configuration.
4351 Usually, a construction environment method and global function with the
4353 same name both exist for convenience. In the following list, the global
4354 function is documented in this style:
4355 Function(arguments, [optional arguments])
4357 and the construction environment method looks like:
4359 env.Function(arguments, [optional arguments])
4361 If the function can be called both ways, then both forms are listed.
4363 The global function and same-named construction environment method
4365 provide almost identical functionality, with a couple of exceptions.
4366 First, many of the construction environment methods affect only that
4367 construction environment, while the global function has a global
4368 effect. Second, where appropriate, calling the functionality through a
4369 construction environment will substitute construction variables into
4370 any supplied string arguments, while the global function doesn't have
4371 the context of a construction environment to pick variables from, so it
4372 cannot perform the substitution. For example:
4373 Default('$FOO')
4375 env = Environment(FOO='foo')
4377 env.Default('$FOO')
4378 In the above example, the call to the global Default function will add
4380 a target named $FOO to the list of default targets, while the call to
4381 the env.Default construction environment method will expand the value
4382 and add a target named foo to the list of default targets. For more on
4383 construction variable expansion, see the next section on construction
4384 variables.
4385 Global functions may be called from custom Python modules that you
4387 import into an SConscript file by adding the following import to the
4388 Python module:
4389 from SCons.Script import *
4391 Construction environment methods and global functions provided by scons
4393 include:
4394 Action(action, [output, [var, ...]] [key=value, ...]),
4396 env.Action(action, [output, [var, ...]] [key=value, ...])
4397 A factory function to create an Action object for the specified
4398 action. See the manpage section "Action Objects" for a complete
4399 explanation of the arguments and behavior.
4400 Note that the env.Action form of the invocation will expand
4402 construction variables in any argument strings, including the
4403 action argument, at the time it is called using the construction
4404 variables in the env construction environment through which
4405 env.Action was called. The Action global function form delays all
4406 variable expansion until the Action object is actually used.
4407 AddMethod(object, function, [name]), env.AddMethod(function, [name])
4409 Adds function to an object as a method. function will be called
4410 with an instance object as the first argument as for other methods.
4411 If name is given, it is used as the name of the new method, else
4412 the name of function is used.
4413 When the global function AddMethod is called, the object to add the
4415 method to must be passed as the first argument; typically this will
4416 be Environment, in order to create a method which applies to all
4417 construction environments subsequently constructed. When called
4418 using the env.AddMethod form, the method is added to the specified
4419 construction environment only. Added methods propagate through
4420 env.Clone calls.
4421 More examples:
4423 # Function to add must accept an instance argument.
4425 # The Python convention is to call this 'self'.
4426 def my_method(self, arg):
4427 print("my_method() got", arg)
4428 # Use the global function to add a method to the Environment class:
4430 AddMethod(Environment, my_method)
4431 env = Environment()
4432 env.my_method('arg')
4433 # Use the optional name argument to set the name of the method:
4435 env.AddMethod(my_method, 'other_method_name')
4436 env.other_method_name('another arg')
4437 AddOption(arguments)
4439 Adds a local (project-specific) command-line option. arguments are
4440 the same as those supported by the add_option method in the
4441 standard Python library module optparse, with a few additional
4442 capabilities noted below. See the documentation for optparse for a
4443 thorough discussion of its option-processing capabities.
4444 In addition to the arguments and values supported by the optparse
4446 add_option method, AddOption allows setting the nargs keyword value
4447 to a string consisting of a question mark ('?') to indicate that
4448 the option argument for that option string is optional. If the
4449 option string is present on the command line but has no matching
4450 option argument, the value of the const keyword argument is
4451 produced as the value of the option. If the option string is
4452 omitted from the command line, the value of the default keyword
4453 argument is produced, as usual; if there is no default keyword
4454 argument in the AddOption call, None is produced.
4455 optparse recognizes abbreviations of long option names, as long as
4458 they can be unambiguously resolved. For example, if add_option is
4459 called to define a --devicename option, it will recognize --device,
4460 --dev and so forth as long as there is no other option which could
4461 also match to the same abbreviation. Options added via AddOption do
4462 not support the automatic recognition of abbreviations. Instead, to
4463 allow specific abbreviations, include them as synonyms in the
4464 AddOption call itself.
4465 Once a new command-line option has been added with AddOption, the
4467 option value may be accessed using GetOption or env.GetOption.
4468 SetOption is not currently supported for options added with
4469 AddOption.
4470 Help text for an option is a combination of the string supplied in
4472 the help keyword argument to AddOption and information collected
4473 from the other keyword arguments. Such help is displayed if the -h
4474 command line option is used (but not with -H). Help for all local
4475 options is displayed under the separate heading Local Options. The
4476 options are unsorted - they will appear in the help text in the
4477 order in which the AddOption calls occur.
4478 Example:
4480 AddOption(
4482 '--prefix',
4483 dest='prefix',
4484 nargs=1,
4485 type='string',
4486 action='store',
4487 metavar='DIR',
4488 help='installation prefix',
4489 )
4490 env = Environment(PREFIX=GetOption('prefix'))
4491 For that example, the following help text would be produced:
4493 Local Options:
4495 --prefix=DIR installation prefix
4496 Help text for local options may be unavailable if the Help function
4498 has been called, see the Help documentation for details.
4499 Note
4501 As an artifact of the internal implementation, the behavior of
4502 options added by AddOption which take option arguments is
4503 undefined if whitespace (rather than an = sign) is used as the
4504 separator on the command line. Users should avoid such usage;
4505 it is recommended to add a note to this effect to project
4506 documentation if the situation is likely to arise. In addition,
4507 if the nargs keyword is used to specify more than one following
4508 option argument (that is, with a value of 2 or greater), such
4509 arguments would necessarily be whitespace separated, triggering
4510 the issue. Developers should not use AddOption this way. Future
4511 versions of SCons will likely forbid such usage.
4512 AddPostAction(target, action), env.AddPostAction(target, action)
4514 Arranges for the specified action to be performed after the
4515 specified target has been built. The specified action(s) may be an
4516 Action object, or anything that can be converted into an Action
4517 object See the manpage section "Action Objects" for a complete
4518 explanation.
4519 When multiple targets are supplied, the action may be called
4521 multiple times, once after each action that generates one or more
4522 targets in the list.
4523 AddPreAction(target, action), env.AddPreAction(target, action)
4525 Arranges for the specified action to be performed before the
4526 specified target is built. The specified action(s) may be an Action
4527 object, or anything that can be converted into an Action object See
4528 the manpage section "Action Objects" for a complete explanation.
4529 When multiple targets are specified, the action(s) may be called
4531 multiple times, once before each action that generates one or more
4532 targets in the list.
4533 Note that if any of the targets are built in multiple steps, the
4535 action will be invoked just before the "final" action that
4536 specifically generates the specified target(s). For example, when
4537 building an executable program from a specified source .c file via
4538 an intermediate object file:
4539 foo = Program('foo.c')
4541 AddPreAction(foo, 'pre_action')
4542 The specified pre_action would be executed before scons calls the
4544 link command that actually generates the executable program binary
4545 foo, not before compiling the foo.c file into an object file.
4546 Alias(alias, [targets, [action]]), env.Alias(alias, [targets,
4548 [action]])
4549 Creates one or more phony targets that expand to one or more other
4550 targets. An optional action (command) or list of actions can be
4551 specified that will be executed whenever the any of the alias
4552 targets are out-of-date. Returns the Node object representing the
4553 alias, which exists outside of any file system. This Node object,
4554 or the alias name, may be used as a dependency of any other target,
4555 including another alias. Alias can be called multiple times for
4556 the same alias to add additional targets to the alias, or
4557 additional actions to the list for this alias. Aliases are global
4558 even if set through the construction environment method.
4559 Examples:
4561 Alias('install')
4563 Alias('install', '/usr/bin')
4564 Alias(['install', 'install-lib'], '/usr/local/lib')
4565 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
4567 env.Alias('install', ['/usr/local/man'])
4568 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
4570 AllowSubstExceptions([exception, ...])
4572 Specifies the exceptions that will be allowed when expanding
4573 construction variables. By default, any construction variable
4574 expansions that generate a NameError or IndexError exception will
4575 expand to a '' (an empty string) and not cause scons to fail. All
4576 exceptions not in the specified list will generate an error message
4577 and terminate processing.
4578 If AllowSubstExceptions is called multiple times, each call
4580 completely overwrites the previous list of allowed exceptions.
4581 Example:
4583 # Requires that all construction variable names exist.
4585 # (You may wish to do this if you want to enforce strictly
4586 # that all construction variables must be defined before use.)
4587 AllowSubstExceptions()
4588 # Also allow a string containing a zero-division expansion
4590 # like '${1 / 0}' to evalute to ''.
4591 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
4592 AlwaysBuild(target, ...), env.AlwaysBuild(target, ...)
4594 Marks each given target so that it is always assumed to be out of
4595 date, and will always be rebuilt if needed. Note, however, that
4596 AlwaysBuild does not add its target(s) to the default target list,
4597 so the targets will only be built if they are specified on the
4598 command line, or are a dependent of a target specified on the
4599 command line--but they will always be built if so specified.
4600 Multiple targets can be passed in to a single call to AlwaysBuild.
4601 env.Append(key=val, [...])
4603 Intelligently append values to construction variables in the
4604 construction environment named by env. The construction variables
4605 and values to add to them are passed as key=val pairs (Python
4606 keyword arguments). env.Append is designed to allow adding values
4607 without normally having to know the data type of an existing
4608 construction variable. Regular Python syntax can also be used to
4609 manipulate the construction variable, but for that you must know
4610 the type of the construction variable: for example, different
4611 Python syntax is needed to combine a list of values with a single
4612 string value, or vice versa. Some pre-defined construction
4613 variables do have type expectations based on how SCons will use
4614 them, for example $CPPDEFINES is normally a string or a list of
4615 strings, but can be a string, a list of strings, a list of tuples,
4616 or a dictionary, while $LIBEMITTER would expect a callable or list
4617 of callables, and $BUILDERS would expect a mapping type. Consult
4618 the documentation for the various construction variables for more
4619 details.
4620 The following descriptions apply to both the append and prepend
4622 functions, the only difference being the insertion point of the
4623 added values.
4624 If env. does not have a construction variable indicated by key, val
4626 is added to the environment under that key as-is.
4627 val can be almost any type, and SCons will combine it with an
4630 existing value into an appropriate type, but there are a few
4631 special cases to be aware of. When two strings are combined, the
4632 result is normally a new string, with the caller responsible for
4633 supplying any needed separation. The exception to this is the
4634 construction variable $CPPDEFINES, in which each item will be
4635 postprocessed by adding a prefix and/or suffix, so the contents are
4636 treated as a list of strings, that is, adding a string will result
4637 in a separate string entry, not a combined string. For $CPPDEFINES
4638 as well as for $LIBS, and the various *PATH; variables, SCons will
4639 supply the compiler-specific syntax (e.g. adding a -D or /D prefix
4640 for $CPPDEFINES), so this syntax should be omitted when adding
4641 values to these variables. Example (gcc syntax shown in the
4642 expansion of CPPDEFINES):
4643 env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE")
4645 print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['CPPDEFINES']))
4646 # notice including a leading space in CXXFLAGS value
4647 env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA")
4648 print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['CPPDEFINES']))
4649 print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFLAGS")))
4650 $ scons -Q
4652 CXXFLAGS=-std=c11, CPPDEFINES=RELEASE
4653 CXXFLAGS=-std=c11 -O, CPPDEFINES=['RELEASE', 'EXTRA']
4654 CPPDEFINES will expand to -DRELEASE -DEXTRA
4655 scons: `.' is up to date.
4656 Because $CPPDEFINES is intended to describe C/C++ pre-processor
4658 macro definitions, it accepts additional syntax. Preprocessor
4659 macros can be valued, or un-valued, as in -DBAR=1 or -DFOO. The
4660 macro can be be supplied as a complete string including the value,
4661 or as a tuple (or list) of macro, value, or as a dictionary.
4662 Example (again gcc syntax in the expanded defines):
4663 env = Environment(CPPDEFINES="FOO")
4665 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4666 env.Append(CPPDEFINES="BAR=1")
4667 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4668 env.Append(CPPDEFINES=("OTHER", 2))
4669 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4670 env.Append(CPPDEFINES={"EXTRA": "arg"})
4671 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4672 print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFLAGS")))
4673 $ scons -Q
4675 CPPDEFINES=FOO
4676 CPPDEFINES=['FOO', 'BAR=1']
4677 CPPDEFINES=['FOO', 'BAR=1', ('OTHER', 2)]
4678 CPPDEFINES=['FOO', 'BAR=1', ('OTHER', 2), {'EXTRA': 'arg'}]
4679 CPPDEFINES will expand to -DFOO -DBAR=1 -DOTHER=2 -DEXTRA=arg
4680 scons: `.' is up to date.
4681 Adding a string val to a dictonary construction variable will enter
4683 val as the key in the dict, and None as its value. Using a tuple
4684 type to supply a key + value only works for the special case of
4685 $CPPDEFINES described above.
4686 Although most combinations of types work without needing to know
4688 the details, some combinations do not make sense and a Python
4689 exception will be raised.
4690 When using env.Append to modify construction variables which are
4692 path specifications (conventionally, the names of such end in
4693 PATH), it is recommended to add the values as a list of strings,
4694 even if there is only a single string to add. The same goes for
4695 adding library names to $LIBS.
4696 env.Append(CPPPATH=["#/include"])
4698 See also env.AppendUnique, env.Prepend and env.PrependUnique.
4700 env.AppendENVPath(name, newpath, [envname, sep, delete_existing=False])
4702 Append path elements specified by newpath to the given search path
4703 string or list name in mapping envname in the construction
4704 environment. Supplying envname is optional: the default is the
4705 execution environment $ENV. Optional sep is used as the search path
4706 separator, the default is the platform's separator (os.pathsep). A
4707 path element will only appear once. Any duplicates in newpath are
4708 dropped, keeping the last appearing (to preserve path order). If
4709 delete_existing is False (the default) any addition duplicating an
4710 existing path element is ignored; if delete_existing is True the
4711 existing value will be dropped and the path element will be added
4712 at the end. To help maintain uniqueness all paths are normalized
4713 (using os.path.normpath and os.path.normcase).
4714 Example:
4716 print('before:', env['ENV']['INCLUDE'])
4718 include_path = '/foo/bar:/foo'
4719 env.AppendENVPath('INCLUDE', include_path)
4720 print('after:', env['ENV']['INCLUDE'])
4721 Yields:
4723 before: /foo:/biz
4725 after: /biz:/foo/bar:/foo
4726 See also env.PrependENVPath.
4728 env.AppendUnique(key=val, [...], delete_existing=False)
4730 Append values to construction variables in the current construction
4731 environment, maintaining uniqueness. Works like env.Append (see for
4732 details), except that values already present in the construction
4733 variable will not be added again. If delete_existing is True, the
4734 existing matching value is first removed, and the requested value
4735 is added, having the effect of moving such values to the end.
4736 Example:
4738 env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy'])
4740 See also env.Append, env.Prepend and env.PrependUnique.
4742 Builder(action, [arguments]), env.Builder(action, [arguments])
4744 Creates a Builder object for the specified action. See the manpage
4745 section "Builder Objects" for a complete explanation of the
4746 arguments and behavior.
4747 Note that the env.Builder() form of the invocation will expand
4749 construction variables in any arguments strings, including the
4750 action argument, at the time it is called using the construction
4751 variables in the env construction environment through which
4752 env.Builder was called. The Builder form delays all variable
4753 expansion until after the Builder object is actually called.
4754 CacheDir(cache_dir, custom_class=None), env.CacheDir(cache_dir,
4756 custom_class=None)
4757 Direct scons to maintain a derived-file cache in cache_dir. The
4758 derived files in the cache will be shared among all the builds
4759 specifying the same cache_dir. Specifying a cache_dir of None
4760 disables derived file caching.
4761 When specifying a custom_class which should be a class type which
4763 is a subclass of SCons.CacheDir.CacheDir, SCons will internally
4764 invoke this class to use for performing caching operations. This
4765 argument is optional and if left to default None, will use the
4766 default SCons.CacheDir.CacheDir class.
4767 Calling the environment method env.CacheDir limits the effect to
4769 targets built through the specified construction environment.
4770 Calling the global function CacheDir sets a global default that
4771 will be used by all targets built through construction environments
4772 that do not set up environment-specific caching by calling
4773 env.CacheDir.
4774 When derived-file caching is being used and scons finds a derived
4776 file that needs to be rebuilt, it will first look in the cache to
4777 see if a file with matching build signature exists (indicating the
4778 input file(s) and build action(s) were identical to those for the
4779 current target), and if so, will retrieve the file from the cache.
4780 scons will report Retrieved `file' from cache instead of the normal
4781 build message. If the derived file is not present in the cache,
4782 scons will build it and then place a copy of the built file in the
4783 cache, identified by its build signature, for future use.
4784 The Retrieved `file' from cache messages are useful for human
4786 consumption, but less so when comparing log files between scons
4787 runs which will show differences that are noisy and not actually
4788 significant. To disable, use the --cache-show option. With this
4789 option, scons will print the action that would have been used to
4790 build the file without considering cache retrieval.
4791 Derived-file caching may be disabled for any invocation of scons by
4793 giving the --cache-disable command line option. Cache updating may
4794 be disabled, leaving cache fetching enabled, by giving the
4795 --cache-readonly.
4796 If the --cache-force option is used, scons will place a copy of all
4798 derived files in the cache, even if they already existed and were
4799 not built by this invocation. This is useful to populate a cache
4800 the first time a cache_dir is used for a build, or to bring a cache
4801 up to date after a build with cache updating disabled
4802 (--cache-disable or --cache-readonly) has been done.
4803 The NoCache method can be used to disable caching of specific
4805 files. This can be useful if inputs and/or outputs of some tool are
4806 impossible to predict or prohibitively large.
4807 Note that (at this time) SCons provides no facilities for managing
4809 the derived-file cache. It is up to the developer to arrange for
4810 cache pruning, expiry, etc. if needed.
4811 Clean(targets, files_or_dirs), env.Clean(targets, files_or_dirs)
4813 This specifies a list of files or directories which should be
4814 removed whenever the targets are specified with the -c command line
4815 option. The specified targets may be a list or an individual
4816 target. Multiple calls to Clean are legal, and create new targets
4817 or add files and directories to the clean list for the specified
4818 targets.
4819 Multiple files or directories should be specified either as
4821 separate arguments to the Clean method, or as a list. Clean will
4822 also accept the return value of any of the construction environment
4823 Builder methods. Examples:
4824 The related NoClean function overrides calling Clean for the same
4826 target, and any targets passed to both functions will not be
4827 removed by the -c option.
4828 Examples:
4830 Clean('foo', ['bar', 'baz'])
4832 Clean('dist', env.Program('hello', 'hello.c'))
4833 Clean(['foo', 'bar'], 'something_else_to_clean')
4834 In this example, installing the project creates a subdirectory for
4836 the documentation. This statement causes the subdirectory to be
4837 removed if the project is deinstalled.
4838 Clean(docdir, os.path.join(docdir, projectname))
4840 env.Clone([key=val, ...])
4842 Returns a separate copy of a construction environment. If there are
4843 any keyword arguments specified, they are added to the returned
4844 copy, overwriting any existing values for the keywords.
4845 Example:
4847 env2 = env.Clone()
4849 env3 = env.Clone(CCFLAGS='-g')
4850 Additionally, a list of tools and a toolpath may be specified, as
4852 in the Environment constructor:
4853 def MyTool(env):
4855 env['FOO'] = 'bar'
4856 env4 = env.Clone(tools=['msvc', MyTool])
4858 The parse_flags keyword argument is also recognized to allow
4860 merging command-line style arguments into the appropriate
4861 construction variables (see env.MergeFlags).
4862 # create an environment for compiling programs that use wxWidgets
4864 wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
4865 Command(target, source, action, [key=val, ...]), env.Command(target,
4867 source, action, [key=val, ...])
4868 Executes a specific action (or list of actions) to build a target
4869 file or files from a source file or files. This is more convenient
4870 than defining a separate Builder object for a single special-case
4871 build.
4872 The Command function accepts source_scanner, target_scanner,
4874 source_factory, and target_factory keyword arguments. These
4875 arguments can be used to specify a Scanner object that will be used
4876 to apply a custom scanner for a source or target. For example, the
4877 global DirScanner object can be used if any of the sources will be
4878 directories that must be scanned on-disk for changes to files that
4879 aren't already specified in other Builder of function calls. The
4880 *_factory arguments take a factory function that Command will use
4881 to turn any sources or targets specified as strings into SCons
4882 Nodes. See the manpage section "Builder Objects" for more
4883 information about how these arguments work in a Builder.
4884 Any other keyword arguments specified override any same-named
4886 existing construction variables.
4887 An action can be an external command, specified as a string, or a
4889 callable Python object; see the manpage section "Action Objects"
4890 for more complete information. Also note that a string specifying
4891 an external command may be preceded by an at-sign (@) to suppress
4892 printing the command in question, or by a hyphen (-) to ignore the
4893 exit status of the external command.
4894 Examples:
4896 env.Command(
4898 target='foo.out',
4899 source='foo.in',
4900 action="$FOO_BUILD < $SOURCES > $TARGET"
4901 )
4902 env.Command(
4904 target='bar.out',
4905 source='bar.in',
4906 action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"],
4907 ENV={'PATH': '/usr/local/bin/'},
4908 )
4909 import os
4912 def rename(env, target, source):
4913 os.rename('.tmp', str(target[0]))
4914 env.Command(
4917 target='baz.out',
4918 source='baz.in',
4919 action=["$BAZ_BUILD < $SOURCES > .tmp", rename],
4920 )
4921 Note that the Command function will usually assume, by default,
4923 that the specified targets and/or sources are Files, if no other
4924 part of the configuration identifies what type of entries they are.
4925 If necessary, you can explicitly specify that targets or source
4926 nodes should be treated as directories by using the Dir or env.Dir
4927 functions.
4928 Examples:
4930 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
4932 env['DISTDIR'] = 'destination/directory'
4934 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
4935 Also note that SCons will usually automatically create any
4937 directory necessary to hold a target file, so you normally don't
4938 need to create directories by hand.
4939 Configure(env, [custom_tests, conf_dir, log_file, config_h]),
4941 env.Configure([custom_tests, conf_dir, log_file, config_h])
4942 Creates a Configure object for integrated functionality similar to
4943 GNU autoconf. See the manpage section "Configure Contexts" for a
4944 complete explanation of the arguments and behavior.
4945 Decider(function), env.Decider(function)
4947 Specifies that all up-to-date decisions for targets built through
4948 this construction environment will be handled by the specified
4949 function. function can be the name of a function or one of the
4950 following strings that specify the predefined decision function
4951 that will be applied:
4952 "timestamp-newer"
4954 Specifies that a target shall be considered out of date and
4955 rebuilt if the dependency's timestamp is newer than the target
4956 file's timestamp. This is the behavior of the classic Make
4957 utility, and make can be used a synonym for timestamp-newer.
4958 "timestamp-match"
4960 Specifies that a target shall be considered out of date and
4961 rebuilt if the dependency's timestamp is different than the
4962 timestamp recorded the last time the target was built. This
4963 provides behavior very similar to the classic Make utility (in
4964 particular, files are not opened up so that their contents can
4965 be checksummed) except that the target will also be rebuilt if
4966 a dependency file has been restored to a version with an
4967 earlier timestamp, such as can happen when restoring files from
4968 backup archives.
4969 "content"
4971 Specifies that a target shall be considered out of date and
4972 rebuilt if the dependency's content has changed since the last
4973 time the target was built, as determined be performing an
4974 checksum on the dependency's contents and comparing it to the
4975 checksum recorded the last time the target was built. MD5 can
4976 be used as a synonym for content, but it is deprecated.
4977 "content-timestamp"
4979 Specifies that a target shall be considered out of date and
4980 rebuilt if the dependency's content has changed since the last
4981 time the target was built, except that dependencies with a
4982 timestamp that matches the last time the target was rebuilt
4983 will be assumed to be up-to-date and not rebuilt. This provides
4984 behavior very similar to the content behavior of always
4985 checksumming file contents, with an optimization of not
4986 checking the contents of files whose timestamps haven't
4987 changed. The drawback is that SCons will not detect if a file's
4988 content has changed but its timestamp is the same, as might
4989 happen in an automated script that runs a build, updates a
4990 file, and runs the build again, all within a single second.
4991 MD5-timestamp can be used as a synonym for content-timestamp,
4992 but it is deprecated.
4993 Examples:
4995 # Use exact timestamp matches by default.
4997 Decider('timestamp-match')
4998 # Use hash content signatures for any targets built
5000 # with the attached construction environment.
5001 env.Decider('content')
5002 In addition to the above already-available functions, the function
5004 argument may be a Python function you supply. Such a function must
5005 accept the following four arguments:
5006 dependency
5008 The Node (file) which should cause the target to be rebuilt if
5009 it has "changed" since the last tme target was built.
5010 target
5012 The Node (file) being built. In the normal case, this is what
5013 should get rebuilt if the dependency has "changed."
5014 prev_ni
5016 Stored information about the state of the dependency the last
5017 time the target was built. This can be consulted to match
5018 various file characteristics such as the timestamp, size, or
5019 content signature.
5020 repo_node
5022 If set, use this Node instead of the one specified by
5023 dependency to determine if the dependency has changed. This
5024 argument is optional so should be written as a default argument
5025 (typically it would be written as repo_node=None). A caller
5026 will normally only set this if the target only exists in a
5027 Repository.
5028 The function should return a value which evaluates True if the
5030 dependency has "changed" since the last time the target was built
5031 (indicating that the target should be rebuilt), and a value which
5032 evaluates False otherwise (indicating that the target should not be
5033 rebuilt). Note that the decision can be made using whatever
5034 criteria are appopriate. Ignoring some or all of the function
5035 arguments is perfectly normal.
5036 Example:
5038 def my_decider(dependency, target, prev_ni, repo_node=None):
5040 return not os.path.exists(str(target))
5041 env.Decider(my_decider)
5043 Default(target[, ...]), env.Default(target[, ...])
5045 Specify default targets to the SCons target selection mechanism.
5046 Any call to Default will cause SCons to use the defined default
5047 target list instead of its built-in algorithm for determining
5048 default targets (see the manpage section "Target Selection").
5049 target may be one or more strings, a list of strings, a NodeList as
5052 returned by a Builder, or None. A string target may be the name of
5053 a file or directory, or a target previously defined by a call to
5054 Alias (defining the alias later will still create the alias, but it
5055 will not be recognized as a default). Calls to Default are
5056 additive. A target of None will clear any existing default target
5057 list; subsequent calls to Default will add to the (now empty)
5058 default target list like normal.
5059 Both forms of this call affect the same global list of default
5061 targets; the construction environment method applies construction
5062 variable expansion to the targets.
5063 The current list of targets added using Default is available in the
5065 DEFAULT_TARGETS list (see below).
5066 Examples:
5068 Default('foo', 'bar', 'baz')
5070 env.Default(['a', 'b', 'c'])
5071 hello = env.Program('hello', 'hello.c')
5072 env.Default(hello)
5073 DefaultEnvironment([**kwargs])
5075 Instantiates and returns the default construction environment
5076 object. The default environment is used internally by SCons in
5077 order to execute many of the global functions in this list (that
5078 is, those not called as methods of a specific construction
5079 environment). It is not mandatory to call DefaultEnvironment: the
5080 default environment will be instantiated automatically when the
5081 build phase begins if the function has not been called, however
5082 calling it explicitly gives the opportunity to affect and examine
5083 the contents of the default environment.
5084 The default environment is a singleton, so the keyword arguments
5086 affect it only on the first call, on subsequent calls the
5087 already-constructed object is returned and any keyword arguments
5088 are silently ignored. The default environment can be modified after
5089 instantiation in the same way as any construction environment.
5090 Modifying the default environment has no effect on the construction
5091 environment constructed by an Environment or Clone call.
5092 Depends(target, dependency), env.Depends(target, dependency)
5094 Specifies an explicit dependency; the target will be rebuilt
5095 whenever the dependency has changed. Both the specified target and
5096 dependency can be a string (usually the path name of a file or
5097 directory) or Node objects, or a list of strings or Node objects
5098 (such as returned by a Builder call). This should only be necessary
5099 for cases where the dependency is not caught by a Scanner for the
5100 file.
5101 Example:
5103 env.Depends('foo', 'other-input-file-for-foo')
5105 mylib = env.Library('mylib.c')
5107 installed_lib = env.Install('lib', mylib)
5108 bar = env.Program('bar.c')
5109 # Arrange for the library to be copied into the installation
5111 # directory before trying to build the "bar" program.
5112 # (Note that this is for example only. A "real" library
5113 # dependency would normally be configured through the $LIBS
5114 # and $LIBPATH variables, not using an env.Depends() call.)
5115 env.Depends(bar, installed_lib)
5117 env.Detect(progs)
5119 Find an executable from one or more choices: progs may be a string
5120 or a list of strings. Returns the first value from progs that was
5121 found, or None. Executable is searched by checking the paths in the
5122 execution environment (env['ENV']['PATH']). On Windows systems,
5123 additionally applies the filename suffixes found in the execution
5124 environment (env['ENV']['PATHEXT']) but will not include any such
5125 extension in the return value. env.Detect is a wrapper around
5126 env.WhereIs.
5127 env.Dictionary([vars])
5129 Returns a dictionary object containing the construction variables
5130 in the construction environment. If there are any arguments
5131 specified, the values of the specified construction variables are
5132 returned as a string (if one argument) or as a list of strings.
5133 Example:
5135 cvars = env.Dictionary()
5137 cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
5138 Dir(name, [directory]), env.Dir(name, [directory])
5140 Returns Directory Node(s). A Directory Node is an object that
5141 represents a directory. name can be a relative or absolute path or
5142 a list of such paths. directory is an optional directory that will
5143 be used as the parent directory. If no directory is specified, the
5144 current script's directory is used as the parent.
5145 If name is a single pathname, the corresponding node is returned.
5147 If name is a list, SCons returns a list of nodes. Construction
5148 variables are expanded in name.
5149 Directory Nodes can be used anywhere you would supply a string as a
5151 directory name to a Builder method or function. Directory Nodes
5152 have attributes and methods that are useful in many situations; see
5153 manpage section "File and Directory Nodes" for more information.
5154 env.Dump([key], [format])
5156 Serializes construction variables to a string. The method supports
5157 the following formats specified by format:
5158 pretty
5160 Returns a pretty printed representation of the environment (if
5161 format is not specified, this is the default).
5162 json
5164 Returns a JSON-formatted string representation of the
5165 environment.
5166 If key is None (the default) the entire dictionary of construction
5168 variables is serialized. If supplied, it is taken as the name of a
5169 construction variable whose value is serialized.
5170 This SConstruct:
5172 env=Environment()
5174 print(env.Dump('CCCOM'))
5175 will print:
5177 '$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
5179 While this SConstruct:
5181 env = Environment()
5183 print(env.Dump())
5184 will print:
5186 { 'AR': 'ar',
5188 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
5189 'ARFLAGS': ['r'],
5190 'AS': 'as',
5191 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
5192 'ASFLAGS': [],
5193 ...
5194 EnsurePythonVersion(major, minor), env.EnsurePythonVersion(major,
5196 minor)
5197 Ensure that the Python version is at least major.minor. This
5198 function will print out an error message and exit SCons with a
5199 non-zero exit code if the actual Python version is not late enough.
5200 Example:
5202 EnsurePythonVersion(2,2)
5204 EnsureSConsVersion(major, minor, [revision]),
5206 env.EnsureSConsVersion(major, minor, [revision])
5207 Ensure that the SCons version is at least major.minor, or
5208 major.minor.revision. if revision is specified. This function will
5209 print out an error message and exit SCons with a non-zero exit code
5210 if the actual SCons version is not late enough.
5211 Examples:
5213 EnsureSConsVersion(0,14)
5215 EnsureSConsVersion(0,96,90)
5217 Environment([key=value, ...]), env.Environment([key=value, ...])
5219 Return a new construction environment initialized with the
5220 specified key=value pairs. The keyword arguments parse_flags,
5221 platform, toolpath, tools and variables are also specially
5222 recognized. See the manpage section "Construction Environments" for
5223 more details.
5224 Execute(action, [actionargs ...]), env.Execute(action, [actionargs
5226 ...])
5227 Executes an Action. action may be an Action object or it may be a
5228 command-line string, list of commands, or executable Python
5229 function, each of which will first be converted into an Action
5230 object and then executed. Any additional arguments to Execute are
5231 passed on to the Action factory function which actually creates the
5232 Action object (see the manpage section Action Objects for a
5233 description). Example:
5234 Execute(Copy('file.out', 'file.in'))
5236 Execute performs its action immediately, as part of the
5238 SConscript-reading phase. There are no sources or targets declared
5239 in an Execute call, so any objects it manipulates will not be
5240 tracked as part of the SCons dependency graph. In the example
5241 above, neither file.out nor file.in will be tracked objects.
5242 Execute returns the exit value of the command or return value of
5245 the Python function. scons prints an error message if the executed
5246 action fails (exits with or returns a non-zero value), however it
5247 does not, automatically terminate the build for such a failure. If
5248 you want the build to stop in response to a failed Execute call,
5249 you must explicitly check for a non-zero return value:
5250 if Execute("mkdir sub/dir/ectory"):
5252 # The mkdir failed, don't try to build.
5253 Exit(1)
5254 Exit([value]), env.Exit([value])
5256 This tells scons to exit immediately with the specified value. A
5257 default exit value of 0 (zero) is used if no value is specified.
5258 Export([vars...], [key=value...]), env.Export([vars...],
5260 [key=value...])
5261 Exports variables from the current SConscript file to a global
5262 collection where they can be imported by other SConscript files.
5263 vars may be one or more strings representing variable names to be
5264 exported. If a string contains whitespace, it is split into
5265 separate strings, as if multiple string arguments had been given. A
5266 vars argument may also be a dictionary, which can be used to map
5267 variables to different names when exported. Keyword arguments can
5268 be used to provide names and their values.
5269 Export calls are cumulative. Specifying a previously exported
5272 variable will overwrite the earlier value. Both local variables and
5273 global variables can be exported.
5274 Examples:
5276 env = Environment()
5278 # Make env available for all SConscript files to Import().
5279 Export("env")
5280 package = 'my_name'
5282 # Make env and package available for all SConscript files:.
5283 Export("env", "package")
5284 # Make env and package available for all SConscript files:
5286 Export(["env", "package"])
5287 # Make env available using the name debug:
5289 Export(debug=env)
5290 # Make env available using the name debug:
5292 Export({"debug": env})
5293 Note that the SConscript function supports an exports argument that
5295 allows exporting a variable or set of variables to a specific
5296 SConscript file or files. See the description below.
5297 File(name, [directory]), env.File(name, [directory])
5299 Returns File Node(s). A File Node is an object that represents a
5300 file. name can be a relative or absolute path or a list of such
5301 paths. directory is an optional directory that will be used as the
5302 parent directory. If no directory is specified, the current
5303 script's directory is used as the parent.
5304 If name is a single pathname, the corresponding node is returned.
5306 If name is a list, SCons returns a list of nodes. Construction
5307 variables are expanded in name.
5308 File Nodes can be used anywhere you would supply a string as a file
5310 name to a Builder method or function. File Nodes have attributes
5311 and methods that are useful in many situations; see manpage section
5312 "File and Directory Nodes" for more information.
5313 FindFile(file, dirs), env.FindFile(file, dirs)
5315 Search for file in the path specified by dirs. dirs may be a list
5316 of directory names or a single directory name. In addition to
5317 searching for files that exist in the filesystem, this function
5318 also searches for derived files that have not yet been built.
5319 Example:
5321 foo = env.FindFile('foo', ['dir1', 'dir2'])
5323 FindInstalledFiles(), env.FindInstalledFiles()
5325 Returns the list of targets set up by the Install or InstallAs
5326 builders.
5327 This function serves as a convenient method to select the contents
5329 of a binary package.
5330 Example:
5332 Install('/bin', ['executable_a', 'executable_b'])
5334 # will return the file node list
5336 # ['/bin/executable_a', '/bin/executable_b']
5337 FindInstalledFiles()
5338 Install('/lib', ['some_library'])
5340 # will return the file node list
5342 # ['/bin/executable_a', '/bin/executable_b', '/lib/some_library']
5343 FindInstalledFiles()
5344 FindPathDirs(variable)
5346 Returns a function (actually a callable Python object) intended to
5347 be used as the path_function of a Scanner object. The returned
5348 object will look up the specified variable in a construction
5349 environment and treat the construction variable's value as a list
5350 of directory paths that should be searched (like $CPPPATH,
5351 $LIBPATH, etc.).
5352 Note that use of FindPathDirs is generally preferable to writing
5354 your own path_function for the following reasons: 1) The returned
5355 list will contain all appropriate directories found in source trees
5356 (when VariantDir is used) or in code repositories (when Repository
5357 or the -Y option are used). 2) scons will identify expansions of
5358 variable that evaluate to the same list of directories as, in fact,
5359 the same list, and avoid re-scanning the directories for files,
5360 when possible.
5361 Example:
5363 def my_scan(node, env, path, arg):
5365 # Code to scan file contents goes here...
5366 return include_files
5367 scanner = Scanner(name = 'myscanner',
5369 function = my_scan,
5370 path_function = FindPathDirs('MYPATH'))
5371 FindSourceFiles(node='"."'), env.FindSourceFiles(node='"."')
5373 Returns the list of nodes which serve as the source of the built
5374 files. It does so by inspecting the dependency tree starting at the
5375 optional argument node which defaults to the '"."'-node. It will
5376 then return all leaves of node. These are all children which have
5377 no further children.
5378 This function is a convenient method to select the contents of a
5380 Source Package.
5381 Example:
5383 Program('src/main_a.c')
5385 Program('src/main_b.c')
5386 Program('main_c.c')
5387 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
5389 FindSourceFiles()
5390 # returns ['src/main_b.c', 'src/main_a.c' ]
5392 FindSourceFiles('src')
5393 As you can see build support files (SConstruct in the above
5395 example) will also be returned by this function.
5396 Flatten(sequence), env.Flatten(sequence)
5398 Takes a sequence (that is, a Python list or tuple) that may contain
5399 nested sequences and returns a flattened list containing all of the
5400 individual elements in any sequence. This can be helpful for
5401 collecting the lists returned by calls to Builders; other Builders
5402 will automatically flatten lists specified as input, but direct
5403 Python manipulation of these lists does not.
5404 Examples:
5406 foo = Object('foo.c')
5408 bar = Object('bar.c')
5409 # Because `foo' and `bar' are lists returned by the Object() Builder,
5411 # `objects' will be a list containing nested lists:
5412 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
5413 # Passing such a list to another Builder is all right because
5415 # the Builder will flatten the list automatically:
5416 Program(source = objects)
5417 # If you need to manipulate the list directly using Python, you need to
5419 # call Flatten() yourself, or otherwise handle nested lists:
5420 for object in Flatten(objects):
5421 print(str(object))
5422 GetBuildFailures()
5424 Returns a list of exceptions for the actions that failed while
5425 attempting to build targets. Each element in the returned list is a
5426 BuildError object with the following attributes that record various
5427 aspects of the build failure:
5428 .node The node that was being built when the build failure
5431 occurred.
5432 .status The numeric exit status returned by the command or Python
5435 function that failed when trying to build the specified Node.
5436 .errstr The SCons error string describing the build failure. (This
5439 is often a generic message like "Error 2" to indicate that an
5440 executed command exited with a status of 2.)
5441 .filename The name of the file or directory that actually caused
5444 the failure. This may be different from the .node attribute. For
5445 example, if an attempt to build a target named sub/dir/target fails
5446 because the sub/dir directory could not be created, then the .node
5447 attribute will be sub/dir/target but the .filename attribute will
5448 be sub/dir.
5449 .executor The SCons Executor object for the target Node being
5452 built. This can be used to retrieve the construction environment
5453 used for the failed action.
5454 .action The actual SCons Action object that failed. This will be
5457 one specific action out of the possible list of actions that would
5458 have been executed to build the target.
5459 .command The actual expanded command that was executed and failed,
5462 after expansion of $TARGET, $SOURCE, and other construction
5463 variables.
5464 Note that the GetBuildFailures function will always return an empty
5466 list until any build failure has occurred, which means that
5467 GetBuildFailures will always return an empty list while the
5468 SConscript files are being read. Its primary intended use is for
5469 functions that will be executed before SCons exits by passing them
5470 to the standard Python atexit.register() function. Example:
5471 import atexit
5473 def print_build_failures():
5475 from SCons.Script import GetBuildFailures
5476 for bf in GetBuildFailures():
5477 print("%s failed: %s" % (bf.node, bf.errstr))
5478 atexit.register(print_build_failures)
5480 GetBuildPath(file, [...]), env.GetBuildPath(file, [...])
5482 Returns the scons path name (or names) for the specified file (or
5483 files). The specified file or files may be scons Nodes or strings
5484 representing path names.
5485 GetLaunchDir(), env.GetLaunchDir()
5487 Returns the absolute path name of the directory from which scons
5488 was initially invoked. This can be useful when using the -u, -U or
5489 -D options, which internally change to the directory in which the
5490 SConstruct file is found.
5491 GetOption(name), env.GetOption(name)
5493 This function provides a way to query the value of options which
5494 can be set via the command line or using the SetOption function.
5495 name can be an entry from the following table, which shows the
5498 corresponding command line arguments that could affect the value.
5499 name can be also be the destination variable name from a
5500 project-specific option added using the AddOption function, as long
5501 as the addition happens prior to the GetOption call in the
5502 SConscript files.
5503 ┌────────────────────────┬───────────────────────────┬────────────────────┐
5505 │Query name │ Command-line │ Notes │
5506 │ │ options │ │
5507 ├────────────────────────┼───────────────────────────┼────────────────────┤
5508 │cache_debug │ --cache-debug │ │
5509 ├────────────────────────┼───────────────────────────┼────────────────────┤
5510 │cache_disable │ --cache-disable, │ │
5511 │ │ --no-cache │ │
5512 ├────────────────────────┼───────────────────────────┼────────────────────┤
5513 │cache_force │ --cache-force, │ │
5514 │ │ --cache-populate │ │
5515 ├────────────────────────┼───────────────────────────┼────────────────────┤
5516 │cache_readonly │ --cache-readonly │ │
5517 ├────────────────────────┼───────────────────────────┼────────────────────┤
5518 │cache_show │ --cache-show │ │
5519 ├────────────────────────┼───────────────────────────┼────────────────────┤
5520 │clean │ -c, │ │
5521 │ │ --clean, │ │
5522 │ │ --remove │ │
5523 ├────────────────────────┼───────────────────────────┼────────────────────┤
5524 │climb_up │ -D │ │
5525 │ │ -U │ │
5526 │ │ -u │ │
5527 │ │ --up │ │
5528 │ │ --search_up │ │
5529 ├────────────────────────┼───────────────────────────┼────────────────────┤
5530 │config │ --config │ │
5531 ├────────────────────────┼───────────────────────────┼────────────────────┤
5532 │debug │ --debug │ │
5533 ├────────────────────────┼───────────────────────────┼────────────────────┤
5534 │directory │ -C, --directory │ │
5535 ├────────────────────────┼───────────────────────────┼────────────────────┤
5536 │diskcheck │ --diskcheck │ │
5537 ├────────────────────────┼───────────────────────────┼────────────────────┤
5538 │duplicate │ --duplicate │ │
5539 ├────────────────────────┼───────────────────────────┼────────────────────┤
5540 │enable_virtualenv │ --enable-virtualenv │ │
5541 ├────────────────────────┼───────────────────────────┼────────────────────┤
5542 │experimental │ --experimental │ since 4.2 │
5543 ├────────────────────────┼───────────────────────────┼────────────────────┤
5544 │file │ -f, │ │
5545 │ │ --file, │ │
5546 │ │ --makefile, │ │
5547 │ │ --sconstruct │ │
5548 ├────────────────────────┼───────────────────────────┼────────────────────┤
5549 │hash_format │ --hash-format │ since 4.2 │
5550 ├────────────────────────┼───────────────────────────┼────────────────────┤
5551 │help │ -h, --help │ │
5552 ├────────────────────────┼───────────────────────────┼────────────────────┤
5553 │ignore_errors │ -i, --ignore-errors │ │
5554 ├────────────────────────┼───────────────────────────┼────────────────────┤
5555 │ignore_virtualenv │ --ignore-virtualenv │ │
5556 ├────────────────────────┼───────────────────────────┼────────────────────┤
5557 │implicit_cache │ --implicit-cache │ │
5558 ├────────────────────────┼───────────────────────────┼────────────────────┤
5559 │implicit_deps_changed │ --implicit-deps-changed │ │
5560 ├────────────────────────┼───────────────────────────┼────────────────────┤
5561 │implicit_deps_unchanged │ --implicit-deps-unchanged │ │
5562 ├────────────────────────┼───────────────────────────┼────────────────────┤
5563 │include_dir │ -I, --include-dir │ │
5564 ├────────────────────────┼───────────────────────────┼────────────────────┤
5565 │install_sandbox │ --install-sandbox │ Available only if │
5566 │ │ │ the install tool │
5567 │ │ │ has been called │
5568 ├────────────────────────┼───────────────────────────┼────────────────────┤
5569 │keep_going │ -k, --keep-going │ │
5570 ├────────────────────────┼───────────────────────────┼────────────────────┤
5571 │max_drift │ --max-drift │ │
5572 ├────────────────────────┼───────────────────────────┼────────────────────┤
5573 │md5_chunksize │ --hash-chunksize, │ --hash-chunksize │
5574 │ │ --md5-chunksize │ since 4.2 │
5575 ├────────────────────────┼───────────────────────────┼────────────────────┤
5576 │no_exec │ -n, │ │
5577 │ │ --no-exec, │ │
5578 │ │ --just-print, │ │
5579 │ │ --dry-run, │ │
5580 │ │ --recon │ │
5581 ├────────────────────────┼───────────────────────────┼────────────────────┤
5582 │no_progress │ -Q │ │
5583 ├────────────────────────┼───────────────────────────┼────────────────────┤
5584 │num_jobs │ -j, --jobs │ │
5585 ├────────────────────────┼───────────────────────────┼────────────────────┤
5586 │package_type │ --package-type │ Available only if │
5587 │ │ │ the packaging tool │
5588 │ │ │ has been called │
5589 ├────────────────────────┼───────────────────────────┼────────────────────┤
5590 │profile_file │ --profile │ │
5591 ├────────────────────────┼───────────────────────────┼────────────────────┤
5592 │question │ -q, --question │ │
5593 ├────────────────────────┼───────────────────────────┼────────────────────┤
5594 │random │ --random │ │
5595 ├────────────────────────┼───────────────────────────┼────────────────────┤
5596 │repository │ -Y, │ │
5597 │ │ --repository, │ │
5598 │ │ --srcdir │ │
5599 ├────────────────────────┼───────────────────────────┼────────────────────┤
5600 │silent │ -s, │ │
5601 │ │ --silent, │ │
5602 │ │ --quiet │ │
5603 ├────────────────────────┼───────────────────────────┼────────────────────┤
5604 │site_dir │ --site-dir, --no-site-dir │ │
5605 ├────────────────────────┼───────────────────────────┼────────────────────┤
5606 │stack_size │ --stack-size │ │
5607 ├────────────────────────┼───────────────────────────┼────────────────────┤
5608 │taskmastertrace_file │ --taskmastertrace │ │
5609 ├────────────────────────┼───────────────────────────┼────────────────────┤
5610 │tree_printers │ --tree │ │
5611 ├────────────────────────┼───────────────────────────┼────────────────────┤
5612 │warn │ --warn, --warning │ │
5613 └────────────────────────┴───────────────────────────┴────────────────────┘
5614 See the documentation for the corresponding command line option for
5615 information about each specific option.
5616 Glob(pattern, [ondisk, source, strings, exclude]), env.Glob(pattern,
5618 [ondisk, source, strings, exclude])
5619 Returns Nodes (or strings) that match the specified pattern,
5620 relative to the directory of the current SConscript file. The
5621 evironment method form (env.Glob) performs string substition on
5622 pattern and returns whatever matches the resulting expanded
5623 pattern.
5624 The specified pattern uses Unix shell style metacharacters for
5626 matching:
5627 * matches everything
5629 ? matches any single character
5630 [seq] matches any character in seq
5631 [!seq] matches any char not in seq
5632 If the first character of a filename is a dot, it must be matched
5634 explicitly. Character matches do not span directory separators.
5635 The Glob knows about repositories (see the Repository function) and
5637 source directories (see the VariantDir function) and returns a Node
5638 (or string, if so configured) in the local (SConscript) directory
5639 if a matching Node is found anywhere in a corresponding repository
5640 or source directory.
5641 The ondisk argument may be set to a value which evaluates False to
5643 disable the search for matches on disk, thereby only returning
5644 matches among already-configured File or Dir Nodes. The default
5645 behavior is to return corresponding Nodes for any on-disk matches
5646 found.
5647 The source argument may be set to a value which evaluates True to
5649 specify that, when the local directory is a VariantDir, the
5650 returned Nodes should be from the corresponding source directory,
5651 not the local directory.
5652 The strings argument may be set to a value which evaluates True to
5654 have the Glob function return strings, not Nodes, that represent
5655 the matched files or directories. The returned strings will be
5656 relative to the local (SConscript) directory. (Note that This may
5657 make it easier to perform arbitrary manipulation of file names, but
5658 if the returned strings are passed to a different SConscript file,
5659 any Node translation will be relative to the other SConscript
5660 directory, not the original SConscript directory.)
5661 The exclude argument may be set to a pattern or a list of patterns
5663 (following the same Unix shell semantics) which must be filtered
5664 out of returned elements. Elements matching a least one pattern of
5665 this list will be excluded.
5666 Examples:
5668 Program("foo", Glob("*.c"))
5670 Zip("/tmp/everything", Glob(".??*") + Glob("*"))
5671 sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \
5672 Glob( "os_%s_specific_*.cpp" % currentOS)
5673 Help(text, append=False), env.Help(text, append=False)
5675 Specifies a local help message to be printed if the -h argument is
5676 given to scons. Subsequent calls to Help append text to the
5677 previously defined local help text.
5678 For the first call to Help only, if append is False (the default)
5680 any local help message generated through AddOption calls is
5681 replaced. If append is True, text is appended to the existing help
5682 text.
5683 Ignore(target, dependency), env.Ignore(target, dependency)
5685 The specified dependency file(s) will be ignored when deciding if
5686 the target file(s) need to be rebuilt.
5687 You can also use Ignore to remove a target from the default build.
5689 In order to do this you must specify the directory the target will
5690 be built in as the target, and the file you want to skip building
5691 as the dependency.
5692 Note that this will only remove the dependencies listed from the
5694 files built by default. It will still be built if that dependency
5695 is needed by another object being built. See the third and forth
5696 examples below.
5697 Examples:
5699 env.Ignore('foo', 'foo.c')
5701 env.Ignore('bar', ['bar1.h', 'bar2.h'])
5702 env.Ignore('.', 'foobar.obj')
5703 env.Ignore('bar', 'bar/foobar.obj')
5704 Import(vars...), env.Import(vars...)
5706 Imports variables into the current SConscript file. vars must be
5707 strings representing names of variables which have been previously
5708 exported either by the Export function or by the exports argument
5709 to SConscript. Variables exported by SConscript take precedence.
5710 Multiple variable names can be passed to Import as separate
5711 arguments or as words in a space-separated string. The wildcard "*"
5712 can be used to import all available variables.
5713 Examples:
5715 Import("env")
5717 Import("env", "variable")
5718 Import(["env", "variable"])
5719 Import("*")
5720 Literal(string), env.Literal(string)
5722 The specified string will be preserved as-is and not have
5723 construction variables expanded.
5724 Local(targets), env.Local(targets)
5726 The specified targets will have copies made in the local tree, even
5727 if an already up-to-date copy exists in a repository. Returns a
5728 list of the target Node or Nodes.
5729 env.MergeFlags(arg, [unique])
5731 Merges values from arg into construction variables in the current
5732 construction environment. If arg is not a dictionary, it is
5733 converted to one by calling env.ParseFlags on the argument before
5734 the values are merged. Note that arg must be a single value, so
5735 multiple strings must be passed in as a list, not as separate
5736 arguments to env.MergeFlags.
5737 If unique is true (the default), duplicate values are not stored.
5739 When eliminating duplicate values, any construction variables that
5740 end with the string PATH keep the left-most unique value. All other
5741 construction variables keep the right-most unique value. If unique
5742 is false, values are added even if they are duplicates.
5743 Examples:
5745 # Add an optimization flag to $CCFLAGS.
5747 env.MergeFlags('-O3')
5748 # Combine the flags returned from running pkg-config with an optimization
5750 # flag and merge the result into the construction variables.
5751 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
5752 # Combine an optimization flag with the flags returned from running pkg-config
5754 # twice and merge the result into the construction variables.
5755 env.MergeFlags(
5756 [
5757 '-O3',
5758 '!pkg-config gtk+-2.0 --cflags --libs',
5759 '!pkg-config libpng12 --cflags --libs',
5760 ]
5761 )
5762 NoCache(target, ...), env.NoCache(target, ...)
5764 Specifies a list of files which should not be cached whenever the
5765 CacheDir method has been activated. The specified targets may be a
5766 list or an individual target.
5767 Multiple files should be specified either as separate arguments to
5769 the NoCache method, or as a list. NoCache will also accept the
5770 return value of any of the construction environment Builder
5771 methods.
5772 Calling NoCache on directories and other non-File Node types has no
5774 effect because only File Nodes are cached.
5775 Examples:
5777 NoCache('foo.elf')
5779 NoCache(env.Program('hello', 'hello.c'))
5780 NoClean(target, ...), env.NoClean(target, ...)
5782 Specifies a list of files or directories which should not be
5783 removed whenever the targets (or their dependencies) are specified
5784 with the -c command line option. The specified targets may be a
5785 list or an individual target. Multiple calls to NoClean are legal,
5786 and prevent each specified target from being removed by calls to
5787 the -c option.
5788 Multiple files or directories should be specified either as
5790 separate arguments to the NoClean method, or as a list. NoClean
5791 will also accept the return value of any of the construction
5792 environment Builder methods.
5793 Calling NoClean for a target overrides calling Clean for the same
5795 target, and any targets passed to both functions will not be
5796 removed by the -c option.
5797 Examples:
5799 NoClean('foo.elf')
5801 NoClean(env.Program('hello', 'hello.c'))
5802 env.ParseConfig(command, [function, unique])
5804 Updates the current construction environment with the values
5805 extracted from the output of running external command, by passing
5806 it to a helper function. command may be a string or a list of
5807 strings representing the command and its arguments. If function is
5808 omitted or None, env.MergeFlags is used. By default, duplicate
5809 values are not added to any construction variables; you can specify
5810 unique=False to allow duplicate values to be added.
5811 command is executed using the SCons execution environment (that is,
5814 the construction variable $ENV in the current construction
5815 environment). If command needs additional information to operate
5816 properly, that needs to be set in the execution environment. For
5817 example, pkg-config may need a custom value set in the
5818 PKG_CONFIG_PATH environment variable.
5819 env.MergeFlags needs to understand the output produced by command
5822 in order to distribute it to appropriate construction variables.
5823 env.MergeFlags uses a separate function to do that processing - see
5824 env.ParseFlags for the details, including a a table of options and
5825 corresponding construction variables. To provide alternative
5826 processing of the output of command, you can suppply a custom
5827 function, which must accept three arguments: the construction
5828 environment to modify, a string argument containing the output from
5829 running command, and the optional unique flag.
5830 ParseDepends(filename, [must_exist, only_one]),
5832 env.ParseDepends(filename, [must_exist, only_one])
5833 Parses the contents of filename as a list of dependencies in the
5834 style of Make or mkdep, and explicitly establishes all of the
5835 listed dependencies.
5836 By default, it is not an error if filename does not exist. The
5838 optional must_exist argument may be set to True to have SCons raise
5839 an exception if the file does not exist, or is otherwise
5840 inaccessible.
5841 The optional only_one argument may be set to True to have SCons
5843 raise an exception if the file contains dependency information for
5844 more than one target. This can provide a small sanity check for
5845 files intended to be generated by, for example, the gcc -M flag,
5846 which should typically only write dependency information for one
5847 output file into a corresponding .d file.
5848 filename and all of the files listed therein will be interpreted
5851 relative to the directory of the SConscript file which calls the
5852 ParseDepends function.
5853 env.ParseFlags(flags, ...)
5855 Parses one or more strings containing typical command-line flags
5856 for GCC-style tool chains and returns a dictionary with the flag
5857 values separated into the appropriate SCons construction variables.
5858 Intended as a companion to the env.MergeFlags method, but allows
5859 for the values in the returned dictionary to be modified, if
5860 necessary, before merging them into the construction environment.
5861 (Note that env.MergeFlags will call this method if its argument is
5862 not a dictionary, so it is usually not necessary to call
5863 env.ParseFlags directly unless you want to manipulate the values.)
5864 If the first character in any string is an exclamation mark (!),
5866 the rest of the string is executed as a command, and the output
5867 from the command is parsed as GCC tool chain command-line flags and
5868 added to the resulting dictionary. This can be used to call a
5869 *-config command typical of the POSIX programming environment (for
5870 example, pkg-config). Note that such a comamnd is executed using
5871 the SCons execution environment; if the command needs additional
5872 information, that information needs to be explcitly provided. See
5873 ParseConfig for more details.
5874 Flag values are translated accordig to the prefix found, and added
5876 to the following construction variables:
5877 -arch CCFLAGS, LINKFLAGS
5879 -D CPPDEFINES
5880 -framework FRAMEWORKS
5881 -frameworkdir= FRAMEWORKPATH
5882 -fmerge-all-constants CCFLAGS, LINKFLAGS
5883 -fopenmp CCFLAGS, LINKFLAGS
5884 -include CCFLAGS
5885 -imacros CCFLAGS
5886 -isysroot CCFLAGS, LINKFLAGS
5887 -isystem CCFLAGS
5888 -iquote CCFLAGS
5889 -idirafter CCFLAGS
5890 -I CPPPATH
5891 -l LIBS
5892 -L LIBPATH
5893 -mno-cygwin CCFLAGS, LINKFLAGS
5894 -mwindows LINKFLAGS
5895 -openmp CCFLAGS, LINKFLAGS
5896 -pthread CCFLAGS, LINKFLAGS
5897 -std= CFLAGS
5898 -Wa, ASFLAGS, CCFLAGS
5899 -Wl,-rpath= RPATH
5900 -Wl,-R, RPATH
5901 -Wl,-R RPATH
5902 -Wl, LINKFLAGS
5903 -Wp, CPPFLAGS
5904 - CCFLAGS
5905 + CCFLAGS, LINKFLAGS
5906 Any other strings not associated with options are assumed to be the
5908 names of libraries and added to the $LIBS construction variable.
5909 Examples (all of which produce the same result):
5911 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
5913 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
5914 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
5915 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
5916 Platform(plat), env.Platform(plat)
5918 When called as a global function, returns a callable platform
5919 object selected by plat (defaults to the detected platform for the
5920 current system) that can be used to initialize a construction
5921 environment by passing it as the platform keyword argument to the
5922 Environment function.
5923 Example:
5925 env = Environment(platform=Platform('win32'))
5927 When called as a method of an environment, calls the platform
5929 object indicated by plat to update that environment.
5930 env.Platform('posix')
5932 See the manpage section "Construction Environments" for more
5934 details.
5935 Precious(target, ...), env.Precious(target, ...)
5937 Marks each given target as precious so it is not deleted before it
5938 is rebuilt. Normally scons deletes a target before building it.
5939 Multiple targets can be passed in to a single call to Precious.
5940 env.Prepend(key=val, [...])
5942 Prepend values to construction variables in the current
5943 construction environment, Works like env.Append (see for details),
5944 except that values are added to the front, rather than the end, of
5945 any existing value of the construction variable
5946 Example:
5948 env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy'])
5950 See also env.Append, env.AppendUnique and env.PrependUnique.
5952 env.PrependENVPath(name, newpath, [envname, sep, delete_existing=True])
5954 Prepend path elements specified by newpath to the given search path
5955 string or list name in mapping envname in the construction
5956 environment. Supplying envname is optional: the default is the
5957 execution environment $ENV. Optional sep is used as the search path
5958 separator, the default is the platform's separator (os.pathsep). A
5959 path element will only appear once. Any duplicates in newpath are
5960 dropped, keeping the first appearing (to preserve path order). If
5961 delete_existing is False any addition duplicating an existing path
5962 element is ignored; if delete_existing is True (the default) the
5963 existing value will be dropped and the path element will be
5964 inserted at the beginning. To help maintain uniqueness all paths
5965 are normalized (using os.path.normpath and os.path.normcase).
5966 Example:
5968 print('before:', env['ENV']['INCLUDE'])
5970 include_path = '/foo/bar:/foo'
5971 env.PrependENVPath('INCLUDE', include_path)
5972 print('after:', env['ENV']['INCLUDE'])
5973 Yields:
5975 before: /biz:/foo
5977 after: /foo/bar:/foo:/biz
5978 See also env.AppendENVPath.
5980 env.PrependUnique(key=val, delete_existing=False, [...])
5982 Prepend values to construction variables in the current
5983 construction environment, maintaining uniqueness. Works like
5984 env.Append (see for details), except that values are added to the
5985 front, rather than the end, of any existing value of the
5986 construction variable, and values already present in the
5987 construction variable will not be added again. If delete_existing
5988 is True, the existing matching value is first removed, and the
5989 requested value is inserted, having the effect of moving such
5990 values to the front.
5991 Example:
5993 env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy'])
5995 See also env.Append, env.AppendUnique and env.Prepend.
5997 Progress(callable, [interval]), Progress(string, [interval, file,
5999 overwrite]), Progress(list_of_strings, [interval, file, overwrite])
6000 Allows SCons to show progress made during the build by displaying a
6001 string or calling a function while evaluating Nodes (e.g. files).
6002 If the first specified argument is a Python callable (a function or
6004 an object that has a __call__ method), the function will be called
6005 once every interval times a Node is evaluated (default 1). The
6006 callable will be passed the evaluated Node as its only argument.
6007 (For future compatibility, it's a good idea to also add *args and
6008 **kwargs as arguments to your function or method signatures. This
6009 will prevent the code from breaking if SCons ever changes the
6010 interface to call the function with additional arguments in the
6011 future.)
6012 An example of a simple custom progress function that prints a
6014 string containing the Node name every 10 Nodes:
6015 def my_progress_function(node, *args, **kwargs):
6017 print('Evaluating node %s!' % node)
6018 Progress(my_progress_function, interval=10)
6019 A more complicated example of a custom progress display object that
6021 prints a string containing a count every 100 evaluated Nodes. Note
6022 the use of \r (a carriage return) at the end so that the string
6023 will overwrite itself on a display:
6024 import sys
6026 class ProgressCounter(object):
6027 count = 0
6028 def __call__(self, node, *args, **kw):
6029 self.count += 100
6030 sys.stderr.write('Evaluated %s nodes\r' % self.count)
6031 Progress(ProgressCounter(), interval=100)
6033 If the first argument to Progress is a string or list of strings,
6035 it is taken as text to be displayed every interval evaluated Nodes.
6036 If the first argument is a list of strings, then each string in the
6037 list will be displayed in rotating fashion every interval evaluated
6038 Nodes.
6039 The default is to print the string on standard output. An alternate
6041 output stream may be specified with the file keyword argument,
6042 which the caller must pass already opened.
6043 The following will print a series of dots on the error output, one
6045 dot for every 100 evaluated Nodes:
6046 import sys
6048 Progress('.', interval=100, file=sys.stderr)
6049 If the string contains the verbatim substring $TARGET;, it will be
6051 replaced with the Node. Note that, for performance reasons, this is
6052 not a regular SCons variable substition, so you can not use other
6053 variables or use curly braces. The following example will print the
6054 name of every evaluated Node, using a carriage return) (\r) to
6055 cause each line to overwritten by the next line, and the overwrite
6056 keyword argument (default False) to make sure the
6057 previously-printed file name is overwritten with blank spaces:
6058 import sys
6060 Progress('$TARGET\r', overwrite=True)
6061 A list of strings can be used to implement a "spinner" on the
6063 user's screen as follows, changing every five evaluated Nodes:
6064 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
6066 Pseudo(target, ...), env.Pseudo(target, ...)
6068 This indicates that each given target should not be created by the
6069 build rule, and if the target is created, an error will be
6070 generated. This is similar to the gnu make .PHONY target. However,
6071 in the vast majority of cases, an Alias is more appropriate.
6072 Multiple targets can be passed in to a single call to Pseudo.
6073 PyPackageDir(modulename), env.PyPackageDir(modulename)
6075 This returns a Directory Node similar to Dir. The python module /
6076 package is looked up and if located the directory is returned for
6077 the location. modulename Is a named python package / module to
6078 lookup the directory for it's location.
6079 If modulename is a list, SCons returns a list of Dir nodes.
6081 Construction variables are expanded in modulename.
6082 env.Replace(key=val, [...])
6084 Replaces construction variables in the Environment with the
6085 specified keyword arguments.
6086 Example:
6088 env.Replace(CCFLAGS='-g', FOO='foo.xxx')
6090 Repository(directory), env.Repository(directory)
6092 Specifies that directory is a repository to be searched for files.
6093 Multiple calls to Repository are legal, and each one adds to the
6094 list of repositories that will be searched.
6095 To scons, a repository is a copy of the source tree, from the
6097 top-level directory on down, which may contain both source files
6098 and derived files that can be used to build targets in the local
6099 source tree. The canonical example would be an official source tree
6100 maintained by an integrator. If the repository contains derived
6101 files, then the derived files should have been built using scons,
6102 so that the repository contains the necessary signature information
6103 to allow scons to figure out when it is appropriate to use the
6104 repository copy of a derived file, instead of building one locally.
6105 Note that if an up-to-date derived file already exists in a
6107 repository, scons will not make a copy in the local directory tree.
6108 In order to guarantee that a local copy will be made, use the Local
6109 method.
6110 Requires(target, prerequisite), env.Requires(target, prerequisite)
6112 Specifies an order-only relationship between the specified target
6113 file(s) and the specified prerequisite file(s). The prerequisite
6114 file(s) will be (re)built, if necessary, before the target file(s),
6115 but the target file(s) do not actually depend on the prerequisites
6116 and will not be rebuilt simply because the prerequisite file(s)
6117 change.
6118 Example:
6120 env.Requires('foo', 'file-that-must-be-built-before-foo')
6122 Return([vars..., stop=True])
6124 Return to the calling SConscript, optionally returning the values
6125 of variables named in vars. Multiple strings contaning variable
6126 names may be passed to Return. A string containing white space is
6127 split into individual variable names. Returns the value if one
6128 variable is specified, else returns a tuple of values. Returns an
6129 empty tuple if vars is omitted.
6130 By default Return stops processing the current SConscript and
6132 returns immediately. The optional stop keyword argument may be set
6133 to a false value to continue processing the rest of the SConscript
6134 file after the Return call (this was the default behavior prior to
6135 SCons 0.98.) However, the values returned are still the values of
6136 the variables in the named vars at the point Return was called.
6137 Examples:
6139 # Returns no values (evaluates False)
6141 Return()
6142 # Returns the value of the 'foo' Python variable.
6144 Return("foo")
6145 # Returns the values of the Python variables 'foo' and 'bar'.
6147 Return("foo", "bar")
6148 # Returns the values of Python variables 'val1' and 'val2'.
6150 Return('val1 val2')
6151 Scanner(function, [name, argument, skeys, path_function, node_class,
6153 node_factory, scan_check, recursive]), env.Scanner(function, [name,
6154 argument, skeys, path_function, node_class, node_factory, scan_check,
6155 recursive])
6156 Creates a Scanner object for the specified function. See manpage
6157 section "Scanner Objects" for a complete explanation of the
6158 arguments and behavior.
6159 SConscript(scripts, [exports, variant_dir, duplicate, must_exist]),
6161 env.SConscript(scripts, [exports, variant_dir, duplicate, must_exist]),
6162 SConscript(dirs=subdirs, [name=scriptname, exports, variant_dir,
6163 duplicate, must_exist]), env.SConscript(dirs=subdirs, [name=scriptname,
6164 exports, variant_dir, duplicate, must_exist])
6165 Executes one or more subsidiary SConscript (configuration) files.
6166 There are two ways to call the SConscript function.
6167 The first calling style is to supply one or more SConscript file
6169 names as the first (positional) argument. A single script may be
6170 specified as a string; multiple scripts must be specified as a list
6171 of strings (either explicitly or as created by a function like
6172 Split). Examples:
6173 SConscript('SConscript') # run SConscript in the current directory
6175 SConscript('src/SConscript') # run SConscript in the src directory
6176 SConscript(['src/SConscript', 'doc/SConscript'])
6177 config = SConscript('MyConfig.py')
6178 The other calling style is to omit the positional argument naming
6180 scripts and instead specify a list of directory names using the
6181 dirs keyword argument. In this case, scons will execute a
6182 subsidiary configuration file named SConscript in each of the
6183 specified directories. You may specify a name other than SConscript
6184 by supplying an optional name=scriptname keyword argument. The
6185 first three examples below have the same effect as the first three
6186 examples above:
6187 SConscript(dirs='.') # run SConscript in the current directory
6189 SConscript(dirs='src') # run SConscript in the src directory
6190 SConscript(dirs=['src', 'doc'])
6191 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
6192 The optional exports keyword argument provides a string or list of
6194 strings representing variable names, or a dictionary of named
6195 values, to export. For the first calling style only, a second
6196 positional argument will be interpreted as exports; the second
6197 calling style must use the keyword argument form for exports. These
6198 variables are locally exported only to the called SConscript
6199 file(s) and do not affect the global pool of variables managed by
6200 the Export function. The subsidiary SConscript files must use the
6201 Import function to import the variables. Examples:
6202 foo = SConscript('sub/SConscript', exports='env')
6204 SConscript('dir/SConscript', exports=['env', 'variable'])
6205 SConscript(dirs='subdir', exports='env variable')
6206 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
6207 If the optional variant_dir argument is present, it causes an
6209 effect equivalent to the VariantDir function, but in effect only
6210 within the scope of the SConscript call. The variant_dir argument
6211 is interpreted relative to the directory of the calling SConscript
6212 file. The source directory is the directory in which the called
6213 SConscript file resides and the SConscript file is evaluated as if
6214 it were in the variant_dir directory. Thus:
6215 SConscript('src/SConscript', variant_dir='build')
6217 is equivalent to:
6219 VariantDir('build', 'src')
6221 SConscript('build/SConscript')
6222 If the sources are in the same directory as the SConstruct,
6224 SConscript('SConscript', variant_dir='build')
6226 is equivalent to:
6228 VariantDir('build', '.')
6230 SConscript('build/SConscript')
6231 The optional duplicate argument is interpreted as for VariantDir.
6233 If the variant_dir argument is omitted, the duplicate argument is
6234 ignored. See the description of VariantDir for additional details
6235 and restrictions.
6236 If the optional must_exist is True, causes an exception to be
6240 raised if a requested SConscript file is not found. The current
6241 default is False, causing only a warning to be emitted, but this
6242 default is deprecated (since 3.1). For scripts which truly intend
6243 to be optional, transition to explicitly supplying must_exist=False
6244 to the SConscript call.
6245 Here are some composite examples:
6247 # collect the configuration information and use it to build src and doc
6249 shared_info = SConscript('MyConfig.py')
6250 SConscript('src/SConscript', exports='shared_info')
6251 SConscript('doc/SConscript', exports='shared_info')
6252 # build debugging and production versions. SConscript
6254 # can use Dir('.').path to determine variant.
6255 SConscript('SConscript', variant_dir='debug', duplicate=0)
6256 SConscript('SConscript', variant_dir='prod', duplicate=0)
6257 # build debugging and production versions. SConscript
6259 # is passed flags to use.
6260 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
6261 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
6262 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
6263 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
6264 # build common documentation and compile for different architectures
6266 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
6267 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
6268 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
6269 SConscript returns the values of any variables named by the
6272 executed SConscript file(s) in arguments to the Return function. If
6273 a single SConscript call causes multiple scripts to be executed,
6274 the return value is a tuple containing the returns of each of the
6275 scripts. If an executed script does not explicitly call Return, it
6276 returns None.
6277 SConscriptChdir(value), env.SConscriptChdir(value)
6279 By default, scons changes its working directory to the directory in
6280 which each subsidiary SConscript file lives. This behavior may be
6281 disabled by specifying either:
6282 SConscriptChdir(0)
6284 env.SConscriptChdir(0)
6285 in which case scons will stay in the top-level directory while
6287 reading all SConscript files. (This may be necessary when building
6288 from repositories, when all the directories in which SConscript
6289 files may be found don't necessarily exist locally.) You may enable
6290 and disable this ability by calling SConscriptChdir multiple times.
6291 Example:
6293 env = Environment()
6295 SConscriptChdir(0)
6296 SConscript('foo/SConscript') # will not chdir to foo
6297 env.SConscriptChdir(1)
6298 SConscript('bar/SConscript') # will chdir to bar
6299 SConsignFile([name, dbm_module]), env.SConsignFile([name, dbm_module])
6301 Specify where to store the SCons file signature database, and which
6302 database format to use. This may be useful to specify alternate
6303 database files and/or file locations for different types of builds.
6304 The optional name argument is the base name of the database
6306 file(s). If not an absolute path name, these are placed relative to
6307 the directory containing the top-level SConstruct file. The default
6308 is .sconsign. The actual database file(s) stored on disk may have
6309 an appropriate suffix appended by the chosen dbm_module
6310 The optional dbm_module argument specifies which Python database
6312 module to use for reading/writing the file. The module must be
6313 imported first; then the imported module name is passed as the
6314 argument. The default is a custom SCons.dblite module that uses
6315 pickled Python data structures, which works on all Python versions.
6316 See documentation of the Python dbm module for other available
6317 types.
6318 If called with no arguments, the database will default to
6320 .sconsign.dblite in the top directory of the project, which is also
6321 the default if if SConsignFile is not called.
6322 The setting is global, so the only difference between the global
6324 function and the environment method form is variable expansion on
6325 name. There should only be one active call to this function/method
6326 in a given build setup.
6327 If name is set to None, scons will store file signatures in a
6329 separate .sconsign file in each directory, not in a single combined
6330 database file. This is a backwards-compatibility meaure to support
6331 what was the default behavior prior to SCons 0.97 (i.e. before
6332 2008). Use of this mode is discouraged and may be deprecated in a
6333 future SCons release.
6334 Examples:
6336 # Explicitly stores signatures in ".sconsign.dblite"
6338 # in the top-level SConstruct directory (the default behavior).
6339 SConsignFile()
6340 # Stores signatures in the file "etc/scons-signatures"
6342 # relative to the top-level SConstruct directory.
6343 # SCons will add a database suffix to this name.
6344 SConsignFile("etc/scons-signatures")
6345 # Stores signatures in the specified absolute file name.
6347 # SCons will add a database suffix to this name.
6348 SConsignFile("/home/me/SCons/signatures")
6349 # Stores signatures in a separate .sconsign file
6351 # in each directory.
6352 SConsignFile(None)
6353 # Stores signatures in a GNU dbm format .sconsign file
6355 import dbm.gnu
6356 SConsignFile(dbm_module=dbm.gnu)
6357 env.SetDefault(key=val, [...])
6359 Sets construction variables to default values specified with the
6360 keyword arguments if (and only if) the variables are not already
6361 set. The following statements are equivalent:
6362 env.SetDefault(FOO='foo')
6364 if 'FOO' not in env:
6365 env['FOO'] = 'foo'
6366 SetOption(name, value), env.SetOption(name, value)
6368 Sets scons option variable name to value. These options are all
6369 also settable via command-line options but the variable name may
6370 differ from the command-line option name - see the table for
6371 correspondences. A value set via command-line option will take
6372 precedence over one set with SetOption, which allows setting a
6373 project default in the scripts and temporarily overriding it via
6374 command line. SetOption calls can also be placed in the
6375 site_init.py file.
6376 See the documentation in the manpage for the corresponding command
6378 line option for information about each specific option. The value
6379 parameter is mandatory, for option values which are boolean in
6380 nature (that is, the command line option does not take an argument)
6381 use a value which evaluates to true (e.g. True, 1) or false (e.g.
6382 False, 0).
6383 Options which affect the reading and processing of SConscript files
6385 are not settable using SetOption since those files must be read in
6386 order to find the SetOption call in the first place.
6387 The settable variables with their associated command-line options
6389 are:
6390 ┌────────────────────────┬───────────────────────────┬─────────────────────┐
6392 │Settable name │ Command-line │ Notes │
6393 │ │ options │ │
6394 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6395 │clean │ -c, │ │
6396 │ │ --clean, │ │
6397 │ │ --remove │ │
6398 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6399 │diskcheck │ --diskcheck │ │
6400 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6401 │duplicate │ --duplicate │ │
6402 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6403 │experimental │ --experimental │ since 4.2 │
6404 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6405 │hash_chunksize │ --hash-chunksize │ Actually sets │
6406 │ │ │ md5_chunksize. │
6407 │ │ │ since 4.2 │
6408 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6409 │hash_format │ --hash-format │ since 4.2 │
6410 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6411 │help │ -h, --help │ │
6412 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6413 │implicit_cache │ --implicit-cache │ │
6414 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6415 │implicit_deps_changed │ --implicit-deps-changed │ Also sets │
6416 │ │ │ implicit_cache. │
6417 │ │ │ (settable since │
6418 │ │ │ 4.2) │
6419 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6420 │implicit_deps_unchanged │ --implicit-deps-unchanged │ Also sets │
6421 │ │ │ implicit_cache. │
6422 │ │ │ (settable since │
6423 │ │ │ 4.2) │
6424 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6425 │max_drift │ --max-drift │ │
6426 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6427 │md5_chunksize │ --md5-chunksize │ │
6428 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6429 │no_exec │ -n, │ │
6430 │ │ --no-exec, │ │
6431 │ │ --just-print, │ │
6432 │ │ --dry-run, │ │
6433 │ │ --recon │ │
6434 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6435 │no_progress │ -Q │ See │
6436 │ │ │ [4] │
6437 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6438 │num_jobs │ -j, --jobs │ │
6439 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6440 │random │ --random │ │
6441 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6442 │silent │ -s, │ │
6443 │ │ --silent, │ │
6444 │ │ --quiet │ │
6445 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6446 │stack_size │ --stack-size │ │
6447 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6448 │warn │ --warn │ │
6449 ├────────────────────────┴───────────────────────────┴─────────────────────┤
6450 │---- │
6451 │[a] If no_progress is set via SetOption in an SConscript │
6452 │file (but not if set in a site_init.py file) there will │
6453 │still be an initial status message about reading │
6454 │SConscript files since SCons has to start reading them │
6455 │before it can see the SetOption. │
6456 └──────────────────────────────────────────────────────────────────────────┘
6457 Example:
6458 SetOption('max_drift', 0)
6460 SideEffect(side_effect, target), env.SideEffect(side_effect, target)
6462 Declares side_effect as a side effect of building target. Both
6463 side_effect and target can be a list, a file name, or a node. A
6464 side effect is a target file that is created or updated as a side
6465 effect of building other targets. For example, a Windows PDB file
6466 is created as a side effect of building the .obj files for a static
6467 library, and various log files are created updated as side effects
6468 of various TeX commands. If a target is a side effect of multiple
6469 build commands, scons will ensure that only one set of commands is
6470 executed at a time. Consequently, you only need to use this method
6471 for side-effect targets that are built as a result of multiple
6472 build commands.
6473 Because multiple build commands may update the same side effect
6475 file, by default the side_effect target is not automatically
6476 removed when the target is removed by the -c option. (Note,
6477 however, that the side_effect might be removed as part of cleaning
6478 the directory in which it lives.) If you want to make sure the
6479 side_effect is cleaned whenever a specific target is cleaned, you
6480 must specify this explicitly with the Clean or env.Clean function.
6481 This function returns the list of side effect Node objects that
6483 were successfully added. If the list of side effects contained any
6484 side effects that had already been added, they are not added and
6485 included in the returned list.
6486 Split(arg), env.Split(arg)
6488 If arg is a string, splits on whitespace and returns a list of
6489 strings without whitespace. This mode is the most common case, and
6490 can be used to split a list of filenames (for example) rather than
6491 having to type them as a list of individually quoted words. If arg
6492 is a list or tuple returns the list or tuple unchanged. If arg is
6493 any other type of object, returns a list containing just the
6494 object. These non-string cases do not actually do any spliting, but
6495 allow an argument variable to be passed to Split without having to
6496 first check its type.
6497 Example:
6499 files = Split("f1.c f2.c f3.c")
6501 files = env.Split("f4.c f5.c f6.c")
6502 files = Split("""
6503 f7.c
6504 f8.c
6505 f9.c
6506 """)
6507 env.subst(input, [raw, target, source, conv])
6509 Performs construction variable interpolation (substitution) on
6510 input, which can be a string or a sequence. Substitutable elements
6511 take the form ${expression}, although if there is no ambiguity in
6512 recognizing the element, the braces can be omitted. A literal $ can
6513 be entered by using $$.
6514 By default, leading or trailing white space will be removed from
6516 the result, and all sequences of white space will be compressed to
6517 a single space character. Additionally, any $( and $) character
6518 sequences will be stripped from the returned string, The optional
6519 raw argument may be set to 1 if you want to preserve white space
6520 and $(-$) sequences. The raw argument may be set to 2 if you want
6521 to additionally discard all characters between any $( and $) pairs
6522 (as is done for signature calculation).
6523 If input is a sequence (list or tuple), the individual elements of
6525 the sequence will be expanded, and the results will be returned as
6526 a list.
6527 The optional target and source keyword arguments must be set to
6529 lists of target and source nodes, respectively, if you want the
6530 $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for
6531 expansion. This is usually necessary if you are calling env.subst
6532 from within a Python function used as an SCons action.
6533 Returned string values or sequence elements are converted to their
6535 string representation by default. The optional conv argument may
6536 specify a conversion function that will be used in place of the
6537 default. For example, if you want Python objects (including SCons
6538 Nodes) to be returned as Python objects, you can use a Python
6539 lambda expression to pass in an unnamed function that simply
6540 returns its unconverted argument.
6541 Example:
6543 print(env.subst("The C compiler is: $CC"))
6545 def compile(target, source, env):
6547 sourceDir = env.subst(
6548 "${SOURCE.srcdir}",
6549 target=target,
6550 source=source
6551 )
6552 source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)
6554 Tag(node, tags)
6556 Annotates file or directory Nodes with information about how the
6557 Package Builder should package those files or directories. All
6558 Node-level tags are optional.
6559 Examples:
6561 # makes sure the built library will be installed with 644 file access mode
6563 Tag(Library('lib.c'), UNIX_ATTR="0o644")
6564 # marks file2.txt to be a documentation file
6566 Tag('file2.txt', DOC)
6567 Tool(name, [toolpath, **kwargs]), env.Tool(name, [toolpath, **kwargs])
6569 Locates the tool specification module name and returns a callable
6570 tool object for that tool. The tool module is searched for in
6571 standard locations and in any paths specified by the optional
6572 toolpath parameter. The standard locations are SCons' own internal
6573 path for tools plus the toolpath, if any (see the Tools section in
6574 the manual page for more details). Any additional keyword arguments
6575 kwargs are passed to the tool module's generate function during
6576 tool object construction.
6577 When called, the tool object updates a construction environment
6579 with construction variables and arranges any other initialization
6580 needed to use the mechanisms that tool describes.
6581 When the env.Tool form is used, the tool object is automatically
6583 called to update env and the value of tool is appended to the
6584 $TOOLS construction variable in that environment.
6585 Examples:
6587 env.Tool('gcc')
6589 env.Tool('opengl', toolpath=['build/tools'])
6590 When the global function Tool form is used, the tool object is
6592 constructed but not called, as it lacks the context of an
6593 environment to update. The tool object can be passed to an
6594 Environment or Clone call as part of the tools keyword argument, in
6595 which case the tool is applied to the environment being
6596 constructed, or it can be called directly, in which case a
6597 construction environment to update must be passed as the argument.
6598 Either approach will also update the $TOOLS construction variable.
6599 Examples:
6601 env = Environment(tools=[Tool('msvc')])
6603 env = Environment()
6605 msvctool = Tool('msvc')
6606 msvctool(env) # adds 'msvc' to the TOOLS variable
6607 gltool = Tool('opengl', toolpath = ['tools'])
6608 gltool(env) # adds 'opengl' to the TOOLS variable
6609 Changed in SCons 4.2: env.Tool now returns the tool object,
6612 previously it did not return (i.e. returned None).
6613 Value(value, [built_value], [name]), env.Value(value, [built_value],
6615 [name])
6616 Returns a Node object representing the specified Python value.
6617 Value Nodes can be used as dependencies of targets. If the result
6618 of calling str(value) changes between SCons runs, any targets
6619 depending on Value(value) will be rebuilt. (This is true even when
6620 using timestamps to decide if files are up-to-date.) When using
6621 timestamp source signatures, Value Nodes' timestamps are equal to
6622 the system time when the Node is created. name can be provided as
6623 an alternative name for the resulting Value node; this is advised
6624 if the value parameter can't be converted to a string.
6625 The returned Value Node object has a write() method that can be
6627 used to "build" a Value Node by setting a new value. The optional
6628 built_value argument can be specified when the Value Node is
6629 created to indicate the Node should already be considered "built."
6630 There is a corresponding read() method that will return the built
6631 value of the Node.
6632 Examples:
6634 env = Environment()
6636 def create(target, source, env):
6638 # A function that will write a 'prefix=$SOURCE'
6639 # string into the file name specified as the
6640 # $TARGET.
6641 with open(str(target[0]), 'wb') as f:
6642 f.write('prefix=' + source[0].get_contents())
6643 # Fetch the prefix= argument, if any, from the command
6645 # line, and use /usr/local as the default.
6646 prefix = ARGUMENTS.get('prefix', '/usr/local')
6647 # Attach a .Config() builder for the above function action
6649 # to the construction environment.
6650 env['BUILDERS']['Config'] = Builder(action = create)
6651 env.Config(target = 'package-config', source = Value(prefix))
6652 def build_value(target, source, env):
6654 # A function that "builds" a Python Value by updating
6655 # the Python value with the contents of the file
6656 # specified as the source of the Builder call ($SOURCE).
6657 target[0].write(source[0].get_contents())
6658 output = env.Value('before')
6660 input = env.Value('after')
6661 # Attach a .UpdateValue() builder for the above function
6663 # action to the construction environment.
6664 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6665 env.UpdateValue(target = Value(output), source = Value(input))
6666 VariantDir(variant_dir, src_dir, [duplicate]),
6668 env.VariantDir(variant_dir, src_dir, [duplicate])
6669 Sets up a mapping to define a variant build directory in
6670 variant_dir. src_dir may not be underneath variant_dir. A
6671 VariantDir mapping is global, even if called using the
6672 env.VariantDir form. VariantDir can be called multiple times with
6673 the same src_dir to set up multiple variant builds with different
6674 options.
6675 Note if variant_dir is not under the project top directory, target
6677 selection rules will not pick targets in the variant directory
6678 unless they are explicitly specified.
6679 When files in variant_dir are referenced, SCons backfills as needed
6681 with files from src_dir to create a complete build directory. By
6682 default, SCons physically duplicates the source files, SConscript
6683 files, and directory structure as needed into the variant
6684 directory. Thus, a build performed in the variant directory is
6685 guaranteed to be identical to a build performed in the source
6686 directory even if intermediate source files are generated during
6687 the build, or if preprocessors or other scanners search for
6688 included files using paths relative to the source file, or if
6689 individual compilers or other invoked tools are hard-coded to put
6690 derived files in the same directory as source files. Only the files
6691 SCons calculates are needed for the build are duplicated into
6692 variant_dir. If possible on the platform, the duplication is
6693 performed by linking rather than copying. This behavior is affected
6694 by the --duplicate command-line option.
6695 Duplicating the source files may be disabled by setting the
6697 duplicate argument to False. This will cause SCons to invoke
6698 Builders using the path names of source files in src_dir and the
6699 path names of derived files within variant_dir. This is more
6700 efficient than duplicating, and is safe for most builds; revert to
6701 duplicate=True if it causes problems.
6702 VariantDir works most naturally when used with a subsidiary
6705 SConscript file. The subsidiary SConscript file must be called as
6706 if it were in variant_dir, regardless of the value of duplicate.
6707 When calling an SConscript file, you can use the exports keyword
6708 argument to pass parameters (individually or as an appropriately
6709 set up environment) so the SConscript can pick up the right
6710 settings for that variant build. The SConscript must Import these
6711 to use them. Example:
6712 env1 = Environment(...settings for variant1...)
6714 env2 = Environment(...settings for variant2...)
6715 # run src/SConscript in two variant directories
6717 VariantDir('build/variant1', 'src')
6718 SConscript('build/variant1/SConscript', exports={"env": env1})
6719 VariantDir('build/variant2', 'src')
6720 SConscript('build/variant2/SConscript', exports={"env": env2})
6721 See also the SConscript function for another way to specify a
6723 variant directory in conjunction with calling a subsidiary
6724 SConscript file.
6725 More examples:
6727 # use names in the build directory, not the source directory
6729 VariantDir('build', 'src', duplicate=0)
6730 Program('build/prog', 'build/source.c')
6731 # this builds both the source and docs in a separate subtree
6733 VariantDir('build', '.', duplicate=0)
6734 SConscript(dirs=['build/src','build/doc'])
6735 # same as previous example, but only uses SConscript
6737 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6738 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6739 WhereIs(program, [path, pathext, reject]), env.WhereIs(program, [path,
6741 pathext, reject])
6742 Searches for the specified executable program, returning the full
6743 path to the program or None.
6744 When called as a construction environment method, searches the
6746 paths in the path keyword argument, or if None (the default) the
6747 paths listed in the construction environment (env['ENV']['PATH']).
6748 The external environment's path list (os.environ['PATH']) is used
6749 as a fallback if the key env['ENV']['PATH'] does not exist.
6750 On Windows systems, searches for executable programs with any of
6752 the file extensions listed in the pathext keyword argument, or if
6753 None (the default) the pathname extensions listed in the
6754 construction environment (env['ENV']['PATHEXT']). The external
6755 environment's pathname extensions list (os.environ['PATHEXT']) is
6756 used as a fallback if the key env['ENV']['PATHEXT'] does not exist.
6757 When called as a global function, uses the external environment's
6759 path os.environ['PATH'] and path extensions os.environ['PATHEXT'],
6760 respectively, if path and pathext are None.
6761 Will not select any path name or names in the optional reject list.
6763 SConscript Variables
6765 In addition to the global functions and methods, scons supports a
6766 number of variables that can be used in SConscript files to affect how
6767 you want the build to be performed.
6768 ARGLIST
6770 A list of the keyword=value arguments specified on the command
6771 line. Each element in the list is a tuple containing the argument.
6772 The separate keyword and value elements of the tuple can be
6773 accessed by subscripting for elements [0] and [1] of the tuple, or,
6774 more readably, by using tuple unpacking. Example:
6775 print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
6777 print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
6778 key, value = ARGLIST[2]
6779 print("third keyword, value =", key, value)
6780 for key, value in ARGLIST:
6781 # process key and value
6782 ARGUMENTS
6784 A dictionary of all the keyword=value arguments specified on the
6785 command line. The dictionary is not in order, and if a given
6786 keyword has more than one value assigned to it on the command line,
6787 the last (right-most) value is the one in the ARGUMENTS dictionary.
6788 Example:
6790 if ARGUMENTS.get('debug', 0):
6792 env = Environment(CCFLAGS='-g')
6793 else:
6794 env = Environment()
6795 BUILD_TARGETS
6797 A list of the targets which scons has been asked to build. The
6798 contents will be either those targets listed on the command line,
6799 or, if none, those targets set via calls to the Default function.
6800 It does not contain any dependent targets that scons selects for
6801 building as a result of making the sure the specified targets are
6802 up to date, if those targets did not appear on the command line.
6803 The list is empty if neither command line targets or Default calls
6804 are present.
6805 The elements of this list may be strings or nodes, so you should
6807 run the list through the Python str function to make sure any Node
6808 path names are converted to strings.
6809 Because this list may be taken from the list of targets specified
6811 using the Default function, the contents of the list may change on
6812 each successive call to Default. See the DEFAULT_TARGETS list,
6813 below, for additional information.
6814 Example:
6816 if 'foo' in BUILD_TARGETS:
6818 print("Don't forget to test the `foo' program!")
6819 if 'special/program' in BUILD_TARGETS:
6820 SConscript('special')
6821 COMMAND_LINE_TARGETS
6823 A list of the targets explicitly specified on the command line. If
6824 there are command line targets, this list will have the same
6825 contents as BUILD_TARGETS. If there are no targets specified on the
6826 command line, the list is empty. The elements of this list are
6827 strings. This can be used, for example, to take specific actions
6828 only when certain targets are explicitly being built.
6829 Example:
6831 if 'foo' in COMMAND_LINE_TARGETS:
6833 print("Don't forget to test the `foo' program!")
6834 if 'special/program' in COMMAND_LINE_TARGETS:
6835 SConscript('special')
6836 DEFAULT_TARGETS
6838 A list of the target nodes that have been specified using the
6839 Default function. If there are no command line targets, this list
6840 will have the same contents as BUILD_TARGETS. Since the elements of
6841 the list are nodes, you need to call the Python str function on
6842 them to get the path name for each Node.
6843 Example:
6845 print(str(DEFAULT_TARGETS[0]))
6847 if 'foo' in [str(t) for t in DEFAULT_TARGETS]:
6848 print("Don't forget to test the `foo' program!")
6849 The contents of the DEFAULT_TARGETS list change on on each
6851 successive call to the Default function:
6852 print([str(t) for t in DEFAULT_TARGETS]) # originally []
6854 Default('foo')
6855 print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo']
6856 Default('bar')
6857 print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo', 'bar']
6858 Default(None)
6859 print([str(t) for t in DEFAULT_TARGETS]) # back to []
6860 Consequently, be sure to use DEFAULT_TARGETS only after you've made
6862 all of your Default() calls, or else simply be careful of the order
6863 of these statements in your SConscript files so that you don't look
6864 for a specific default target before it's actually been added to
6865 the list.
6866 These variables may be accessed from custom Python modules that you
6868 import into an SConscript file by adding the following to the Python
6869 module:
6870 from SCons.Script import *
6872 Construction Variables
6874 A construction environment has an associated dictionary of construction
6875 variables that are used by built-in or user-supplied build rules.
6876 Construction variable naming must follow the same rules as Python
6877 identifier naming: the initial character must be an underscore or
6878 letter, followed by any number of underscores, letters, or digits. A
6879 construction environment is not a Python dictionary itself, but it can
6880 be indexed like one to access a construction variable:
6881 env["CC"] = "cc"
6883 flags = env.get("CPPDEFINES", [])
6884 Construction variables can also be retrieved and set by using the
6886 Dictionary method of the construction environment to create an actual
6887 dictionary:
6888 cvars = env.Dictionary()
6890 cvars["CC"] = "cc"
6891 Construction variables can also be passed to the construction
6893 environment constructor:
6894 env = Environment(CC="cc")
6896 or when copying a construction environment using the Clone method:
6898 env2 = env.Clone(CC="cl.exe")
6900 Construction variables can also be supplied as keyword arguments to a
6902 builder, in which case those settings affect only the work done by that
6903 builder call, and not the construction environment as a whole. This
6904 concept is called an override:
6905 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
6907 A number of useful construction variables are automatically defined by
6909 scons for each supported platform, and you can modify these or define
6910 any additional construction variables for your own use, taking care not
6911 to overwrite ones which SCons is using. The following is a list of the
6912 possible automatically defined construction variables.
6913 Note the actual list available at execution time will never include all
6915 of these, as the ones detected as not being useful (wrong platform,
6916 necessary external command or files not installed, etc.) will not be
6917 set up. Correct build setups should be resilient to the possible
6918 absence of certain construction variables before using them, for
6919 example by using a Python dictionary get method to retrieve the value
6920 and taking alternative action if the return indicates the variable is
6921 unset. The env.Dump method can be called to examine the construction
6922 variables set in a particular environment.
6923 __LDMODULEVERSIONFLAGS
6925 This construction variable automatically introduces
6926 $_LDMODULEVERSIONFLAGS if $LDMODULEVERSION is set. Othervise it
6927 evaluates to an empty string.
6928 __SHLIBVERSIONFLAGS
6930 This construction variable automatically introduces
6931 $_SHLIBVERSIONFLAGS if $SHLIBVERSION is set. Othervise it evaluates
6932 to an empty string.
6933 APPLELINK_COMPATIBILITY_VERSION
6935 On Mac OS X this is used to set the linker flag:
6936 -compatibility_version
6937 The value is specified as X[.Y[.Z]] where X is between 1 and 65535,
6939 Y can be omitted or between 1 and 255, Z can be omitted or between
6940 1 and 255. This value will be derived from $SHLIBVERSION if not
6941 specified. The lowest digit will be dropped and replaced by a 0.
6942 If the $APPLELINK_NO_COMPATIBILITY_VERSION is set then no
6944 -compatibility_version will be output.
6945 See MacOS's ld manpage for more details
6947 _APPLELINK_COMPATIBILITY_VERSION
6949 A macro (by default a generator function) used to create the linker
6950 flags to specify apple's linker's -compatibility_version flag. The
6951 default generator uses $APPLELINK_COMPATIBILITY_VERSION and
6952 $APPLELINK_NO_COMPATIBILITY_VERSION and $SHLIBVERSION to determine
6953 the correct flag.
6954 APPLELINK_CURRENT_VERSION
6956 On Mac OS X this is used to set the linker flag: -current_version
6957 The value is specified as X[.Y[.Z]] where X is between 1 and 65535,
6959 Y can be omitted or between 1 and 255, Z can be omitted or between
6960 1 and 255. This value will be set to $SHLIBVERSION if not
6961 specified.
6962 If the $APPLELINK_NO_CURRENT_VERSION is set then no
6964 -current_version will be output.
6965 See MacOS's ld manpage for more details
6967 _APPLELINK_CURRENT_VERSION
6969 A macro (by default a generator function) used to create the linker
6970 flags to specify apple's linker's -current_version flag. The
6971 default generator uses $APPLELINK_CURRENT_VERSION and
6972 $APPLELINK_NO_CURRENT_VERSION and $SHLIBVERSION to determine the
6973 correct flag.
6974 APPLELINK_NO_COMPATIBILITY_VERSION
6976 Set this to any True (1|True|non-empty string) value to disable
6977 adding -compatibility_version flag when generating versioned shared
6978 libraries.
6979 This overrides $APPLELINK_COMPATIBILITY_VERSION.
6981 APPLELINK_NO_CURRENT_VERSION
6983 Set this to any True (1|True|non-empty string) value to disable
6984 adding -current_version flag when generating versioned shared
6985 libraries.
6986 This overrides $APPLELINK_CURRENT_VERSION.
6988 AR
6990 The static library archiver.
6991 ARCHITECTURE
6993 Specifies the system architecture for which the package is being
6994 built. The default is the system architecture of the machine on
6995 which SCons is running. This is used to fill in the Architecture:
6996 field in an Ipkg control file, and the BuildArch: field in the RPM
6997 .spec file, as well as forming part of the name of a generated RPM
6998 package file.
6999 See the Package builder.
7001 ARCOM
7003 The command line used to generate a static library from object
7004 files.
7005 ARCOMSTR
7007 The string displayed when a static library is generated from object
7008 files. If this is not set, then $ARCOM (the command line) is
7009 displayed.
7010 env = Environment(ARCOMSTR = "Archiving $TARGET")
7012 ARFLAGS
7014 General options passed to the static library archiver.
7015 AS
7017 The assembler.
7018 ASCOM
7020 The command line used to generate an object file from an
7021 assembly-language source file.
7022 ASCOMSTR
7024 The string displayed when an object file is generated from an
7025 assembly-language source file. If this is not set, then $ASCOM (the
7026 command line) is displayed.
7027 env = Environment(ASCOMSTR = "Assembling $TARGET")
7029 ASFLAGS
7031 General options passed to the assembler.
7032 ASPPCOM
7034 The command line used to assemble an assembly-language source file
7035 into an object file after first running the file through the C
7036 preprocessor. Any options specified in the $ASFLAGS and $CPPFLAGS
7037 construction variables are included on this command line.
7038 ASPPCOMSTR
7040 The string displayed when an object file is generated from an
7041 assembly-language source file after first running the file through
7042 the C preprocessor. If this is not set, then $ASPPCOM (the command
7043 line) is displayed.
7044 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
7046 ASPPFLAGS
7048 General options when an assembling an assembly-language source file
7049 into an object file after first running the file through the C
7050 preprocessor. The default is to use the value of $ASFLAGS.
7051 BIBTEX
7053 The bibliography generator for the TeX formatter and typesetter and
7054 the LaTeX structured formatter and typesetter.
7055 BIBTEXCOM
7057 The command line used to call the bibliography generator for the
7058 TeX formatter and typesetter and the LaTeX structured formatter and
7059 typesetter.
7060 BIBTEXCOMSTR
7062 The string displayed when generating a bibliography for TeX or
7063 LaTeX. If this is not set, then $BIBTEXCOM (the command line) is
7064 displayed.
7065 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
7067 BIBTEXFLAGS
7069 General options passed to the bibliography generator for the TeX
7070 formatter and typesetter and the LaTeX structured formatter and
7071 typesetter.
7072 BUILDERS
7074 A dictionary mapping the names of the builders available through
7075 the construction environment to underlying Builder objects. Custom
7076 builders need to be added to this to make them available.
7077 A platform-dependent default list of builders such as Program,
7079 Library etc. is used to populate this construction variable when
7080 the construction environment is initialized via the
7081 presence/absence of the tools those builders depend on. $BUILDERS
7082 can be examined to learn which builders will actually be available
7083 at run-time.
7084 Note that if you initialize this construction variable through
7086 assignment when the construction environment is created, that value
7087 for $BUILDERS will override any defaults:
7088 bld = Builder(action='foobuild < $SOURCE > $TARGET')
7090 env = Environment(BUILDERS={'NewBuilder': bld})
7091 To instead use a new Builder object in addition to the default
7093 Builders, add your new Builder object like this:
7094 env = Environment()
7096 env.Append(BUILDERS={'NewBuilder': bld})
7097 or this:
7099 env = Environment()
7101 env['BUILDERS']['NewBuilder'] = bld
7102 CACHEDIR_CLASS
7104 The class type that SCons should use when instantiating a new
7105 CacheDir for the given environment. It must be a subclass of the
7106 SCons.CacheDir.CacheDir class.
7107 CC
7109 The C compiler.
7110 CCCOM
7112 The command line used to compile a C source file to a (static)
7113 object file. Any options specified in the $CFLAGS, $CCFLAGS and
7114 $CPPFLAGS construction variables are included on this command line.
7115 See also $SHCCCOM for compiling to shared objects.
7116 CCCOMSTR
7118 If set, the string displayed when a C source file is compiled to a
7119 (static) object file. If not set, then $CCCOM (the command line) is
7120 displayed. See also $SHCCCOMSTR for compiling to shared objects.
7121 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
7123 CCDEPFLAGS
7125 Options to pass to C or C++ compiler to generate list of dependency
7126 files.
7127 This is set only by compilers which support this functionality.
7129 (gcc, clang, and msvc currently)
7130 CCFLAGS
7132 General options that are passed to the C and C++ compilers. See
7133 also $SHCCFLAGS for compiling to shared objects.
7134 CCPCHFLAGS
7136 Options added to the compiler command line to support building with
7137 precompiled headers. The default value expands expands to the
7138 appropriate Microsoft Visual C++ command-line options when the $PCH
7139 construction variable is set.
7140 CCPDBFLAGS
7142 Options added to the compiler command line to support storing
7143 debugging information in a Microsoft Visual C++ PDB file. The
7144 default value expands expands to appropriate Microsoft Visual C++
7145 command-line options when the $PDB construction variable is set.
7146 The Visual C++ compiler option that SCons uses by default to
7148 generate PDB information is /Z7. This works correctly with parallel
7149 (-j) builds because it embeds the debug information in the
7150 intermediate object files, as opposed to sharing a single PDB file
7151 between multiple object files. This is also the only way to get
7152 debug information embedded into a static library. Using the /Zi
7153 instead may yield improved link-time performance, although parallel
7154 builds will no longer work.
7155 You can generate PDB files with the /Zi switch by overriding the
7157 default $CCPDBFLAGS variable as follows:
7158 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
7160 An alternative would be to use the /Zi to put the debugging
7162 information in a separate .pdb file for each object file by
7163 overriding the $CCPDBFLAGS variable as follows:
7164 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
7166 CCVERSION
7168 The version number of the C compiler. This may or may not be set,
7169 depending on the specific C compiler being used.
7170 CFILESUFFIX
7172 The suffix for C source files. This is used by the internal CFile
7173 builder when generating C files from Lex (.l) or YACC (.y) input
7174 files. The default suffix, of course, is .c (lower case). On
7175 case-insensitive systems (like Windows), SCons also treats .C
7176 (upper case) files as C files.
7177 CFLAGS
7179 General options that are passed to the C compiler (C only; not
7180 C++). See also $SHCFLAGS for compiling to shared objects.
7181 CHANGE_SPECFILE
7183 A hook for modifying the file that controls the packaging build
7184 (the .spec for RPM, the control for Ipkg, the .wxs for MSI). If
7185 set, the function will be called after the SCons template for the
7186 file has been written.
7187 See the Package builder.
7189 CHANGED_SOURCES
7191 A reserved variable name that may not be set or used in a
7192 construction environment. (See the manpage section "Variable
7193 Substitution" for more information).
7194 CHANGED_TARGETS
7196 A reserved variable name that may not be set or used in a
7197 construction environment. (See the manpage section "Variable
7198 Substitution" for more information).
7199 CHANGELOG
7201 The name of a file containing the change log text to be included in
7202 the package. This is included as the %changelog section of the RPM
7203 .spec file.
7204 See the Package builder.
7206 COMPILATIONDB_COMSTR
7208 The string displayed when the CompilationDatabase builder's action
7209 is run.
7210 COMPILATIONDB_PATH_FILTER
7212 A string which instructs CompilationDatabase to only include
7213 entries where the output member matches the pattern in the filter
7214 string using fnmatch, which uses glob style wildcards.
7215 The default value is an empty string '', which disables filtering.
7217 COMPILATIONDB_USE_ABSPATH
7219 A boolean flag to instruct CompilationDatabase whether to write the
7220 file and output members in the compilation database using absolute
7221 or relative paths.
7222 The default value is False (use relative paths)
7224 _concat
7226 A function used to produce variables like $_CPPINCFLAGS. It takes
7227 four mandatory arguments, and up to 4 additional optional
7228 arguments: 1) a prefix to concatenate onto each element, 2) a list
7229 of elements, 3) a suffix to concatenate onto each element, 4) an
7230 environment for variable interpolation, 5) an optional function
7231 that will be called to transform the list before concatenation, 6)
7232 an optionally specified target (Can use TARGET), 7) an optionally
7233 specified source (Can use SOURCE), 8) optional affect_signature
7234 flag which will wrap non-empty returned value with $( and $) to
7235 indicate the contents should not affect the signature of the
7236 generated command line.
7237 env['_CPPINCFLAGS'] = '${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE, affect_signature=False)}'
7239 CONFIGUREDIR
7242 The name of the directory in which Configure context test files are
7243 written. The default is .sconf_temp in the top-level directory
7244 containing the SConstruct file.
7245 CONFIGURELOG
7247 The name of the Configure context log file. The default is
7248 config.log in the top-level directory containing the SConstruct
7249 file.
7250 _CPPDEFFLAGS
7252 An automatically-generated construction variable containing the C
7253 preprocessor command-line options to define values. The value of
7254 $_CPPDEFFLAGS is created by respectively prepending and appending
7255 $CPPDEFPREFIX and $CPPDEFSUFFIX to each definition in $CPPDEFINES.
7256 CPPDEFINES
7258 A platform independent specification of C preprocessor macro
7259 definitions. The definitions will be added to command lines through
7260 the automatically-generated $_CPPDEFFLAGS construction variable
7261 (see above), which is constructed according to the type of value of
7262 $CPPDEFINES:
7263 If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and
7265 $CPPDEFSUFFIX construction variables will be respectively prepended
7266 and appended to each definition in $CPPDEFINES.
7267 # Will add -Dxyz to POSIX compiler command lines,
7269 # and /Dxyz to Microsoft Visual C++ command lines.
7270 env = Environment(CPPDEFINES='xyz')
7271 If $CPPDEFINES is a list, the values of the $CPPDEFPREFIX and
7273 $CPPDEFSUFFIX construction variables will be respectively prepended
7274 and appended to each element in the list. If any element is a list
7275 or tuple, then the first item is the name being defined and the
7276 second item is its value:
7277 # Will add -DB=2 -DA to POSIX compiler command lines,
7279 # and /DB=2 /DA to Microsoft Visual C++ command lines.
7280 env = Environment(CPPDEFINES=[('B', 2), 'A'])
7281 If $CPPDEFINES is a dictionary, the values of the $CPPDEFPREFIX and
7283 $CPPDEFSUFFIX construction variables will be respectively prepended
7284 and appended to each item from the dictionary. The key of each
7285 dictionary item is a name being defined to the dictionary item's
7286 corresponding value; if the value is None, then the name is defined
7287 without an explicit value. Note that the resulting flags are sorted
7288 by keyword to ensure that the order of the options on the command
7289 line is consistent each time scons is run.
7290 # Will add -DA -DB=2 to POSIX compiler command lines,
7292 # and /DA /DB=2 to Microsoft Visual C++ command lines.
7293 env = Environment(CPPDEFINES={'B':2, 'A':None})
7294 CPPDEFPREFIX
7296 The prefix used to specify preprocessor macro definitions on the C
7297 compiler command line. This will be prepended to each definition in
7298 the $CPPDEFINES construction variable when the $_CPPDEFFLAGS
7299 variable is automatically generated.
7300 CPPDEFSUFFIX
7302 The suffix used to specify preprocessor macro definitions on the C
7303 compiler command line. This will be appended to each definition in
7304 the $CPPDEFINES construction variable when the $_CPPDEFFLAGS
7305 variable is automatically generated.
7306 CPPFLAGS
7308 User-specified C preprocessor options. These will be included in
7309 any command that uses the C preprocessor, including not just
7310 compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
7311 $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
7312 $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
7313 compile a Fortran source file, and the $ASPPCOM command line used
7314 to assemble an assembly language source file, after first running
7315 each file through the C preprocessor. Note that this variable does
7316 not contain -I (or similar) include search path options that scons
7317 generates automatically from $CPPPATH. See $_CPPINCFLAGS, below,
7318 for the variable that expands to those options.
7319 _CPPINCFLAGS
7321 An automatically-generated construction variable containing the C
7322 preprocessor command-line options for specifying directories to be
7323 searched for include files. The value of $_CPPINCFLAGS is created
7324 by respectively prepending and appending $INCPREFIX and $INCSUFFIX
7325 to each directory in $CPPPATH.
7326 CPPPATH
7328 The list of directories that the C preprocessor will search for
7329 include directories. The C/C++ implicit dependency scanner will
7330 search these directories for include files. In general it's not
7331 advised to put include directory directives directly into $CCFLAGS
7332 or $CXXFLAGS as the result will be non-portable and the directories
7333 will not be searched by the dependency scanner. $CPPPATH should be
7334 a list of path strings, or a single string, not a pathname list
7335 joined by Python's os.sep.
7336 Note: directory names in $CPPPATH will be looked-up relative to the
7338 directory of the SConscript file when they are used in a command.
7339 To force scons to look-up a directory relative to the root of the
7340 source tree use the # prefix:
7341 env = Environment(CPPPATH='#/include')
7343 The directory look-up can also be forced using the Dir function:
7345 include = Dir('include')
7347 env = Environment(CPPPATH=include)
7348 The directory list will be added to command lines through the
7350 automatically-generated $_CPPINCFLAGS construction variable, which
7351 is constructed by respectively prepending and appending the values
7352 of the $INCPREFIX and $INCSUFFIX construction variables to each
7353 directory in $CPPPATH. Any command lines you define that need the
7354 $CPPPATH directory list should include $_CPPINCFLAGS:
7355 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
7357 CPPSUFFIXES
7359 The list of suffixes of files that will be scanned for C
7360 preprocessor implicit dependencies (#include lines). The default
7361 list is:
7362 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
7364 ".h", ".H", ".hxx", ".hpp", ".hh",
7365 ".F", ".fpp", ".FPP",
7366 ".m", ".mm",
7367 ".S", ".spp", ".SPP"]
7368 CXX
7370 The C++ compiler. See also $SHCXX for compiling to shared objects..
7371 CXXCOM
7373 The command line used to compile a C++ source file to an object
7374 file. Any options specified in the $CXXFLAGS and $CPPFLAGS
7375 construction variables are included on this command line. See also
7376 $SHCXXCOM for compiling to shared objects..
7377 CXXCOMSTR
7379 If set, the string displayed when a C++ source file is compiled to
7380 a (static) object file. If not set, then $CXXCOM (the command line)
7381 is displayed. See also $SHCXXCOMSTR for compiling to shared
7382 objects..
7383 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
7385 CXXFILESUFFIX
7387 The suffix for C++ source files. This is used by the internal
7388 CXXFile builder when generating C++ files from Lex (.ll) or YACC
7389 (.yy) input files. The default suffix is .cc. SCons also treats
7390 files with the suffixes .cpp, .cxx, .c++, and .C++ as C++ files,
7391 and files with .mm suffixes as Objective C++ files. On
7392 case-sensitive systems (Linux, UNIX, and other POSIX-alikes), SCons
7393 also treats .C (upper case) files as C++ files.
7394 CXXFLAGS
7396 General options that are passed to the C++ compiler. By default,
7397 this includes the value of $CCFLAGS, so that setting $CCFLAGS
7398 affects both C and C++ compilation. If you want to add C++-specific
7399 flags, you must set or override the value of $CXXFLAGS. See also
7400 $SHCXXFLAGS for compiling to shared objects..
7401 CXXVERSION
7403 The version number of the C++ compiler. This may or may not be set,
7404 depending on the specific C++ compiler being used.
7405 DC
7407 The D compiler to use. See also $SHDC for compiling to shared
7408 objects.
7409 DCOM
7411 The command line used to compile a D file to an object file. Any
7412 options specified in the $DFLAGS construction variable is included
7413 on this command line. See also $SHDCOM for compiling to shared
7414 objects.
7415 DCOMSTR
7417 If set, the string displayed when a D source file is compiled to a
7418 (static) object file. If not set, then $DCOM (the command line) is
7419 displayed. See also $SHDCOMSTR for compiling to shared objects.
7420 DDEBUG
7422 List of debug tags to enable when compiling.
7423 DDEBUGPREFIX
7425 DDEBUGPREFIX.
7426 DDEBUGSUFFIX
7428 DDEBUGSUFFIX.
7429 DESCRIPTION
7431 A long description of the project being packaged. This is included
7432 in the relevant section of the file that controls the packaging
7433 build.
7434 See the Package builder.
7436 DESCRIPTION_lang
7438 A language-specific long description for the specified lang. This
7439 is used to populate a %description -l section of an RPM .spec file.
7440 See the Package builder.
7442 DFILESUFFIX
7444 DFILESUFFIX.
7445 DFLAGPREFIX
7447 DFLAGPREFIX.
7448 DFLAGS
7450 General options that are passed to the D compiler.
7451 DFLAGSUFFIX
7453 DFLAGSUFFIX.
7454 DINCPREFIX
7456 DINCPREFIX.
7457 DINCSUFFIX
7459 DLIBFLAGSUFFIX.
7460 Dir
7462 A function that converts a string into a Dir instance relative to
7463 the target being built.
7464 Dirs
7466 A function that converts a list of strings into a list of Dir
7467 instances relative to the target being built.
7468 DLIB
7470 Name of the lib tool to use for D codes.
7471 DLIBCOM
7473 The command line to use when creating libraries.
7474 DLIBDIRPREFIX
7476 DLIBLINKPREFIX.
7477 DLIBDIRSUFFIX
7479 DLIBLINKSUFFIX.
7480 DLIBFLAGPREFIX
7482 DLIBFLAGPREFIX.
7483 DLIBFLAGSUFFIX
7485 DLIBFLAGSUFFIX.
7486 DLIBLINKPREFIX
7488 DLIBLINKPREFIX.
7489 DLIBLINKSUFFIX
7491 DLIBLINKSUFFIX.
7492 DLINK
7494 Name of the linker to use for linking systems including D sources.
7495 See also $SHDLINK for linking shared objects.
7496 DLINKCOM
7498 The command line to use when linking systems including D sources.
7499 See also $SHDLINKCOM for linking shared objects.
7500 DLINKFLAGPREFIX
7502 DLINKFLAGPREFIX.
7503 DLINKFLAGS
7505 List of linker flags. See also $SHDLINKFLAGS for linking shared
7506 objects.
7507 DLINKFLAGSUFFIX
7509 DLINKFLAGSUFFIX.
7510 DOCBOOK_DEFAULT_XSL_EPUB
7512 The default XSLT file for the DocbookEpub builder within the
7513 current environment, if no other XSLT gets specified via keyword.
7514 DOCBOOK_DEFAULT_XSL_HTML
7516 The default XSLT file for the DocbookHtml builder within the
7517 current environment, if no other XSLT gets specified via keyword.
7518 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
7520 The default XSLT file for the DocbookHtmlChunked builder within the
7521 current environment, if no other XSLT gets specified via keyword.
7522 DOCBOOK_DEFAULT_XSL_HTMLHELP
7524 The default XSLT file for the DocbookHtmlhelp builder within the
7525 current environment, if no other XSLT gets specified via keyword.
7526 DOCBOOK_DEFAULT_XSL_MAN
7528 The default XSLT file for the DocbookMan builder within the current
7529 environment, if no other XSLT gets specified via keyword.
7530 DOCBOOK_DEFAULT_XSL_PDF
7532 The default XSLT file for the DocbookPdf builder within the current
7533 environment, if no other XSLT gets specified via keyword.
7534 DOCBOOK_DEFAULT_XSL_SLIDESHTML
7536 The default XSLT file for the DocbookSlidesHtml builder within the
7537 current environment, if no other XSLT gets specified via keyword.
7538 DOCBOOK_DEFAULT_XSL_SLIDESPDF
7540 The default XSLT file for the DocbookSlidesPdf builder within the
7541 current environment, if no other XSLT gets specified via keyword.
7542 DOCBOOK_FOP
7544 The path to the PDF renderer fop or xep, if one of them is
7545 installed (fop gets checked first).
7546 DOCBOOK_FOPCOM
7548 The full command-line for the PDF renderer fop or xep.
7549 DOCBOOK_FOPCOMSTR
7551 The string displayed when a renderer like fop or xep is used to
7552 create PDF output from an XML file.
7553 DOCBOOK_FOPFLAGS
7555 Additonal command-line flags for the PDF renderer fop or xep.
7556 DOCBOOK_XMLLINT
7558 The path to the external executable xmllint, if it's installed.
7559 Note, that this is only used as last fallback for resolving
7560 XIncludes, if no lxml Python binding can be imported in the current
7561 system.
7562 DOCBOOK_XMLLINTCOM
7564 The full command-line for the external executable xmllint.
7565 DOCBOOK_XMLLINTCOMSTR
7567 The string displayed when xmllint is used to resolve XIncludes for
7568 a given XML file.
7569 DOCBOOK_XMLLINTFLAGS
7571 Additonal command-line flags for the external executable xmllint.
7572 DOCBOOK_XSLTPROC
7574 The path to the external executable xsltproc (or saxon, xalan), if
7575 one of them is installed. Note, that this is only used as last
7576 fallback for XSL transformations, if no lxml Python binding can be
7577 imported in the current system.
7578 DOCBOOK_XSLTPROCCOM
7580 The full command-line for the external executable xsltproc (or
7581 saxon, xalan).
7582 DOCBOOK_XSLTPROCCOMSTR
7584 The string displayed when xsltproc is used to transform an XML file
7585 via a given XSLT stylesheet.
7586 DOCBOOK_XSLTPROCFLAGS
7588 Additonal command-line flags for the external executable xsltproc
7589 (or saxon, xalan).
7590 DOCBOOK_XSLTPROCPARAMS
7592 Additonal parameters that are not intended for the XSLT processor
7593 executable, but the XSL processing itself. By default, they get
7594 appended at the end of the command line for saxon and saxon-xslt,
7595 respectively.
7596 DPATH
7598 List of paths to search for import modules.
7599 DRPATHPREFIX
7601 DRPATHPREFIX.
7602 DRPATHSUFFIX
7604 DRPATHSUFFIX.
7605 DSUFFIXES
7607 The list of suffixes of files that will be scanned for imported D
7608 package files. The default list is ['.d'].
7609 DVERPREFIX
7611 DVERPREFIX.
7612 DVERSIONS
7614 List of version tags to enable when compiling.
7615 DVERSUFFIX
7617 DVERSUFFIX.
7618 DVIPDF
7620 The TeX DVI file to PDF file converter.
7621 DVIPDFCOM
7623 The command line used to convert TeX DVI files into a PDF file.
7624 DVIPDFCOMSTR
7626 The string displayed when a TeX DVI file is converted into a PDF
7627 file. If this is not set, then $DVIPDFCOM (the command line) is
7628 displayed.
7629 DVIPDFFLAGS
7631 General options passed to the TeX DVI file to PDF file converter.
7632 DVIPS
7634 The TeX DVI file to PostScript converter.
7635 DVIPSFLAGS
7637 General options passed to the TeX DVI file to PostScript converter.
7638 ENV
7640 The execution environment - a dictionary of environment variables
7641 used when SCons invokes external commands to build targets defined
7642 in this construction environment. When $ENV is passed to a command,
7643 all list values are assumed to be path lists and are joined using
7644 the search path separator. Any other non-string values are coerced
7645 to a string.
7646 Note that by default SCons does not propagate the environment in
7648 effect when you execute scons (the "shell environment") to the
7649 execution environment. This is so that builds will be guaranteed
7650 repeatable regardless of the environment variables set at the time
7651 scons is invoked. If you want to propagate a shell environment
7652 variable to the commands executed to build target files, you must
7653 do so explicitly. A common example is the system PATH environment
7654 variable, so that scons will find utilities the same way as the
7655 invoking shell (or other process):
7656 import os
7658 env = Environment(ENV={'PATH': os.environ['PATH']})
7659 Although it is usually not recommended, you can propagate the
7661 entire shell environment in one go:
7662 import os
7664 env = Environment(ENV=os.environ.copy())
7665 ESCAPE
7667 A function that will be called to escape shell special characters
7668 in command lines. The function should take one argument: the
7669 command line string to escape; and should return the escaped
7670 command line.
7671 F03
7673 The Fortran 03 compiler. You should normally set the $FORTRAN
7674 variable, which specifies the default Fortran compiler for all
7675 Fortran versions. You only need to set $F03 if you need to use a
7676 specific compiler or compiler version for Fortran 03 files.
7677 F03COM
7679 The command line used to compile a Fortran 03 source file to an
7680 object file. You only need to set $F03COM if you need to use a
7681 specific command line for Fortran 03 files. You should normally set
7682 the $FORTRANCOM variable, which specifies the default command line
7683 for all Fortran versions.
7684 F03COMSTR
7686 If set, the string displayed when a Fortran 03 source file is
7687 compiled to an object file. If not set, then $F03COM or $FORTRANCOM
7688 (the command line) is displayed.
7689 F03FILESUFFIXES
7691 The list of file extensions for which the F03 dialect will be used.
7692 By default, this is ['.f03']
7693 F03FLAGS
7695 General user-specified options that are passed to the Fortran 03
7696 compiler. Note that this variable does not contain -I (or similar)
7697 include search path options that scons generates automatically from
7698 $F03PATH. See $_F03INCFLAGS below, for the variable that expands to
7699 those options. You only need to set $F03FLAGS if you need to define
7700 specific user options for Fortran 03 files. You should normally set
7701 the $FORTRANFLAGS variable, which specifies the user-specified
7702 options passed to the default Fortran compiler for all Fortran
7703 versions.
7704 _F03INCFLAGS
7706 An automatically-generated construction variable containing the
7707 Fortran 03 compiler command-line options for specifying directories
7708 to be searched for include files. The value of $_F03INCFLAGS is
7709 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7710 end of each directory in $F03PATH.
7711 F03PATH
7713 The list of directories that the Fortran 03 compiler will search
7714 for include directories. The implicit dependency scanner will
7715 search these directories for include files. Don't explicitly put
7716 include directory arguments in $F03FLAGS because the result will be
7717 non-portable and the directories will not be searched by the
7718 dependency scanner. Note: directory names in $F03PATH will be
7719 looked-up relative to the SConscript directory when they are used
7720 in a command. To force scons to look-up a directory relative to the
7721 root of the source tree use #: You only need to set $F03PATH if you
7722 need to define a specific include path for Fortran 03 files. You
7723 should normally set the $FORTRANPATH variable, which specifies the
7724 include path for the default Fortran compiler for all Fortran
7725 versions.
7726 env = Environment(F03PATH='#/include')
7728 The directory look-up can also be forced using the Dir() function:
7730 include = Dir('include')
7732 env = Environment(F03PATH=include)
7733 The directory list will be added to command lines through the
7735 automatically-generated $_F03INCFLAGS construction variable, which
7736 is constructed by appending the values of the $INCPREFIX and
7737 $INCSUFFIX construction variables to the beginning and end of each
7738 directory in $F03PATH. Any command lines you define that need the
7739 F03PATH directory list should include $_F03INCFLAGS:
7740 env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
7742 F03PPCOM
7744 The command line used to compile a Fortran 03 source file to an
7745 object file after first running the file through the C
7746 preprocessor. Any options specified in the $F03FLAGS and $CPPFLAGS
7747 construction variables are included on this command line. You only
7748 need to set $F03PPCOM if you need to use a specific C-preprocessor
7749 command line for Fortran 03 files. You should normally set the
7750 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7751 command line for all Fortran versions.
7752 F03PPCOMSTR
7754 If set, the string displayed when a Fortran 03 source file is
7755 compiled to an object file after first running the file through the
7756 C preprocessor. If not set, then $F03PPCOM or $FORTRANPPCOM (the
7757 command line) is displayed.
7758 F03PPFILESUFFIXES
7760 The list of file extensions for which the compilation +
7761 preprocessor pass for F03 dialect will be used. By default, this is
7762 empty.
7763 F08
7765 The Fortran 08 compiler. You should normally set the $FORTRAN
7766 variable, which specifies the default Fortran compiler for all
7767 Fortran versions. You only need to set $F08 if you need to use a
7768 specific compiler or compiler version for Fortran 08 files.
7769 F08COM
7771 The command line used to compile a Fortran 08 source file to an
7772 object file. You only need to set $F08COM if you need to use a
7773 specific command line for Fortran 08 files. You should normally set
7774 the $FORTRANCOM variable, which specifies the default command line
7775 for all Fortran versions.
7776 F08COMSTR
7778 If set, the string displayed when a Fortran 08 source file is
7779 compiled to an object file. If not set, then $F08COM or $FORTRANCOM
7780 (the command line) is displayed.
7781 F08FILESUFFIXES
7783 The list of file extensions for which the F08 dialect will be used.
7784 By default, this is ['.f08']
7785 F08FLAGS
7787 General user-specified options that are passed to the Fortran 08
7788 compiler. Note that this variable does not contain -I (or similar)
7789 include search path options that scons generates automatically from
7790 $F08PATH. See $_F08INCFLAGS below, for the variable that expands to
7791 those options. You only need to set $F08FLAGS if you need to define
7792 specific user options for Fortran 08 files. You should normally set
7793 the $FORTRANFLAGS variable, which specifies the user-specified
7794 options passed to the default Fortran compiler for all Fortran
7795 versions.
7796 _F08INCFLAGS
7798 An automatically-generated construction variable containing the
7799 Fortran 08 compiler command-line options for specifying directories
7800 to be searched for include files. The value of $_F08INCFLAGS is
7801 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7802 end of each directory in $F08PATH.
7803 F08PATH
7805 The list of directories that the Fortran 08 compiler will search
7806 for include directories. The implicit dependency scanner will
7807 search these directories for include files. Don't explicitly put
7808 include directory arguments in $F08FLAGS because the result will be
7809 non-portable and the directories will not be searched by the
7810 dependency scanner. Note: directory names in $F08PATH will be
7811 looked-up relative to the SConscript directory when they are used
7812 in a command. To force scons to look-up a directory relative to the
7813 root of the source tree use #: You only need to set $F08PATH if you
7814 need to define a specific include path for Fortran 08 files. You
7815 should normally set the $FORTRANPATH variable, which specifies the
7816 include path for the default Fortran compiler for all Fortran
7817 versions.
7818 env = Environment(F08PATH='#/include')
7820 The directory look-up can also be forced using the Dir() function:
7822 include = Dir('include')
7824 env = Environment(F08PATH=include)
7825 The directory list will be added to command lines through the
7827 automatically-generated $_F08INCFLAGS construction variable, which
7828 is constructed by appending the values of the $INCPREFIX and
7829 $INCSUFFIX construction variables to the beginning and end of each
7830 directory in $F08PATH. Any command lines you define that need the
7831 F08PATH directory list should include $_F08INCFLAGS:
7832 env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
7834 F08PPCOM
7836 The command line used to compile a Fortran 08 source file to an
7837 object file after first running the file through the C
7838 preprocessor. Any options specified in the $F08FLAGS and $CPPFLAGS
7839 construction variables are included on this command line. You only
7840 need to set $F08PPCOM if you need to use a specific C-preprocessor
7841 command line for Fortran 08 files. You should normally set the
7842 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7843 command line for all Fortran versions.
7844 F08PPCOMSTR
7846 If set, the string displayed when a Fortran 08 source file is
7847 compiled to an object file after first running the file through the
7848 C preprocessor. If not set, then $F08PPCOM or $FORTRANPPCOM (the
7849 command line) is displayed.
7850 F08PPFILESUFFIXES
7852 The list of file extensions for which the compilation +
7853 preprocessor pass for F08 dialect will be used. By default, this is
7854 empty.
7855 F77
7857 The Fortran 77 compiler. You should normally set the $FORTRAN
7858 variable, which specifies the default Fortran compiler for all
7859 Fortran versions. You only need to set $F77 if you need to use a
7860 specific compiler or compiler version for Fortran 77 files.
7861 F77COM
7863 The command line used to compile a Fortran 77 source file to an
7864 object file. You only need to set $F77COM if you need to use a
7865 specific command line for Fortran 77 files. You should normally set
7866 the $FORTRANCOM variable, which specifies the default command line
7867 for all Fortran versions.
7868 F77COMSTR
7870 If set, the string displayed when a Fortran 77 source file is
7871 compiled to an object file. If not set, then $F77COM or $FORTRANCOM
7872 (the command line) is displayed.
7873 F77FILESUFFIXES
7875 The list of file extensions for which the F77 dialect will be used.
7876 By default, this is ['.f77']
7877 F77FLAGS
7879 General user-specified options that are passed to the Fortran 77
7880 compiler. Note that this variable does not contain -I (or similar)
7881 include search path options that scons generates automatically from
7882 $F77PATH. See $_F77INCFLAGS below, for the variable that expands to
7883 those options. You only need to set $F77FLAGS if you need to define
7884 specific user options for Fortran 77 files. You should normally set
7885 the $FORTRANFLAGS variable, which specifies the user-specified
7886 options passed to the default Fortran compiler for all Fortran
7887 versions.
7888 _F77INCFLAGS
7890 An automatically-generated construction variable containing the
7891 Fortran 77 compiler command-line options for specifying directories
7892 to be searched for include files. The value of $_F77INCFLAGS is
7893 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7894 end of each directory in $F77PATH.
7895 F77PATH
7897 The list of directories that the Fortran 77 compiler will search
7898 for include directories. The implicit dependency scanner will
7899 search these directories for include files. Don't explicitly put
7900 include directory arguments in $F77FLAGS because the result will be
7901 non-portable and the directories will not be searched by the
7902 dependency scanner. Note: directory names in $F77PATH will be
7903 looked-up relative to the SConscript directory when they are used
7904 in a command. To force scons to look-up a directory relative to the
7905 root of the source tree use #: You only need to set $F77PATH if you
7906 need to define a specific include path for Fortran 77 files. You
7907 should normally set the $FORTRANPATH variable, which specifies the
7908 include path for the default Fortran compiler for all Fortran
7909 versions.
7910 env = Environment(F77PATH='#/include')
7912 The directory look-up can also be forced using the Dir() function:
7914 include = Dir('include')
7916 env = Environment(F77PATH=include)
7917 The directory list will be added to command lines through the
7919 automatically-generated $_F77INCFLAGS construction variable, which
7920 is constructed by appending the values of the $INCPREFIX and
7921 $INCSUFFIX construction variables to the beginning and end of each
7922 directory in $F77PATH. Any command lines you define that need the
7923 F77PATH directory list should include $_F77INCFLAGS:
7924 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
7926 F77PPCOM
7928 The command line used to compile a Fortran 77 source file to an
7929 object file after first running the file through the C
7930 preprocessor. Any options specified in the $F77FLAGS and $CPPFLAGS
7931 construction variables are included on this command line. You only
7932 need to set $F77PPCOM if you need to use a specific C-preprocessor
7933 command line for Fortran 77 files. You should normally set the
7934 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7935 command line for all Fortran versions.
7936 F77PPCOMSTR
7938 If set, the string displayed when a Fortran 77 source file is
7939 compiled to an object file after first running the file through the
7940 C preprocessor. If not set, then $F77PPCOM or $FORTRANPPCOM (the
7941 command line) is displayed.
7942 F77PPFILESUFFIXES
7944 The list of file extensions for which the compilation +
7945 preprocessor pass for F77 dialect will be used. By default, this is
7946 empty.
7947 F90
7949 The Fortran 90 compiler. You should normally set the $FORTRAN
7950 variable, which specifies the default Fortran compiler for all
7951 Fortran versions. You only need to set $F90 if you need to use a
7952 specific compiler or compiler version for Fortran 90 files.
7953 F90COM
7955 The command line used to compile a Fortran 90 source file to an
7956 object file. You only need to set $F90COM if you need to use a
7957 specific command line for Fortran 90 files. You should normally set
7958 the $FORTRANCOM variable, which specifies the default command line
7959 for all Fortran versions.
7960 F90COMSTR
7962 If set, the string displayed when a Fortran 90 source file is
7963 compiled to an object file. If not set, then $F90COM or $FORTRANCOM
7964 (the command line) is displayed.
7965 F90FILESUFFIXES
7967 The list of file extensions for which the F90 dialect will be used.
7968 By default, this is ['.f90']
7969 F90FLAGS
7971 General user-specified options that are passed to the Fortran 90
7972 compiler. Note that this variable does not contain -I (or similar)
7973 include search path options that scons generates automatically from
7974 $F90PATH. See $_F90INCFLAGS below, for the variable that expands to
7975 those options. You only need to set $F90FLAGS if you need to define
7976 specific user options for Fortran 90 files. You should normally set
7977 the $FORTRANFLAGS variable, which specifies the user-specified
7978 options passed to the default Fortran compiler for all Fortran
7979 versions.
7980 _F90INCFLAGS
7982 An automatically-generated construction variable containing the
7983 Fortran 90 compiler command-line options for specifying directories
7984 to be searched for include files. The value of $_F90INCFLAGS is
7985 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7986 end of each directory in $F90PATH.
7987 F90PATH
7989 The list of directories that the Fortran 90 compiler will search
7990 for include directories. The implicit dependency scanner will
7991 search these directories for include files. Don't explicitly put
7992 include directory arguments in $F90FLAGS because the result will be
7993 non-portable and the directories will not be searched by the
7994 dependency scanner. Note: directory names in $F90PATH will be
7995 looked-up relative to the SConscript directory when they are used
7996 in a command. To force scons to look-up a directory relative to the
7997 root of the source tree use #: You only need to set $F90PATH if you
7998 need to define a specific include path for Fortran 90 files. You
7999 should normally set the $FORTRANPATH variable, which specifies the
8000 include path for the default Fortran compiler for all Fortran
8001 versions.
8002 env = Environment(F90PATH='#/include')
8004 The directory look-up can also be forced using the Dir() function:
8006 include = Dir('include')
8008 env = Environment(F90PATH=include)
8009 The directory list will be added to command lines through the
8011 automatically-generated $_F90INCFLAGS construction variable, which
8012 is constructed by appending the values of the $INCPREFIX and
8013 $INCSUFFIX construction variables to the beginning and end of each
8014 directory in $F90PATH. Any command lines you define that need the
8015 F90PATH directory list should include $_F90INCFLAGS:
8016 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
8018 F90PPCOM
8020 The command line used to compile a Fortran 90 source file to an
8021 object file after first running the file through the C
8022 preprocessor. Any options specified in the $F90FLAGS and $CPPFLAGS
8023 construction variables are included on this command line. You only
8024 need to set $F90PPCOM if you need to use a specific C-preprocessor
8025 command line for Fortran 90 files. You should normally set the
8026 $FORTRANPPCOM variable, which specifies the default C-preprocessor
8027 command line for all Fortran versions.
8028 F90PPCOMSTR
8030 If set, the string displayed when a Fortran 90 source file is
8031 compiled after first running the file through the C preprocessor.
8032 If not set, then $F90PPCOM or $FORTRANPPCOM (the command line) is
8033 displayed.
8034 F90PPFILESUFFIXES
8036 The list of file extensions for which the compilation +
8037 preprocessor pass for F90 dialect will be used. By default, this is
8038 empty.
8039 F95
8041 The Fortran 95 compiler. You should normally set the $FORTRAN
8042 variable, which specifies the default Fortran compiler for all
8043 Fortran versions. You only need to set $F95 if you need to use a
8044 specific compiler or compiler version for Fortran 95 files.
8045 F95COM
8047 The command line used to compile a Fortran 95 source file to an
8048 object file. You only need to set $F95COM if you need to use a
8049 specific command line for Fortran 95 files. You should normally set
8050 the $FORTRANCOM variable, which specifies the default command line
8051 for all Fortran versions.
8052 F95COMSTR
8054 If set, the string displayed when a Fortran 95 source file is
8055 compiled to an object file. If not set, then $F95COM or $FORTRANCOM
8056 (the command line) is displayed.
8057 F95FILESUFFIXES
8059 The list of file extensions for which the F95 dialect will be used.
8060 By default, this is ['.f95']
8061 F95FLAGS
8063 General user-specified options that are passed to the Fortran 95
8064 compiler. Note that this variable does not contain -I (or similar)
8065 include search path options that scons generates automatically from
8066 $F95PATH. See $_F95INCFLAGS below, for the variable that expands to
8067 those options. You only need to set $F95FLAGS if you need to define
8068 specific user options for Fortran 95 files. You should normally set
8069 the $FORTRANFLAGS variable, which specifies the user-specified
8070 options passed to the default Fortran compiler for all Fortran
8071 versions.
8072 _F95INCFLAGS
8074 An automatically-generated construction variable containing the
8075 Fortran 95 compiler command-line options for specifying directories
8076 to be searched for include files. The value of $_F95INCFLAGS is
8077 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
8078 end of each directory in $F95PATH.
8079 F95PATH
8081 The list of directories that the Fortran 95 compiler will search
8082 for include directories. The implicit dependency scanner will
8083 search these directories for include files. Don't explicitly put
8084 include directory arguments in $F95FLAGS because the result will be
8085 non-portable and the directories will not be searched by the
8086 dependency scanner. Note: directory names in $F95PATH will be
8087 looked-up relative to the SConscript directory when they are used
8088 in a command. To force scons to look-up a directory relative to the
8089 root of the source tree use #: You only need to set $F95PATH if you
8090 need to define a specific include path for Fortran 95 files. You
8091 should normally set the $FORTRANPATH variable, which specifies the
8092 include path for the default Fortran compiler for all Fortran
8093 versions.
8094 env = Environment(F95PATH='#/include')
8096 The directory look-up can also be forced using the Dir() function:
8098 include = Dir('include')
8100 env = Environment(F95PATH=include)
8101 The directory list will be added to command lines through the
8103 automatically-generated $_F95INCFLAGS construction variable, which
8104 is constructed by appending the values of the $INCPREFIX and
8105 $INCSUFFIX construction variables to the beginning and end of each
8106 directory in $F95PATH. Any command lines you define that need the
8107 F95PATH directory list should include $_F95INCFLAGS:
8108 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
8110 F95PPCOM
8112 The command line used to compile a Fortran 95 source file to an
8113 object file after first running the file through the C
8114 preprocessor. Any options specified in the $F95FLAGS and $CPPFLAGS
8115 construction variables are included on this command line. You only
8116 need to set $F95PPCOM if you need to use a specific C-preprocessor
8117 command line for Fortran 95 files. You should normally set the
8118 $FORTRANPPCOM variable, which specifies the default C-preprocessor
8119 command line for all Fortran versions.
8120 F95PPCOMSTR
8122 If set, the string displayed when a Fortran 95 source file is
8123 compiled to an object file after first running the file through the
8124 C preprocessor. If not set, then $F95PPCOM or $FORTRANPPCOM (the
8125 command line) is displayed.
8126 F95PPFILESUFFIXES
8128 The list of file extensions for which the compilation +
8129 preprocessor pass for F95 dialect will be used. By default, this is
8130 empty.
8131 File
8133 A function that converts a string into a File instance relative to
8134 the target being built.
8135 FORTRAN
8137 The default Fortran compiler for all versions of Fortran.
8138 FORTRANCOM
8140 The command line used to compile a Fortran source file to an object
8141 file. By default, any options specified in the $FORTRANFLAGS,
8142 $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction variables are
8143 included on this command line.
8144 FORTRANCOMMONFLAGS
8146 General user-specified options that are passed to the Fortran
8147 compiler. Similar to $FORTRANFLAGS, but this variable is applied to
8148 all dialects.
8149 FORTRANCOMSTR
8151 If set, the string displayed when a Fortran source file is compiled
8152 to an object file. If not set, then $FORTRANCOM (the command line)
8153 is displayed.
8154 FORTRANFILESUFFIXES
8156 The list of file extensions for which the FORTRAN dialect will be
8157 used. By default, this is ['.f', '.for', '.ftn']
8158 FORTRANFLAGS
8160 General user-specified options for the FORTRAN dialect that are
8161 passed to the Fortran compiler. Note that this variable does not
8162 contain -I (or similar) include or module search path options that
8163 scons generates automatically from $FORTRANPATH. See
8164 $_FORTRANINCFLAGS and $_FORTRANMODFLAG, below, for the variables
8165 that expand those options.
8166 _FORTRANINCFLAGS
8168 An automatically-generated construction variable containing the
8169 Fortran compiler command-line options for specifying directories to
8170 be searched for include files and module files. The value of
8171 $_FORTRANINCFLAGS is created by respectively prepending and
8172 appending $INCPREFIX and $INCSUFFIX to the beginning and end of
8173 each directory in $FORTRANPATH.
8174 FORTRANMODDIR
8176 Directory location where the Fortran compiler should place any
8177 module files it generates. This variable is empty, by default. Some
8178 Fortran compilers will internally append this directory in the
8179 search path for module files, as well.
8180 FORTRANMODDIRPREFIX
8182 The prefix used to specify a module directory on the Fortran
8183 compiler command line. This will be prepended to the beginning of
8184 the directory in the $FORTRANMODDIR construction variables when the
8185 $_FORTRANMODFLAG variables is automatically generated.
8186 FORTRANMODDIRSUFFIX
8188 The suffix used to specify a module directory on the Fortran
8189 compiler command line. This will be appended to the end of the
8190 directory in the $FORTRANMODDIR construction variables when the
8191 $_FORTRANMODFLAG variables is automatically generated.
8192 _FORTRANMODFLAG
8194 An automatically-generated construction variable containing the
8195 Fortran compiler command-line option for specifying the directory
8196 location where the Fortran compiler should place any module files
8197 that happen to get generated during compilation. The value of
8198 $_FORTRANMODFLAG is created by respectively prepending and
8199 appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the
8200 beginning and end of the directory in $FORTRANMODDIR.
8201 FORTRANMODPREFIX
8203 The module file prefix used by the Fortran compiler. SCons assumes
8204 that the Fortran compiler follows the quasi-standard naming
8205 convention for module files of module_name.mod. As a result, this
8206 variable is left empty, by default. For situations in which the
8207 compiler does not necessarily follow the normal convention, the
8208 user may use this variable. Its value will be appended to every
8209 module file name as scons attempts to resolve dependencies.
8210 FORTRANMODSUFFIX
8212 The module file suffix used by the Fortran compiler. SCons assumes
8213 that the Fortran compiler follows the quasi-standard naming
8214 convention for module files of module_name.mod. As a result, this
8215 variable is set to ".mod", by default. For situations in which the
8216 compiler does not necessarily follow the normal convention, the
8217 user may use this variable. Its value will be appended to every
8218 module file name as scons attempts to resolve dependencies.
8219 FORTRANPATH
8221 The list of directories that the Fortran compiler will search for
8222 include files and (for some compilers) module files. The Fortran
8223 implicit dependency scanner will search these directories for
8224 include files (but not module files since they are autogenerated
8225 and, as such, may not actually exist at the time the scan takes
8226 place). Don't explicitly put include directory arguments in
8227 FORTRANFLAGS because the result will be non-portable and the
8228 directories will not be searched by the dependency scanner. Note:
8229 directory names in FORTRANPATH will be looked-up relative to the
8230 SConscript directory when they are used in a command. To force
8231 scons to look-up a directory relative to the root of the source
8232 tree use #:
8233 env = Environment(FORTRANPATH='#/include')
8235 The directory look-up can also be forced using the Dir() function:
8237 include = Dir('include')
8239 env = Environment(FORTRANPATH=include)
8240 The directory list will be added to command lines through the
8242 automatically-generated $_FORTRANINCFLAGS construction variable,
8243 which is constructed by respectively prepending and appending the
8244 values of the $INCPREFIX and $INCSUFFIX construction variables to
8245 the beginning and end of each directory in $FORTRANPATH. Any
8246 command lines you define that need the FORTRANPATH directory list
8247 should include $_FORTRANINCFLAGS:
8248 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
8250 FORTRANPPCOM
8252 The command line used to compile a Fortran source file to an object
8253 file after first running the file through the C preprocessor. By
8254 default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
8255 $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction
8256 variables are included on this command line.
8257 FORTRANPPCOMSTR
8259 If set, the string displayed when a Fortran source file is compiled
8260 to an object file after first running the file through the C
8261 preprocessor. If not set, then $FORTRANPPCOM (the command line) is
8262 displayed.
8263 FORTRANPPFILESUFFIXES
8265 The list of file extensions for which the compilation +
8266 preprocessor pass for FORTRAN dialect will be used. By default,
8267 this is ['.fpp', '.FPP']
8268 FORTRANSUFFIXES
8270 The list of suffixes of files that will be scanned for Fortran
8271 implicit dependencies (INCLUDE lines and USE statements). The
8272 default list is:
8273 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
8275 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
8276 FRAMEWORKPATH
8278 On Mac OS X with gcc, a list containing the paths to search for
8279 frameworks. Used by the compiler to find framework-style includes
8280 like #include <Fmwk/Header.h>. Used by the linker to find
8281 user-specified frameworks when linking (see $FRAMEWORKS). For
8282 example:
8283 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
8285 will add
8288 ... -Fmyframeworkdir
8290 to the compiler and linker command lines.
8293 _FRAMEWORKPATH
8295 On Mac OS X with gcc, an automatically-generated construction
8296 variable containing the linker command-line options corresponding
8297 to $FRAMEWORKPATH.
8298 FRAMEWORKPATHPREFIX
8300 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH
8301 entries. (see $FRAMEWORKPATH). The default value is -F.
8302 FRAMEWORKPREFIX
8304 On Mac OS X with gcc, the prefix to be used for linking in
8305 frameworks (see $FRAMEWORKS). The default value is -framework.
8306 FRAMEWORKS
8308 On Mac OS X with gcc, a list of the framework names to be linked
8309 into a program or shared library or bundle. The default value is
8310 the empty list. For example:
8311 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
8313 _FRAMEWORKS
8316 On Mac OS X with gcc, an automatically-generated construction
8317 variable containing the linker command-line options for linking
8318 with FRAMEWORKS.
8319 FRAMEWORKSFLAGS
8321 On Mac OS X with gcc, general user-supplied frameworks options to
8322 be added at the end of a command line building a loadable module.
8323 (This has been largely superseded by the $FRAMEWORKPATH,
8324 $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS variables
8325 described above.)
8326 GS
8328 The Ghostscript program used to, for example, convert PostScript to
8329 PDF files.
8330 GSCOM
8332 The full Ghostscript command line used for the conversion process.
8333 Its default value is “$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES”.
8334 GSCOMSTR
8336 The string displayed when Ghostscript is called for the conversion
8337 process. If this is not set (the default), then $GSCOM (the command
8338 line) is displayed.
8339 GSFLAGS
8341 General options passed to the Ghostscript program, when converting
8342 PostScript to PDF files for example. Its default value is
8343 “-dNOPAUSE -dBATCH -sDEVICE=pdfwrite”
8344 HOST_ARCH
8346 The name of the host hardware architecture used to create this
8347 construction environment. The platform code sets this when
8348 initializing (see $PLATFORM and the platform argument to
8349 Environment). Note the detected name of the architecture may not be
8350 identical to that returned by the Python platform.machine method.
8351 On the win32 platform, if the Microsoft Visual C++ compiler is
8353 available, msvc tool setup is done using $HOST_ARCH and
8354 $TARGET_ARCH. Changing the values at any later time will not cause
8355 the tool to be reinitialized. Valid host arch values are x86 and
8356 arm for 32-bit hosts and amd64 and x86_64 for 64-bit hosts.
8357 Should be considered immutable. $HOST_ARCH is not currently used
8359 by other platforms, but the option is reserved to do so in future
8360 HOST_OS
8362 The name of the host operating system for the platform used to
8363 create this construction environment. The platform code sets this
8364 when initializing (see $PLATFORM and the platform argument to
8365 Environment).
8366 Should be considered immutable. $HOST_OS is not currently used by
8368 SCons, but the option is reserved to do so in future
8369 IDLSUFFIXES
8371 The list of suffixes of files that will be scanned for IDL implicit
8372 dependencies (#include or import lines). The default list is:
8373 [".idl", ".IDL"]
8375 IMPLIBNOVERSIONSYMLINKS
8377 Used to override $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS
8378 when creating versioned import library for a shared
8379 library/loadable module. If not defined, then
8380 $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS is used to
8381 determine whether to disable symlink generation or not.
8382 IMPLIBPREFIX
8384 The prefix used for import library names. For example, cygwin uses
8385 import libraries (libfoo.dll.a) in pair with dynamic libraries
8386 (cygfoo.dll). The cyglink linker sets $IMPLIBPREFIX to 'lib' and
8387 $SHLIBPREFIX to 'cyg'.
8388 IMPLIBSUFFIX
8390 The suffix used for import library names. For example, cygwin uses
8391 import libraries (libfoo.dll.a) in pair with dynamic libraries
8392 (cygfoo.dll). The cyglink linker sets $IMPLIBSUFFIX to '.dll.a' and
8393 $SHLIBSUFFIX to '.dll'.
8394 IMPLIBVERSION
8396 Used to override $SHLIBVERSION/$LDMODULEVERSION when generating
8397 versioned import library for a shared library/loadable module. If
8398 undefined, the $SHLIBVERSION/$LDMODULEVERSION is used to determine
8399 the version of versioned import library.
8400 IMPLICIT_COMMAND_DEPENDENCIES
8402 Controls whether or not SCons will add implicit dependencies for
8403 the commands executed to build targets.
8404 By default, SCons will add to each target an implicit dependency on
8406 the command represented by the first argument of any command line
8407 it executes (which is typically the command itself). By setting
8408 such a dependency, SCons can determine that a target should be
8409 rebuilt if the command changes, such as when a compiler is upgraded
8410 to a new version. The specific file for the dependency is found by
8411 searching the PATH variable in the ENV dictionary in the
8412 construction environment used to execute the command. The default
8413 is the same as setting the construction variable
8414 $IMPLICIT_COMMAND_DEPENDENCIES to a True-like value (“true”, “yes”,
8415 or “1” - but not a number greater than one, as that has a different
8416 meaning).
8417 Action strings can be segmented by the use of an AND operator, &&.
8419 In a segemented string, each segment is a separate “command line”,
8420 these are run sequentially until one fails or the entire sequence
8421 has been executed. If an action string is segmented, then the
8422 selected behavior of $IMPLICIT_COMMAND_DEPENDENCIES is applied to
8423 each segment.
8424 If $IMPLICIT_COMMAND_DEPENDENCIES is set to a False-like value
8426 (“none”, “false”, “no”, “0”, etc.), then the implicit dependency
8427 will not be added to the targets built with that construction
8428 environment.
8429 If $IMPLICIT_COMMAND_DEPENDENCIES is set to “2” or higher, then
8431 that number of arguments in the command line will be scanned for
8432 relative or absolute paths. If any are present, they will be added
8433 as implicit dependencies to the targets built with that
8434 construction environment. The first argument in the command line
8435 will be searched for using the PATH variable in the ENV dictionary
8436 in the construction environment used to execute the command. The
8437 other arguments will only be found if they are absolute paths or
8438 valid paths relative to the working directory.
8439 If $IMPLICIT_COMMAND_DEPENDENCIES is set to “all”, then all
8441 arguments in the command line will be scanned for relative or
8442 absolute paths. If any are present, they will be added as implicit
8443 dependencies to the targets built with that construction
8444 environment. The first argument in the command line will be
8445 searched for using the PATH variable in the ENV dictionary in the
8446 construction environment used to execute the command. The other
8447 arguments will only be found if they are absolute paths or valid
8448 paths relative to the working directory.
8449 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
8451 INCPREFIX
8453 The prefix used to specify an include directory on the C compiler
8454 command line. This will be prepended to each directory in the
8455 $CPPPATH and $FORTRANPATH construction variables when the
8456 $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically
8457 generated.
8458 INCSUFFIX
8460 The suffix used to specify an include directory on the C compiler
8461 command line. This will be appended to each directory in the
8462 $CPPPATH and $FORTRANPATH construction variables when the
8463 $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically
8464 generated.
8465 INSTALL
8467 A function to be called to install a file into a destination file
8468 name. The default function copies the file into the destination
8469 (and sets the destination file's mode and permission bits to match
8470 the source file's). The function takes the following arguments:
8471 def install(dest, source, env):
8473 dest is the path name of the destination file. source is the path
8476 name of the source file. env is the construction environment (a
8477 dictionary of construction values) in force for this file
8478 installation.
8479 INSTALLSTR
8481 The string displayed when a file is installed into a destination
8482 file name. The default is:
8483 Install file: "$SOURCE" as "$TARGET"
8485 INTEL_C_COMPILER_VERSION
8487 Set by the intelc Tool to the major version number of the Intel C
8488 compiler selected for use.
8489 JAR
8491 The Java archive tool.
8492 JARCHDIR
8494 The directory to which the Java archive tool should change (using
8495 the -C option).
8496 JARCOM
8498 The command line used to call the Java archive tool.
8499 JARCOMSTR
8501 The string displayed when the Java archive tool is called If this
8502 is not set, then $JARCOM (the command line) is displayed.
8503 env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")
8505 JARFLAGS
8507 General options passed to the Java archive tool. By default this is
8508 set to cf to create the necessary jar file.
8509 JARSUFFIX
8511 The suffix for Java archives: .jar by default.
8512 JAVABOOTCLASSPATH
8514 Specifies the list of directories that will be added to the javac
8515 command line via the -bootclasspath option. The individual
8516 directory names will be separated by the operating system's path
8517 separate character (: on UNIX/Linux/POSIX, ; on Windows).
8518 JAVAC
8520 The Java compiler.
8521 JAVACCOM
8523 The command line used to compile a directory tree containing Java
8524 source files to corresponding Java class files. Any options
8525 specified in the $JAVACFLAGS construction variable are included on
8526 this command line.
8527 JAVACCOMSTR
8529 The string displayed when compiling a directory tree of Java source
8530 files to corresponding Java class files. If this is not set, then
8531 $JAVACCOM (the command line) is displayed.
8532 env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
8534 JAVACFLAGS
8537 General options that are passed to the Java compiler.
8538 JAVACLASSDIR
8540 The directory in which Java class files may be found. This is
8541 stripped from the beginning of any Java .class file names supplied
8542 to the JavaH builder.
8543 JAVACLASSPATH
8545 Specifies the list of directories that will be searched for Java
8546 .class file. The directories in this list will be added to the
8547 javac and javah command lines via the -classpath option. The
8548 individual directory names will be separated by the operating
8549 system's path separate character (: on UNIX/Linux/POSIX, ; on
8550 Windows).
8551 JAVACLASSSUFFIX
8553 The suffix for Java class files; .class by default.
8554 JAVAH
8556 The Java generator for C header and stub files.
8557 JAVAHCOM
8559 The command line used to generate C header and stub files from Java
8560 classes. Any options specified in the $JAVAHFLAGS construction
8561 variable are included on this command line.
8562 JAVAHCOMSTR
8564 The string displayed when C header and stub files are generated
8565 from Java classes. If this is not set, then $JAVAHCOM (the command
8566 line) is displayed.
8567 env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
8569 JAVAHFLAGS
8571 General options passed to the C header and stub file generator for
8572 Java classes.
8573 JAVAINCLUDES
8575 Include path for Java header files (such as jni.h)
8576 JAVASOURCEPATH
8578 Specifies the list of directories that will be searched for input
8579 .java file. The directories in this list will be added to the javac
8580 command line via the -sourcepath option. The individual directory
8581 names will be separated by the operating system's path separate
8582 character (: on UNIX/Linux/POSIX, ; on Windows).
8583 Note that this currently just adds the specified directory via the
8585 -sourcepath option. SCons does not currently search the
8586 $JAVASOURCEPATH directories for dependency .java files.
8587 JAVASUFFIX
8589 The suffix for Java files; .java by default.
8590 JAVAVERSION
8592 Specifies the Java version being used by the Java builder. Set this
8593 to specify the version of Java targeted by the javac compiler. This
8594 is sometimes necessary because Java 1.5 changed the file names that
8595 are created for nested anonymous inner classes, which can cause a
8596 mismatch with the files that SCons expects will be generated by the
8597 javac compiler. Setting $JAVAVERSION to a version greater than 1.4
8598 makes SCons realize that a build with such a compiler is actually
8599 up to date. The default is 1.4.
8600 While this is not primarily intended for selecting one version of
8602 the Java compiler vs. another, it does have that effect on the
8603 Windows platform. A more precise approach is to set $JAVAC (and
8604 related construction variables for related utilities) to the path
8605 to the specific Java compiler you want, if that is not the default
8606 compiler. On non-Windows platforms, the alternatives system may
8607 provide a way to adjust the default Java compiler without having to
8608 specify explicit paths.
8609 LATEX
8611 The LaTeX structured formatter and typesetter.
8612 LATEXCOM
8614 The command line used to call the LaTeX structured formatter and
8615 typesetter.
8616 LATEXCOMSTR
8618 The string displayed when calling the LaTeX structured formatter
8619 and typesetter. If this is not set, then $LATEXCOM (the command
8620 line) is displayed.
8621 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
8623 LATEXFLAGS
8625 General options passed to the LaTeX structured formatter and
8626 typesetter.
8627 LATEXRETRIES
8629 The maximum number of times that LaTeX will be re-run if the .log
8630 generated by the $LATEXCOM command indicates that there are
8631 undefined references. The default is to try to resolve undefined
8632 references by re-running LaTeX up to three times.
8633 LATEXSUFFIXES
8635 The list of suffixes of files that will be scanned for LaTeX
8636 implicit dependencies (\include or \import files). The default list
8637 is:
8638 [".tex", ".ltx", ".latex"]
8640 LDMODULE
8642 The linker for building loadable modules. By default, this is the
8643 same as $SHLINK.
8644 LDMODULECOM
8646 The command line for building loadable modules. On Mac OS X, this
8647 uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
8648 On other systems, this is the same as $SHLINK.
8649 LDMODULECOMSTR
8651 If set, the string displayed when building loadable modules. If not
8652 set, then $LDMODULECOM (the command line) is displayed.
8653 LDMODULEEMITTER
8655 Contains the emitter specification for the LoadableModule builder.
8656 The manpage section "Builder Objects" contains general information
8657 on specifying emitters.
8658 LDMODULEFLAGS
8660 General user options passed to the linker for building loadable
8661 modules.
8662 LDMODULENOVERSIONSYMLINKS
8664 Instructs the LoadableModule builder to not automatically create
8665 symlinks for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS
8666 LDMODULEPREFIX
8668 The prefix used for loadable module file names. On Mac OS X, this
8669 is null; on other systems, this is the same as $SHLIBPREFIX.
8670 _LDMODULESONAME
8672 A macro that automatically generates loadable module's SONAME based
8673 on $TARGET, $LDMODULEVERSION and $LDMODULESUFFIX. Used by
8674 LoadableModule builder when the linker tool supports SONAME (e.g.
8675 gnulink).
8676 LDMODULESUFFIX
8678 The suffix used for loadable module file names. On Mac OS X, this
8679 is null; on other systems, this is the same as $SHLIBSUFFIX.
8680 LDMODULEVERSION
8682 When this construction variable is defined, a versioned loadable
8683 module is created by LoadableModule builder. This activates the
8684 $_LDMODULEVERSIONFLAGS and thus modifies the $LDMODULECOM as
8685 required, adds the version number to the library name, and creates
8686 the symlinks that are needed. $LDMODULEVERSION versions should
8687 exist in the same format as $SHLIBVERSION.
8688 _LDMODULEVERSIONFLAGS
8690 This macro automatically introduces extra flags to $LDMODULECOM
8691 when building versioned LoadableModule (that is when
8692 $LDMODULEVERSION is set). _LDMODULEVERSIONFLAGS usually adds
8693 $SHLIBVERSIONFLAGS and some extra dynamically generated options
8694 (such as -Wl,-soname=$_LDMODULESONAME). It is unused by plain
8695 (unversioned) loadable modules.
8696 LDMODULEVERSIONFLAGS
8698 Extra flags added to $LDMODULECOM when building versioned
8699 LoadableModule. These flags are only used when $LDMODULEVERSION is
8700 set.
8701 LEX
8703 The lexical analyzer generator.
8704 LEX_HEADER_FILE
8706 If supplied, generate a C header file with the name taken from this
8707 variable. Will be emitted as a --header-file= command-line option.
8708 Use this in preference to including --header-file= in $LEXFLAGS
8709 directly.
8710 LEX_TABLES_FILE
8712 If supplied, write the lex tables to a file with the name taken
8713 from this variable. Will be emitted as a --tables-file=
8714 command-line option. Use this in preference to including
8715 --tables-file= in $LEXFLAGS directly.
8716 LEXCOM
8718 The command line used to call the lexical analyzer generator to
8719 generate a source file.
8720 LEXCOMSTR
8722 The string displayed when generating a source file using the
8723 lexical analyzer generator. If this is not set, then $LEXCOM (the
8724 command line) is displayed.
8725 env = Environment(LEXCOMSTR="Lex'ing $TARGET from $SOURCES")
8727 LEXFLAGS
8729 General options passed to the lexical analyzer generator. In
8730 addition to passing the value on during invocation, the lex tool
8731 also examines this construction variable for options which cause
8732 additional output files to be generated, and adds those to the
8733 target list. Recognized for this purpose are GNU flex options
8734 --header-file= and --tables-file=; the output file is named by the
8735 option argument.
8736 Note that files specified by --header-file= and --tables-file= may
8738 not be properly handled by SCons in all situations. Consider using
8739 $LEX_HEADER_FILE and $LEX_TABLES_FILE instead.
8740 LEXUNISTD
8742 Used only on windows environments to set a lex flag to prevent
8743 'unistd.h' from being included. The default value is '--nounistd'.
8744 _LIBDIRFLAGS
8746 An automatically-generated construction variable containing the
8747 linker command-line options for specifying directories to be
8748 searched for library. The value of $_LIBDIRFLAGS is created by
8749 respectively prepending and appending $LIBDIRPREFIX and
8750 $LIBDIRSUFFIX to each directory in $LIBPATH.
8751 LIBDIRPREFIX
8753 The prefix used to specify a library directory on the linker
8754 command line. This will be prepended to each directory in the
8755 $LIBPATH construction variable when the $_LIBDIRFLAGS variable is
8756 automatically generated.
8757 LIBDIRSUFFIX
8759 The suffix used to specify a library directory on the linker
8760 command line. This will be appended to each directory in the
8761 $LIBPATH construction variable when the $_LIBDIRFLAGS variable is
8762 automatically generated.
8763 LIBEMITTER
8765 Contains the emitter specification for the StaticLibrary builder.
8766 The manpage section "Builder Objects" contains general information
8767 on specifying emitters.
8768 _LIBFLAGS
8770 An automatically-generated construction variable containing the
8771 linker command-line options for specifying libraries to be linked
8772 with the resulting target. The value of $_LIBFLAGS is created by
8773 respectively prepending and appending $LIBLINKPREFIX and
8774 $LIBLINKSUFFIX to each filename in $LIBS.
8775 LIBLINKPREFIX
8777 The prefix used to specify a library to link on the linker command
8778 line. This will be prepended to each library in the $LIBS
8779 construction variable when the $_LIBFLAGS variable is automatically
8780 generated.
8781 LIBLINKSUFFIX
8783 The suffix used to specify a library to link on the linker command
8784 line. This will be appended to each library in the $LIBS
8785 construction variable when the $_LIBFLAGS variable is automatically
8786 generated.
8787 LIBPATH
8789 The list of directories that will be searched for libraries
8790 specified by the $LIBS construction variable. $LIBPATH should be a
8791 list of path strings, or a single string, not a pathname list
8792 joined by Python's os.sep.
8793 Do not put library search directives directly into $LINKFLAGS or
8795 $SHLINKFLAGS as the result will be non-portable.
8796 Note: directory names in $LIBPATH will be looked-up relative to the
8798 directory of the SConscript file when they are used in a command.
8799 To force scons to look-up a directory relative to the root of the
8800 source tree use the # prefix:
8801 env = Environment(LIBPATH='#/libs')
8803 The directory look-up can also be forced using the Dir function:
8805 libs = Dir('libs')
8807 env = Environment(LIBPATH=libs)
8808 The directory list will be added to command lines through the
8810 automatically-generated $_LIBDIRFLAGS construction variable, which
8811 is constructed by respectively prepending and appending the values
8812 of the $LIBDIRPREFIX and $LIBDIRSUFFIX construction variables to
8813 each directory in $LIBPATH. Any command lines you define that need
8814 the $LIBPATH directory list should include $_LIBDIRFLAGS:
8815 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8817 LIBPREFIX
8819 The prefix used for (static) library file names. A default value is
8820 set for each platform (posix, win32, os2, etc.), but the value is
8821 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8822 etc.) to reflect the names of the libraries they create.
8823 LIBPREFIXES
8825 A list of all legal prefixes for library file names. When searching
8826 for library dependencies, SCons will look for files with these
8827 prefixes, the base library name, and suffixes from the $LIBSUFFIXES
8828 list.
8829 LIBS
8831 A list of one or more libraries that will be added to the link line
8832 for linking with any executable program, shared library, or
8833 loadable module created by the construction environment or
8834 override.
8835 String-valued library names should include only the library base
8837 names, without prefixes such as lib or suffixes such as .so or
8838 .dll. The library list will be added to command lines through the
8839 automatically-generated $_LIBFLAGS construction variable which is
8840 constructed by respectively prepending and appending the values of
8841 the $LIBLINKPREFIX and $LIBLINKSUFFIX construction variables to
8842 each library name in $LIBS. Library name strings should not include
8843 a path component, instead the compiler will be directed to look for
8844 libraries in the paths specified by $LIBPATH.
8845 Any command lines you define that need the $LIBS library list
8847 should include $_LIBFLAGS:
8848 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8850 If you add a File object to the $LIBS list, the name of that file
8852 will be added to $_LIBFLAGS, and thus to the link line, as-is,
8853 without $LIBLINKPREFIX or $LIBLINKSUFFIX. For example:
8854 env.Append(LIBS=File('/tmp/mylib.so'))
8856 In all cases, scons will add dependencies from the executable
8858 program to all the libraries in this list.
8859 LIBSUFFIX
8861 The suffix used for (static) library file names. A default value is
8862 set for each platform (posix, win32, os2, etc.), but the value is
8863 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8864 etc.) to reflect the names of the libraries they create.
8865 LIBSUFFIXES
8867 A list of all legal suffixes for library file names. When searching
8868 for library dependencies, SCons will look for files with prefixes
8869 from the $LIBPREFIXES list, the base library name, and these
8870 suffixes.
8871 LICENSE
8873 The abbreviated name, preferably the SPDX code, of the license
8874 under which this project is released (GPL-3.0, LGPL-2.1,
8875 BSD-2-Clause etc.). See
8876 http://www.opensource.org/licenses/alphabetical[5] for a list of
8877 license names and SPDX codes.
8878 See the Package builder.
8880 LINESEPARATOR
8882 The separator used by the Substfile and Textfile builders. This
8883 value is used between sources when constructing the target. It
8884 defaults to the current system line separator.
8885 LINGUAS_FILE
8887 The $LINGUAS_FILE defines file(s) containing list of additional
8888 linguas to be processed by POInit, POUpdate or MOFiles builders. It
8889 also affects Translate builder. If the variable contains a string,
8890 it defines name of the list file. The $LINGUAS_FILE may be a list
8891 of file names as well. If $LINGUAS_FILE is set to True (or non-zero
8892 numeric value), the list will be read from default file named
8893 LINGUAS.
8894 LINK
8896 The linker. See also $SHLINK for linking shared objects.
8897 On POSIX systems (those using the link tool), you should normally
8899 not change this value as it defaults to a "smart" linker tool which
8900 selects a compiler driver matching the type of source files in use.
8901 So for example, if you set $CXX to a specific compiler name, and
8902 are compiling C++ sources, the smartlink function will
8903 automatically select the same compiler for linking.
8904 LINKCOM
8906 The command line used to link object files into an executable. See
8907 also $SHLINKCOM for linking shared objects.
8908 LINKCOMSTR
8910 If set, the string displayed when object files are linked into an
8911 executable. If not set, then $LINKCOM (the command line) is
8912 displayed. See also $SHLINKCOMSTR. for linking shared objects.
8913 env = Environment(LINKCOMSTR = "Linking $TARGET")
8915 LINKFLAGS
8917 General user options passed to the linker. Note that this variable
8918 should not contain -l (or similar) options for linking with the
8919 libraries listed in $LIBS, nor -L (or similar) library search path
8920 options that scons generates automatically from $LIBPATH. See
8921 $_LIBFLAGS above, for the variable that expands to library-link
8922 options, and $_LIBDIRFLAGS above, for the variable that expands to
8923 library search path options. See also $SHLINKFLAGS. for linking
8924 shared objects.
8925 M4
8927 The M4 macro preprocessor.
8928 M4COM
8930 The command line used to pass files through the M4 macro
8931 preprocessor.
8932 M4COMSTR
8934 The string displayed when a file is passed through the M4 macro
8935 preprocessor. If this is not set, then $M4COM (the command line) is
8936 displayed.
8937 M4FLAGS
8939 General options passed to the M4 macro preprocessor.
8940 MAKEINDEX
8942 The makeindex generator for the TeX formatter and typesetter and
8943 the LaTeX structured formatter and typesetter.
8944 MAKEINDEXCOM
8946 The command line used to call the makeindex generator for the TeX
8947 formatter and typesetter and the LaTeX structured formatter and
8948 typesetter.
8949 MAKEINDEXCOMSTR
8951 The string displayed when calling the makeindex generator for the
8952 TeX formatter and typesetter and the LaTeX structured formatter and
8953 typesetter. If this is not set, then $MAKEINDEXCOM (the command
8954 line) is displayed.
8955 MAKEINDEXFLAGS
8957 General options passed to the makeindex generator for the TeX
8958 formatter and typesetter and the LaTeX structured formatter and
8959 typesetter.
8960 MAXLINELENGTH
8962 The maximum number of characters allowed on an external command
8963 line. On Win32 systems, link lines longer than this many characters
8964 are linked via a temporary file name.
8965 MIDL
8967 The Microsoft IDL compiler.
8968 MIDLCOM
8970 The command line used to pass files to the Microsoft IDL compiler.
8971 MIDLCOMSTR
8973 The string displayed when the Microsoft IDL compiler is called. If
8974 this is not set, then $MIDLCOM (the command line) is displayed.
8975 MIDLFLAGS
8977 General options passed to the Microsoft IDL compiler.
8978 MOSUFFIX
8980 Suffix used for MO files (default: '.mo'). See msgfmt tool and
8981 MOFiles builder.
8982 MSGFMT
8984 Absolute path to msgfmt(1) binary, found by Detect(). See msgfmt
8985 tool and MOFiles builder.
8986 MSGFMTCOM
8988 Complete command line to run msgfmt(1) program. See msgfmt tool and
8989 MOFiles builder.
8990 MSGFMTCOMSTR
8992 String to display when msgfmt(1) is invoked (default: '', which
8993 means ``print $MSGFMTCOM''). See msgfmt tool and MOFiles builder.
8994 MSGFMTFLAGS
8996 Additional flags to msgfmt(1). See msgfmt tool and MOFiles builder.
8997 MSGINIT
8999 Path to msginit(1) program (found via Detect()). See msginit tool
9000 and POInit builder.
9001 MSGINITCOM
9003 Complete command line to run msginit(1) program. See msginit tool
9004 and POInit builder.
9005 MSGINITCOMSTR
9007 String to display when msginit(1) is invoked (default: '', which
9008 means ``print $MSGINITCOM''). See msginit tool and POInit builder.
9009 MSGINITFLAGS
9011 List of additional flags to msginit(1) (default: []). See msginit
9012 tool and POInit builder.
9013 _MSGINITLOCALE
9015 Internal ``macro''. Computes locale (language) name based on target
9016 filename (default: '${TARGET.filebase}').
9017 See msginit tool and POInit builder.
9019 MSGMERGE
9021 Absolute path to msgmerge(1) binary as found by Detect(). See
9022 msgmerge tool and POUpdate builder.
9023 MSGMERGECOM
9025 Complete command line to run msgmerge(1) command. See msgmerge tool
9026 and POUpdate builder.
9027 MSGMERGECOMSTR
9029 String to be displayed when msgmerge(1) is invoked (default: '',
9030 which means ``print $MSGMERGECOM''). See msgmerge tool and POUpdate
9031 builder.
9032 MSGMERGEFLAGS
9034 Additional flags to msgmerge(1) command. See msgmerge tool and
9035 POUpdate builder.
9036 MSSDK_DIR
9038 The directory containing the Microsoft SDK (either Platform SDK or
9039 Windows SDK) to be used for compilation.
9040 MSSDK_VERSION
9042 The version string of the Microsoft SDK (either Platform SDK or
9043 Windows SDK) to be used for compilation. Supported versions include
9044 6.1, 6.0A, 6.0, 2003R2 and 2003R1.
9045 MSVC_BATCH
9047 When set to any true value, specifies that SCons should batch
9048 compilation of object files when calling the Microsoft Visual C/C++
9049 compiler. All compilations of source files from the same source
9050 directory that generate target files in a same output directory and
9051 were configured in SCons using the same construction environment
9052 will be built in a single call to the compiler. Only source files
9053 that have changed since their object files were built will be
9054 passed to each compiler invocation (via the $CHANGED_SOURCES
9055 construction variable). Any compilations where the object (target)
9056 file base name (minus the .obj) does not match the source file base
9057 name will be compiled separately.
9058 MSVC_NOTFOUND_POLICY
9060 Specify the scons behavior when the Microsoft Visual C/C++ compiler
9061 is not detected.
9062 The $MSVC_NOTFOUND_POLICY specifies the scons behavior when no msvc
9064 versions are detected or when the requested msvc version is not
9065 detected.
9066 The valid values for $MSVC_NOTFOUND_POLICY and the corresponding
9068 scons behavior are:
9069 'Error' or 'Exception'
9071 Raise an exception when no msvc versions are detected or when
9072 the requested msvc version is not detected.
9073 'Warning' or 'Warn'
9075 Issue a warning and continue when no msvc versions are detected
9076 or when the requested msvc version is not detected. Depending
9077 on usage, this could result in build failure(s).
9078 'Ignore' or 'Suppress'
9080 Take no action and continue when no msvc versions are detected
9081 or when the requested msvc version is not detected. Depending
9082 on usage, this could result in build failure(s).
9083 Note: in addition to the camel case values shown above, lower case
9085 and upper case values are accepted as well.
9086 The $MSVC_NOTFOUND_POLICY is applied when any of the following
9088 conditions are satisfied:
9089 • $MSVC_VERSION is specified, the default tools list is
9091 implicitly defined (i.e., the tools list is not specified), and
9092 the default tools list contains one or more of the msvc tools.
9093 • $MSVC_VERSION is specified, the default tools list is
9095 explicitly specified (e.g., tools=['default']), and the default
9096 tools list contains one or more of the msvc tools.
9097 • A non-default tools list is specified that contains one or more
9099 of the msvc tools (e.g., tools=['msvc', 'mslink']).
9100 The $MSVC_NOTFOUND_POLICY is ignored when any of the following
9102 conditions are satisfied:
9103 • $MSVC_VERSION is not specified and the default tools list is
9105 implicitly defined (i.e., the tools list is not specified).
9106 • $MSVC_VERSION is not specified and the default tools list is
9108 explicitly specified (e.g., tools=['default']).
9109 • A non-default tool list is specified that does not contain any
9111 of the msvc tools (e.g., tools=['mingw']).
9112 Important usage details:
9114 • $MSVC_NOTFOUND_POLICY must be passed as an argument to the
9116 Environment constructor when an msvc tool (e.g., msvc, msvs,
9117 etc.) is loaded via the default tools list or via a tools list
9118 passed to the Environment constructor. Otherwise,
9119 $MSVC_NOTFOUND_POLICY must be set before the first msvc tool is
9120 loaded into the environment.
9121 When $MSVC_NOTFOUND_POLICY is not specified, the default scons
9123 behavior is to issue a warning and continue subject to the
9124 conditions listed above. The default scons behavior may change in
9125 the future.
9126 MSVC_SCRIPT_ARGS
9128 Pass user-defined arguments to the Visual C++ batch file determined
9129 via autodetection.
9130 $MSVC_SCRIPT_ARGS is available for msvc batch file arguments that
9133 do not have first-class support via construction variables or when
9134 there is an issue with the appropriate construction variable
9135 validation. When available, it is recommended to use the
9136 appropriate construction variables (e.g., $MSVC_TOOLSET_VERSION)
9137 rather than $MSVC_SCRIPT_ARGS arguments.
9138 The valid values for $MSVC_SCRIPT_ARGS are: None, a string, or a
9140 list of strings.
9141 The $MSVC_SCRIPT_ARGS value is converted to a scalar string (i.e.,
9143 "flattened"). The resulting scalar string, if not empty, is passed
9144 as an argument to the msvc batch file determined via autodetection
9145 subject to the validation conditions listed below.
9146 $MSVC_SCRIPT_ARGS is ignored when the value is None and when the
9149 result from argument conversion is an empty string. The validation
9150 conditions below do not apply.
9151 An exception is raised when any of the following conditions are
9153 satisfied:
9154 • $MSVC_SCRIPT_ARGS is specified for Visual Studio 2013 and
9156 earlier.
9157 • Multiple SDK version arguments (e.g., '10.0.20348.0') are
9159 specified in $MSVC_SCRIPT_ARGS.
9160 • $MSVC_SDK_VERSION is specified and an SDK version argument
9162 (e.g., '10.0.20348.0') is specified in $MSVC_SCRIPT_ARGS.
9163 Multiple SDK version declarations via $MSVC_SDK_VERSION and
9164 $MSVC_SCRIPT_ARGS are not allowed.
9165 • Multiple toolset version arguments (e.g., '-vcvars_ver=14.29')
9167 are specified in $MSVC_SCRIPT_ARGS.
9168 • $MSVC_TOOLSET_VERSION is specified and a toolset version
9170 argument (e.g., '-vcvars_ver=14.29') is specified in
9171 $MSVC_SCRIPT_ARGS. Multiple toolset version declarations via
9172 $MSVC_TOOLSET_VERSION and $MSVC_SCRIPT_ARGS are not allowed.
9173 • Multiple spectre library arguments (e.g.,
9175 '-vcvars_spectre_libs=spectre') are specified in
9176 $MSVC_SCRIPT_ARGS.
9177 • $MSVC_SPECTRE_LIBS is enabled and a spectre library argument
9179 (e.g., '-vcvars_spectre_libs=spectre') is specified in
9180 $MSVC_SCRIPT_ARGS. Multiple spectre library declarations via
9181 $MSVC_SPECTRE_LIBS and $MSVC_SCRIPT_ARGS are not allowed.
9182 • Multiple UWP arguments (e.g., uwp or store) are specified in
9184 $MSVC_SCRIPT_ARGS.
9185 • $MSVC_UWP_APP is enabled and a UWP argument (e.g., uwp or
9187 store) is specified in $MSVC_SCRIPT_ARGS. Multiple UWP
9188 declarations via $MSVC_UWP_APP and $MSVC_SCRIPT_ARGS are not
9189 allowed.
9190 Example 1 - A Visual Studio 2022 build with an SDK version and a
9192 toolset version specified with a string argument:
9193 env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS='10.0.20348.0 -vcvars_ver=14.29.30133')
9195 Example 2 - A Visual Studio 2022 build with an SDK version and a
9197 toolset version specified with a list argument:
9198 env = Environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['10.0.20348.0', '-vcvars_ver=14.29.30133'])
9200 Important usage details:
9202 • $MSVC_SCRIPT_ARGS must be passed as an argument to the
9204 Environment constructor when an msvc tool (e.g., msvc, msvs,
9205 etc.) is loaded via the default tools list or via a tools list
9206 passed to the Environment constructor. Otherwise,
9207 $MSVC_SCRIPT_ARGS must be set before the first msvc tool is
9208 loaded into the environment.
9209 • Other than checking for multiple declarations as described
9211 above, $MSVC_SCRIPT_ARGS arguments are not validated.
9212 •
9214 Erroneous, inconsistent, and/or version incompatible
9215 $MSVC_SCRIPT_ARGS arguments are likely to result in build
9216 failures for reasons that are not readily apparent and may be
9217 difficult to diagnose. The burden is on the user to ensure
9218 that the arguments provided to the msvc batch file are valid,
9219 consistent and compatible with the version of msvc selected.
9220 MSVC_SCRIPTERROR_POLICY
9223 Specify the scons behavior when Microsoft Visual C/C++ batch file
9224 errors are detected.
9225 The $MSVC_SCRIPTERROR_POLICY specifies the scons behavior when msvc
9227 batch file errors are detected. When $MSVC_SCRIPTERROR_POLICY is
9228 not specified, the default scons behavior is to suppress msvc batch
9229 file error messages.
9230 The root cause of msvc build failures may be difficult to diagnose.
9232 In these situations, setting the scons behavior to issue a warning
9233 when msvc batch file errors are detected may produce additional
9234 diagnostic information.
9235 The valid values for $MSVC_SCRIPTERROR_POLICY and the corresponding
9237 scons behavior are:
9238 'Error' or 'Exception'
9240 Raise an exception when msvc batch file errors are detected.
9241 'Warning' or 'Warn'
9243 Issue a warning when msvc batch file errors are detected.
9244 'Ignore' or 'Suppress'
9246 Suppress msvc batch file error messages.
9247 Note: in addition to the camel case values shown above, lower case
9249 and upper case values are accepted as well.
9250 Example 1 - A Visual Studio 2022 build with user-defined script
9252 arguments:
9253 env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'])
9255 env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
9256 Example 1 - Output fragment:
9258 ...
9260 link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
9261 LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
9262 ...
9263 Example 2 - A Visual Studio 2022 build with user-defined script
9265 arguments and the script error policy set to issue a warning when
9266 msvc batch file errors are detected:
9267 env = environment(MSVC_VERSION='14.3', MSVC_SCRIPT_ARGS=['8.1', 'store', '-vcvars_ver=14.1'], MSVC_SCRIPTERROR_POLICY='warn')
9269 env.Program('hello', ['hello.c'], CCFLAGS='/MD', LIBS=['kernel32', 'user32', 'runtimeobject'])
9270 Example 2 - Output fragment:
9272 ...
9274 scons: warning: vc script errors detected:
9275 [ERROR:vcvars.bat] The UWP Application Platform requires a Windows 10 SDK.
9276 [ERROR:vcvars.bat] WindowsSdkDir = "C:\Program Files (x86)\Windows Kits\8.1\"
9277 [ERROR:vcvars.bat] host/target architecture is not supported : { x64 , x64 }
9278 ...
9279 link /nologo /OUT:_build001\hello.exe kernel32.lib user32.lib runtimeobject.lib _build001\hello.obj
9280 LINK : fatal error LNK1104: cannot open file 'MSVCRT.lib'
9281 Important usage details:
9283 • $MSVC_SCRIPTERROR_POLICY must be passed as an argument to the
9285 Environment constructor when an msvc tool (e.g., msvc, msvs,
9286 etc.) is loaded via the default tools list or via a tools list
9287 passed to the Environment constructor. Otherwise,
9288 $MSVC_SCRIPTERROR_POLICY must be set before the first msvc tool
9289 is loaded into the environment.
9290 • Due to scons implementation details, not all Windows system
9292 environment variables are propagated to the environment in
9293 which the msvc batch file is executed. Depending on Visual
9294 Studio version and installation options, non-fatal msvc batch
9295 file error messages may be generated for ancillary tools which
9296 may not affect builds with the msvc compiler. For this reason,
9297 caution is recommended when setting the script error policy to
9298 raise an exception (e.g., 'Error').
9299 MSVC_SDK_VERSION
9302 Build with a specific version of the Microsoft Software Development
9303 Kit (SDK).
9304 The valid values for $MSVC_SDK_VERSION are: None or a string
9306 containing the requested SDK version (e.g., '10.0.20348.0').
9307 $MSVC_SDK_VERSION is ignored when the value is None and when the
9310 value is an empty string. The validation conditions below do not
9311 apply.
9312 An exception is raised when any of the following conditions are
9314 satisfied:
9315 • $MSVC_SDK_VERSION is specified for Visual Studio 2013 and
9317 earlier.
9318 • $MSVC_SDK_VERSION is specified and an SDK version argument is
9320 specified in $MSVC_SCRIPT_ARGS. Multiple SDK version
9321 declarations via $MSVC_SDK_VERSION and $MSVC_SCRIPT_ARGS are
9322 not allowed.
9323 • The $MSVC_SDK_VERSION specified does not match any of the
9325 supported formats:
9326 • '10.0.XXXXX.Y' [SDK 10.0]
9328 • '8.1' [SDK 8.1]
9330 • The system folder for the corresponding $MSVC_SDK_VERSION
9333 version is not found. The requested SDK version does not appear
9334 to be installed.
9335 • The $MSVC_SDK_VERSION version does not appear to support the
9337 requested platform type (i.e., UWP or Desktop). The requested
9338 SDK version platform type components do not appear to be
9339 installed.
9340 • The $MSVC_SDK_VERSION version is 8.1, the platform type is UWP,
9342 and the build tools selected are from Visual Studio 2017 and
9343 later (i.e., $MSVC_VERSION must be '14.0' or
9344 $MSVC_TOOLSET_VERSION must be '14.0').
9345 Example 1 - A Visual Studio 2022 build with a specific Windows SDK
9347 version:
9348 env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0')
9350 Example 2 - A Visual Studio 2022 build with a specific SDK version
9352 for the Universal Windows Platform:
9353 env = Environment(MSVC_VERSION='14.3', MSVC_SDK_VERSION='10.0.20348.0', MSVC_UWP_APP=True)
9355 Important usage details:
9357 • $MSVC_SDK_VERSION must be passed as an argument to the
9359 Environment constructor when an msvc tool (e.g., msvc, msvs,
9360 etc.) is loaded via the default tools list or via a tools list
9361 passed to the Environment constructor. Otherwise,
9362 $MSVC_SDK_VERSION must be set before the first msvc tool is
9363 loaded into the environment.
9364 • Should a SDK 10.0 version be installed that does not follow
9366 the naming scheme above, the SDK version will need to be
9367 specified via $MSVC_SCRIPT_ARGS until the version number
9368 validation format can be extended.
9369 • Should an exception be raised indicating that the SDK version
9371 is not found, verify that the requested SDK version is
9372 installed with the necessary platform type components.
9373 • There is a known issue with the Microsoft libraries when the
9375 target architecture is ARM64 and a Windows 11 SDK (version
9376 '10.0.22000.0' and later) is used with the v141 build tools and
9377 older v142 toolsets (versions '14.28.29333' and earlier).
9378 Should build failures arise with these combinations of settings
9379 due to unresolved symbols in the Microsoft libraries,
9380 $MSVC_SDK_VERSION may be employed to specify a Windows 10 SDK
9381 (e.g., '10.0.20348.0') for the build.
9382 MSVC_SPECTRE_LIBS
9385 Build with the spectre-mitigated Visual C++ libraries.
9386 The valid values for $MSVC_SPECTRE_LIBS are: True, False, or None.
9388 When $MSVC_SPECTRE_LIBS is enabled (i.e., True), the Visual C++
9390 environment will include the paths to the spectre-mitigated
9391 implementations of the Microsoft Visual C++ libraries.
9392 An exception is raised when any of the following conditions are
9394 satisfied:
9395 • $MSVC_SPECTRE_LIBS is enabled for Visual Studio 2015 and
9397 earlier.
9398 • $MSVC_SPECTRE_LIBS is enabled and a spectre library argument
9400 is specified in $MSVC_SCRIPT_ARGS. Multiple spectre library
9401 declarations via $MSVC_SPECTRE_LIBS and $MSVC_SCRIPT_ARGS are
9402 not allowed.
9403 • $MSVC_SPECTRE_LIBS is enabled and the platform type is UWP.
9405 There are no spectre-mitigated libraries for Universal Windows
9406 Platform (UWP) applications or components.
9407 Example - A Visual Studio 2022 build with spectre mitigated Visual
9409 C++ libraries:
9410 env = Environment(MSVC_VERSION='14.3', MSVC_SPECTRE_LIBS=True)
9412 Important usage details:
9414 • $MSVC_SPECTRE_LIBS must be passed as an argument to the
9416 Environment constructor when an msvc tool (e.g., msvc, msvs,
9417 etc.) is loaded via the default tools list or via a tools list
9418 passed to the Environment constructor. Otherwise,
9419 $MSVC_SPECTRE_LIBS must be set before the first msvc tool is
9420 loaded into the environment.
9421 • Additional compiler switches (e.g., /Qspectre) are necessary
9423 for including spectre mitigations when building user artifacts.
9424 Refer to the Visual Studio documentation for details.
9425 •
9427 The existence of the spectre libraries host architecture and
9428 target architecture folders are not verified when
9429 $MSVC_SPECTRE_LIBS is enabled which could result in build
9430 failures. The burden is on the user to ensure the requisite
9431 libraries with spectre mitigations are installed.
9432 MSVC_TOOLSET_VERSION
9435 Build with a specific Visual C++ toolset version.
9436 Specifying $MSVC_TOOLSET_VERSION does not affect the autodetection
9438 and selection of msvc instances. The $MSVC_TOOLSET_VERSION is
9439 applied after an msvc instance is selected. This could be the
9440 default version of msvc if $MSVC_VERSION is not specified.
9441 The valid values for $MSVC_TOOLSET_VERSION are: None or a string
9443 containing the requested toolset version (e.g., '14.29').
9444 $MSVC_TOOLSET_VERSION is ignored when the value is None and when
9447 the value is an empty string. The validation conditions below do
9448 not apply.
9449 An exception is raised when any of the following conditions are
9451 satisfied:
9452 • $MSVC_TOOLSET_VERSION is specified for Visual Studio 2015 and
9454 earlier.
9455 • $MSVC_TOOLSET_VERSION is specified and a toolset version
9457 argument is specified in $MSVC_SCRIPT_ARGS. Multiple toolset
9458 version declarations via $MSVC_TOOLSET_VERSION and
9459 $MSVC_SCRIPT_ARGS are not allowed.
9460 • The $MSVC_TOOLSET_VERSION specified does not match any of the
9462 supported formats:
9463 • 'XX.Y'
9465 • 'XX.YY'
9467 • 'XX.YY.ZZZZZ'
9469 • 'XX.YY.Z' to 'XX.YY.ZZZZ'
9471 [scons extension not directly supported by the msvc batch
9472 files and may be removed in the future]
9473 • 'XX.YY.ZZ.N' [SxS format]
9475 • 'XX.YY.ZZ.NN' [SxS format]
9477 • The major msvc version prefix (i.e., 'XX.Y') of the
9479 $MSVC_TOOLSET_VERSION specified is for Visual Studio 2013 and
9480 earlier (e.g., '12.0').
9481 • The major msvc version prefix (i.e., 'XX.Y') of the
9483 $MSVC_TOOLSET_VERSION specified is greater than the msvc
9484 version selected (e.g., '99.0').
9485 • A system folder for the corresponding $MSVC_TOOLSET_VERSION
9487 version is not found. The requested toolset version does not
9488 appear to be installed.
9489 Toolset selection details:
9491 • When $MSVC_TOOLSET_VERSION is not an SxS version number or a
9493 full toolset version number: the first toolset version, ranked
9494 in descending order, that matches the $MSVC_TOOLSET_VERSION
9495 prefix is selected.
9496 • When $MSVC_TOOLSET_VERSION is specified using the major msvc
9498 version prefix (i.e., 'XX.Y') and the major msvc version is
9499 that of the latest release of Visual Studio, the selected
9500 toolset version may not be the same as the default Visual C++
9501 toolset version.
9502 In the latest release of Visual Studio, the default Visual C++
9504 toolset version is not necessarily the toolset with the largest
9505 version number.
9506 Example 1 - A default Visual Studio build with a partial toolset
9508 version specified:
9509 env = Environment(MSVC_TOOLSET_VERSION='14.2')
9511 Example 2 - A default Visual Studio build with a partial toolset
9513 version specified:
9514 env = Environment(MSVC_TOOLSET_VERSION='14.29')
9516 Example 3 - A Visual Studio 2022 build with a full toolset version
9518 specified:
9519 env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.30133')
9521 Example 4 - A Visual Studio 2022 build with an SxS toolset version
9523 specified:
9524 env = Environment(MSVC_VERSION='14.3', MSVC_TOOLSET_VERSION='14.29.16.11')
9526 Important usage details:
9528 • $MSVC_TOOLSET_VERSION must be passed as an argument to the
9530 Environment constructor when an msvc tool (e.g., msvc, msvs,
9531 etc.) is loaded via the default tools list or via a tools list
9532 passed to the Environment constructor. Otherwise,
9533 $MSVC_TOOLSET_VERSION must be set before the first msvc tool is
9534 loaded into the environment.
9535 •
9537 The existence of the toolset host architecture and target
9538 architecture folders are not verified when
9539 $MSVC_TOOLSET_VERSION is specified which could result in build
9540 failures. The burden is on the user to ensure the requisite
9541 toolset target architecture build tools are installed.
9542 MSVC_USE_SCRIPT
9545 Use a batch script to set up the Microsoft Visual C++ compiler.
9546 If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
9548 SCons will run that batch file instead of the auto-detected one,
9549 and extract the relevant variables from the result (typically
9550 %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can
9551 be useful to force the use of a compiler version that SCons does
9552 not detect. $MSVC_USE_SCRIPT_ARGS provides arguments passed to
9553 this script.
9554 Setting $MSVC_USE_SCRIPT to None bypasses the Visual Studio
9556 autodetection entirely; use this if you are running SCons in a
9557 Visual Studio cmd window and importing the shell's environment
9558 variables - that is, if you are sure everything is set correctly
9559 already and you don't want SCons to change anything.
9560 $MSVC_USE_SCRIPT ignores $MSVC_VERSION and $TARGET_ARCH.
9563 MSVC_USE_SCRIPT_ARGS
9565 Provides arguments passed to the script $MSVC_USE_SCRIPT.
9566 MSVC_USE_SETTINGS
9568 Use a dictionary to set up the Microsoft Visual C++ compiler.
9569 $MSVC_USE_SETTINGS is ignored when $MSVC_USE_SCRIPT is defined
9572 and/or when $MSVC_USE_SETTINGS is set to None.
9573 The dictionary is used to populate the environment with the
9575 relevant variables (typically %INCLUDE%, %LIB%, and %PATH%) for
9576 supplying to the build. This can be useful to force the use of a
9577 compiler environment that SCons does not configure correctly. This
9578 is an alternative to manually configuring the environment when
9579 bypassing Visual Studio autodetection entirely by setting
9580 $MSVC_USE_SCRIPT to None.
9581 Here is an example of configuring a build environment using the
9583 Microsoft Visual C/C++ compiler included in the Microsoft SDK on a
9584 64-bit host and building for a 64-bit architecture:
9585 # Microsoft SDK 6.0 (MSVC 8.0): 64-bit host and 64-bit target
9587 msvc_use_settings = {
9588 "PATH": [
9589 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Bin\\x64",
9590 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin\\x64",
9591 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Bin",
9592 "C:\\Windows\\Microsoft.NET\\Framework\\v2.0.50727",
9593 "C:\\Windows\\system32",
9594 "C:\\Windows",
9595 "C:\\Windows\\System32\\Wbem",
9596 "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\"
9597 ],
9598 "INCLUDE": [
9599 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include",
9600 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Include\\Sys",
9601 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include",
9602 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Include\\gl",
9603 ],
9604 "LIB": [
9605 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\VC\\Lib\\x64",
9606 "C:\\Program Files\\Microsoft SDKs\\Windows\\v6.0\\Lib\\x64",
9607 ],
9608 "LIBPATH": [],
9609 "VSCMD_ARG_app_plat": [],
9610 "VCINSTALLDIR": [],
9611 "VCToolsInstallDir": []
9612 }
9613 # Specifying MSVC_VERSION is recommended
9615 env = Environment(MSVC_VERSION='8.0', MSVC_USE_SETTINGS=msvc_use_settings)
9616 Important usage details:
9618 • $MSVC_USE_SETTINGS must be passed as an argument to the
9620 Environment constructor when an msvc tool (e.g., msvc, msvs,
9621 etc.) is loaded via the default tools list or via a tools list
9622 passed to the Environment constructor. Otherwise,
9623 $MSVC_USE_SETTINGS must be set before the first msvc tool is
9624 loaded into the environment.
9625 •
9627 The dictionary content requirements are based on the internal
9628 msvc implementation and therefore may change at any time. The
9629 burden is on the user to ensure the dictionary contents are
9630 minimally sufficient to ensure successful builds.
9631 MSVC_UWP_APP
9634 Build with the Universal Windows Platform (UWP) application Visual
9635 C++ libraries.
9636 The valid values for $MSVC_UWP_APP are: True, '1', False, '0', or
9638 None.
9639 When $MSVC_UWP_APP is enabled (i.e., True or '1'), the Visual C++
9641 environment will be set up to point to the Windows Store compatible
9642 libraries and Visual C++ runtimes. In doing so, any libraries that
9643 are built will be able to be used in a UWP App and published to the
9644 Windows Store.
9645 An exception is raised when any of the following conditions are
9648 satisfied:
9649 • $MSVC_UWP_APP is enabled for Visual Studio 2013 and earlier.
9651 • $MSVC_UWP_APP is enabled and a UWP argument is specified in
9653 $MSVC_SCRIPT_ARGS. Multiple UWP declarations via $MSVC_UWP_APP
9654 and $MSVC_SCRIPT_ARGS are not allowed.
9655 Example - A Visual Studio 2022 build for the Universal Windows
9657 Platform:
9658 env = Environment(MSVC_VERSION='14.3', MSVC_UWP_APP=True)
9660 Important usage details:
9662 • $MSVC_UWP_APP must be passed as an argument to the Environment
9664 constructor when an msvc tool (e.g., msvc, msvs, etc.) is
9665 loaded via the default tools list or via a tools list passed to
9666 the Environment constructor. Otherwise, $MSVC_UWP_APP must be
9667 set before the first msvc tool is loaded into the environment.
9668 •
9670 The existence of the UWP libraries is not verified when
9671 $MSVC_UWP_APP is enabled which could result in build failures.
9672 The burden is on the user to ensure the requisite UWP libraries
9673 are installed.
9674 MSVC_VERSION
9677 Sets the preferred version of Microsoft Visual C/C++ to use.
9678 If $MSVC_VERSION is not set, SCons will (by default) select the
9680 latest version of Visual C/C++ installed on your system. If the
9681 specified version isn't installed, tool initialization will fail.
9682 $MSVC_VERSION must be passed as an argument to the Environment
9685 constructor when an msvc tool (e.g., msvc, msvs, etc.) is loaded
9686 via the default tools list or via a tools list passed to the
9687 Environment constructor. Otherwise, $MSVC_VERSION must be set
9688 before the first msvc tool is loaded into the environment.
9689 Valid values for Windows are 14.3, 14.2, 14.1, 14.1Exp, 14.0,
9691 14.0Exp, 12.0, 12.0Exp, 11.0, 11.0Exp, 10.0, 10.0Exp, 9.0, 9.0Exp,
9692 8.0, 8.0Exp, 7.1, 7.0, and 6.0. Versions ending in Exp refer to
9693 "Express" or "Express for Desktop" editions.
9694 MSVS
9696 When the Microsoft Visual Studio tools are initialized, they set up
9697 this dictionary with the following keys:
9698 VERSION
9700 the version of MSVS being used (can be set via $MSVS_VERSION)
9701 VERSIONS
9703 the available versions of MSVS installed
9704 VCINSTALLDIR
9706 installed directory of Visual C++
9707 VSINSTALLDIR
9709 installed directory of Visual Studio
9710 FRAMEWORKDIR
9712 installed directory of the .NET framework
9713 FRAMEWORKVERSIONS
9715 list of installed versions of the .NET framework, sorted latest
9716 to oldest.
9717 FRAMEWORKVERSION
9719 latest installed version of the .NET framework
9720 FRAMEWORKSDKDIR
9722 installed location of the .NET SDK.
9723 PLATFORMSDKDIR
9725 installed location of the Platform SDK.
9726 PLATFORMSDK_MODULES
9728 dictionary of installed Platform SDK modules, where the
9729 dictionary keys are keywords for the various modules, and the
9730 values are 2-tuples where the first is the release date, and
9731 the second is the version number.
9732 If a value is not set, it was not available in the registry.
9734 MSVS_ARCH
9736 Sets the architecture for which the generated project(s) should
9737 build.
9738 The default value is x86. amd64 is also supported by SCons for
9740 most Visual Studio versions. Since Visual Studio 2015 arm is
9741 supported, and since Visual Studio 2017 arm64 is supported. Trying
9742 to set $MSVS_ARCH to an architecture that's not supported for a
9743 given Visual Studio version will generate an error.
9744 MSVS_PROJECT_GUID
9746 The string placed in a generated Microsoft Visual Studio project
9747 file as the value of the ProjectGUID attribute. There is no default
9748 value. If not defined, a new GUID is generated.
9749 MSVS_SCC_AUX_PATH
9751 The path name placed in a generated Microsoft Visual Studio project
9752 file as the value of the SccAuxPath attribute if the
9753 MSVS_SCC_PROVIDER construction variable is also set. There is no
9754 default value.
9755 MSVS_SCC_CONNECTION_ROOT
9757 The root path of projects in your SCC workspace, i.e the path under
9758 which all project and solution files will be generated. It is used
9759 as a reference path from which the relative paths of the generated
9760 Microsoft Visual Studio project and solution files are computed.
9761 The relative project file path is placed as the value of the
9762 SccLocalPath attribute of the project file and as the values of the
9763 SccProjectFilePathRelativizedFromConnection[i] (where [i] ranges
9764 from 0 to the number of projects in the solution) attributes of the
9765 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9766 Studio solution file. Similarly the relative solution file path is
9767 placed as the values of the SccLocalPath[i] (where [i] ranges from
9768 0 to the number of projects in the solution) attributes of the
9769 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9770 Studio solution file. This is used only if the MSVS_SCC_PROVIDER
9771 construction variable is also set. The default value is the current
9772 working directory.
9773 MSVS_SCC_PROJECT_NAME
9775 The project name placed in a generated Microsoft Visual Studio
9776 project file as the value of the SccProjectName attribute if the
9777 MSVS_SCC_PROVIDER construction variable is also set. In this case
9778 the string is also placed in the SccProjectName0 attribute of the
9779 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9780 Studio solution file. There is no default value.
9781 MSVS_SCC_PROVIDER
9783 The string placed in a generated Microsoft Visual Studio project
9784 file as the value of the SccProvider attribute. The string is also
9785 placed in the SccProvider0 attribute of the
9786 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9787 Studio solution file. There is no default value.
9788 MSVS_VERSION
9790 Sets the preferred version of Microsoft Visual Studio to use.
9791 If $MSVS_VERSION is not set, SCons will (by default) select the
9793 latest version of Visual Studio installed on your system. So, if
9794 you have version 6 and version 7 (MSVS .NET) installed, it will
9795 prefer version 7. You can override this by specifying the
9796 MSVS_VERSION variable in the Environment initialization, setting it
9797 to the appropriate version ('6.0' or '7.0', for example). If the
9798 specified version isn't installed, tool initialization will fail.
9799 This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is
9801 set and $MSVC_VERSION is not, $MSVC_VERSION will be set
9802 automatically to $MSVS_VERSION. If both are set to different
9803 values, scons will raise an error.
9804 MSVSBUILDCOM
9806 The build command line placed in a generated Microsoft Visual
9807 Studio project file. The default is to have Visual Studio invoke
9808 SCons with any specified build targets.
9809 MSVSCLEANCOM
9811 The clean command line placed in a generated Microsoft Visual
9812 Studio project file. The default is to have Visual Studio invoke
9813 SCons with the -c option to remove any specified targets.
9814 MSVSENCODING
9816 The encoding string placed in a generated Microsoft Visual Studio
9817 project file. The default is encoding Windows-1252.
9818 MSVSPROJECTCOM
9820 The action used to generate Microsoft Visual Studio project files.
9821 MSVSPROJECTSUFFIX
9823 The suffix used for Microsoft Visual Studio project (DSP) files.
9824 The default value is .vcproj when using Visual Studio version 7.x
9825 (.NET) or later version, and .dsp when using earlier versions of
9826 Visual Studio.
9827 MSVSREBUILDCOM
9829 The rebuild command line placed in a generated Microsoft Visual
9830 Studio project file. The default is to have Visual Studio invoke
9831 SCons with any specified rebuild targets.
9832 MSVSSCONS
9834 The SCons used in generated Microsoft Visual Studio project files.
9835 The default is the version of SCons being used to generate the
9836 project file.
9837 MSVSSCONSCOM
9839 The default SCons command used in generated Microsoft Visual Studio
9840 project files.
9841 MSVSSCONSCRIPT
9843 The sconscript file (that is, SConstruct or SConscript file) that
9844 will be invoked by Visual Studio project files (through the
9845 $MSVSSCONSCOM variable). The default is the same sconscript file
9846 that contains the call to MSVSProject to build the project file.
9847 MSVSSCONSFLAGS
9849 The SCons flags used in generated Microsoft Visual Studio project
9850 files.
9851 MSVSSOLUTIONCOM
9853 The action used to generate Microsoft Visual Studio solution files.
9854 MSVSSOLUTIONSUFFIX
9856 The suffix used for Microsoft Visual Studio solution (DSW) files.
9857 The default value is .sln when using Visual Studio version 7.x
9858 (.NET), and .dsw when using earlier versions of Visual Studio.
9859 MT
9861 The program used on Windows systems to embed manifests into DLLs
9862 and EXEs. See also $WINDOWS_EMBED_MANIFEST.
9863 MTEXECOM
9865 The Windows command line used to embed manifests into executables.
9866 See also $MTSHLIBCOM.
9867 MTFLAGS
9869 Flags passed to the $MT manifest embedding program (Windows only).
9870 MTSHLIBCOM
9872 The Windows command line used to embed manifests into shared
9873 libraries (DLLs). See also $MTEXECOM.
9874 MWCW_VERSION
9876 The version number of the MetroWerks CodeWarrior C compiler to be
9877 used.
9878 MWCW_VERSIONS
9880 A list of installed versions of the MetroWerks CodeWarrior C
9881 compiler on this system.
9882 NAME
9884 Specfies the name of the project to package.
9885 See the Package builder.
9887 NINJA_ALIAS_NAME
9889 The name of the alias target which will cause SCons to create the
9890 ninja build file, and then (optionally) run ninja. The default
9891 value is generate-ninja.
9892 NINJA_CMD_ARGS
9894 A string which will pass arguments through SCons to the ninja
9895 command when scons executes ninja. Has no effect if
9896 $NINJA_DISABLE_AUTO_RUN is set.
9897 This value can also be passed on the command line:
9899 scons NINJA_CMD_ARGS=-v
9901 or
9902 scons NINJA_CMD_ARGS="-v -j 3"
9903 NINJA_COMPDB_EXPAND
9906 Boolean value to instruct ninja to expand the command line
9907 arguments normally put into response files. If true, prevents
9908 unexpanded lines in the compilation database like “gcc @rsp_file”
9909 and instead yields expanded lines like “gcc -c -o myfile.o myfile.c
9910 -Ia -DXYZ”.
9911 Ninja's compdb tool added the -x flag in Ninja V1.9.0
9913 NINJA_DEPFILE_PARSE_FORMAT
9915 Determines the type of format ninja should expect when parsing
9916 header include depfiles. Can be msvc, gcc, or clang. The msvc
9917 option corresponds to /showIncludes format, and gcc or clang
9918 correspond to -MMD -MF.
9919 NINJA_DIR
9921 The builddir value. Propagates directly into the generated ninja
9922 build file. From Ninja's docs: “ A directory for some Ninja output
9923 files. ... (You can also store other build output in this
9924 directory.) ” The default value is .ninja.
9925 NINJA_DISABLE_AUTO_RUN
9927 Boolean. Default: False. If true, SCons will not run ninja
9928 automatically after creating the ninja build file.
9929 If not explicitly set, this will be set to True if
9931 --disable_execute_ninja or SetOption('disable_execute_ninja', True)
9932 is seen.
9933 NINJA_ENV_VAR_CACHE
9935 A string that sets the environment for any environment variables
9936 that differ between the OS environment and the SCons execution
9937 environment.
9938 It will be compatible with the default shell of the operating
9940 system.
9941 If not explicitly set, SCons will generate this dynamically from
9943 the execution environment stored in the current construction
9944 environment (e.g. env['ENV']) where those values differ from the
9945 existing shell..
9946 NINJA_FILE_NAME
9948 The filename for the generated Ninja build file. The default is
9949 ninja.build.
9950 NINJA_FORCE_SCONS_BUILD
9952 If true, causes the build nodes to callback to scons instead of
9953 using ninja to build them. This is intended to be passed to the
9954 environment on the builder invocation. It is useful if you have a
9955 build node which does something which is not easily translated into
9956 ninja.
9957 NINJA_GENERATED_SOURCE_ALIAS_NAME
9959 A string matching the name of a user defined alias which represents
9960 a list of all generated sources. This will prevent the
9961 auto-detection of generated sources from
9962 $NINJA_GENERATED_SOURCE_SUFFIXES. Then all other source files will
9963 be made to depend on this in the ninja build file, forcing the
9964 generated sources to be built first.
9965 NINJA_GENERATED_SOURCE_SUFFIXES
9967 The list of source file suffixes which are generated by SCons build
9968 steps. All source files which match these suffixes will be added to
9969 the _generated_sources alias in the output ninja build file. Then
9970 all other source files will be made to depend on this in the ninja
9971 build file, forcing the generated sources to be built first.
9972 NINJA_MSVC_DEPS_PREFIX
9974 The msvc_deps_prefix string. Propagates directly into the generated
9975 ninja build file. From Ninja's docs: “defines the string which
9976 should be stripped from msvc's /showIncludes output”
9977 NINJA_POOL
9979 Set the ninja_pool for this or all targets in scope for this env
9980 var.
9981 NINJA_REGENERATE_DEPS
9983 A generator function used to create a ninja depfile which includes
9984 all the files which would require SCons to be invoked if they
9985 change. Or a list of said files.
9986 _NINJA_REGENERATE_DEPS_FUNC
9988 Internal value used to specify the function to call with argument
9989 env to generate the list of files which if changed would require
9990 the ninja build file to be regenerated.
9991 NINJA_SCONS_DAEMON_KEEP_ALIVE
9993 The number of seconds for the SCons deamon launched by ninja to
9994 stay alive. (Default: 180000)
9995 NINJA_SCONS_DAEMON_PORT
9997 The TCP/IP port for the SCons daemon to listen on. NOTE: You
9998 cannot use a port already being listened to on your build machine.
9999 (Default: random number between 10000,60000)
10000 NINJA_SYNTAX
10002 The path to a custom ninja_syntax.py file which is used in
10003 generation. The tool currently assumes you have ninja installed as
10004 a Python module and grabs the syntax file from that installation if
10005 $NINJA_SYNTAX is not explicitly set.
10006 no_import_lib
10008 When set to non-zero, suppresses creation of a corresponding
10009 Windows static import lib by the SharedLibrary builder when used
10010 with MinGW, Microsoft Visual Studio or Metrowerks. This also
10011 suppresses creation of an export (.exp) file when using Microsoft
10012 Visual Studio.
10013 OBJPREFIX
10015 The prefix used for (static) object file names.
10016 OBJSUFFIX
10018 The suffix used for (static) object file names.
10019 PACKAGEROOT
10021 Specifies the directory where all files in resulting archive will
10022 be placed if applicable. The default value is “$NAME-$VERSION”.
10023 See the Package builder.
10025 PACKAGETYPE
10027 Selects the package type to build when using the Package builder.
10028 May be a string or list of strings. See the docuentation for the
10029 builder for the currently supported types.
10030 $PACKAGETYPE may be overridden with the --package-type command line
10033 option.
10034 See the Package builder.
10036 PACKAGEVERSION
10038 The version of the package (not the underlying project). This is
10039 currently only used by the rpm packager and should reflect changes
10040 in the packaging, not the underlying project code itself.
10041 See the Package builder.
10043 PCH
10045 The Microsoft Visual C++ precompiled header that will be used when
10046 compiling object files. This variable is ignored by tools other
10047 than Microsoft Visual C++. When this variable is defined SCons will
10048 add options to the compiler command line to cause it to use the
10049 precompiled header, and will also set up the dependencies for the
10050 PCH file. Example:
10051 env['PCH'] = File('StdAfx.pch')
10053 PCHCOM
10055 The command line used by the PCH builder to generated a precompiled
10056 header.
10057 PCHCOMSTR
10059 The string displayed when generating a precompiled header. If this
10060 is not set, then $PCHCOM (the command line) is displayed.
10061 PCHPDBFLAGS
10063 A construction variable that, when expanded, adds the /yD flag to
10064 the command line only if the $PDB construction variable is set.
10065 PCHSTOP
10067 This variable specifies how much of a source file is precompiled.
10068 This variable is ignored by tools other than Microsoft Visual C++,
10069 or when the PCH variable is not being used. When this variable is
10070 define it must be a string that is the name of the header that is
10071 included at the end of the precompiled portion of the source files,
10072 or the empty string if the "#pragma hrdstop" construct is being
10073 used:
10074 env['PCHSTOP'] = 'StdAfx.h'
10076 PDB
10078 The Microsoft Visual C++ PDB file that will store debugging
10079 information for object files, shared libraries, and programs. This
10080 variable is ignored by tools other than Microsoft Visual C++. When
10081 this variable is defined SCons will add options to the compiler and
10082 linker command line to cause them to generate external debugging
10083 information, and will also set up the dependencies for the PDB
10084 file. Example:
10085 env['PDB'] = 'hello.pdb'
10087 The Visual C++ compiler switch that SCons uses by default to
10089 generate PDB information is /Z7. This works correctly with parallel
10090 (-j) builds because it embeds the debug information in the
10091 intermediate object files, as opposed to sharing a single PDB file
10092 between multiple object files. This is also the only way to get
10093 debug information embedded into a static library. Using the /Zi
10094 instead may yield improved link-time performance, although parallel
10095 builds will no longer work. You can generate PDB files with the /Zi
10096 switch by overriding the default $CCPDBFLAGS variable; see the
10097 entry for that variable for specific examples.
10098 PDFLATEX
10100 The pdflatex utility.
10101 PDFLATEXCOM
10103 The command line used to call the pdflatex utility.
10104 PDFLATEXCOMSTR
10106 The string displayed when calling the pdflatex utility. If this is
10107 not set, then $PDFLATEXCOM (the command line) is displayed.
10108 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
10110 PDFLATEXFLAGS
10112 General options passed to the pdflatex utility.
10113 PDFPREFIX
10115 The prefix used for PDF file names.
10116 PDFSUFFIX
10118 The suffix used for PDF file names.
10119 PDFTEX
10121 The pdftex utility.
10122 PDFTEXCOM
10124 The command line used to call the pdftex utility.
10125 PDFTEXCOMSTR
10127 The string displayed when calling the pdftex utility. If this is
10128 not set, then $PDFTEXCOM (the command line) is displayed.
10129 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
10131 PDFTEXFLAGS
10133 General options passed to the pdftex utility.
10134 PKGCHK
10136 On Solaris systems, the package-checking program that will be used
10137 (along with $PKGINFO) to look for installed versions of the Sun PRO
10138 C++ compiler. The default is /usr/sbin/pgkchk.
10139 PKGINFO
10141 On Solaris systems, the package information program that will be
10142 used (along with $PKGCHK) to look for installed versions of the Sun
10143 PRO C++ compiler. The default is pkginfo.
10144 PLATFORM
10146 The name of the platform used to create this construction
10147 environment. SCons sets this when initializing the platform, which
10148 by default is auto-detected (see the platform argument to
10149 Environment).
10150 env = Environment(tools=[])
10152 if env['PLATFORM'] == 'cygwin':
10153 Tool('mingw')(env)
10154 else:
10155 Tool('msvc')(env)
10156 POAUTOINIT
10159 The $POAUTOINIT variable, if set to True (on non-zero numeric
10160 value), let the msginit tool to automatically initialize missing PO
10161 files with msginit(1). This applies to both, POInit and POUpdate
10162 builders (and others that use any of them).
10163 POCREATE_ALIAS
10165 Common alias for all PO files created with POInit builder (default:
10166 'po-create'). See msginit tool and POInit builder.
10167 POSUFFIX
10169 Suffix used for PO files (default: '.po') See msginit tool and
10170 POInit builder.
10171 POTDOMAIN
10173 The $POTDOMAIN defines default domain, used to generate POT
10174 filename as $POTDOMAIN.pot when no POT file name is provided by the
10175 user. This applies to POTUpdate, POInit and POUpdate builders (and
10176 builders, that use them, e.g. Translate). Normally (if $POTDOMAIN
10177 is not defined), the builders use messages.pot as default POT file
10178 name.
10179 POTSUFFIX
10181 Suffix used for PO Template files (default: '.pot'). See xgettext
10182 tool and POTUpdate builder.
10183 POTUPDATE_ALIAS
10185 Name of the common phony target for all PO Templates created with
10186 POUpdate (default: 'pot-update'). See xgettext tool and POTUpdate
10187 builder.
10188 POUPDATE_ALIAS
10190 Common alias for all PO files being defined with POUpdate builder
10191 (default: 'po-update'). See msgmerge tool and POUpdate builder.
10192 PRINT_CMD_LINE_FUNC
10194 A Python function used to print the command lines as they are
10195 executed (assuming command printing is not disabled by the -q or -s
10196 options or their equivalents). The function must accept four
10197 arguments: s, target, source and env. s is a string showing the
10198 command being executed, target, is the target being built (file
10199 node, list, or string name(s)), source, is the source(s) used (file
10200 node, list, or string name(s)), and env is the environment being
10201 used.
10202 The function must do the printing itself. The default
10204 implementation, used if this variable is not set or is None, is to
10205 just print the string, as in:
10206 def print_cmd_line(s, target, source, env):
10208 sys.stdout.write(s + "\n")
10209 Here is an example of a more interesting function:
10211 def print_cmd_line(s, target, source, env):
10213 sys.stdout.write(
10214 "Building %s -> %s...\n"
10215 % (
10216 ' and '.join([str(x) for x in source]),
10217 ' and '.join([str(x) for x in target]),
10218 )
10219 )
10220 env = Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
10222 env.Program('foo', ['foo.c', 'bar.c'])
10223 This prints:
10225 ...
10227 scons: Building targets ...
10228 Building bar.c -> bar.o...
10229 Building foo.c -> foo.o...
10230 Building foo.o and bar.o -> foo...
10231 scons: done building targets.
10232 Another example could be a function that logs the actual commands
10234 to a file.
10235 PROGEMITTER
10237 Contains the emitter specification for the Program builder. The
10238 manpage section "Builder Objects" contains general information on
10239 specifying emitters.
10240 PROGPREFIX
10242 The prefix used for executable file names.
10243 PROGSUFFIX
10245 The suffix used for executable file names.
10246 PSCOM
10248 The command line used to convert TeX DVI files into a PostScript
10249 file.
10250 PSCOMSTR
10252 The string displayed when a TeX DVI file is converted into a
10253 PostScript file. If this is not set, then $PSCOM (the command line)
10254 is displayed.
10255 PSPREFIX
10257 The prefix used for PostScript file names.
10258 PSSUFFIX
10260 The prefix used for PostScript file names.
10261 QT_AUTOSCAN
10263 Turn off scanning for mocable files. Use the Moc Builder to
10264 explicitly specify files to run moc on.
10265 QT_BINPATH
10267 The path where the Qt binaries are installed. The default value is
10268 '$QTDIR/bin'.
10269 QT_CPPPATH
10271 The path where the Qt header files are installed. The default value
10272 is '$QTDIR/include'. Note: If you set this variable to None, the
10273 tool won't change the $CPPPATH construction variable.
10274 QT_DEBUG
10276 Prints lots of debugging information while scanning for moc files.
10277 QT_LIB
10279 Default value is 'qt'. You may want to set this to 'qt-mt'. Note:
10280 If you set this variable to None, the tool won't change the $LIBS
10281 variable.
10282 QT_LIBPATH
10284 The path where the Qt libraries are installed. The default value is
10285 '$QTDIR/lib'. Note: If you set this variable to None, the tool
10286 won't change the $LIBPATH construction variable.
10287 QT_MOC
10289 Default value is '$QT_BINPATH/moc'.
10290 QT_MOCCXXPREFIX
10292 Default value is ''. Prefix for moc output files when source is a
10293 C++ file.
10294 QT_MOCCXXSUFFIX
10296 Default value is '.moc'. Suffix for moc output files when source is
10297 a C++ file.
10298 QT_MOCFROMCXXCOM
10300 Command to generate a moc file from a C++ file.
10301 QT_MOCFROMCXXCOMSTR
10303 The string displayed when generating a moc file from a C++ file. If
10304 this is not set, then $QT_MOCFROMCXXCOM (the command line) is
10305 displayed.
10306 QT_MOCFROMCXXFLAGS
10308 Default value is '-i'. These flags are passed to moc when moccing a
10309 C++ file.
10310 QT_MOCFROMHCOM
10312 Command to generate a moc file from a header.
10313 QT_MOCFROMHCOMSTR
10315 The string displayed when generating a moc file from a C++ file. If
10316 this is not set, then $QT_MOCFROMHCOM (the command line) is
10317 displayed.
10318 QT_MOCFROMHFLAGS
10320 Default value is ''. These flags are passed to moc when moccing a
10321 header file.
10322 QT_MOCHPREFIX
10324 Default value is 'moc_'. Prefix for moc output files when source is
10325 a header.
10326 QT_MOCHSUFFIX
10328 Default value is '$CXXFILESUFFIX'. Suffix for moc output files when
10329 source is a header.
10330 QT_UIC
10332 Default value is '$QT_BINPATH/uic'.
10333 QT_UICCOM
10335 Command to generate header files from .ui files.
10336 QT_UICCOMSTR
10338 The string displayed when generating header files from .ui files.
10339 If this is not set, then $QT_UICCOM (the command line) is
10340 displayed.
10341 QT_UICDECLFLAGS
10343 Default value is ''. These flags are passed to uic when creating a
10344 header file from a .ui file.
10345 QT_UICDECLPREFIX
10347 Default value is ''. Prefix for uic generated header files.
10348 QT_UICDECLSUFFIX
10350 Default value is '.h'. Suffix for uic generated header files.
10351 QT_UICIMPLFLAGS
10353 Default value is ''. These flags are passed to uic when creating a
10354 C++ file from a .ui file.
10355 QT_UICIMPLPREFIX
10357 Default value is 'uic_'. Prefix for uic generated implementation
10358 files.
10359 QT_UICIMPLSUFFIX
10361 Default value is '$CXXFILESUFFIX'. Suffix for uic generated
10362 implementation files.
10363 QT_UISUFFIX
10365 Default value is '.ui'. Suffix of designer input files.
10366 QTDIR
10368 The path to the Qt installation to build against. If not already
10369 set, qt tool tries to obtain this from os.environ; if not found
10370 there, it tries to make a guess.
10371 RANLIB
10373 The archive indexer.
10374 RANLIBCOM
10376 The command line used to index a static library archive.
10377 RANLIBCOMSTR
10379 The string displayed when a static library archive is indexed. If
10380 this is not set, then $RANLIBCOM (the command line) is displayed.
10381 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
10383 RANLIBFLAGS
10385 General options passed to the archive indexer.
10386 RC
10388 The resource compiler used to build a Microsoft Visual C++ resource
10389 file.
10390 RCCOM
10392 The command line used to build a Microsoft Visual C++ resource
10393 file.
10394 RCCOMSTR
10396 The string displayed when invoking the resource compiler to build a
10397 Microsoft Visual C++ resource file. If this is not set, then $RCCOM
10398 (the command line) is displayed.
10399 RCFLAGS
10401 The flags passed to the resource compiler by the RES builder.
10402 RCINCFLAGS
10404 An automatically-generated construction variable containing the
10405 command-line options for specifying directories to be searched by
10406 the resource compiler. The value of $RCINCFLAGS is created by
10407 respectively prepending and appending $RCINCPREFIX and $RCINCSUFFIX
10408 to the beginning and end of each directory in $CPPPATH.
10409 RCINCPREFIX
10411 The prefix (flag) used to specify an include directory on the
10412 resource compiler command line. This will be prepended to the
10413 beginning of each directory in the $CPPPATH construction variable
10414 when the $RCINCFLAGS variable is expanded.
10415 RCINCSUFFIX
10417 The suffix used to specify an include directory on the resource
10418 compiler command line. This will be appended to the end of each
10419 directory in the $CPPPATH construction variable when the
10420 $RCINCFLAGS variable is expanded.
10421 RDirs
10423 A function that converts a string into a list of Dir instances by
10424 searching the repositories.
10425 REGSVR
10427 The program used on Windows systems to register a newly-built DLL
10428 library whenever the SharedLibrary builder is passed a keyword
10429 argument of register=True.
10430 REGSVRCOM
10432 The command line used on Windows systems to register a newly-built
10433 DLL library whenever the SharedLibrary builder is passed a keyword
10434 argument of register=True.
10435 REGSVRCOMSTR
10437 The string displayed when registering a newly-built DLL file. If
10438 this is not set, then $REGSVRCOM (the command line) is displayed.
10439 REGSVRFLAGS
10441 Flags passed to the DLL registration program on Windows systems
10442 when a newly-built DLL library is registered. By default, this
10443 includes the /s that prevents dialog boxes from popping up and
10444 requiring user attention.
10445 RMIC
10447 The Java RMI stub compiler.
10448 RMICCOM
10450 The command line used to compile stub and skeleton class files from
10451 Java classes that contain RMI implementations. Any options
10452 specified in the $RMICFLAGS construction variable are included on
10453 this command line.
10454 RMICCOMSTR
10456 The string displayed when compiling stub and skeleton class files
10457 from Java classes that contain RMI implementations. If this is not
10458 set, then $RMICCOM (the command line) is displayed.
10459 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
10461 RMICFLAGS
10463 General options passed to the Java RMI stub compiler.
10464 RPATH
10466 A list of paths to search for shared libraries when running
10467 programs. Currently only used in the GNU (gnulink), IRIX (sgilink)
10468 and Sun (sunlink) linkers. Ignored on platforms and toolchains that
10469 don't support it. Note that the paths added to RPATH are not
10470 transformed by scons in any way: if you want an absolute path, you
10471 must make it absolute yourself.
10472 _RPATH
10474 An automatically-generated construction variable containing the
10475 rpath flags to be used when linking a program with shared
10476 libraries. The value of $_RPATH is created by respectively
10477 prepending $RPATHPREFIX and appending $RPATHSUFFIX to the beginning
10478 and end of each directory in $RPATH.
10479 RPATHPREFIX
10481 The prefix used to specify a directory to be searched for shared
10482 libraries when running programs. This will be prepended to the
10483 beginning of each directory in the $RPATH construction variable
10484 when the $_RPATH variable is automatically generated.
10485 RPATHSUFFIX
10487 The suffix used to specify a directory to be searched for shared
10488 libraries when running programs. This will be appended to the end
10489 of each directory in the $RPATH construction variable when the
10490 $_RPATH variable is automatically generated.
10491 RPCGEN
10493 The RPC protocol compiler.
10494 RPCGENCLIENTFLAGS
10496 Options passed to the RPC protocol compiler when generating client
10497 side stubs. These are in addition to any flags specified in the
10498 $RPCGENFLAGS construction variable.
10499 RPCGENFLAGS
10501 General options passed to the RPC protocol compiler.
10502 RPCGENHEADERFLAGS
10504 Options passed to the RPC protocol compiler when generating a
10505 header file. These are in addition to any flags specified in the
10506 $RPCGENFLAGS construction variable.
10507 RPCGENSERVICEFLAGS
10509 Options passed to the RPC protocol compiler when generating server
10510 side stubs. These are in addition to any flags specified in the
10511 $RPCGENFLAGS construction variable.
10512 RPCGENXDRFLAGS
10514 Options passed to the RPC protocol compiler when generating XDR
10515 routines. These are in addition to any flags specified in the
10516 $RPCGENFLAGS construction variable.
10517 SCANNERS
10519 A list of the available implicit dependency scanners. New file
10520 scanners may be added by appending to this list, although the more
10521 flexible approach is to associate scanners with a specific Builder.
10522 See the manpage sections "Builder Objects" and "Scanner Objects"
10523 for more information.
10524 SCONS_HOME
10526 The (optional) path to the SCons library directory, initialized
10527 from the external environment. If set, this is used to construct a
10528 shorter and more efficient search path in the $MSVSSCONS command
10529 line executed from Microsoft Visual Studio project files.
10530 SHCC
10532 The C compiler used for generating shared-library objects. See also
10533 $CC for compiling to static objects.
10534 SHCCCOM
10536 The command line used to compile a C source file to a
10537 shared-library object file. Any options specified in the $SHCFLAGS,
10538 $SHCCFLAGS and $CPPFLAGS construction variables are included on
10539 this command line. See also $CCCOM for compiling to static objects.
10540 SHCCCOMSTR
10542 If set, the string displayed when a C source file is compiled to a
10543 shared object file. If not set, then $SHCCCOM (the command line) is
10544 displayed. See also $CCCOMSTR for compiling to static objects.
10545 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
10547 SHCCFLAGS
10549 Options that are passed to the C and C++ compilers to generate
10550 shared-library objects. See also $CCFLAGS for compiling to static
10551 objects.
10552 SHCFLAGS
10554 Options that are passed to the C compiler (only; not C++) to
10555 generate shared-library objects. See also $CFLAGS for compiling to
10556 static objects.
10557 SHCXX
10559 The C++ compiler used for generating shared-library objects. See
10560 also $CXX for compiling to static objects.
10561 SHCXXCOM
10563 The command line used to compile a C++ source file to a
10564 shared-library object file. Any options specified in the
10565 $SHCXXFLAGS and $CPPFLAGS construction variables are included on
10566 this command line. See also $CXXCOM for compiling to static
10567 objects.
10568 SHCXXCOMSTR
10570 If set, the string displayed when a C++ source file is compiled to
10571 a shared object file. If not set, then $SHCXXCOM (the command line)
10572 is displayed. See also $CXXCOMSTR for compiling to static objects.
10573 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
10575 SHCXXFLAGS
10577 Options that are passed to the C++ compiler to generate
10578 shared-library objects. See also $CXXFLAGS for compiling to static
10579 objects.
10580 SHDC
10582 The name of the compiler to use when compiling D source destined to
10583 be in a shared objects. See also $DC for compiling to static
10584 objects.
10585 SHDCOM
10587 The command line to use when compiling code to be part of shared
10588 objects. See also $DCOM for compiling to static objects.
10589 SHDCOMSTR
10591 If set, the string displayed when a D source file is compiled to a
10592 (shared) object file. If not set, then $SHDCOM (the command line)
10593 is displayed. See also $DCOMSTR for compiling to static objects.
10594 SHDLIBVERSIONFLAGS
10596 Extra flags added to $SHDLINKCOM when building versioned
10597 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
10598 SHDLINK
10600 The linker to use when creating shared objects for code bases
10601 include D sources. See also $DLINK for linking static objects.
10602 SHDLINKCOM
10604 The command line to use when generating shared objects. See also
10605 $DLINKCOM for linking static objects.
10606 SHDLINKFLAGS
10608 The list of flags to use when generating a shared object. See also
10609 $DLINKFLAGS for linking static objects.
10610 SHELL
10612 A string naming the shell program that will be passed to the $SPAWN
10613 function. See the $SPAWN construction variable for more
10614 information.
10615 SHELL_ENV_GENERATORS
10617 Must be a list (or an iterable) containing functions where each
10618 function generates or alters the environment dictionary which will
10619 be used when executing the $SPAWN function. The functions will
10620 initially be passed a reference of the current execution
10621 environment (e.g. env['ENV']), and each called while iterating the
10622 list. Each function must return a dictionary which will then be
10623 passed to the next function iterated. The return dictionary should
10624 contain keys which represent the environment variables and their
10625 respective values. This primary purpose of this construction
10626 variable is to give the user the ability to substitute execution
10627 environment variables based on env, targets, and sources. If
10628 desired, the user can completely customize the execution
10629 environment for particular targets.
10630 def custom_shell_env(env, target, source, shell_env):
10632 """customize shell_env if desired"""
10633 if str(target[0]) == 'special_target':
10634 shell_env['SPECIAL_VAR'] = env.subst('SOME_VAR', target=target, source=source)
10635 return shell_env
10636 env["SHELL_ENV_GENERATORS"] = [custom_shell_env]
10638 env The SCons construction environment from which the execution
10642 environment can be derived from.
10643 target The list of targets associated with this action.
10646 source The list of sources associated with this action.
10649 shell_env The current shell_env after iterating other
10652 SHELL_ENV_GENERATORS functions. This can be compared to the passed
10653 env['ENV'] to detect any changes.
10654 SHF03
10656 The Fortran 03 compiler used for generating shared-library objects.
10657 You should normally set the $SHFORTRAN variable, which specifies
10658 the default Fortran compiler for all Fortran versions. You only
10659 need to set $SHF03 if you need to use a specific compiler or
10660 compiler version for Fortran 03 files.
10661 SHF03COM
10663 The command line used to compile a Fortran 03 source file to a
10664 shared-library object file. You only need to set $SHF03COM if you
10665 need to use a specific command line for Fortran 03 files. You
10666 should normally set the $SHFORTRANCOM variable, which specifies the
10667 default command line for all Fortran versions.
10668 SHF03COMSTR
10670 If set, the string displayed when a Fortran 03 source file is
10671 compiled to a shared-library object file. If not set, then
10672 $SHF03COM or $SHFORTRANCOM (the command line) is displayed.
10673 SHF03FLAGS
10675 Options that are passed to the Fortran 03 compiler to generated
10676 shared-library objects. You only need to set $SHF03FLAGS if you
10677 need to define specific user options for Fortran 03 files. You
10678 should normally set the $FORTRANCOMMONFLAGS variable, which
10679 specifies the user-specified options passed to the default Fortran
10680 compiler for all Fortran versions.
10681 SHF03PPCOM
10683 The command line used to compile a Fortran 03 source file to a
10684 shared-library object file after first running the file through the
10685 C preprocessor. Any options specified in the $SHF03FLAGS and
10686 $CPPFLAGS construction variables are included on this command line.
10687 You only need to set $SHF03PPCOM if you need to use a specific
10688 C-preprocessor command line for Fortran 03 files. You should
10689 normally set the $SHFORTRANPPCOM variable, which specifies the
10690 default C-preprocessor command line for all Fortran versions.
10691 SHF03PPCOMSTR
10693 If set, the string displayed when a Fortran 03 source file is
10694 compiled to a shared-library object file after first running the
10695 file through the C preprocessor. If not set, then $SHF03PPCOM or
10696 $SHFORTRANPPCOM (the command line) is displayed.
10697 SHF08
10699 The Fortran 08 compiler used for generating shared-library objects.
10700 You should normally set the $SHFORTRAN variable, which specifies
10701 the default Fortran compiler for all Fortran versions. You only
10702 need to set $SHF08 if you need to use a specific compiler or
10703 compiler version for Fortran 08 files.
10704 SHF08COM
10706 The command line used to compile a Fortran 08 source file to a
10707 shared-library object file. You only need to set $SHF08COM if you
10708 need to use a specific command line for Fortran 08 files. You
10709 should normally set the $SHFORTRANCOM variable, which specifies the
10710 default command line for all Fortran versions.
10711 SHF08COMSTR
10713 If set, the string displayed when a Fortran 08 source file is
10714 compiled to a shared-library object file. If not set, then
10715 $SHF08COM or $SHFORTRANCOM (the command line) is displayed.
10716 SHF08FLAGS
10718 Options that are passed to the Fortran 08 compiler to generated
10719 shared-library objects. You only need to set $SHF08FLAGS if you
10720 need to define specific user options for Fortran 08 files. You
10721 should normally set the $FORTRANCOMMONFLAGS variable, which
10722 specifies the user-specified options passed to the default Fortran
10723 compiler for all Fortran versions.
10724 SHF08PPCOM
10726 The command line used to compile a Fortran 08 source file to a
10727 shared-library object file after first running the file through the
10728 C preprocessor. Any options specified in the $SHF08FLAGS and
10729 $CPPFLAGS construction variables are included on this command line.
10730 You only need to set $SHF08PPCOM if you need to use a specific
10731 C-preprocessor command line for Fortran 08 files. You should
10732 normally set the $SHFORTRANPPCOM variable, which specifies the
10733 default C-preprocessor command line for all Fortran versions.
10734 SHF08PPCOMSTR
10736 If set, the string displayed when a Fortran 08 source file is
10737 compiled to a shared-library object file after first running the
10738 file through the C preprocessor. If not set, then $SHF08PPCOM or
10739 $SHFORTRANPPCOM (the command line) is displayed.
10740 SHF77
10742 The Fortran 77 compiler used for generating shared-library objects.
10743 You should normally set the $SHFORTRAN variable, which specifies
10744 the default Fortran compiler for all Fortran versions. You only
10745 need to set $SHF77 if you need to use a specific compiler or
10746 compiler version for Fortran 77 files.
10747 SHF77COM
10749 The command line used to compile a Fortran 77 source file to a
10750 shared-library object file. You only need to set $SHF77COM if you
10751 need to use a specific command line for Fortran 77 files. You
10752 should normally set the $SHFORTRANCOM variable, which specifies the
10753 default command line for all Fortran versions.
10754 SHF77COMSTR
10756 If set, the string displayed when a Fortran 77 source file is
10757 compiled to a shared-library object file. If not set, then
10758 $SHF77COM or $SHFORTRANCOM (the command line) is displayed.
10759 SHF77FLAGS
10761 Options that are passed to the Fortran 77 compiler to generated
10762 shared-library objects. You only need to set $SHF77FLAGS if you
10763 need to define specific user options for Fortran 77 files. You
10764 should normally set the $FORTRANCOMMONFLAGS variable, which
10765 specifies the user-specified options passed to the default Fortran
10766 compiler for all Fortran versions.
10767 SHF77PPCOM
10769 The command line used to compile a Fortran 77 source file to a
10770 shared-library object file after first running the file through the
10771 C preprocessor. Any options specified in the $SHF77FLAGS and
10772 $CPPFLAGS construction variables are included on this command line.
10773 You only need to set $SHF77PPCOM if you need to use a specific
10774 C-preprocessor command line for Fortran 77 files. You should
10775 normally set the $SHFORTRANPPCOM variable, which specifies the
10776 default C-preprocessor command line for all Fortran versions.
10777 SHF77PPCOMSTR
10779 If set, the string displayed when a Fortran 77 source file is
10780 compiled to a shared-library object file after first running the
10781 file through the C preprocessor. If not set, then $SHF77PPCOM or
10782 $SHFORTRANPPCOM (the command line) is displayed.
10783 SHF90
10785 The Fortran 90 compiler used for generating shared-library objects.
10786 You should normally set the $SHFORTRAN variable, which specifies
10787 the default Fortran compiler for all Fortran versions. You only
10788 need to set $SHF90 if you need to use a specific compiler or
10789 compiler version for Fortran 90 files.
10790 SHF90COM
10792 The command line used to compile a Fortran 90 source file to a
10793 shared-library object file. You only need to set $SHF90COM if you
10794 need to use a specific command line for Fortran 90 files. You
10795 should normally set the $SHFORTRANCOM variable, which specifies the
10796 default command line for all Fortran versions.
10797 SHF90COMSTR
10799 If set, the string displayed when a Fortran 90 source file is
10800 compiled to a shared-library object file. If not set, then
10801 $SHF90COM or $SHFORTRANCOM (the command line) is displayed.
10802 SHF90FLAGS
10804 Options that are passed to the Fortran 90 compiler to generated
10805 shared-library objects. You only need to set $SHF90FLAGS if you
10806 need to define specific user options for Fortran 90 files. You
10807 should normally set the $FORTRANCOMMONFLAGS variable, which
10808 specifies the user-specified options passed to the default Fortran
10809 compiler for all Fortran versions.
10810 SHF90PPCOM
10812 The command line used to compile a Fortran 90 source file to a
10813 shared-library object file after first running the file through the
10814 C preprocessor. Any options specified in the $SHF90FLAGS and
10815 $CPPFLAGS construction variables are included on this command line.
10816 You only need to set $SHF90PPCOM if you need to use a specific
10817 C-preprocessor command line for Fortran 90 files. You should
10818 normally set the $SHFORTRANPPCOM variable, which specifies the
10819 default C-preprocessor command line for all Fortran versions.
10820 SHF90PPCOMSTR
10822 If set, the string displayed when a Fortran 90 source file is
10823 compiled to a shared-library object file after first running the
10824 file through the C preprocessor. If not set, then $SHF90PPCOM or
10825 $SHFORTRANPPCOM (the command line) is displayed.
10826 SHF95
10828 The Fortran 95 compiler used for generating shared-library objects.
10829 You should normally set the $SHFORTRAN variable, which specifies
10830 the default Fortran compiler for all Fortran versions. You only
10831 need to set $SHF95 if you need to use a specific compiler or
10832 compiler version for Fortran 95 files.
10833 SHF95COM
10835 The command line used to compile a Fortran 95 source file to a
10836 shared-library object file. You only need to set $SHF95COM if you
10837 need to use a specific command line for Fortran 95 files. You
10838 should normally set the $SHFORTRANCOM variable, which specifies the
10839 default command line for all Fortran versions.
10840 SHF95COMSTR
10842 If set, the string displayed when a Fortran 95 source file is
10843 compiled to a shared-library object file. If not set, then
10844 $SHF95COM or $SHFORTRANCOM (the command line) is displayed.
10845 SHF95FLAGS
10847 Options that are passed to the Fortran 95 compiler to generated
10848 shared-library objects. You only need to set $SHF95FLAGS if you
10849 need to define specific user options for Fortran 95 files. You
10850 should normally set the $FORTRANCOMMONFLAGS variable, which
10851 specifies the user-specified options passed to the default Fortran
10852 compiler for all Fortran versions.
10853 SHF95PPCOM
10855 The command line used to compile a Fortran 95 source file to a
10856 shared-library object file after first running the file through the
10857 C preprocessor. Any options specified in the $SHF95FLAGS and
10858 $CPPFLAGS construction variables are included on this command line.
10859 You only need to set $SHF95PPCOM if you need to use a specific
10860 C-preprocessor command line for Fortran 95 files. You should
10861 normally set the $SHFORTRANPPCOM variable, which specifies the
10862 default C-preprocessor command line for all Fortran versions.
10863 SHF95PPCOMSTR
10865 If set, the string displayed when a Fortran 95 source file is
10866 compiled to a shared-library object file after first running the
10867 file through the C preprocessor. If not set, then $SHF95PPCOM or
10868 $SHFORTRANPPCOM (the command line) is displayed.
10869 SHFORTRAN
10871 The default Fortran compiler used for generating shared-library
10872 objects.
10873 SHFORTRANCOM
10875 The command line used to compile a Fortran source file to a
10876 shared-library object file. By default, any options specified in
10877 the $SHFORTRANFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
10878 construction variables are included on this command line. See also
10879 $FORTRANCOM.
10880 SHFORTRANCOMSTR
10882 If set, the string displayed when a Fortran source file is compiled
10883 to a shared-library object file. If not set, then $SHFORTRANCOM
10884 (the command line) is displayed.
10885 SHFORTRANFLAGS
10887 Options that are passed to the Fortran compiler to generate
10888 shared-library objects.
10889 SHFORTRANPPCOM
10891 The command line used to compile a Fortran source file to a
10892 shared-library object file after first running the file through the
10893 C preprocessor. By default, any options specified in the
10894 $SHFORTRANFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and
10895 $_FORTRANINCFLAGS construction variables are included on this
10896 command line. See also $SHFORTRANCOM.
10897 SHFORTRANPPCOMSTR
10899 If set, the string displayed when a Fortran source file is compiled
10900 to a shared-library object file after first running the file
10901 through the C preprocessor. If not set, then $SHFORTRANPPCOM (the
10902 command line) is displayed.
10903 SHLIBEMITTER
10905 Contains the emitter specification for the SharedLibrary builder.
10906 The manpage section "Builder Objects" contains general information
10907 on specifying emitters.
10908 SHLIBNOVERSIONSYMLINKS
10910 Instructs the SharedLibrary builder to not create symlinks for
10911 versioned shared libraries.
10912 SHLIBPREFIX
10914 The prefix used for shared library file names.
10915 _SHLIBSONAME
10917 A macro that automatically generates shared library's SONAME based
10918 on $TARGET, $SHLIBVERSION and $SHLIBSUFFIX. Used by SharedLibrary
10919 builder when the linker tool supports SONAME (e.g. gnulink).
10920 SHLIBSUFFIX
10922 The suffix used for shared library file names.
10923 SHLIBVERSION
10925 When this construction variable is defined, a versioned shared
10926 library is created by the SharedLibrary builder. This activates the
10927 $_SHLIBVERSIONFLAGS and thus modifies the $SHLINKCOM as required,
10928 adds the version number to the library name, and creates the
10929 symlinks that are needed. $SHLIBVERSION versions should exist as
10930 alpha-numeric, decimal-delimited values as defined by the regular
10931 expression "\w+[\.\w+]*". Example $SHLIBVERSION values include '1',
10932 '1.2.3', and '1.2.gitaa412c8b'.
10933 _SHLIBVERSIONFLAGS
10935 This macro automatically introduces extra flags to $SHLINKCOM when
10936 building versioned SharedLibrary (that is when $SHLIBVERSION is
10937 set). _SHLIBVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS and some
10938 extra dynamically generated options (such as
10939 -Wl,-soname=$_SHLIBSONAME. It is unused by "plain" (unversioned)
10940 shared libraries.
10941 SHLIBVERSIONFLAGS
10943 Extra flags added to $SHLINKCOM when building versioned
10944 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
10945 SHLINK
10947 The linker for programs that use shared libraries. See also $LINK
10948 for linking static objects.
10949 On POSIX systems (those using the link tool), you should normally
10951 not change this value as it defaults to a "smart" linker tool which
10952 selects a compiler driver matching the type of source files in use.
10953 So for example, if you set $SHCXX to a specific compiler name, and
10954 are compiling C++ sources, the smartlink function will
10955 automatically select the same compiler for linking.
10956 SHLINKCOM
10958 The command line used to link programs using shared libraries. See
10959 also $LINKCOM for linking static objects.
10960 SHLINKCOMSTR
10962 The string displayed when programs using shared libraries are
10963 linked. If this is not set, then $SHLINKCOM (the command line) is
10964 displayed. See also $LINKCOMSTR for linking static objects.
10965 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
10967 SHLINKFLAGS
10969 General user options passed to the linker for programs using shared
10970 libraries. Note that this variable should not contain -l (or
10971 similar) options for linking with the libraries listed in $LIBS,
10972 nor -L (or similar) include search path options that scons
10973 generates automatically from $LIBPATH. See $_LIBFLAGS above, for
10974 the variable that expands to library-link options, and
10975 $_LIBDIRFLAGS above, for the variable that expands to library
10976 search path options. See also $LINKFLAGS for linking static
10977 objects.
10978 SHOBJPREFIX
10980 The prefix used for shared object file names.
10981 SHOBJSUFFIX
10983 The suffix used for shared object file names.
10984 SONAME
10986 Variable used to hard-code SONAME for versioned shared
10987 library/loadable module.
10988 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
10990 The variable is used, for example, by gnulink linker tool.
10992 SOURCE
10994 A reserved variable name that may not be set or used in a
10995 construction environment. (See the manpage section "Variable
10996 Substitution" for more information).
10997 SOURCE_URL
10999 The URL (web address) of the location from which the project was
11000 retrieved. This is used to fill in the Source: field in the
11001 controlling information for Ipkg and RPM packages.
11002 See the Package builder.
11004 SOURCES
11006 A reserved variable name that may not be set or used in a
11007 construction environment. (See the manpage section "Variable
11008 Substitution" for more information).
11009 SOVERSION
11011 This will construct the SONAME using on the base library name (test
11012 in the example below) and use specified SOVERSION to create SONAME.
11013 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
11015 The variable is used, for example, by gnulink linker tool.
11017 In the example above SONAME would be libtest.so.2 which would be a
11019 symlink and point to libtest.so.0.1.2
11020 SPAWN
11022 A command interpreter function that will be called to execute
11023 command line strings. The function must accept five arguments:
11024 def spawn(shell, escape, cmd, args, env):
11026 shell is a string naming the shell program to use, escape is a
11029 function that can be called to escape shell special characters in
11030 the command line, cmd is the path to the command to be executed,
11031 args holds the arguments to the command and env is a dictionary of
11032 environment variables defining the execution environment in which
11033 the command should be executed.
11034 STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME
11036 When this variable is true, static objects and shared objects are
11037 assumed to be the same; that is, SCons does not check for linking
11038 static objects into a shared library.
11039 SUBST_DICT
11041 The dictionary used by the Substfile or Textfile builders for
11042 substitution values. It can be anything acceptable to the dict()
11043 constructor, so in addition to a dictionary, lists of tuples are
11044 also acceptable.
11045 SUBSTFILEPREFIX
11047 The prefix used for Substfile file names, an empty string by
11048 default.
11049 SUBSTFILESUFFIX
11051 The suffix used for Substfile file names, an empty string by
11052 default.
11053 SUMMARY
11055 A short summary of what the project is about. This is used to fill
11056 in the Summary: field in the controlling information for Ipkg and
11057 RPM packages, and as the Description: field in MSI packages.
11058 See the Package builder.
11060 SWIG
11062 The name of the SWIG compiler to use.
11063 SWIGCFILESUFFIX
11065 The suffix that will be used for intermediate C source files
11066 generated by SWIG. The default value is '_wrap$CFILESUFFIX' - that
11067 is, the concatenation of the string _wrap and the current C suffix
11068 $CFILESUFFIX. By default, this value is used whenever the -c++
11069 option is not specified as part of the $SWIGFLAGS construction
11070 variable.
11071 SWIGCOM
11073 The command line used to call SWIG.
11074 SWIGCOMSTR
11076 The string displayed when calling SWIG. If this is not set, then
11077 $SWIGCOM (the command line) is displayed.
11078 SWIGCXXFILESUFFIX
11080 The suffix that will be used for intermediate C++ source files
11081 generated by SWIG. The default value is '_wrap$CXXFILESUFFIX' -
11082 that is, the concatenation of the string _wrap and the current C++
11083 suffix $CXXFILESUFFIX. By default, this value is used whenever the
11084 -c++ option is specified as part of the $SWIGFLAGS construction
11085 variable.
11086 SWIGDIRECTORSUFFIX
11088 The suffix that will be used for intermediate C++ header files
11089 generated by SWIG. These are only generated for C++ code when the
11090 SWIG 'directors' feature is turned on. The default value is
11091 _wrap.h.
11092 SWIGFLAGS
11094 General options passed to SWIG. This is where you should set the
11095 target language (-python, -perl5, -tcl, etc.) and whatever other
11096 options you want to specify to SWIG, such as the -c++ to generate
11097 C++ code instead of C Code.
11098 _SWIGINCFLAGS
11100 An automatically-generated construction variable containing the
11101 SWIG command-line options for specifying directories to be searched
11102 for included files. The value of $_SWIGINCFLAGS is created by
11103 respectively prepending and appending $SWIGINCPREFIX and
11104 $SWIGINCSUFFIX to the beginning and end of each directory in
11105 $SWIGPATH.
11106 SWIGINCPREFIX
11108 The prefix used to specify an include directory on the SWIG command
11109 line. This will be prepended to the beginning of each directory in
11110 the $SWIGPATH construction variable when the $_SWIGINCFLAGS
11111 variable is automatically generated.
11112 SWIGINCSUFFIX
11114 The suffix used to specify an include directory on the SWIG command
11115 line. This will be appended to the end of each directory in the
11116 $SWIGPATH construction variable when the $_SWIGINCFLAGS variable is
11117 automatically generated.
11118 SWIGOUTDIR
11120 Specifies the output directory in which SWIG should place generated
11121 language-specific files. This will be used by SCons to identify the
11122 files that will be generated by the SWIG call, and translated into
11123 the swig -outdir option on the command line.
11124 SWIGPATH
11126 The list of directories that SWIG will search for included files.
11127 SCons' SWIG implicit dependency scanner will search these
11128 directories for include files. The default value is an empty list.
11129 Don't explicitly put include directory arguments in $SWIGFLAGS the
11131 result will be non-portable and the directories will not be
11132 searched by the dependency scanner. Note: directory names in
11133 $SWIGPATH will be looked-up relative to the SConscript directory
11134 when they are used in a command. To force scons to look-up a
11135 directory relative to the root of the source tree use a
11136 top-relative path (#):
11137 env = Environment(SWIGPATH='#/include')
11139 The directory look-up can also be forced using the Dir() function:
11141 include = Dir('include')
11143 env = Environment(SWIGPATH=include)
11144 The directory list will be added to command lines through the
11146 automatically-generated $_SWIGINCFLAGS construction variable, which
11147 is constructed by respectively prepending and appending the values
11148 of the $SWIGINCPREFIX and $SWIGINCSUFFIX construction variables to
11149 the beginning and end of each directory in $SWIGPATH. Any command
11150 lines you define that need the SWIGPATH directory list should
11151 include $_SWIGINCFLAGS:
11152 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
11154 SWIGVERSION
11156 The detected version string of the SWIG tool.
11157 TAR
11159 The tar archiver.
11160 TARCOM
11162 The command line used to call the tar archiver.
11163 TARCOMSTR
11165 The string displayed when archiving files using the tar archiver.
11166 If this is not set, then $TARCOM (the command line) is displayed.
11167 env = Environment(TARCOMSTR = "Archiving $TARGET")
11169 TARFLAGS
11171 General options passed to the tar archiver.
11172 TARGET
11174 A reserved variable name that may not be set or used in a
11175 construction environment. (See the manpage section "Variable
11176 Substitution" for more information).
11177 TARGET_ARCH
11179 The name of the hardware architecture that objects created using
11180 this construction environment should target. Can be set when
11181 creating a construction environment by passing as a keyword
11182 argument in the Environment call.
11183 On the win32 platform, if the Microsoft Visual C++ compiler is
11185 available, msvc tool setup is done using $HOST_ARCH and
11186 $TARGET_ARCH. If a value is not specified, will be set to the same
11187 value as $HOST_ARCH. Changing the value after the environment is
11188 initialized will not cause the tool to be reinitialized. Compiled
11189 objects will be in the target architecture if the compilation
11190 system supports generating for that target. The latest compiler
11191 which can fulfill the requirement will be selected, unless a
11192 different version is directed by the value of the $MSVC_VERSION
11193 construction variable.
11194 On the win32/msvc combination, valid target arch values are x86,
11196 arm, i386 for 32-bit targets and amd64, arm64, x86_64 and ia64
11197 (Itanium) for 64-bit targets. For example, if you want to compile
11198 64-bit binaries, you would set TARGET_ARCH='x86_64' when creating
11199 the construction environment. Note that not all target
11200 architectures are supported for all Visual Studio / MSVC versions.
11201 Check the relevant Microsoft documentation.
11202 $TARGET_ARCH is not currently used by other compilation tools, but
11205 the option is reserved to do so in future
11206 TARGET_OS
11208 The name of the operating system that objects created using this
11209 construction environment should target. Can be set when creating a
11210 construction environment by passing as a keyword argument in the
11211 Environment call;.
11212 $TARGET_OS is not currently used by SCons but the option is
11215 reserved to do so in future
11216 TARGETS
11218 A reserved variable name that may not be set or used in a
11219 construction environment. (See the manpage section "Variable
11220 Substitution" for more information).
11221 TARSUFFIX
11223 The suffix used for tar file names.
11224 TEMPFILE
11226 A callable object used to handle overly long command line strings,
11227 since operations which call out to a shell will fail if the line is
11228 longer than the shell can accept. This tends to particularly impact
11229 linking. The tempfile object stores the command line in a temporary
11230 file in the appropriate format, and returns an alternate command
11231 line so the invoked tool will make use of the contents of the
11232 temporary file. If you need to replace the default tempfile object,
11233 the callable should take into account the settings of
11234 $MAXLINELENGTH, $TEMPFILEPREFIX, $TEMPFILESUFFIX, $TEMPFILEARGJOIN,
11235 $TEMPFILEDIR and $TEMPFILEARGESCFUNC.
11236 TEMPFILEARGESCFUNC
11238 The default argument escape function is SCons.Subst.quote_spaces.
11239 If you need to apply extra operations on a command argument (to fix
11240 Windows slashes, normalize paths, etc.) before writing to the
11241 temporary file, you can set the $TEMPFILEARGESCFUNC variable to a
11242 custom function. Such a function takes a single string argument and
11243 returns a new string with any modifications applied. Example:
11244 import sys
11246 import re
11247 from SCons.Subst import quote_spaces
11248 WINPATHSEP_RE = re.compile(r"\\([^\"'\\]|$)")
11250 def tempfile_arg_esc_func(arg):
11252 arg = quote_spaces(arg)
11253 if sys.platform != "win32":
11254 return arg
11255 # GCC requires double Windows slashes, let's use UNIX separator
11256 return WINPATHSEP_RE.sub(r"/\1", arg)
11257 env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func
11259 TEMPFILEARGJOIN
11261 The string to use to join the arguments passed to $TEMPFILE when
11262 the command line exceeds the limit set by $MAXLINELENGTH. The
11263 default value is a space. However for MSVC, MSLINK the default is a
11264 line separator as defined by os.linesep. Note this value is used
11265 literally and not expanded by the subst logic.
11266 TEMPFILEDIR
11268 The directory to create the long-lines temporary file in.
11269 TEMPFILEPREFIX
11271 The prefix for the name of the temporary file used to store command
11272 lines exceeding $MAXLINELENGTH. The default prefix is '@', which
11273 works for the Microsoft and GNU toolchains on Windows. Set this
11274 appropriately for other toolchains, for example '-@' for the diab
11275 compiler or '-via' for ARM toolchain.
11276 TEMPFILESUFFIX
11278 The suffix for the name of the temporary file used to store command
11279 lines exceeding $MAXLINELENGTH. The suffix should include the dot
11280 ('.') if one is wanted as it will not be added automatically. The
11281 default is .lnk.
11282 TEX
11284 The TeX formatter and typesetter.
11285 TEXCOM
11287 The command line used to call the TeX formatter and typesetter.
11288 TEXCOMSTR
11290 The string displayed when calling the TeX formatter and typesetter.
11291 If this is not set, then $TEXCOM (the command line) is displayed.
11292 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
11294 TEXFLAGS
11296 General options passed to the TeX formatter and typesetter.
11297 TEXINPUTS
11299 List of directories that the LaTeX program will search for include
11300 directories. The LaTeX implicit dependency scanner will search
11301 these directories for \include and \import files.
11302 TEXTFILEPREFIX
11304 The prefix used for Textfile file names, an empty string by
11305 default.
11306 TEXTFILESUFFIX
11308 The suffix used for Textfile file names; .txt by default.
11309 TOOLS
11311 A list of the names of the Tool specifications that are part of
11312 this construction environment.
11313 UNCHANGED_SOURCES
11315 A reserved variable name that may not be set or used in a
11316 construction environment. (See the manpage section "Variable
11317 Substitution" for more information).
11318 UNCHANGED_TARGETS
11320 A reserved variable name that may not be set or used in a
11321 construction environment. (See the manpage section "Variable
11322 Substitution" for more information).
11323 VENDOR
11325 The person or organization who supply the packaged software. This
11326 is used to fill in the Vendor: field in the controlling information
11327 for RPM packages, and the Manufacturer: field in the controlling
11328 information for MSI packages.
11329 See the Package builder.
11331 VERSION
11333 The version of the project, specified as a string.
11334 See the Package builder.
11336 VSWHERE
11338 Specify the location of vswhere.exe.
11339 The vswhere.exe executable is distributed with Microsoft Visual
11341 Studio and Build Tools since the 2017 edition, but is also
11342 available standalone. It provides full information about
11343 installations of 2017 and later editions. With the -legacy
11344 argument, vswhere.exe can detect installations of the 2010 through
11345 2015 editions with limited data returned. If VSWHERE is set, SCons
11346 will use that location.
11347 Otherwise SCons will look in the following locations and set
11349 VSWHERE to the path of the first vswhere.exe located.
11350 • %ProgramFiles(x86)%\Microsoft Visual Studio\Installer
11352 • %ProgramFiles%\Microsoft Visual Studio\Installer
11354 • %ChocolateyInstall%\bin
11356 Note that VSWHERE must be set at the same time or prior to any of
11358 msvc, msvs , and/or mslink Tool being initialized. Either set it as
11359 follows
11360 env = Environment(VSWHERE='c:/my/path/to/vswhere')
11362 or if your construction environment is created specifying an empty
11364 tools list (or a list of tools which omits all of default, msvs,
11365 msvc, and mslink), and also before env.Tool is called to
11366 ininitialize any of those tools:
11367 env = Environment(tools=[])
11369 env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
11370 env.Tool('msvc')
11371 env.Tool('mslink')
11372 env.Tool('msvs')
11373 WINDOWS_EMBED_MANIFEST
11377 Set to True to embed the compiler-generated manifest (normally
11378 ${TARGET}.manifest) into all Windows executables and DLLs built
11379 with this environment, as a resource during their link step. This
11380 is done using $MT and $MTEXECOM and $MTSHLIBCOM. See also
11381 $WINDOWS_INSERT_MANIFEST.
11382 WINDOWS_INSERT_DEF
11384 If set to true, a library build of a Windows shared library (.dll
11385 file) will include a reference to the corresponding
11386 module-definition file at the same time, if a module-definition
11387 file is not already listed as a build target. The name of the
11388 module-definition file will be constructed from the base name of
11389 the library and the construction variables $WINDOWSDEFSUFFIX and
11390 $WINDOWSDEFPREFIX. The default is to not add a module-definition
11391 file. The module-definition file is not created by this directive,
11392 and must be supplied by the developer.
11393 WINDOWS_INSERT_MANIFEST
11395 If set to true, scons will add the manifest file generated by
11396 Microsoft Visual C++ 8.0 and later to the target list so SCons will
11397 be aware they were generated. In the case of an executable, the
11398 manifest file name is constructed using $WINDOWSPROGMANIFESTSUFFIX
11399 and $WINDOWSPROGMANIFESTPREFIX. In the case of a shared library,
11400 the manifest file name is constructed using
11401 $WINDOWSSHLIBMANIFESTSUFFIX and $WINDOWSSHLIBMANIFESTPREFIX. See
11402 also $WINDOWS_EMBED_MANIFEST.
11403 WINDOWSDEFPREFIX
11405 The prefix used for a Windows linker module-definition file name.
11406 Defaults to empty.
11407 WINDOWSDEFSUFFIX
11409 The suffix used for a Windows linker module-definition file name.
11410 Defaults to .def.
11411 WINDOWSEXPPREFIX
11413 The prefix used for Windows linker exports file names. Defaults to
11414 empty.
11415 WINDOWSEXPSUFFIX
11417 The suffix used for Windows linker exports file names. Defaults to
11418 .exp.
11419 WINDOWSPROGMANIFESTPREFIX
11421 The prefix used for executable program manifest files generated by
11422 Microsoft Visual C/C++. Defaults to empty.
11423 WINDOWSPROGMANIFESTSUFFIX
11425 The suffix used for executable program manifest files generated by
11426 Microsoft Visual C/C++. Defaults to .manifest.
11427 WINDOWSSHLIBMANIFESTPREFIX
11429 The prefix used for shared library manifest files generated by
11430 Microsoft Visual C/C++. Defaults to empty.
11431 WINDOWSSHLIBMANIFESTSUFFIX
11433 The suffix used for shared library manifest files generated by
11434 Microsoft Visual C/C++. Defaults to .manifest.
11435 X_IPK_DEPENDS
11437 This is used to fill in the Depends: field in the controlling
11438 information for Ipkg packages.
11439 See the Package builder.
11441 X_IPK_DESCRIPTION
11443 This is used to fill in the Description: field in the controlling
11444 information for Ipkg packages. The default value is
11445 “$SUMMARY\n$DESCRIPTION”
11446 X_IPK_MAINTAINER
11448 This is used to fill in the Maintainer: field in the controlling
11449 information for Ipkg packages.
11450 X_IPK_PRIORITY
11452 This is used to fill in the Priority: field in the controlling
11453 information for Ipkg packages.
11454 X_IPK_SECTION
11456 This is used to fill in the Section: field in the controlling
11457 information for Ipkg packages.
11458 X_MSI_LANGUAGE
11460 This is used to fill in the Language: attribute in the controlling
11461 information for MSI packages.
11462 See the Package builder.
11464 X_MSI_LICENSE_TEXT
11466 The text of the software license in RTF format. Carriage return
11467 characters will be replaced with the RTF equivalent \\par.
11468 See the Package builder.
11470 X_MSI_UPGRADE_CODE
11472 TODO
11473 X_RPM_AUTOREQPROV
11475 This is used to fill in the AutoReqProv: field in the RPM .spec
11476 file.
11477 See the Package builder.
11479 X_RPM_BUILD
11481 internal, but overridable
11482 X_RPM_BUILDREQUIRES
11484 This is used to fill in the BuildRequires: field in the RPM .spec
11485 file. Note this should only be used on a host managed by rpm as the
11486 dependencies will not be resolvable at build time otherwise.
11487 X_RPM_BUILDROOT
11489 internal, but overridable
11490 X_RPM_CLEAN
11492 internal, but overridable
11493 X_RPM_CONFLICTS
11495 This is used to fill in the Conflicts: field in the RPM .spec file.
11496 X_RPM_DEFATTR
11498 This value is used as the default attributes for the files in the
11499 RPM package. The default value is “(-,root,root)”.
11500 X_RPM_DISTRIBUTION
11502 This is used to fill in the Distribution: field in the RPM .spec
11503 file.
11504 X_RPM_EPOCH
11506 This is used to fill in the Epoch: field in the RPM .spec file.
11507 X_RPM_EXCLUDEARCH
11509 This is used to fill in the ExcludeArch: field in the RPM .spec
11510 file.
11511 X_RPM_EXLUSIVEARCH
11513 This is used to fill in the ExclusiveArch: field in the RPM .spec
11514 file.
11515 X_RPM_EXTRADEFS
11517 A list used to supply extra defintions or flags to be added to the
11518 RPM .spec file. Each item is added as-is with a carriage return
11519 appended. This is useful if some specific RPM feature not otherwise
11520 anticipated by SCons needs to be turned on or off. Note if this
11521 variable is omitted, SCons will by default supply the value
11522 '%global debug_package %{nil}' to disable debug package generation.
11523 To enable debug package generation, include this variable set
11524 either to None, or to a custom list that does not include the
11525 default line. Added in version 3.1.
11526 env.Package(
11528 NAME="foo",
11529 ...
11530 X_RPM_EXTRADEFS=[
11531 "%define _unpackaged_files_terminate_build 0"
11532 "%define _missing_doc_files_terminate_build 0"
11533 ],
11534 ...
11535 )
11536 X_RPM_GROUP
11538 This is used to fill in the Group: field in the RPM .spec file.
11539 X_RPM_GROUP_lang
11541 This is used to fill in the Group(lang): field in the RPM .spec
11542 file. Note that lang is not literal and should be replaced by the
11543 appropriate language code.
11544 X_RPM_ICON
11546 This is used to fill in the Icon: field in the RPM .spec file.
11547 X_RPM_INSTALL
11549 internal, but overridable
11550 X_RPM_PACKAGER
11552 This is used to fill in the Packager: field in the RPM .spec file.
11553 X_RPM_POSTINSTALL
11555 This is used to fill in the %post: section in the RPM .spec file.
11556 X_RPM_POSTUNINSTALL
11558 This is used to fill in the %postun: section in the RPM .spec file.
11559 X_RPM_PREFIX
11561 This is used to fill in the Prefix: field in the RPM .spec file.
11562 X_RPM_PREINSTALL
11564 This is used to fill in the %pre: section in the RPM .spec file.
11565 X_RPM_PREP
11567 internal, but overridable
11568 X_RPM_PREUNINSTALL
11570 This is used to fill in the %preun: section in the RPM .spec file.
11571 X_RPM_PROVIDES
11573 This is used to fill in the Provides: field in the RPM .spec file.
11574 X_RPM_REQUIRES
11576 This is used to fill in the Requires: field in the RPM .spec file.
11577 X_RPM_SERIAL
11579 This is used to fill in the Serial: field in the RPM .spec file.
11580 X_RPM_URL
11582 This is used to fill in the Url: field in the RPM .spec file.
11583 XGETTEXT
11585 Path to xgettext(1) program (found via Detect()). See xgettext tool
11586 and POTUpdate builder.
11587 XGETTEXTCOM
11589 Complete xgettext command line. See xgettext tool and POTUpdate
11590 builder.
11591 XGETTEXTCOMSTR
11593 A string that is shown when xgettext(1) command is invoked
11594 (default: '', which means "print $XGETTEXTCOM"). See xgettext tool
11595 and POTUpdate builder.
11596 _XGETTEXTDOMAIN
11598 Internal "macro". Generates xgettext domain name form source and
11599 target (default: '${TARGET.filebase}').
11600 XGETTEXTFLAGS
11602 Additional flags to xgettext(1). See xgettext tool and POTUpdate
11603 builder.
11604 XGETTEXTFROM
11606 Name of file containing list of xgettext(1)'s source files.
11607 Autotools' users know this as POTFILES.in so they will in most
11608 cases set XGETTEXTFROM="POTFILES.in" here. The $XGETTEXTFROM files
11609 have same syntax and semantics as the well known GNU POTFILES.in.
11610 See xgettext tool and POTUpdate builder.
11611 _XGETTEXTFROMFLAGS
11613 Internal "macro". Genrates list of -D<dir> flags from the
11614 $XGETTEXTPATH list.
11615 XGETTEXTFROMPREFIX
11617 This flag is used to add single $XGETTEXTFROM file to xgettext(1)'s
11618 commandline (default: '-f').
11619 XGETTEXTFROMSUFFIX
11621 (default: '')
11622 XGETTEXTPATH
11624 List of directories, there xgettext(1) will look for source files
11625 (default: []).
11626 Note
11628 This variable works only together with $XGETTEXTFROM
11629 See also xgettext tool and POTUpdate builder.
11630 _XGETTEXTPATHFLAGS
11632 Internal "macro". Generates list of -f<file> flags from
11633 $XGETTEXTFROM.
11634 XGETTEXTPATHPREFIX
11636 This flag is used to add single search path to xgettext(1)'s
11637 commandline (default: '-D').
11638 XGETTEXTPATHSUFFIX
11640 (default: '')
11641 YACC
11643 The parser generator.
11644 YACC_GRAPH_FILE
11646 If supplied, write a graph of the automaton to a file with the name
11647 taken from this variable. Will be emitted as a --graph=
11648 command-line option. Use this in preference to including --graph=
11649 in $YACCFLAGS directly.
11650 YACC_HEADER_FILE
11652 If supplied, generate a header file with the name taken from this
11653 variable. Will be emitted as a --header= command-line option. Use
11654 this in preference to including --header= in $YACCFLAGS directly.
11655 YACCCOM
11657 The command line used to call the parser generator to generate a
11658 source file.
11659 YACCCOMSTR
11661 The string displayed when generating a source file using the parser
11662 generator. If this is not set, then $YACCCOM (the command line) is
11663 displayed.
11664 env = Environment(YACCCOMSTR="Yacc'ing $TARGET from $SOURCES")
11666 YACCFLAGS
11668 General options passed to the parser generator. In addition to
11669 passing the value on during invocation, the yacc tool also examines
11670 this construction variable for options which cause additional
11671 output files to be generated, and adds those to the target list.
11672 If a -d option is present, scons assumes that the call will also
11674 create a header file with the suffix defined by $YACCHFILESUFFIX if
11675 the yacc source file ends in a .y suffix, or a file with the suffix
11676 defined by $YACCHXXFILESUFFIX if the yacc source file ends in a .yy
11677 suffix.
11678 If a -g option is present, scons assumes that the call will also
11680 create a graph file with the suffix defined by $YACCVCGFILESUFFIX.
11681 If a -v option is present, scons assumes that the call will also
11683 create an output debug file with the suffix .output.
11684 Also recognized are GNU bison options --header= and its deprecated
11686 synonym --defines=, which is similar to -d but the output filename
11687 is named by the option argument; and --graph=, which is similar to
11688 -g but the output filename is named by the option argument.
11689 Note that files specified by --header= and --graph= may not be
11691 properly handled by SCons in all situations. Consider using
11692 $YACC_HEADER_FILE and $YACC_GRAPH_FILE instead.
11693 YACCHFILESUFFIX
11695 The suffix of the C header file generated by the parser generator
11696 when the -d option is used. Note that setting this variable does
11697 not cause the parser generator to generate a header file with the
11698 specified suffix, it exists to allow you to specify what suffix the
11699 parser generator will use of its own accord. The default value is
11700 .h.
11701 YACCHXXFILESUFFIX
11703 The suffix of the C++ header file generated by the parser generator
11704 when the -d option is used. Note that setting this variable does
11705 not cause the parser generator to generate a header file with the
11706 specified suffix, it exists to allow you to specify what suffix the
11707 parser generator will use of its own accord. The default value is
11708 .hpp, except on Mac OS X, where the default is ${TARGET.suffix}.h.
11709 because the default bison parser generator just appends .h to the
11710 name of the generated C++ file.
11711 YACCVCGFILESUFFIX
11713 The suffix of the file containing the VCG grammar automaton
11714 definition when the --graph= option is used. Note that setting this
11715 variable does not cause the parser generator to generate a VCG file
11716 with the specified suffix, it exists to allow you to specify what
11717 suffix the parser generator will use of its own accord. The default
11718 value is .vcg.
11719 ZIP
11721 The zip compression and file packaging utility.
11722 ZIP_OVERRIDE_TIMESTAMP
11724 An optional timestamp which overrides the last modification time of
11725 the file when stored inside the Zip archive. This is a tuple of six
11726 values: Year (>= 1980) Month (one-based) Day of month (one-based)
11727 Hours (zero-based) Minutes (zero-based) Seconds (zero-based)
11728 ZIPCOM
11730 The command line used to call the zip utility, or the internal
11731 Python function used to create a zip archive.
11732 ZIPCOMPRESSION
11734 The compression flag from the Python zipfile module used by the
11735 internal Python function to control whether the zip archive is
11736 compressed or not. The default value is zipfile.ZIP_DEFLATED, which
11737 creates a compressed zip archive. This value has no effect if the
11738 zipfile module is unavailable.
11739 ZIPCOMSTR
11741 The string displayed when archiving files using the zip utility. If
11742 this is not set, then $ZIPCOM (the command line or internal Python
11743 function) is displayed.
11744 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
11746 ZIPFLAGS
11748 General options passed to the zip utility.
11749 ZIPROOT
11751 An optional zip root directory (default empty). The filenames
11752 stored in the zip file will be relative to this directory, if
11753 given. Otherwise the filenames are relative to the current
11754 directory of the command. For instance:
11755 env = Environment()
11757 env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
11758 will produce a zip file foo.zip containing a file with the name
11760 subdir2/file1 rather than subdir1/subdir2/file1.
11761 ZIPSUFFIX
11763 The suffix used for zip file names.
11764 Configure Contexts
11766 SCons supports a configure context, an integrated mechanism similar to
11767 the various AC_CHECK macros in GNU Autoconf for testing the existence
11768 of external items needed for the build, such as C header files,
11769 libraries, etc. The mechanism is portable across platforms.
11770 scons does not maintain an explicit cache of the tested values (this is
11772 different than Autoconf), but uses its normal dependency tracking to
11773 keep the checked values up to date. However, users may override this
11774 behaviour with the --config command line option.
11775 Configure(env, [custom_tests, conf_dir, log_file, config_h, clean,
11777 help]), env.Configure([custom_tests, conf_dir, log_file, config_h,
11778 clean, help])
11779 Create a configure context, which tracks information discovered
11780 while running tests. The context includes a local construction
11781 environment (available as context.env) which is used when running
11782 the tests and which can be updated with the check results. Only one
11783 context may be active at a time (since 4.0, scons will raise an
11784 exception on an attempt to create a new context when there is an
11785 active context), but a new context can be created after the active
11786 one is completed. For the global function form, the required env
11787 describes the initial values for the context's local construction
11788 environment; for the construction environment method form the
11789 instance provides the values.
11790 custom_tests specifies a dictionary containing custom tests (see
11792 the section on custom tests below). The default value is None,
11793 meaning no custom tests are added to the configure context.
11794 conf_dir specifies a directory where the test cases are built. This
11797 directory is not used for building normal targets. The default
11798 value is “#/.sconf_temp”.
11799 log_file specifies a file which collects the output from commands
11802 that are executed to check for the existence of header files,
11803 libraries, etc. The default is “#/config.log”. If you are using the
11804 VariantDir function, you may want to specify a subdirectory under
11805 your variant directory.
11806 config_h specifies a C header file where the results of tests will
11809 be written. The results will consist of lines like #define
11810 HAVE_STDIO_H, #define HAVE_LIBM, etc. Customarily, the name chosen
11811 is “config.h”. The default is to not write a config_h file. You can
11812 specify the same config_h file in multiple calls to Configure, in
11813 which case SCons will concatenate all results in the specified
11814 file. Note that SCons uses its normal dependency checking to decide
11815 if it's necessary to rebuild the specified config_h file. This
11816 means that the file is not necessarily re-built each time scons is
11817 run, but is only rebuilt if its contents will have changed and some
11818 target that depends on the config_h file is being built.
11819 The clean and help arguments can be used to suppress execution of
11821 the configuration tests when the -c/--clean or -H/-h/--help options
11822 are used, respectively. The default behavior is always to execute
11823 configure context tests, since the results of the tests may affect
11824 the list of targets to be cleaned or the help text. If the
11825 configure tests do not affect these, then you may add the
11826 clean=False or help=False arguments (or both) to avoid unnecessary
11827 test execution.
11828 context.Finish()
11830 This method must be called after configuration is done. Though
11831 required, this is not enforced except if Configure is called again
11832 while there is still an active context, in which case an exception
11833 is raised. Finish returns the environment as modified during the
11834 course of running the configuration checks. After this method is
11835 called, no further checks can be performed with this configuration
11836 context. However, you can create a new configure context to perform
11837 additional checks.
11838 Example of a typical Configure usage:
11840 env = Environment()
11842 conf = Configure(env)
11843 if not conf.CheckCHeader("math.h"):
11844 print("We really need math.h!")
11845 Exit(1)
11846 if conf.CheckLibWithHeader("qt", "qapp.h", "c++", "QApplication qapp(0,0);"):
11847 # do stuff for qt - usage, e.g.
11848 conf.env.Append(CPPDEFINES="WITH_QT")
11849 env = conf.Finish()
11850 A configure context has the following predefined methods which can be
11852 used to perform checks. Where language is a required or optional
11853 parameter, the choice can currently be C or C++. The spellings accepted
11854 for C are “C” or “c”; for C++ the value can be “CXX”, “cxx”, “C++” or
11855 “c++”.
11856 context.CheckHeader(header, [include_quotes, language])
11858 Checks if header is usable in the specified language. header may
11859 be a list, in which case the last item in the list is the header
11860 file to be checked, and the previous list items are header files
11861 whose #include lines should precede the header line being checked
11862 for. The optional argument include_quotes must be a two character
11863 string, where the first character denotes the opening quote and the
11864 second character denotes the closing quote. By default, both
11865 characters are " (double quote). The optional argument language
11866 should be either C or C++ and selects the compiler to be used for
11867 the check. Returns a boolean indicating success or failure.
11868 context.CheckCHeader(header, [include_quotes])
11870 Checks if header is usable when compiling a C language program.
11871 header may be a list, in which case the last item in the list is
11872 the header file to be checked, and the previous list items are
11873 header files whose #include lines should precede the header line
11874 being checked for. The optional argument include_quotes must be a
11875 two character string, where the first character denotes the opening
11876 quote and the second character denotes the closing quote. By
11877 default, both characters are " (double quote). Note this is a
11878 wrapper around CheckHeader. Returns a boolean indicating success or
11879 failure.
11880 context.CheckCXXHeader(header, [include_quotes])
11882 Checks if header is usable when compiling a C++ language program.
11883 header may be a list, in which case the last item in the list is
11884 the header file to be checked, and the previous list items are
11885 header files whose #include lines should precede the header line
11886 being checked for. The optional argument include_quotes must be a
11887 two character string, where the first character denotes the opening
11888 quote and the second character denotes the closing quote. By
11889 default, both characters are " (double quote). Note this is a
11890 wrapper around CheckHeader. Returns a boolean indicating success or
11891 failure.
11892 context.CheckFunc(function_name, [header, language])
11894 Checks if the specified C or C++ library function is available
11895 based on the context's local environment settings (that is, using
11896 the values of $CFLAGS, $CPPFLAGS, $LIBS or other relevant
11897 construction variables).
11898 function_name is the name of the function to check for. The
11901 optional header argument is a string that will be placed at the top
11902 of the test file that will be compiled to check if the function
11903 exists; the default is:
11904 #ifdef __cplusplus
11906 extern "C"
11907 #endif
11908 char function_name();
11909 Returns an empty string on success, a string containing an error
11911 message on failure.
11912 context.CheckLib([library, symbol, header, language, autoadd=True])
11914 Checks if library provides symbol. If autoadd is true (the default)
11915 and the library provides the specified symbol, appends the library
11916 to the LIBS construction variable library may also be None (the
11917 default), in which case symbol is checked with the current LIBS
11918 variable, or a list of library names, in which case each library in
11919 the list will be checked for symbol. If symbol is not set or is
11920 None, then CheckLib just checks if you can link against the
11921 specified library. Note though it is legal syntax, it would not be
11922 very useful to call this method with library and symbol both
11923 omitted or None. Returns a boolean indicating success or failure.
11924 context.CheckLibWithHeader(library, header, language, [call,
11926 autoadd=True])
11927 Provides a more sophisticated way to check against libraries then
11928 the CheckLib call. library specifies the library or a list of
11929 libraries to check. header specifies a header to check for.
11930 header may be a list, in which case the last item in the list is
11931 the header file to be checked, and the previous list items are
11932 header files whose #include lines should precede the header line
11933 being checked for. call can be any valid expression (with a
11934 trailing ';'). If call is not set, the default simply checks that
11935 you can link against the specified library. autoadd (default true)
11936 specifies whether to add the library to the environment if the
11937 check succeeds. Returns a boolean indicating success or failure.
11938 context.CheckType(type_name, [includes, language])
11940 Checks for the existence of a type defined by typedef. type_name
11941 specifies the typedef name to check for. includes is a string
11942 containing one or more #include lines that will be inserted into
11943 the program that will be run to test for the existence of the type.
11944 Example:
11945 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
11947 Returns an empty string on success, a string containing an error
11949 message on failure.
11950 context.CheckTypeSize(type_name, [header, language, expect])
11952 Checks for the size of a type defined by typedef. type_name
11953 specifies the typedef name to check for. The optional header
11954 argument is a string that will be placed at the top of the test
11955 file that will be compiled to check if the type exists; the default
11956 is empty. If the optional expect, is supplied, it should be an
11957 integer size; CheckTypeSize will fail unless type_name is actually
11958 that size. Returns the size in bytes, or zero if the type was not
11959 found (or if the size did not match expect).
11960 For example,
11962 CheckTypeSize('short', expect=2)
11964 will return the size 2 only if short is actually two bytes.
11966 context.CheckCC()
11968 Checks whether the C compiler (as defined by the $CC construction
11969 variable) works, by trying to compile a small source file. This
11970 provides a more rigorous check: by default, SCons itself only
11971 detects if there is a program with the correct name, not if it is a
11972 functioning compiler. Returns a boolean indicating success or
11973 failure.
11974 The test program will be built with the same command line as the
11976 one used by the Object builder for C source files, so by setting
11977 relevant construction variables it can be used to detect if
11978 particular compiler flags will be accepted or rejected by the
11979 compiler.
11980 context.CheckCXX()
11982 Checks whether the C++ compiler (as defined by the $CXX
11983 construction variable) works, by trying to compile a small source
11984 file. This provides a more rigorous check: by default, SCons itself
11985 only detects if there is a program with the correct name, not if it
11986 is a functioning compiler. Returns a boolean indicating success or
11987 failure.
11988 The test program will be built with the same command line as the
11990 one used by the Object builder for C++ source files, so by setting
11991 relevant construction variables it can be used to detect if
11992 particular compiler flags will be accepted or rejected by the
11993 compiler.
11994 context.CheckSHCC()
11996 Checks whether the shared-object C compiler (as defined by the
11997 $SHCC construction variable) works by trying to compile a small
11998 source file. This provides a more rigorous check: by default, SCons
11999 itself only detects if there is a program with the correct name,
12000 not if it is a functioning compiler. Returns a boolean indicating
12001 success or failure.
12002 The test program will be built with the same command line as the
12004 one used by the SharedObject builder for C source files, so by
12005 setting relevant construction variables it can be used to detect if
12006 particular compiler flags will be accepted or rejected by the
12007 compiler. Note this does not check whether a shared library/dll can
12008 be created.
12009 context.CheckSHCXX()
12011 Checks whether the shared-object C++ compiler (as defined by the
12012 $SHCXX construction variable) works by trying to compile a small
12013 source file. This provides a more rigorous check: by default, SCons
12014 itself only detects if there is a program with the correct name,
12015 not if it is a functioning compiler. Returns a boolean indicating
12016 success or failure.
12017 The test program will be built with the same command line as the
12019 one used by the SharedObject builder for C++ source files, so by
12020 setting relevant construction variables it can be used to detect if
12021 particular compiler flags will be accepted or rejected by the
12022 compiler. Note this does not check whether a shared library/dll can
12023 be created.
12024 context.CheckProg(prog_name)
12026 Checks if prog_name exists in the path SCons will use at build
12027 time. (context.env['ENV']['PATH']). Returns a string containing the
12028 path to the program, or None on failure.
12029 context.CheckDeclaration(symbol, [includes, language])
12031 Checks if the specified symbol is declared. includes is a string
12032 containing one or more #include lines that will be inserted into
12033 the program that will be run to test for the existence of the
12034 symbol. Returns a boolean indicating success or failure.
12035 context.CheckMember(aggregate_member, [header, language])
12037 Checks for the existence of a member of the C/C++ struct or class.
12038 aggregate_member specifies the struct/class and member to check
12039 for. header is a string containing one or more #include lines that
12040 will be inserted into the program that will be run to test for the
12041 existence of the member. Example:
12042 sconf.CheckMember('struct tm.tm_sec', '#include <time.h>')
12044 Returns a boolean indicating success or failure.
12047 context.Define(symbol, [value, comment])
12049 This method does not check for anything, but rather forces the
12050 definition of a preprocessor macro that will be added to the
12051 configuration header file. name is the macro's identifier. If
12052 value is given, it will be be used as the macro replacement value.
12053 If value is a string and needs to display with quotes, the quotes
12054 need to be included, as in '"string"' If the optional comment is
12055 given, it is inserted as a comment above the macro definition
12056 (suitable comment marks will be added automatically). This is
12057 analogous to using AC_DEFINE in Autoconf.
12058 Examples:
12060 env = Environment()
12062 conf = Configure(env)
12063 # Puts the following line in the config header file:
12065 # #define A_SYMBOL
12066 conf.Define("A_SYMBOL")
12067 # Puts the following line in the config header file:
12069 # #define A_SYMBOL 1
12070 conf.Define("A_SYMBOL", 1)
12071 Examples of quoting string values:
12073 env = Environment()
12075 conf = Configure(env)
12076 # Puts the following line in the config header file:
12078 # #define A_SYMBOL YA
12079 conf.Define("A_SYMBOL", "YA")
12080 # Puts the following line in the config header file:
12082 # #define A_SYMBOL "YA"
12083 conf.Define("A_SYMBOL", '"YA"')
12084 Example including comment:
12086 env = Environment()
12088 conf = Configure(env)
12089 # Puts the following lines in the config header file:
12091 # /* Set to 1 if you have a symbol */
12092 # #define A_SYMBOL 1
12093 conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol")
12094 You can define your own custom checks in addition to using the
12096 predefined checks. To enable custom checks, pass a dictionary to the
12097 Configure function as the custom_tests parameter. The dictionary maps
12098 the names of the checks to the custom check callables (either a Python
12099 function or an instance of a class implementing a __call__ method).
12100 Each custom check will be called with a a CheckContext instance as the
12101 first parameter followed by the remaining arguments, which must be
12102 supplied by the user of the check. A CheckContext is not the same as a
12103 configure context; rather it is an instance of a class which contains a
12104 configure context (available as chk_ctx.sconf). A CheckContext provides
12105 the following methods which custom checks can make use of::
12106 chk_ctx.Message(text)
12108 Displays text as an indicator of progess. For example: Checking for
12109 library X.... Usually called before the check is started.
12110 chk_ctx.Result(res)
12112 Displays a result message as an indicator of progress. If res is an
12113 integer, displays yes if res evaluates true or no if false. If res
12114 is a string, it is displayed as-is. Usually called after the check
12115 has completed.
12116 chk_ctx.TryCompile(text, extension='')
12118 Checks if a file containing text and given the specified extension
12119 (e.g. '.c') can be compiled to an object file using the
12120 environment's Object builder. Returns a boolean indicating success
12121 or failure.
12122 chk_ctx.TryLink(text, extension='')
12124 Checks if a file containing text and given the specified extension
12125 (e.g. '.c') can be compiled to an executable program using the
12126 environment's Program builder. Returns a boolean indicating success
12127 or failure.
12128 chk_ctx.TryRun(text, extension='')
12130 Checks if a file containing text and given the specified extension
12131 (e.g. '.c') can be compiled to an excutable program using the
12132 environment's Program builder and subsequently executed. Execution
12133 is only attempted if the build succeeds. If the program executes
12134 successfully (that is, its return status is 0), a tuple (True,
12135 outputStr) is returned, where outputStr is the standard output of
12136 the program. If the program fails execution (its return status is
12137 non-zero), then (False, '') is returned.
12138 chk_ctx.TryAction(action, [text, extension=''])
12140 Checks if the specified action with an optional source file
12141 (contents text, given extension extension) can be executed. action
12142 may be anything which can be converted to an Action Object. On
12143 success, a tuple (True, outputStr) is returned, where outputStr is
12144 the content of the target file. On failure (False, '') is returned.
12145 chk_ctx.TryBuild(builder, [text, extension=''])
12147 Low level implementation for testing specific builds; the methods
12148 above are based on this method. Given the Builder instance builder
12149 and the optional text of a source file with optional extension,
12150 returns a boolean indicating success or failure. In addition,
12151 chk_ctx.lastTarget is set to the build target node if the build was
12152 successful.
12153 Example of implementing and using custom tests:
12155 def CheckQt(chk_ctx, qtdir):
12157 chk_ctx.Message('Checking for qt ...')
12158 lastLIBS = chk_ctx.env['LIBS']
12159 lastLIBPATH = chk_ctx.env['LIBPATH']
12160 lastCPPPATH = chk_ctx.env['CPPPATH']
12161 chk_ctx.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include')
12162 ret = chk_ctx.TryLink(
12163 """\
12164 #include <qapp.h>
12165 int main(int argc, char **argv) {
12166 QApplication qapp(argc, argv);
12167 return 0;
12168 }
12169 """
12170 )
12171 if not ret:
12172 chkctx.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
12173 chkctx.Result(ret)
12174 return ret
12175 env = Environment()
12177 conf = Configure(env, custom_tests={'CheckQt': CheckQt})
12178 if not conf.CheckQt('/usr/lib/qt'):
12179 print('We really need qt!')
12180 Exit(1)
12181 env = conf.Finish()
12182 Command-Line Construction Variables
12184 Often when building software, some variables need to be specified at
12185 build time. For example, libraries needed for the build may be in
12186 non-standard locations, or site-specific compiler options may need to
12187 be passed to the compiler. SCons provides a Variables object to
12188 support overriding construction variables with values obtained from
12189 various sources, often from the command line:
12190 scons VARIABLE=foo
12192 The variable values can also be specified in a configuration file or an
12194 SConscript file.
12195 To obtain the object for manipulating values, call the Variables
12197 function:
12198 Variables([files, [args]])
12200 If files is a file or list of files, they are executed as Python
12201 scripts, and the values of (global) Python variables set in those
12202 files are added as construction variables in the Default
12203 Environment. If no files are specified, or the files argument is
12204 None, then no files will be read (supplying None is necessary if
12205 there are no files but you want to specify args as a positional
12206 argument).
12207 The following example file contents could be used to set an
12209 alternative C compiler:
12210 CC = 'my_cc'
12212 If args is specified, it is a dictionary of values that will
12214 override anything read from files. The primary use is to pass the
12215 ARGUMENTS dictionary that holds variables specified on the command
12216 line, allowing you to indicate that if a setting appears on both
12217 the command line and in the file(s), the command line setting takes
12218 precedence. However, any dictionary can be passed. Examples:
12219 vars = Variables('custom.py')
12221 vars = Variables('overrides.py', ARGUMENTS)
12222 vars = Variables(None, {FOO:'expansion', BAR:7})
12223 Calling Variables with no arguments is equivalent to:
12225 vars = Variables(files=None, args=ARGUMENTS)
12227 Note that since the variables are eventually added as construction
12229 variables, you should choose variable names which do not
12230 unintentionally change pre-defined construction variables that your
12231 project will make use of (see the section called “Construction
12232 Variables”).
12233 Variables objects have the following methods:
12235 vars.Add(key, [help, default, validator, converter])
12237 Add a customizable construction variable to the Variables object.
12238 key is either the name of the variable, or a tuple (or list), in
12239 which case the first item in the tuple is taken as the variable
12240 name, and any remaining values are considered aliases for the
12241 variable. help is the help text for the variable (default empty
12242 string). default is the default value of the variable (default
12243 None). If default is None and a value is not specified, the
12244 construction variable will not be added to the construction
12245 environment.
12246 As a special case, if key is a tuple (or list) and is the only
12248 argument, the tuple is unpacked into the five parameters listed
12249 above left to right, with any missing members filled with the
12250 respecitive default values. This form allows Add to consume a tuple
12251 emitted by the convenience functions BoolVariable, EnumVariable,
12252 ListVariable, PackageVariable and PathVariable.
12253 If the optional validator is supplied, it is called to validate the
12255 value of the variable. A function supplied as a validator must
12256 accept three arguments: key, value and env, and should raise an
12257 exception with a helpful error message if value is invalid. No
12258 return value is expected from the validator.
12259 If the optional converter is supplied, it is called to convert the
12261 value before putting it in the environment, and should take either
12262 a value or a value and environment as parameters. The converter
12263 function must return a value, which will be converted into a string
12264 and be passed to the validator (if any) and then added to the
12265 construction environment.
12266 Examples:
12268 vars.Add('CC', help='The C compiler')
12270 def valid_color(key, val, env):
12272 if not val in ['red', 'blue', 'yellow']:
12273 raise Exception("Invalid color value '%s'" % val)
12274 vars.Add('COLOR', validator=valid_color)
12276 vars.AddVariables(args)
12278 A convenience method that adds one or more customizable
12279 construction variables to a Variables object in one call;
12280 equivalent to calling Add multiple times. The args are tuples (or
12281 lists) that contain the arguments for an individual call to the Add
12282 method. Since tuples are not Python mappings, the arguments cannot
12283 use the keyword form, but rather are positional arguments as
12284 documented for Add: a required name, the other four optional, but
12285 must be in the specified order if used.
12286 opt.AddVariables(
12288 ("debug", "", 0),
12289 ("CC", "The C compiler"),
12290 ("VALIDATE", "An option for testing validation", "notset", validator, None),
12291 )
12292 vars.Update(env, [args])
12294 Update a construction environment env with the customized
12295 construction variables. Any specified variables that are not
12296 configured for the Variables object will be saved and may be
12297 retrieved using the UnknownVariables method.
12298 Normally this method is not called directly, but rather invoked
12300 indirectly by passing the Variables object to the Environment
12301 function:
12302 env = Environment(variables=vars)
12304 vars.UnknownVariables()
12306 Returns a dictionary containing any variables that were specified
12307 either in the files or the dictionary with which the Variables
12308 object was initialized, but for which the Variables object was not
12309 configured.
12310 env = Environment(variables=vars)
12312 for key, value in vars.UnknownVariables():
12313 print("unknown variable: %s=%s" % (key, value))
12314 vars.Save(filename, env)
12316 Save the currently set variables into a script file named by
12317 filename. Only variables that are set to non-default values are
12318 saved. You can load these saved settings on a subsequent run by
12319 passing filename to the Variables function, providing a way to
12320 cache particular settings for reuse.
12321 env = Environment()
12323 vars = Variables(['variables.cache', 'custom.py'])
12324 vars.Add(...)
12325 vars.Update(env)
12326 vars.Save('variables.cache', env)
12327 vars.GenerateHelpText(env, [sort])
12329 Generate help text documenting the customizable construction
12330 variables, suitable for passing in to the Help function. env is
12331 the construction environment that will be used to get the actual
12332 values of the customizable variables. If the (optional) value of
12333 sort is callable, it is used as a comparison function to determine
12334 how to sort the added variables. This function must accept two
12335 arguments, compare them, and return a negative integer if the first
12336 is less-than the second, zero for equality, or a positive integer
12337 for greater-than. Optionally a Boolean value of True for sort will
12338 cause a standard alphabetical sort to be performed.
12339 Help(vars.GenerateHelpText(env))
12341 def cmp(a, b):
12343 return (a > b) - (a < b)
12344 Help(vars.GenerateHelpText(env, sort=cmp))
12346 vars.FormatVariableHelpText(env, opt, help, default, actual)
12348 Returns a formatted string containing the printable help text for
12349 one option. It is normally not called directly, but is called by
12350 the GenerateHelpText method to create the returned help text. It
12351 may be overridden with your own function that takes the arguments
12352 specified above and returns a string of help text formatted to your
12353 liking. Note that GenerateHelpText will not put any blank lines or
12354 extra characters in between the entries, so you must add those
12355 characters to the returned string if you want the entries
12356 separated.
12357 def my_format(env, opt, help, default, actual):
12359 fmt = "\n%s: default=%s actual=%s (%s)\n"
12360 return fmt % (opt, default, actual, help)
12361 vars.FormatVariableHelpText = my_format
12363 To make it more convenient to work with customizable Variables, scons
12365 provides a number of functions that make it easy to set up various
12366 types of Variables. Each of these return a tuple ready to be passed to
12367 the Add or AddVariables method:
12368 BoolVariable(key, help, default)
12370 Returns a tuple of arguments to set up a Boolean option. The option
12371 will use the specified name key, have a default value of default,
12372 and help will form the descriptive part of the help text. The
12373 option will interpret the values y, yes, t, true, 1, on and all as
12374 true, and the values n, no, f, false, 0, off and none as false.
12375 EnumVariable(key, help, default, allowed_values, [map, ignorecase])
12377 Returns a tuple of arguments to set up an option whose value may be
12378 one of a specified list of legal enumerated values. The option will
12379 use the specified name key, have a default value of default, and
12380 help will form the descriptive part of the help text. The option
12381 will only support those values in the allowed_values list. The
12382 optional map argument is a dictionary that can be used to convert
12383 input values into specific legal values in the allowed_values list.
12384 If the value of ignore_case is 0 (the default), then the values are
12385 case-sensitive. If the value of ignore_case is 1, then values will
12386 be matched case-insensitively. If the value of ignore_case is 2,
12387 then values will be matched case-insensitively, and all input
12388 values will be converted to lower case.
12389 ListVariable(key, help, default, names, [map])
12391 Returns a tuple of arguments to set up an option whose value may be
12392 one or more of a specified list of legal enumerated values. The
12393 option will use the specified name key, have a default value of
12394 default, and help will form the descriptive part of the help text.
12395 The option will only accept the values “all”, “none”, or the values
12396 in the names list. More than one value may be specified, separated
12397 by commas. The default may be a string of comma-separated default
12398 values, or a list of the default values. The optional map argument
12399 is a dictionary that can be used to convert input values into
12400 specific legal values in the names list. (Note that the additional
12401 values accepted through the use of a map are not reflected in the
12402 generated help message).
12403 PackageVariable(key, help, default)
12405 Returns a tuple of arguments to set up an option whose value is a
12406 path name of a package that may be enabled, disabled or given an
12407 explicit path name. The option will use the specified name key,
12408 have a default value of default, and help will form the descriptive
12409 part of the help text. The option will support the values yes,
12410 true, on, enable or search, in which case the specified default
12411 will be used, or the option may be set to an arbitrary string
12412 (typically the path name to a package that is being enabled). The
12413 option will also support the values no, false, off or disable to
12414 disable use of the specified option.
12415 PathVariable(key, help, default, [validator])
12417 Returns a tuple of arguments to set up an option whose value is
12418 expected to be a path name. The option will use the specified name
12419 key, have a default value of default, and help will form the
12420 descriptive part of the help text. An additional validator may be
12421 specified that will be called to verify that the specified path is
12422 acceptable. SCons supplies the following ready-made validators:
12423 PathVariable.PathExists
12425 Verify that the specified path exists (this the default
12426 behavior if no validator is supplied).
12427 PathVariable.PathIsFile
12429 Verify that the specified path exists and is a regular file.
12430 PathVariable.PathIsDir
12432 Verify that the specified path exists and is a directory.
12433 PathVariable.PathIsDirCreate
12435 Verify that the specified path exists and is a directory; if it
12436 does not exist, create the directory.
12437 PathVariable.PathAccept
12439 Accept the specific path name argument without validation,
12440 suitable for when you want your users to be able to specify a
12441 directory path that will be created as part of the build
12442 process, for example.
12443 You may supply your own validator function, which must accept three
12445 arguments (key, the name of the variable to be set; val, the
12446 specified value being checked; and env, the construction
12447 environment) and should raise an exception if the specified value
12448 is not acceptable.
12449 These functions make it convenient to create a number of variables with
12451 consistent behavior in a single call to the AddVariables method:
12452 vars.AddVariables(
12454 BoolVariable(
12455 "warnings",
12456 help="compilation with -Wall and similar",
12457 default=1,
12458 ),
12459 EnumVariable(
12460 "debug",
12461 help="debug output and symbols",
12462 default="no",
12463 allowed_values=("yes", "no", "full"),
12464 map={},
12465 ignorecase=0, # case sensitive
12466 ),
12467 ListVariable(
12468 "shared",
12469 help="libraries to build as shared libraries",
12470 default="all",
12471 names=list_of_libs,
12472 ),
12473 PackageVariable(
12474 "x11",
12475 help="use X11 installed here (yes = search some places)",
12476 default="yes",
12477 ),
12478 PathVariable(
12479 "qtdir",
12480 help="where the root of Qt is installed",
12481 default=qtdir),
12482 PathVariable(
12483 "foopath",
12484 help="where the foo library is installed",
12485 default=foopath,
12486 validator=PathVariable.PathIsDir,
12487 ),
12488 )
12489 Node Objects
12491 SCons represents objects that are the sources or targets of build
12492 operations as Nodes, which are internal data structures. There are a
12493 number of user-visible types of nodes: File Nodes, Directory Nodes,
12494 Value Nodes and Alias Nodes. Some of the node types have public
12495 attributes and methods, described below. Each of the node types has a
12496 global function and a matching environment method to create instances:
12497 File, Dir, Value and Alias.
12498 Filesystem Nodes
12500 The File and Dir functions/methods return File and Directory Nodes,
12501 respectively. File and Directory Nodes (collectively, Filesystem
12502 Nodes) represent build components that correspond to an entry in
12503 the computer's filesystem, whether or not such an entry exists at
12504 the time the Node is created. You do not usually need to explicitly
12505 create filesystem Nodes, since when you supply a string as a target
12506 or source of a Builder, SCons will create the Nodes as needed to
12507 populate the dependency graph. Builders return the target Node(s)
12508 in the form of a list, which you can then make use of. However,
12509 since filesystem Nodes have some useful public attributes and
12510 methods that you can use in SConscript files, it is sometimes
12511 appropriate to create them manually, outside the regular context of
12512 a Builder call.
12513 The following attributes provide information about a Node:
12515 node.path
12517 The build path of the given file or directory. This path is
12518 relative to the top-level directory (where the SConstruct file
12519 is found). The build path is the same as the source path if
12520 variant_dir is not being used.
12521 node.abspath
12523 The absolute build path of the given file or directory.
12524 node.relpath
12526 The build path of the given file or directory relative to the
12527 root SConstruct file's directory.
12528 node.srcnode()
12530 The srcnode method returns another File or Directory Node
12531 representing the source path of the given File or Directory
12532 Node.
12533 Examples:
12535 # Get the current build dir's path, relative to top.
12537 Dir('.').path
12538 # Current dir's absolute path
12540 Dir('.').abspath
12541 # Current dir's path relative to the root SConstruct file's directory
12543 Dir('.').relpath
12544 # Next line is always '.', because it is the top dir's path relative to itself.
12546 Dir('#.').path
12547 # Source path of the given source file.
12549 File('foo.c').srcnode().path
12550 # Builders return lists of File objects:
12552 foo = env.Program('foo.c')
12553 print("foo will be built in", foo[0].path)
12554 Filesystem Node objects have methods to create new File and
12556 Directory Nodes relative to the original Node. There are also times
12557 when you may need to refer to an entry in a filesystem without
12558 knowing in advance whether it's a file or a directory. For those
12559 situations, there is an Entry method of filesystem node objects,
12560 which returns a Node that can represent either a file or a
12561 directory.
12562 If the original Node is a Directory Node, these methods will place
12564 the new Node within the directory the original Node represents:
12565 node.Dir(name)
12567 Returns a directory Node name which is a subdirectory of the
12568 directory represented by node.
12569 node.File(name)
12571 Returns a file Node name in the directory represented by node.
12572 node.Entry(name)
12574 Returns an unresolved Node name in the directory represented by
12575 node.
12576 If the original Node is a File Node, these methods will place the
12578 the new Node in the same directory as the one the original Node
12579 represents:
12580 node.Dir(name)
12582 Returns a Node name for a directory in the parent directory of
12583 the file represented by node.
12584 node.File(name)
12586 Returns a Node name for a file in the parent directory of the
12587 file represented by node.
12588 node.Entry(name)
12590 Returns an unresolved Node name in the parent directory of the
12591 file represented by node.
12592 For example:
12594 # Get a Node for a file within a directory
12596 incl = Dir('include')
12597 f = incl.File('header.h')
12598 # Get a Node for a subdirectory within a directory
12600 dist = Dir('project-3.2.1')
12601 src = dist.Dir('src')
12602 # Get a Node for a file in the same directory
12604 cfile = File('sample.c')
12605 hfile = cfile.File('sample.h')
12606 # Combined example
12608 docs = Dir('docs')
12609 html = docs.Dir('html')
12610 index = html.File('index.html')
12611 css = index.File('app.css')
12612 Value and Alias Nodes
12614 SCons provides two other Node types to represent object that will
12615 not have an equivalent filesystem entry. Such Nodes always need to
12616 be created explicitly.
12617 The Alias method returns an Alias Node. Aliases are virtual objects
12619 - they will not themselves result in physical objects being
12620 constructed, but are entered into the dependency graph related to
12621 their sources. An alias is checked for up to date by checking if
12622 its sources are up to date. An alias is built by making sure its
12623 sources have been built, and if any building took place, applying
12624 any Actions that are defined as part of the alias.
12625 An Alias call creates an entry in the alias namespace, which is
12627 used for disambiguation. If an alias source has a string valued
12628 name, it will be resolved to a filesystem entry Node, unless it is
12629 found in the alias namespace, in which case it it resolved to the
12630 matching alias Node. As a result, the order of Alias calls is
12631 significant. An alias can refer to another alias, but only if the
12632 other alias has previously been created.
12633 The Value method returns a Value Node. Value nodes are often used
12635 for generated data that will not have any corresponding filesystem
12636 entry, but will be used to determine whether a build target is out
12637 of date, or to include as part of a build Action. Common examples
12638 are timestamp strings, revision control version strings and other
12639 run-time generated strings.
12640 A Value Node can also be the target of a builder.
12642
12644 SCons is designed to be extensible through provided facilities, so
12645 changing the code of SCons itself is only rarely needed to customize
12646 its behavior. A number of the main operations use callable objects
12647 which can be supplemented by writing your own. Builders, Scanners and
12648 Tools each use a kind of plugin system, allowing you to easily drop in
12649 new ones. Information about creating Builder Objects and Scanner
12650 Objects appear in the following sections. The instructions SCons
12651 actually uses to construct things are called Actions, and it is easy to
12652 create Action Objects and hand them to the objects that need to know
12653 about those actions (besides Builders, see AddPostAction, AddPreAction
12654 and Alias for some examples of other places that take Actions). Action
12655 Objects are also described below. Adding new Tool modules is described
12656 in Tool Modules
12657 Builder Objects
12659 scons can be extended to build different types of targets by adding new
12660 Builder objects to a construction environment. In general, you should
12661 only need to add a new Builder object when you want to build a new type
12662 of file or other external target. For output file types scons already
12663 knows about, you can usually modify the behavior of premade Builders
12664 such as Program, Object or Library by changing the construction
12665 variables they use ($CC, $LINK, etc.). In this manner you can, for
12666 example, change the compiler to use, which is simpler and less
12667 error-prone than writing a new builder. The documentation for each
12668 Builder lists which construction variables it uses.
12669 Builder objects are created using the Builder factory function. Once
12671 created, a builder is added to an environment by entering it in the
12672 $BUILDERS dictionary in that environment (some of the examples in this
12673 section illustrate this). Doing so automatically triggers SCons to add
12674 a method with the name of the builder to the environment.
12675 The Builder function accepts the following keyword arguments:
12677 action
12679 The command used to build the target from the source. action may
12680 be a string representing a template command line to execute, a list
12681 of strings representing the command to execute with its arguments
12682 (suitable for enclosing white space in an argument), a dictionary
12683 mapping source file name suffixes to any combination of command
12684 line strings (if the builder should accept multiple source file
12685 extensions), a Python function, an Action object (see Action
12686 Objects) or a list of any of the above.
12687 An action function must accept three arguments: source, target and
12689 env. source is a list of source nodes; target is a list of target
12690 nodes; env is the construction environment to use for context.
12691 The action and generator arguments must not both be used for the
12693 same Builder.
12694 prefix
12696 The prefix to prepend to the target file name. prefix may be a
12697 string, a function (or other callable) that takes two arguments (a
12698 construction environment and a list of sources) and returns a
12699 prefix string, or a dictionary specifying a mapping from a specific
12700 source suffix (of the first source specified) to a corresponding
12701 target prefix string. For the dictionary form, both the source
12702 suffix (key) and target prefix (value) specifications may use
12703 environment variable substitution, and the target prefix may also
12704 be a callable object. The default target prefix may be indicated by
12705 a dictionary entry with a key of None.
12706 b = Builder("build_it < $SOURCE > $TARGET",
12708 prefix="file-")
12709 def gen_prefix(env, sources):
12711 return "file-" + env['PLATFORM'] + '-'
12712 b = Builder("build_it < $SOURCE > $TARGET",
12714 prefix=gen_prefix)
12715 b = Builder("build_it < $SOURCE > $TARGET",
12717 suffix={None: "file-", "$SRC_SFX_A": gen_prefix})
12718 suffix
12720 The suffix to append to the target file name. Specified in the same
12721 manner as for prefix above. If the suffix is a string, then scons
12722 prepends a '.' to the suffix if it's not already there. The string
12723 returned by the callable object or obtained from the dictionary is
12724 untouched and you need to manually prepend a '.' if one is
12725 required.
12726 b = Builder("build_it < $SOURCE > $TARGET"
12728 suffix="-file")
12729 def gen_suffix(env, sources):
12731 return "." + env['PLATFORM'] + "-file"
12732 b = Builder("build_it < $SOURCE > $TARGET",
12734 suffix=gen_suffix)
12735 b = Builder("build_it < $SOURCE > $TARGET",
12737 suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix})
12738 ensure_suffix
12740 If set to a true value, ensures that targets will end in suffix.
12741 Thus, the suffix will also be added to any target strings that have
12742 a suffix that is not already suffix. The default behavior (also
12743 indicated by a false value) is to leave unchanged any target string
12744 that looks like it already has a suffix.
12745 b1 = Builder("build_it < $SOURCE > $TARGET"
12747 suffix = ".out")
12748 b2 = Builder("build_it < $SOURCE > $TARGET"
12749 suffix = ".out",
12750 ensure_suffix=True)
12751 env = Environment()
12752 env['BUILDERS']['B1'] = b1
12753 env['BUILDERS']['B2'] = b2
12754 # Builds "foo.txt" because ensure_suffix is not set.
12756 env.B1('foo.txt', 'foo.in')
12757 # Builds "bar.txt.out" because ensure_suffix is set.
12759 env.B2('bar.txt', 'bar.in')
12760 src_suffix
12762 The expected source file name suffix. src_suffix may be a string
12763 or a list of strings.
12764 target_scanner
12766 A Scanner object that will be invoked to find implicit dependencies
12767 for this target file. This keyword argument should be used for
12768 Scanner objects that find implicit dependencies based only on the
12769 target file and the construction environment, not for implicit
12770 dependencies based on source files. See the section called “Scanner
12771 Objects” for information about creating Scanner objects.
12772 source_scanner
12774 A Scanner object that will be invoked to find implicit dependencies
12775 in any source files used to build this target file. This is where
12776 you would specify a scanner to find things like #include lines in
12777 source files. The pre-built DirScanner Scanner object may be used
12778 to indicate that this Builder should scan directory trees for
12779 on-disk changes to files that scons does not know about from other
12780 Builder or function calls. See the section called “Scanner Objects”
12781 for information about creating your own Scanner objects.
12782 target_factory
12784 A factory function that the Builder will use to turn any targets
12785 specified as strings into SCons Nodes. By default, SCons assumes
12786 that all targets are files. Other useful target_factory values
12787 include Dir, for when a Builder creates a directory target, and
12788 Entry, for when a Builder can create either a file or directory
12789 target.
12790 Example:
12792 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
12794 env = Environment()
12795 env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder})
12796 env.MakeDirectory('new_directory', [])
12797 Note that the call to this MakeDirectory Builder needs to specify
12799 an empty source list to make the string represent the builder's
12800 target; without that, it would assume the argument is the source,
12801 and would try to deduce the target name from it, which in the
12802 absence of an automatically-added prefix or suffix would lead to a
12803 matching target and source name and a circular dependency.
12804 source_factory
12806 A factory function that the Builder will use to turn any sources
12807 specified as strings into SCons Nodes. By default, SCons assumes
12808 that all source are files. Other useful source_factory values
12809 include Dir, for when a Builder uses a directory as a source, and
12810 Entry, for when a Builder can use files or directories (or both) as
12811 sources.
12812 Example:
12814 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
12816 env = Environment()
12817 env.Append(BUILDERS={'Collect': CollectBuilder})
12818 env.Collect('archive', ['directory_name', 'file_name'])
12819 emitter
12821 A function or list of functions to manipulate the target and source
12822 lists before dependencies are established and the target(s) are
12823 actually built. emitter can also be a string containing a
12824 construction variable to expand to an emitter function or list of
12825 functions, or a dictionary mapping source file suffixes to emitter
12826 functions. (Only the suffix of the first source file is used to
12827 select the actual emitter function from an emitter dictionary.)
12828 A function passed as emitter must accept three arguments: source,
12830 target and env. source is a list of source nodes, target is a list
12831 of target nodes, env is the construction environment to use for
12832 context.
12833 An emitter must return a tuple containing two lists, the list of
12835 targets to be built by this builder, and the list of sources for
12836 this builder.
12837 Example:
12839 def e(target, source, env):
12841 return target + ['foo.foo'], source + ['foo.src']
12842 # Simple association of an emitter function with a Builder.
12844 b = Builder("my_build < $TARGET > $SOURCE", emitter=e)
12845 def e2(target, source, env):
12847 return target + ['bar.foo'], source + ['bar.src']
12848 # Simple association of a list of emitter functions with a Builder.
12850 b = Builder("my_build < $TARGET > $SOURCE", emitter=[e, e2])
12851 # Calling an emitter function through a construction variable.
12853 env = Environment(MY_EMITTER=e)
12854 b = Builder("my_build < $TARGET > $SOURCE", emitter='$MY_EMITTER')
12855 # Calling a list of emitter functions through a construction variable.
12857 env = Environment(EMITTER_LIST=[e, e2])
12858 b = Builder("my_build < $TARGET > $SOURCE", emitter='$EMITTER_LIST')
12859 # Associating multiple emitters with different file
12861 # suffixes using a dictionary.
12862 def e_suf1(target, source, env):
12863 return target + ['another_target_file'], source
12864 def e_suf2(target, source, env):
12866 return target, source + ['another_source_file']
12867 b = Builder(
12869 action="my_build < $TARGET > $SOURCE",
12870 emitter={'.suf1': e_suf1, '.suf2': e_suf2}
12871 )
12872 multi
12874 Specifies whether this builder is allowed to be called multiple
12875 times for the same target file(s). The default is False, which
12876 means the builder can not be called multiple times for the same
12877 target file(s). Calling a builder multiple times for the same
12878 target simply adds additional source files to the target; it is not
12879 allowed to change the environment associated with the target,
12880 specify additional environment overrides, or associate a different
12881 builder with the target.
12882 env
12884 A construction environment that can be used to fetch source code
12885 using this Builder. (Note that this environment is not used for
12886 normal builds of normal target files, which use the environment
12887 that was used to call the Builder for the target file.)
12888 generator
12890 A function that returns a list of actions that will be executed to
12891 build the target(s) from the source(s). The returned action(s) may
12892 be an Action object, or anything that can be converted into an
12893 Action object (see the next section).
12894 A function passed as generator must accept four arguments: source,
12896 target, env and for_signature. source is a list of source nodes,
12897 target is a list of target nodes, env is the construction
12898 environment to use for context, and for_signature is a Boolean
12899 value that tells the function if it is being called for the purpose
12900 of generating a build signature (as opposed to actually executing
12901 the command). Since the build signature is used for rebuild
12902 determination, the function should omit those elements that do not
12903 affect whether a rebuild should be triggered if for_signature is
12904 true.
12905 Example:
12907 def g(source, target, env, for_signature):
12909 return [["gcc", "-c", "-o"] + target + source]
12910 b = Builder(generator=g)
12912 The generator and action arguments must not both be used for the
12914 same Builder.
12915 src_builder
12917 Specifies a builder to use when a source file name suffix does not
12918 match any of the suffixes of the builder. Using this argument
12919 produces a multi-stage builder.
12920 single_source
12922 Specifies that this builder expects exactly one source file per
12923 call. Giving more than one source file without target files results
12924 in implicitly calling the builder multiple times (once for each
12925 source given). Giving multiple source files together with target
12926 files results in a UserError exception.
12927 source_ext_match
12929 When the specified action argument is a dictionary, the default
12930 behavior when a builder is passed multiple source files is to make
12931 sure that the extensions of all the source files match. If it is
12932 legal for this builder to be called with a list of source files
12933 with different extensions, this check can be suppressed by setting
12934 source_ext_match to False or some other non-true value. In this
12935 case, scons will use the suffix of the first specified source file
12936 to select the appropriate action from the action dictionary.
12937 In the following example, the setting of source_ext_match prevents
12939 scons from exiting with an error due to the mismatched suffixes of
12940 foo.in and foo.extra.
12941 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
12943 source_ext_match=False)
12944 env = Environment(BUILDERS={'MyBuild':b})
12946 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
12947 env
12949 A construction environment that can be used to fetch source code
12950 using this Builder. (Note that this environment is not used for
12951 normal builds of normal target files, which use the environment
12952 that was used to call the Builder for the target file.)
12953 b = Builder(action="build < $SOURCE > $TARGET")
12955 env = Environment(BUILDERS={'MyBuild' : b})
12956 env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy')
12957 chdir
12959 A directory from which scons will execute the action(s) specified
12960 for this Builder. If the chdir argument is a string or a directory
12961 Node, scons will change to the specified directory. If the chdir is
12962 not a string or Node and is non-zero, then scons will change to the
12963 target file's directory.
12964 Note that scons will not automatically modify its expansion of
12966 construction variables like $TARGET and $SOURCE when using the
12967 chdir keyword argument--that is, the expanded file names will still
12968 be relative to the top-level directory containing the SConstruct
12969 file, and consequently incorrect relative to the chdir directory.
12970 Builders created using chdir keyword argument, will need to use
12971 construction variable expansions like ${TARGET.file} and
12972 ${SOURCE.file} to use just the filename portion of the targets and
12973 source.
12974 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
12976 chdir=1)
12977 env = Environment(BUILDERS={'MyBuild' : b})
12978 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
12979 Warning
12981 Python only keeps one current directory location even if there
12982 are multiple threads. This means that use of the chdir argument
12983 will not work with the SCons -j option, because individual
12984 worker threads spawned by SCons interfere with each other when
12985 they start changing directory.
12986 Any additional keyword arguments supplied when a Builder object is
12988 created (that is, when the Builder function is called) will be set in
12989 the executing construction environment when the Builder object is
12990 called. The canonical example here would be to set a construction
12991 variable to the repository of a source code system.
12992 Any such keyword arguments supplied when a Builder object is called
12994 will only be associated with the target created by that particular
12995 Builder call (and any other files built as a result of the call). These
12996 extra keyword arguments are passed to the following functions: command
12997 generator functions, function Actions, and emitter functions.
12998 Action Objects
13000 The Builder factory function will turn its action keyword argument into
13001 an appropriate internal Action object, as will the Command function.
13002 You can also explicitly create Action objects for passing to Builder,
13003 or other functions that take actions as arguments, by calling the
13004 Action factory function. This may more efficient when multiple Builder
13005 objects need to do the same thing rather than letting each of those
13006 Builder objects create a separate Action object. It also allows more
13007 flexible configuration of an Action object. For example, to control the
13008 message printed when the action is taken you need to create the action
13009 object using Action.
13010 The Action factory function returns an appropriate object for the
13012 action represented by the type of the action argument (the first
13013 positional parameter):
13014 • If action is already an Action object, the object is simply
13016 returned.
13017 • If action is a string, a command-line Action is returned. If such a
13019 string begins with @, the command line is not printed. If the
13020 string begins with hyphen (-), the exit status from the specified
13021 command is ignored, allowing execution to continue even if the
13022 command reports failure:
13023 Action('$CC -c -o $TARGET $SOURCES')
13025 # Doesn't print the line being executed.
13027 Action('@build $TARGET $SOURCES')
13028 # Ignores return value
13030 Action('-build $TARGET $SOURCES')
13031 • If action is a list, then a list of Action objects is returned. An
13033 Action object is created as necessary for each element in the list.
13034 If an element within the list is itself a list, the embedded list
13035 is taken as the command and arguments to be executed via the
13036 command line. This allows white space to be enclosed in an argument
13037 rather than taken as a separator by defining a command in a list
13038 within a list:
13039 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
13041 • If action is a callable object, a Function Action is returned. The
13043 callable must accept three keyword arguments: target, source and
13044 env. target is a Node object representing the target file, source
13045 is a Node object representing the source file and env is the
13046 construction environment used for building the target file.
13047 The target and source arguments may be lists of Node objects if
13049 there is more than one target file or source file. The actual
13050 target and source file name(s) may be retrieved from their Node
13051 objects via the built-in Python str function:
13052 target_file_name = str(target)
13054 source_file_names = [str(x) for x in source]
13055 The function should return 0 or None to indicate a successful build
13057 of the target file(s). The function may raise an exception or
13058 return a non-zero exit status to indicate an unsuccessful build.
13059 def build_it(target=None, source=None, env=None):
13061 # build the target from the source
13062 return 0
13063 a = Action(build_it)
13065 • If action is not one of the above types, no action object is
13067 generated and Action returns None.
13068 The environment method form env.Action will expand construction
13070 variables in any argument strings, including action, at the time it is
13071 called, using the construction variables in the construction
13072 environment through which it was called. The global function form
13073 Action delays variable expansion until the Action object is actually
13074 used.
13075 The optional second argument to Action is used to control the output
13077 which is printed when the Action is actually performed. If this
13078 parameter is omitted, or if the value is an empty string, a default
13079 output depending on the type of the action is used. For example, a
13080 command-line action will print the executed command. The following
13081 argument types are accepted:
13082 • If the second argument is a string, or if the cmdstr keyword
13084 argument is supplied, the string defines what is printed.
13085 Substitution is performed on the string before it is printed. The
13086 string typically contains substitutable variables, notably
13087 $TARGET(S) and $SOURCE(S), or consists of just a single variable
13088 which is optionally defined somewhere else. SCons itself heavily
13089 uses the latter variant.
13090 • If the second argument is a function, or if the strfunction keyword
13092 argument is supplied, the function will be called to obtain the
13093 string to be printed when the action is performed. The function
13094 must accept three keyword arguments: target, source and env, with
13095 the same interpretation as for a callable action argument above.
13096 The function is responsible for handling any required
13097 substitutions.
13098 • If the second argument is None, or if cmdstr=None is supplied,
13100 output is suppressed entirely.
13101 The cmdstr and strfunction keyword arguments may not both be supplied
13103 in a single call to Action
13104 Printing of action strings is affected by the setting of
13106 $PRINT_CMD_LINE_FUNC.
13107 Examples:
13109 def build_it(target, source, env):
13111 # build the target from the source
13112 return 0
13113 def string_it(target, source, env):
13115 return "building '%s' from '%s'" % (target[0], source[0])
13116 # Use a positional argument.
13118 f = Action(build_it, string_it)
13119 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
13120 # Alternatively, use a keyword argument.
13122 f = Action(build_it, strfunction=string_it)
13123 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
13124 # You can provide a configurable variable.
13126 l = Action(build_it, '$STRINGIT')
13127 Any additional positional arguments, if present, may either be
13129 construction variables or lists of construction variables whose values
13130 will be included in the signature of the Action (the build signature)
13131 when deciding whether a target should be rebuilt because the action
13132 changed. Such variables may also be specified using the varlist keyword
13133 parameter; both positional and keyword forms may be present, and will
13134 be combined. This is necessary whenever you want a target to be rebuilt
13135 when a specific construction variable changes. This is not often needed
13136 for a string action, as the expanded variables will normally be part of
13137 the command line, but may be needed if a Python function action uses
13138 the value of a construction variable when generating the command line.
13139 def build_it(target, source, env):
13141 # build the target from the 'XXX' construction variable
13142 with open(target[0], 'w') as f:
13143 f.write(env['XXX'])
13144 return 0
13145 # Use positional arguments.
13147 a = Action(build_it, '$STRINGIT', ['XXX'])
13148 # Alternatively, use a keyword argument.
13150 a = Action(build_it, varlist=['XXX'])
13151 The Action factory function can be passed the following optional
13153 keyword arguments to modify the Action object's behavior:
13154 chdir
13156 If chdir is true (the default is False), SCons will change
13157 directories before executing the action. If the value of chdir is a
13158 string or a directory Node, SCons will change to the specified
13159 directory. Otherwise, if chdir evaluates true, SCons will change to
13160 the target file's directory.
13161 Note that SCons will not automatically modify its expansion of
13163 construction variables like $TARGET and $SOURCE when using the
13164 chdir parameter - that is, the expanded file names will still be
13165 relative to the top-level directory containing the SConstruct file,
13166 and consequently incorrect relative to the chdir directory.
13167 Builders created using chdir keyword argument, will need to use
13168 construction variable expansions like ${TARGET.file} and
13169 ${SOURCE.file} to use just the filename portion of the targets and
13170 source. Example:
13171 a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=True)
13173 exitstatfunc
13175 If provided, must be a callable which accepts a single parameter,
13176 the exit status (or return value) from the specified action, and
13177 which returns an arbitrary or modified value. This can be used, for
13178 example, to specify that an Action object's return value should be
13179 ignored under special conditions and SCons should, therefore,
13180 consider that the action always succeeds. Example:
13181 def always_succeed(s):
13183 # Always return 0, which indicates success.
13184 return 0
13185 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
13187 exitstatfunc=always_succeed)
13188 batch_key
13190 If provided, indicates that the Action can create multiple target
13191 files by processing multiple independent source files
13192 simultaneously. (The canonical example is "batch compilation" of
13193 multiple object files by passing multiple source files to a single
13194 invocation of a compiler such as Microsoft's Visual C / C++
13195 compiler.) If the batch_key argument evaluates True and is not a
13196 callable object, the configured Action object will cause scons to
13197 collect all targets built with the Action object and configured
13198 with the same construction environment into single invocations of
13199 the Action object's command line or function. Command lines will
13200 typically want to use the $CHANGED_SOURCES construction variable
13201 (and possibly $CHANGED_TARGETS as well) to only pass to the command
13202 line those sources that have actually changed since their targets
13203 were built. Example:
13204 a = Action('build $CHANGED_SOURCES', batch_key=True)
13206 The batch_key argument may also be a callable function that returns
13208 a key that will be used to identify different "batches" of target
13209 files to be collected for batch building. A batch_key function must
13210 accept four parameters: action, env, target and source. The first
13211 parameter, action, is the active action object. The second
13212 parameter, env, is the construction environment configured for the
13213 target. The target and source parameters are the lists of targets
13214 and sources for the configured action.
13215 The returned key should typically be a tuple of values derived from
13217 the arguments, using any appropriate logic to decide how multiple
13218 invocations should be batched. For example, a batch_key function
13219 may decide to return the value of a specific construction variable
13220 from env which will cause scons to batch-build targets with
13221 matching values of that construction variable, or perhaps return
13222 the Python id() of the entire construction environment, in which
13223 case scons will batch-build all targets configured with the same
13224 construction environment. Returning None indicates that the
13225 particular target should not be part of any batched build, but
13226 instead will be built by a separate invocation of action's command
13227 or function. Example:
13228 def batch_key(action, env, target, source):
13230 tdir = target[0].dir
13231 if tdir.name == 'special':
13232 # Don't batch-build any target
13233 # in the special/ subdirectory.
13234 return None
13235 return (id(action), id(env), tdir)
13236 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
13237 Miscellaneous Action Functions
13239 SCons supplies Action functions that arrange for various common
13240 file and directory manipulations to be performed. These are similar
13241 in concept to "tasks" in the Ant build tool, although the
13242 implementation is slightly different. These functions do not
13243 actually perform the specified action at the time the function is
13244 called, but rather are factory functions which return an Action
13245 object that can be executed at the appropriate time.
13246 There are two natural ways that these Action Functions are intended
13248 to be used.
13249 First, if you need to perform the action at the time the SConscript
13251 file is being read, you can use the Execute global function:
13252 Execute(Touch('file'))
13254 Second, you can use these functions to supply Actions in a list for
13256 use by the env.Command method. This can allow you to perform more
13257 complicated sequences of file manipulation without relying on
13258 platform-specific external commands:
13259 env = Environment(TMPBUILD='/tmp/builddir')
13261 env.Command(
13262 target='foo.out',
13263 source='foo.in',
13264 action=[
13265 Mkdir('$TMPBUILD'),
13266 Copy('$TMPBUILD', '${SOURCE.dir}'),
13267 "cd $TMPBUILD && make",
13268 Delete('$TMPBUILD'),
13269 ],
13270 )
13271 Chmod(dest, mode)
13273 Returns an Action object that changes the permissions on the
13274 specified dest file or directory to the specified mode which
13275 can be octal or string, similar to the bash command. Examples:
13276 Execute(Chmod('file', 0o755))
13278 env.Command('foo.out', 'foo.in',
13280 [Copy('$TARGET', '$SOURCE'),
13281 Chmod('$TARGET', 0o755)])
13282 Execute(Chmod('file', "ugo+w"))
13284 env.Command('foo.out', 'foo.in',
13286 [Copy('$TARGET', '$SOURCE'),
13287 Chmod('$TARGET', "ugo+w")])
13288 The behavior of Chmod is limited on Windows, see the notes in
13290 the Python documentation for os.chmod, which is the underlying
13291 function.
13292 Copy(dest, src)
13294 Returns an Action object that will copy the src source file or
13295 directory to the dest destination file or directory. Examples:
13296 Execute(Copy('foo.output', 'foo.input'))
13298 env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE'))
13300 Delete(entry, [must_exist])
13302 Returns an Action that deletes the specified entry, which may
13303 be a file or a directory tree. If a directory is specified, the
13304 entire directory tree will be removed. If the must_exist flag
13305 is set to a true value, then a Python error will be raised if
13306 the specified entry does not exist; the default is false, that
13307 is, the Action will silently do nothing if the entry does not
13308 exist. Examples:
13309 Execute(Delete('/tmp/buildroot'))
13311 env.Command(
13313 'foo.out',
13314 'foo.in',
13315 action=[
13316 Delete('${TARGET.dir}'),
13317 MyBuildAction,
13318 ],
13319 )
13320 Execute(Delete('file_that_must_exist', must_exist=True))
13322 Mkdir(name)
13324 Returns an Action that creates the directory name and all
13325 needed intermediate directories. name may also be a list of
13326 directories to create. Examples:
13327 Execute(Mkdir('/tmp/outputdir'))
13329 env.Command(
13331 'foo.out',
13332 'foo.in',
13333 action=[
13334 Mkdir('/tmp/builddir'),
13335 Copy('/tmp/builddir/foo.in', '$SOURCE'),
13336 "cd /tmp/builddir && make",
13337 Copy('$TARGET', '/tmp/builddir/foo.out'),
13338 ],
13339 )
13340 Move(dest, src)
13342 Returns an Action that moves the specified src file or
13343 directory to the specified dest file or directory. Examples:
13344 Execute(Move('file.destination', 'file.source'))
13346 env.Command(
13348 'output_file',
13349 'input_file',
13350 action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')],
13351 )
13352 Touch(file)
13354 Returns an Action that updates the modification time on the
13355 specified file. Examples:
13356 Execute(Touch('file_to_be_touched'))
13358 env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')])
13360 Variable Substitution
13362 Before executing a command, scons performs parameter expansion
13363 (substitution) on the string that makes up the action part of the
13364 builder. The format of a substitutable parameter is ${expression}.
13365 If expression refers to a variable, the braces in ${expression} can
13366 be omitted unless the variable name is immediately followed by a
13367 character that could either be interpreted as part of the name, or
13368 is Python syntax such as [ (for indexing/slicing) or . (for
13369 attribute access - see Special Attributes below).
13370 If expression refers to a construction variable, it is replaced
13372 with the value of that variable in the construction environment at
13373 the time of execution. If expression looks like a variable name but
13374 is not defined in the construction environment it is replaced with
13375 an empty string. If expression refers to one of the Special
13376 Variables (see below) the corresponding value of the variable is
13377 substituted. expression may also be a Python expression to be
13378 evaluated. See Python Code Substitution below for a description.
13379 SCons uses the following rules when converting construction
13381 variables into command line strings:
13382 • If the value is a string it is interpreted as space delimited
13384 command line arguments.
13385 • If the value is a list it is interpreted as a list of command
13387 line arguments. Each element of the list is converted to a
13388 string.
13389 • Anything that is not a list or string is converted to a string
13391 and interpreted as a single command line argument.
13392 • Newline characters (\n) delimit lines. The newline parsing is
13394 done after all other parsing, so it is not possible for
13395 arguments (e.g. file names) to contain embedded newline
13396 characters.
13397 • For a literal $ use $$. For example, $$FOO will be left in the
13399 final string as $FOO.
13400 When a build action is executed, a hash of the command line is
13402 saved, together with other information about the target(s) built by
13403 the action, for future use in rebuild determination. This is called
13404 the build signature (or build action signature). The escape
13405 sequence $( subexpression $) may be used to indicate parts of a
13406 command line that may change without causing a rebuild--that is,
13407 which are not to be included when calculating the build signature.
13408 All text from $( up to and including the matching $) will be
13409 removed from the command line before it is added to the build
13410 signature while only the $( and $) will be removed before the
13411 command is executed. For example, the command line string:
13412 "echo Last build occurred $( $TODAY $). > $TARGET"
13414 would execute the command:
13416 echo Last build occurred $TODAY. > $TARGET
13418 but the build signature added to any target files would be computed
13420 from:
13421 echo Last build occurred . > $TARGET
13423 While construction variables are normally directly substituted, if
13425 a construction variable has a value which is a callable Python
13426 object (a function, or a class with a __call__ method), that object
13427 is called during substitution. The callable must accept four
13428 arguments: target, source, env and for_signature. source is a list
13429 of source nodes, target is a list of target nodes, env is the
13430 construction environment to use for context, and for_signature is a
13431 boolean value that tells the callable if it is being called for the
13432 purpose of generating a build signature. Since the build signature
13433 is used for rebuild determination, variable elements that do not
13434 affect whether a rebuild should be triggered should be omitted from
13435 the returned string if for_signature is true. See $( and $) above
13436 for the syntax.
13437 SCons will insert whatever the callable returns into the expanded
13439 string:
13440 def foo(target, source, env, for_signature):
13442 return "bar"
13443 # Will expand $BAR to "bar baz"
13445 env = Environment(FOO=foo, BAR="$FOO baz")
13446 As a reminder, substitution happens when $BAR is actually used in a
13448 builder action. The value of env['BAR'] will be exactly as it was
13449 set: "$FOO baz". This can make debugging tricky, as the substituted
13450 result is not available at the time the SConscript files are being
13451 interpreted and thus not available to print(). However, you can
13452 perform the substitution on demand by calling the env.subst method
13453 for this purpose.
13454 You can use this feature to pass arguments to a callable variable
13456 by creating a callable class that stores passed arguments in the
13457 instance, and then uses them (in the __call__ method) when the
13458 instance is called. Note that in this case, the entire variable
13459 expansion must be enclosed by curly braces so that the arguments
13460 will be associated with the instantiation of the class:
13461 class foo:
13463 def __init__(self, arg):
13464 self.arg = arg
13465 def __call__(self, target, source, env, for_signature):
13467 return self.arg + " bar"
13468 # Will expand $BAR to "my argument bar baz"
13470 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
13471 Substitution: Special Variables
13473 Besides regular construction variables, scons provides the
13474 following Special Variables for use in expanding commands:
13475 $CHANGED_SOURCES
13477 The file names of all sources of the build command that have
13478 changed since the target was last built.
13479 $CHANGED_TARGETS
13481 The file names of all targets that would be built from sources
13482 that have changed since the target was last built.
13483 $SOURCE
13485 The file name of the source of the build command, or the file
13486 name of the first source if multiple sources are being built.
13487 $SOURCES
13489 The file names of the sources of the build command.
13490 $TARGET
13492 The file name of the target being built, or the file name of
13493 the first target if multiple targets are being built.
13494 $TARGETS
13496 The file names of all targets being built.
13497 $UNCHANGED_SOURCES
13499 The file names of all sources of the build command that have
13500 not changed since the target was last built.
13501 $UNCHANGED_TARGETS
13503 The file names of all targets that would be built from sources
13504 that have not changed since the target was last built.
13505 These names are reserved and may not be assigned to or used as
13507 construction variables. SCons computes them in a context-dependent
13508 manner and they and are not retrieved from a construction
13509 environment.
13510 For example, the following builder call:
13512 env = Environment(CC='cc')
13514 env.Command(
13515 target=['foo'],
13516 source=['foo.c', 'bar.c'],
13517 action='@echo $CC -c -o $TARGET $SOURCES'
13518 )
13519 would produce the following output:
13521 cc -c -o foo foo.c bar.c
13523 In the previous example, a string ${SOURCES[1]} would expand to:
13525 bar.c.
13526 Substitution: Special Attributes
13528 A variable name may have the following modifiers appended within
13529 the enclosing curly braces to access properties of the interpolated
13530 string. These are known as special attributes.
13531 base -
13532 The base path of the file name,
13533 including the directory path
13534 but excluding any suffix.
13535 dir - The name of the directory in which the file exists.
13537 file - The file name, minus any directory portion.
13538 filebase - Like file but minus its suffix.
13539 suffix - Just the file suffix.
13540 abspath - The absolute path name of the file.
13541 relpath - The path name of the file relative to the root
13542 SConstruct file's directory.
13543 posix -
13544 The path with directories separated by forward slashes
13545 (/).
13546 Sometimes necessary on Windows systems
13547 when a path references a file on other (POSIX) systems.
13548 windows -
13550 The path with directories separated by backslashes
13551 (\\).
13552 Sometimes necessary on POSIX-style systems
13553 when a path references a file on other (Windows) systems.
13554 win32 is a (deprecated) synonym for
13555 windows.
13556 srcpath -
13558 The directory and file name to the source file linked to
13559 this file through
13560 VariantDir().
13561 If this file isn't linked,
13562 it just returns the directory and filename unchanged.
13563 srcdir -
13565 The directory containing the source file linked to this
13566 file through
13567 VariantDir().
13568 If this file isn't linked,
13569 it just returns the directory part of the filename.
13570 rsrcpath -
13572 The directory and file name to the source file linked to
13573 this file through
13574 VariantDir().
13575 If the file does not exist locally but exists in a
13576 Repository,
13577 the path in the Repository is returned.
13578 If this file isn't linked, it just returns the
13579 directory and filename unchanged.
13580 rsrcdir -
13582 The Repository directory containing the source file linked
13583 to this file through
13584 VariantDir().
13585 If this file isn't linked,
13586 it just returns the directory part of the filename.
13587 For example, the specified target will expand as follows for the
13590 corresponding modifiers:
13591 $TARGET => sub/dir/file.x
13593 ${TARGET.base} => sub/dir/file
13594 ${TARGET.dir} => sub/dir
13595 ${TARGET.file} => file.x
13596 ${TARGET.filebase} => file
13597 ${TARGET.suffix} => .x
13598 ${TARGET.abspath} => /top/dir/sub/dir/file.x
13599 ${TARGET.relpath} => sub/dir/file.x
13600 $TARGET => ../dir2/file.x
13602 ${TARGET.abspath} => /top/dir2/file.x
13603 ${TARGET.relpath} => ../dir2/file.x
13604 SConscript('src/SConscript', variant_dir='sub/dir')
13606 $SOURCE => sub/dir/file.x
13607 ${SOURCE.srcpath} => src/file.x
13608 ${SOURCE.srcdir} => src
13609 Repository('/usr/repository')
13611 $SOURCE => sub/dir/file.x
13612 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
13613 ${SOURCE.rsrcdir} => /usr/repository/src
13614 Some modifiers can be combined, like ${TARGET.srcpath.base),
13616 ${TARGET.file.suffix}, etc.
13617 Python Code Substitution
13619 If a substitutable expression using the notation ${expression} does
13620 not appear to match one of the other substitution patterns, it is
13621 evaluated as a Python expression. This uses Python's eval function,
13622 with the globals parameter set to the current environment's set of
13623 construction variables, and the result substituted in. So in the
13624 following case:
13625 env.Command(
13627 'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET"
13628 )
13629 the command executed will be either
13631 echo FOO > foo.out
13633 or
13635 echo BAR > foo.out
13637 according to the current value of env['COND'] when the command is
13639 executed. The evaluation takes place when the target is being
13640 built, not when the SConscript is being read. So if env['COND'] is
13641 changed later in the SConscript, the final value will be used.
13642 Here's a more complete example. Note that all of COND, FOO, and BAR
13644 are construction variables, and their values are substituted into
13645 the final command. FOO is a list, so its elements are interpolated
13646 separated by spaces.
13647 env=Environment()
13649 env['COND'] = 1
13650 env['FOO'] = ['foo1', 'foo2']
13651 env['BAR'] = 'barbar'
13652 env.Command(
13653 'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} > $TARGET"
13654 )
13655 will execute:
13657 echo foo1 foo2 > foo.out
13659 In point of fact, Python expression evaluation is how the special
13661 attributes are substituted: they are simply attributes of the
13662 Python objects that represent $TARGET, $SOURCES, etc., which SCons
13663 passes to eval which returns the value.
13664 Note
13666 Use of the Python eval function is considered to have security
13667 implications, since, depending on input sources, arbitrary
13668 unchecked strings of code can be executed by the Python
13669 interpreter. Although SCons makes use of it in a somewhat
13670 restricted context, you should be aware of this issue when
13671 using the ${python-expression-for-subst} form.
13672 Scanner Objects
13674 Scanner objects are used to scan specific file types for implicit
13675 dependencies, for example embedded preprocessor/compiler directives
13676 that cause other files to be included during processing. SCons has a
13677 number of pre-built Scanner objects, so it is usually only necessary to
13678 set up Scanners for new file types. You do this by calling the Scanner
13679 factory function. Scanner accepts the following arguments. Only
13680 function is required; the rest are optional:
13681 function
13683 A scanner function to call to process a given Node (usually a file)
13684 and return a list of Nodes representing the implicit dependencies
13685 (usually files) found in the contents. The function must accept
13686 three required arguments, node, env and path, and an optional
13687 fourth, arg. node is the internal SCons node representing the file
13688 to scan, env is the construction environment to use during the
13689 scan, and path is a tuple of directories that can be searched for
13690 files, as generated by the optional scanner path_function (see
13691 below). If argument was supplied when the Scanner object was
13692 created, it is given as arg when the scanner function is called;
13693 since argument is optional, the default is no arg.
13694 The function can use use str(node) to fetch the name of the file,
13696 node.dir to fetch the directory the file is in, node.get_contents()
13697 to fetch the contents of the file as bytes or
13698 node.get_text_contents() to fetch the contents of the file as text.
13699 The function must take into account the path directories when
13701 generating the dependency Nodes. To illustrate this, a C language
13702 source file may contain a line like #include "foo.h". However,
13703 there is no guarantee that foo.h exists in the current directory:
13704 the contents of $CPPPATH is passed to the C preprocessor which will
13705 look in those places for the header, so the scanner function needs
13706 to look in those places as well in order to build Nodes with
13707 correct paths. Using FindPathDirs with an argument of CPPPATH as
13708 the path_function in the Scanner call means the scanner function
13709 will be called with the paths extracted from $CPPPATH in the
13710 environment env passed as the paths parameter.
13711 Note that the file to scan is not guaranteed to exist at the time
13713 the scanner is called - it could be a generated file which has not
13714 been generated yet - so the scanner function must be tolerant of
13715 that.
13716 Alternatively, you can supply a dictionary as the function
13718 parameter, to map keys (such as file suffixes) to other Scanner
13719 objects. A Scanner created this way serves as a dispatcher: the
13720 Scanner's skeys parameter is automatically populated with the
13721 dictionary's keys, indicating that the Scanner handles Nodes which
13722 would be selected by those keys; the mapping is then used to pass
13723 the file on to a different Scanner that would not have been
13724 selected to handle that Node based on its own skeys.
13725 name
13727 The name to use for the Scanner. This is mainly used to identify
13728 the Scanner internally. The default value is "NONE".
13729 argument
13731 If specified, will be passed to the scanner function function and
13732 the path function path_function when called, as the optional
13733 parameter each of those functions takes.
13734 skeys
13736 Scanner key(s) indicating the file types this scanner is associated
13737 with. Used internally to select an appropriate scanner. In the
13738 usual case of scanning for file names, this argument will be a list
13739 of suffixes for the different file types that this Scanner knows
13740 how to scan. If skeys is a string, it will be expanded into a list
13741 by the current environment.
13742 path_function
13744 A Python function that takes four or five arguments: a construction
13745 environment, a Node for the directory containing the SConscript
13746 file in which the first target was defined, a list of target nodes,
13747 a list of source nodes, and the value of argument if it was
13748 supplied when the Scanner was created. Must return a tuple of
13749 directories that can be searched for files to be returned by this
13750 Scanner object. (Note that the FindPathDirs function can be used to
13751 return a ready-made path_function for a given construction variable
13752 name, instead of having to write your own function from scratch.)
13753 node_class
13755 The class of Node that should be returned by this Scanner object.
13756 Any strings or other objects returned by the scanner function that
13757 are not of this class will be run through the function supplied by
13758 the node_factory argument. A value of None can be supplied to
13759 indicate no conversion; the default is to return File nodes.
13760 node_factory
13762 A Python function that will take a string or other object and turn
13763 it into the appropriate class of Node to be returned by this
13764 Scanner object, as indicated by node_class.
13765 scan_check
13767 A Python function that takes two arguments, a Node (file) and a
13768 construction environment, and returns whether the Node should, in
13769 fact, be scanned for dependencies. This check can be used to
13770 eliminate unnecessary calls to the scanner function when, for
13771 example, the underlying file represented by a Node does not yet
13772 exist.
13773 recursive
13775 Specifies whether this scanner should be re-invoked on the
13776 dependency files returned by the scanner. If omitted, the Node
13777 subsystem will only invoke the scanner on the file being scanned
13778 and not recurse. Recursion is needed when the files returned by the
13779 scanner may themselves contain further file dependencies, as in the
13780 case of preprocessor #include lines. A value that evaluates true
13781 enables recursion; recursive may be a callable function, in which
13782 case it will be called with a list of Nodes found and should return
13783 a list of Nodes that should be scanned recursively; this can be
13784 used to select a specific subset of Nodes for additional scanning.
13785 Once created, a Scanner can added to an environment by setting it in
13787 the $SCANNERS list, which automatically triggers SCons to also add it
13788 to the environment as a method. However, usually a scanner is not truly
13789 standalone, but needs to be plugged in to the existing selection
13790 mechanism for deciding how to scan source files based on filename
13791 extensions. For this, SCons has a global SourceFileScanner object that
13792 is used by the Object, SharedObject and StaticObject builders to decide
13793 which scanner should be used. You can use the
13794 SourceFileScanner.add_scanner() method to add your own Scanner object
13795 to the SCons infrastructure that builds target programs or libraries
13796 from a list of source files of different types:
13797 def xyz_scan(node, env, path):
13799 contents = node.get_text_contents()
13800 # Scan the contents and return the included files.
13801 XYZScanner = Scanner(xyz_scan)
13803 SourceFileScanner.add_scanner('.xyz', XYZScanner)
13805 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
13807 Tool Modules
13809 Additional tools can be added to a project either by placing them in a
13810 site_tools subdirectory of a site directory, or in a custom location
13811 specified to scons by giving the toolpath keyword argument to
13812 Environment. A tool module is a form of Python module, invoked
13813 internally using the Python import mechanism, so a tool can consist
13814 either of a single source file taking the name of the tool (e.g.
13815 mytool.py) or a directory taking the name of the tool (e.g. mytool/)
13816 which contains at least an __init__.py file.
13817 The toolpath parameter takes a list as its value:
13819 env = Environment(tools=['default', 'foo'], toolpath=['tools'])
13821 This looks for a tool specification module (mytool.py, or directory
13823 mytool) in directory tools and in the standard locations, as well as
13824 using the ordinary default tools for the platform.
13825 Directories specified via toolpath are prepended to the existing tool
13827 path. The default tool path is any site_tools directories, so tools in
13828 a specified toolpath take priority, followed by tools in a site_tools
13829 directory, followed by built-in tools. For example, adding a tool
13830 specification module gcc.py to the toolpath directory would override
13831 the built-in gcc tool. The tool path is stored in the environment and
13832 will be used by subsequent calls to the Tool method, as well as by
13833 env.Clone.
13834 base = Environment(toolpath=['custom_path'])
13836 derived = base.Clone(tools=['custom_tool'])
13837 derived.CustomBuilder()
13838 A tool specification module must include two functions:
13840 generate(env, **kwargs)
13842 Modify the construction environment env to set up necessary
13843 construction variables, Builders, Emitters, etc., so the facilities
13844 represented by the tool can be executed. Care should be taken not
13845 to overwrite construction variables intended to be settable by the
13846 user. For example:
13847 def generate(env):
13849 ...
13850 if 'MYTOOL' not in env:
13851 env['MYTOOL'] = env.Detect("mytool")
13852 if 'MYTOOLFLAGS' not in env:
13853 env['MYTOOLFLAGS'] = SCons.Util.CLVar('--myarg')
13854 ...
13855 The generate function may use any keyword arguments that the user
13857 supplies via kwargs to vary its initialization.
13858 exists(env)
13860 Return a true value if the tool can be called in the context of
13861 env. else false. Usually this means looking up one or more known
13862 programs using the PATH from the supplied env, but the tool can
13863 make the exists decision in any way it chooses.
13864 Note
13866 At the moment, user-added tools do not automatically have their
13867 exists function called. As a result, it is recommended that the
13868 generate function be defensively coded - that is, do not rely on
13869 any necessary existence checks already having been performed. This
13870 is expected to be a temporary limitation, and the exists function
13871 should still be provided.
13872 The elements of the tools list may also be functions or callable
13874 objects, in which case the Environment method will call those objects
13875 to update the new construction environment (see Tool for more details):
13876 def my_tool(env):
13878 env['XYZZY'] = 'xyzzy'
13879 env = Environment(tools=[my_tool])
13881 The individual elements of the tools list may also themselves be lists
13883 or tuples of the form (toolname, kw_dict). SCons searches for the
13884 toolname specification file as described above, and passes kw_dict,
13885 which must be a dictionary, as keyword arguments to the tool's generate
13886 function. The generate function can use the arguments to modify the
13887 tool's behavior by setting up the environment in different ways or
13888 otherwise changing its initialization.
13889 # in tools/my_tool.py:
13891 def generate(env, **kwargs):
13892 # Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
13893 env['MY_TOOL'] = kwargs.get('arg1', '1')
13894 def exists(env):
13896 return True
13897 # in SConstruct:
13899 env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
13900 toolpath=['tools'])
13901 The tool specification (my_tool in the example) can use the $PLATFORM
13903 variable from the construction environment it is passed to customize
13904 the tool for different platforms.
13905 Tools can be "nested" - that is, they can be located within a
13907 subdirectory in the toolpath. A nested tool name uses a dot to
13908 represent a directory separator
13909 # namespaced builder
13911 env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.SomeTool'])
13912 env.SomeTool(targets, sources)
13913 # Search Paths
13915 # SCons\Tool\SubDir1\SubDir2\SomeTool.py
13916 # SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
13917 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
13918 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
13919
13921 scons and its configuration files are very portable, due largely to its
13922 implementation in Python. There are, however, a few portability issues
13923 waiting to trap the unwary.
13924 .C File Suffix
13926 scons handles the upper-case .C file suffix differently, depending on
13927 the capabilities of the underlying system. On a case-sensitive system
13928 such as Linux or UNIX, scons treats a file with a .C suffix as a C++
13929 source file. On a case-insensitive system such as Windows, scons treats
13930 a file with a .C suffix as a C source file.
13931 Fortran File Suffixes
13933 There are several ways source file suffixes impact the behavior of
13934 SCons when working with Fortran language code (not all are
13935 system-specific, but they are included here for completeness).
13936 As the Fortran language has evolved through multiple standards
13938 editions, projects might have a need to handle files from different
13939 language generations differently. To this end, SCons dispatches to a
13940 different compiler dialect setup (expressed as a set of construction
13941 variables) depending on the file suffix. By default, all of these
13942 setups start out the same, but individual construction variables can be
13943 modified as needed to tune a given dialect. Each of these dialacts has
13944 a tool specification module whose documentation describes the
13945 construction variables associated with that dialect: .f (as well as
13946 .for and .ftn) in fortran; (construction variables start with FORTRAN)
13947 .f77 in f77; (construction variables start with F77) .f90 in f90;
13948 (construction variables start with F90) .f95 in f95; (construction
13949 variables start with F95) .f03 in f03; (construction variables start
13950 with F03) .f08 in f08 (construction variables start with F08).
13951 While SCons recognizes multiple internal dialects based on filename
13953 suffixes, the convention of various available Fortran compilers is to
13954 assign an actual meaning to only two of these suffixes: .f (as well as
13955 .for and .ftn) refers to the fixed-format source code that was the only
13956 available option in FORTRAN 77 and earlier, and .f90 refers to
13957 free-format source code which became available as of the Fortran 90
13958 standard. Some compilers recognize suffixes which correspond to Fortran
13959 specifications later then F90 as equivalent to .f90 for this purpose,
13960 while some do not - check the documentation for your compiler. An
13961 occasionally suggested policy suggestion is to use only .f and .f90 as
13962 Fortran filename suffixes. The fixed/free form determination can
13963 usually be controlled explicitly with compiler flags (e.g.
13964 -ffixed-form for gfortran), overriding any assumption that may be made
13965 based on the source file suffix.
13966 The source file suffix does not imply conformance with the
13968 similarly-named Fortran standard - a suffix of .f08 does not mean you
13969 are compiling specifically for Fortran 2008. Normally, compilers
13970 provide command-line options for making this selection (e.g.
13971 -std=f2008 for gfortran).
13972 For dialects from F90 on (including the generic FORTRAN dialect), a
13974 suffix of .mod is recognized for Fortran modules. These files are a
13975 side effect of compiling a Fortran source file containing module
13976 declarations, and must be available when other code which declares that
13977 it uses the module is processed. SCons does not currently have
13978 integrated support for submodules, introduced in the Fortran 2008
13979 standard - the invoked compiler will produce results, but SCons will
13980 not recognize .smod files as tracked objects.
13981 On a case-sensitive system such as Linux or UNIX, a file with a an
13983 upper-cased suffix from the set .F, .FOR, .FTN, .F90, .F95, .F03 and
13984 .F08 is treated as a Fortran source file which shall first be run
13985 through the standard C preprocessor. The lower-cased versions of these
13986 suffixes do not trigger this behavior. On systems which do not
13987 distinguish between uppper and lower case in filenames, this behavior
13988 is not available, but files suffixed with either .FPP or .fpp are
13989 always passed to the preprocessor first. This matches the convention of
13990 gfortran from the GNU Compiler Collection, and also followed by certain
13991 other Fortran compilers. For these two suffixes, the generic FORTRAN
13992 dialect will be selected.
13993 SCons itself does not invoke the preprocessor, that is handled by the
13995 compiler, but it adds construction variables which are applicable to
13996 the preprocessor run. You can see this difference by examining
13997 $FORTRANPPCOM and $FORTRANPPCOMSTR which are used instead of
13998 $FORTRANCOM and $FORTRANCOMSTR for that dialect.
13999 Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
14001 Cygwin supplies a set of tools and utilities that let users work on a
14002 Windows system using a POSIX-like environment. The Cygwin tools,
14003 including Cygwin Python, do this, in part, by sharing an ability to
14004 interpret POSIX-style path names. For example, the Cygwin tools will
14005 internally translate a Cygwin path name like /cygdrive/c/mydir to an
14006 equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
14007 Versions of Python that are built for native Windows execution, such as
14009 the python.org and ActiveState versions, do not understand the Cygwin
14010 path name semantics. This means that using a native Windows version of
14011 Python to build compiled programs using Cygwin tools (such as gcc,
14012 bison and flex) may yield unpredictable results. "Mixing and matching"
14013 in this way can be made to work, but it requires careful attention to
14014 the use of path names in your SConscript files.
14015 In practice, users can sidestep the issue by adopting the following
14017 guidelines: When using Cygwin's gcc for compiling, use the
14018 Cygwin-supplied Python interpreter to run scons; when using Microsoft
14019 Visual C/C++ (or some other "native" Windows compiler) use the
14020 python.org, Microsoft Store, ActiveState or other native version of
14021 Python to run scons.
14022 This discussion largely applies to the msys2 environment as well (with
14024 the use of the mingw compiler toolchain), in particular the
14025 recommendation to use the msys2 version of Python if running scons from
14026 inside an msys2 shell.
14027 Windows: scons.bat file
14029 On Windows, if scons is executed via a wrapper scons.bat batch file,
14030 there are (at least) two ramifications. Note this is no longer the
14031 default - scons installed via Python''s pip installer will have an
14032 scons.exe which does not have these limitations:
14033 First, Windows command-line users that want to use variable assignment
14035 on the command line may have to put double quotes around the
14036 assignments, otherwise the Windows command shell will consume those as
14037 arguments to itself, not to scons:
14038 scons "FOO=BAR" "BAZ=BLEH"
14040 Second, the Cygwin shell does not recognize typing scons at the command
14042 line prompt as referring to this wrapper. You can work around this
14043 either by executing scons.bat (including the extension) from the Cygwin
14044 command line, or by creating a wrapper shell script named scons which
14045 invokes scons.bat.
14046 MinGW
14048 The MinGW bin directory must be in your PATH environment variable or
14049 the ['ENV']['PATH'] construction variable for scons to detect and use
14050 the MinGW tools. When running under the native Windows Python;
14051 interpreter, scons will prefer the MinGW tools over the Cygwin tools,
14052 if they are both installed, regardless of the order of the bin
14053 directories in the PATH variable. If you have both MSVC and MinGW
14054 installed and you want to use MinGW instead of MSVC, then you must
14055 explicitly tell scons to use MinGW by passing tools=['mingw'] to the
14056 Environment function, because scons will prefer the MSVC tools over the
14057 MinGW tools.
14058
14060 In general, scons is not controlled by environment variables set in the
14061 shell used to invoke it, leaving it up to the SConscript file author to
14062 import those if desired. However the following variables are imported
14063 by scons itself if set:
14064 SCONS_LIB_DIR
14066 Specifies the directory that contains the scons Python module
14067 directory. Normally scons can deduce this, but in some
14068 circumstances, such as working with a source release, it may be
14069 necessary to specify (for example,
14070 /home/aroach/scons-src-0.01/src/engine).
14071 SCONSFLAGS
14073 A string containing options that will be used by scons in addition
14074 to those passed on the command line. Can be used to reduce frequent
14075 retyping of common options. The contents of SCONSFLAGS are
14076 considered before any passed command line options, so the command
14077 line can be used to override SCONSFLAGS options if necessary.
14078 SCONS_CACHE_MSVC_CONFIG
14080 (Windows only). If set, save the shell environment variables
14081 generated when setting up the Microsoft Visual C++ compiler (and/or
14082 Build Tools) to a cache file, to give these settings, which are
14083 relatively expensive to generate, persistence across scons
14084 invocations. Use of this option is primarily intended to aid
14085 performance in tightly controlled Continuous Integration setups.
14086 If set to a True-like value ("1", "true" or "True") will cache to a
14088 file named .scons_msvc_cache.json in the user's home directory. If
14089 set to a pathname, will use that pathname for the cache.
14090 Note: use this cache with caution as it might be somewhat fragile:
14092 while each major toolset version (e.g. Visual Studio 2017 vs 2019)
14093 and architecture pair will get separate cache entries, if toolset
14094 updates cause a change to settings within a given release series,
14095 scons will not detect the change and will reuse old settings.
14096 Remove the cache file in case of problems with this. scons will
14097 ignore failures reading or writing the file and will silently
14098 revert to non-cached behavior in such cases.
14099 Available since scons 3.1 (experimental).
14101 QTDIR
14103 If using the qt tool, this is the path to the Qt installation to
14104 build against. SCons respects this setting because it is a
14105 long-standing convention in the Qt world, where multiple Qt
14106 installations are possible.
14107
14109 The SCons User Guide at
14110 https://scons.org/doc/production/HTML/scons-user.html
14111 The SCons Design Document (old)
14113 The SCons Cookbook at
14115 https://scons-cookbook.readthedocs.io
14116 for examples of how to solve various problems with SCons.
14117 SCons source code
14120 on GitHub[6]
14121 The SCons API Reference
14124 https://scons.org/doc/production/HTML/scons-api/index.html
14125 (for internal details)
14126
14129 Originally: Steven Knight knight@baldmt.com and Anthony Roach
14130 aroach@electriceyeball.com.
14131 Since 2010: The SCons Development Team scons-dev@scons.org.
14133
14135 The SCons Development Team
14136
14138 Copyright © 2001 - 2023 The SCons Foundation
14139
14141 1. https://github.com/SCons/scons-contrib
14142 https://github.com/SCons/scons-contrib
14143 2. LLVM specification
14145 https://clang.llvm.org/docs/JSONCompilationDatabase.html
14146 3. JEP 313
14148 https:openjdk.java.net/jeps/313
14149 4. If no_progress is set via SetOption in an SConscript file (but not
14151 if set in a site_init.py file) there will still be an initial
14152 status message about reading SConscript files since SCons has to
14153 start reading them before it can see the SetOption.
14154 5. http://www.opensource.org/licenses/alphabetical
14156 http://www.opensource.org/licenses/alphabetical
14157 6. on GitHub
14159 https://github.com/SCons/scons
14160SCons 4.4.0<pVuebrdsaitoen>R4e.l4e.a0sed Sat, 21 Jan 2023 00:00:00 +0000</pubdate> SCONS(1)