1SCONS(1) SCons 4.3.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.5 or later to run; there should be no other
21 dependencies or requirements.
22 Support for Python 3.5 is deprecated since SCons 4.2 and will be
23 dropped in a future release. The CPython project has retired 3.5:
24 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 files. For example
34 if you specify a library target named "foo", scons keeps track of the
35 actual operating system dependent filename (such as libfoo.so on a
36 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, so this does not have to be specified manually.
41 When invoked, scons looks for a file named SConstruct in the current
43 directory and reads the build configuration from that file (other names
44 are allowed, see the section called “SConscript Files” for more
45 information). The SConstruct file may specify subsidiary configuration
46 files by calling the SConscript function. By convention, these
47 subsidiary files are named SConscript, although any name may be used.
48 As a result of this naming convention, the term SConscript files is
49 used to refer generically to the complete set of configuration files
50 for a project (including the SConstruct file), regardless of the actual
51 file names or number of such files.
52 Before reading the SConscript files, scons looks for a directory named
54 site_scons in various system directories and in the directory
55 containing the SConstruct file or, if specified, the directory from the
56 --site-dir option instead, and prepends the ones it finds to the Python
57 module search path (sys.path), thus allowing modules in such
58 directories to be imported in the normal Python way in SConscript
59 files. For each found site directory, (1) if it contains a file
60 site_init.py that file is evaluated, and (2) if it contains a directory
61 site_tools the path to that directory is prepended to the default
62 toolpath. See the --site-dir and --no-site-dir options for details on
63 default paths and controlling the site directories.
64 SConscript files are written in the Python programming language,
66 although it is normally not necessary to be a Python programmer to use
67 scons effectively. SConscript files are invoked in a context that makes
68 the facilities described in this manual page available in their local
69 namespace without any special steps. Standard Python scripting
70 capabilities such as flow control, data manipulation, and imported
71 Python libraries are available to use to handle complicated build
72 situations. Other Python files can be made a part of the build system,
73 but they do not automatically have the SCons context and need to import
74 it if they need access (described later).
75 scons reads and executes all of the included SConscript files before it
77 begins building any targets. To make this clear, scons prints the
78 following messages about what it is doing:
79 $ scons foo.out
81 scons: Reading SConscript files ...
82 scons: done reading SConscript files.
83 scons: Building targets ...
84 cp foo.in foo.out
85 scons: done building targets.
86 $
87 The status messages (lines beginning with the scons: tag) may be
89 suppressed using the -Q option.
90 scons does not automatically propagate the external environment used to
92 execute scons to the commands used to build target files. This is so
93 that builds will be guaranteed repeatable regardless of the environment
94 variables set at the time scons is invoked. This also means that if the
95 compiler or other commands that you want to use to build your target
96 files are not in standard system locations, scons will not find them
97 unless you explicitly include the locations into the execution
98 environment by setting the path in the ENV construction variable in the
99 internal construction environment:
100 import os
102 env = Environment(ENV={'PATH': os.environ['PATH']})
103 Similarly, if the commands use specific external environment variables
105 that scons does not recognize, they can be propagated into the
106 execution environment:
107 import os
109 env = Environment(
111 ENV={
112 'PATH': os.environ['PATH'],
113 'ANDROID_HOME': os.environ['ANDROID_HOME'],
114 'ANDROID_NDK_HOME': os.environ['ANDROID_NDK_HOME'],
115 }
116 )
117 Or you may explicitly propagate the invoking user's complete external
119 environment:
120 import os
122 env = Environment(ENV=os.environ.copy())
123 This comes at the expense of making your build dependent on the user's
125 environment being set correctly, but it may be more convenient for many
126 configurations. It should not cause problems if done in a build setup
127 which tightly controls how the environment is set up before invoking
128 scons, as in many continuous integration setups.
129 scons can scan known input file types automatically for dependency
131 information (for example, #include preprocessor directives in C or C++
132 files) and will rebuild dependent files appropriately whenever any
133 "included" input file changes. scons supports the ability to define
134 new scanners to support additional input file types.
135 scons is normally executed in a top-level directory containing an
137 SConstruct file. When scons is invoked, the command line (including the
138 contents of the SCONSFLAGS environment variable, if set) is processed.
139 Command-line options (see the section called “OPTIONS”) are consumed.
140 Any variable argument assignments are collected, and remaining
141 arguments are taken as targets to build.
142 Values of variables to be passed to the SConscript files may be
144 specified on the command line:
145 scons debug=1
147 These variables are available through the ARGUMENTS dictionary, and can
149 be used in the SConscript files to modify the build in any way:
150 if ARGUMENTS.get('debug', 0):
152 env = Environment(CCFLAGS='-g')
153 else:
154 env = Environment()
155 The command-line variable arguments are also available in the ARGLIST
157 list, indexed by their order on the command line. This allows you to
158 process them in order rather than by name, if necessary. Each ARGLIST
159 entry is a tuple containing (argname, argvalue).
160 See the section called “Command-Line Construction Variables” for more
162 information.
163 scons can maintain a cache of target (derived) files that can be shared
165 between multiple builds. When derived-file caching is enabled in an
166 SConscript file, any target files built by scons will be copied to the
167 cache. If an up-to-date target file is found in the cache, it will be
168 retrieved from the cache instead of being rebuilt locally. Caching
169 behavior may be disabled and controlled in other ways by the
170 --cache-force, --cache-disable, --cache-readonly, and --cache-show
171 command-line options. The --random option is useful to prevent multiple
172 builds from trying to update the cache simultaneously.
173 By default, scons searches for known programming tools on various
175 systems and initializes itself based on what is found. On Windows
176 systems which identify as win32, scons searches in order for the
177 Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler
178 tools, and the PharLap ETS compiler. On Windows system which identify
179 as cygwin (that is, if scons is invoked from a cygwin shell), the order
180 changes to prefer the GCC toolchain over the MSVC tools. On OS/2
181 systems, scons searches in order for the OS/2 compiler, the GCC tool
182 chain, and the Microsoft Visual C++ tools, On SGI IRIX, IBM AIX,
183 Hewlett Packard HP-UX, and Oracle Solaris systems, scons searches for
184 the native compiler tools (MIPSpro, Visual Age, aCC, and Forte tools
185 respectively) and the GCC tool chain. On all other platforms, including
186 POSIX (Linux and UNIX) platforms, scons searches in order for the GCC
187 tool chain, and the Intel compiler tools. These default values may be
188 overridden by appropriate setting of construction variables.
189 Target Selection
191 SCons acts on the selected targets, whether the requested operation is
192 build, no-exec or clean. Targets are selected as follows:
193 1. Targets specified on the command line. These may be files,
195 directories, or phony targets defined using the Alias function.
196 Directory targets are scanned by scons for any targets that may be
197 found with a destination in or under that directory. The targets
198 listed on the command line are made available in the
199 COMMAND_LINE_TARGETS list.
200 2. If no targets are specified on the command line, scons will select
202 those targets specified in the SConscript files via calls to the
203 Default function. These are known as the default targets, and are
204 made available in the DEFAULT_TARGETS list.
205 3. If no targets are selected by the previous steps, scons selects the
207 current directory for scanning, unless command-line options which
208 affect the target scan are detected (-C, -D, -u, -U). Since targets
209 thus selected were not the result of user instructions, this target
210 list is not made available for direct inspection; use the
211 --debug=explain option if they need to be examined.
212 4. scons always adds to the selected targets any intermediate targets
214 which are necessary to build the specified ones. For example, if
215 constructing a shared library or dll from C source files, scons
216 will also build the object files which will make up the library.
217 To ignore the default targets specified through calls to Default and
219 instead build all target files in or below the current directory
220 specify the current directory (.) as a command-line target:
221 scons .
223 To build all target files, including any files outside of the current
225 directory, supply a command-line target of the root directory (on POSIX
226 systems):
227 scons /
229 or the path name(s) of the volume(s) in which all the targets should be
231 built (on Windows systems):
232 scons C:\ D:\
234 A subset of a hierarchical tree may be built by remaining at the
236 top-level directory (where the SConstruct file lives) and specifying
237 the subdirectory as the target to build:
238 scons src/subdir
240 or by changing directory and invoking scons with the -u option, which
242 traverses up the directory hierarchy until it finds the SConstruct
243 file, and then builds targets relatively to the current subdirectory
244 (see also the related -D and -U options):
245 cd src/subdir
247 scons -u .
248 In all cases, more files may be built than are requested, as scons
250 needs to make sure any dependent files are built.
251 Specifying "cleanup" targets in SConscript files is usually not
253 necessary. The -c flag removes all selected targets:
254 scons -c .
256 to remove all target files in or under the current directory, or:
258 scons -c build export
260 to remove target files under build and export.
262 Additional files or directories to remove can be specified using the
264 Clean function in the SConscript files. Conversely, targets that would
265 normally be removed by the -c invocation can be retained by calling the
266 NoClean function with those targets.
267 scons supports building multiple targets in parallel via a -j option
269 that takes, as its argument, the number of simultaneous tasks that may
270 be spawned:
271 scons -j 4
273 builds four targets in parallel, for example.
275
277 In general, scons supports the same command-line options as GNU Make
278 and many of those supported by cons.
279 -b
281 Ignored for compatibility with non-GNU versions of Make
282 -c, --clean, --remove
284 Set clean mode. Clean up by removing the selected targets, well as
285 any files or directories associated with a selected target through
286 calls to the Clean function. Will not remove any targets which are
287 marked for preservation through calls to the NoClean function.
288 While clean mode removes targets rather than building them, work
290 which is done directly in Python code in SConscript files will
291 still be carried out. If it is important to avoid some such work
292 from taking place in clean mode, it should be protected. An
293 SConscript file can determine which mode is active by querying
294 GetOption, as in the call if GetOption("clean"):
295 --cache-debug=file
297 Write debug information about derived-file caching to the specified
298 file. If file is a hyphen (-), the debug information is printed to
299 the standard output. The printed messages describe what
300 signature-file names are being looked for in, retrieved from, or
301 written to the derived-file cache specified by CacheDir.
302 --cache-disable, --no-cache
304 Disable derived-file caching. scons will neither retrieve files
305 from the cache nor copy files to the cache. This option can be used
306 to temporarily disable the cache without modifying the build
307 scripts.
308 --cache-force, --cache-populate
310 When using CacheDir, populate a derived-file cache by copying any
311 already-existing, up-to-date derived files to the cache, in
312 addition to files built by this invocation. This is useful to
313 populate a new cache with all the current derived files, or to add
314 to the cache any derived files recently built with caching disabled
315 via the --cache-disable option.
316 --cache-readonly
318 Use the derived-file cache, if enabled, to retrieve files, but do
319 not not update the cache with any files actually built during this
320 invocation.
321 --cache-show
323 When using a derived-file cache show the command that would have
324 been executed to build the file (or the corresponding *COMSTR
325 contents if set) even if the file is retrieved from cache. Without
326 this option, scons shows a cache retrieval message if the file is
327 fetched from cache. This allows producing consistent output for
328 build logs, regardless of whether a target file was rebuilt or
329 retrieved from the cache.
330 --config=mode
332 Control how the Configure call should use or generate the results
333 of configuration tests. mode should be one of the following
334 choices:
335 auto
337 SCons will use its normal dependency mechanisms to decide if a
338 test must be rebuilt or not. This saves time by not running the
339 same configuration tests every time you invoke scons, but will
340 overlook changes in system header files or external commands
341 (such as compilers) if you don't specify those dependecies
342 explicitly. This is the default behavior.
343 force
345 If this mode is specified, all configuration tests will be
346 re-run regardless of whether the cached results are out of
347 date. This can be used to explicitly force the configuration
348 tests to be updated in response to an otherwise unconfigured
349 change in a system header file or compiler.
350 cache
352 If this mode is specified, no configuration tests will be rerun
353 and all results will be taken from cache. scons will report an
354 error if --config=cache is specified and a necessary test does
355 not have any results in the cache.
356 -C directory, --directory=directory
359 Run as if scons was started in directory instead of the current
360 working directory. That is, change directory before searching for
361 the SConstruct, Sconstruct, sconstruct, SConstruct.py,
362 Sconstruct.py or sconstruct.py file or doing anything else. When
363 multiple -C options are given, each subsequent non-absolute -C
364 directory is interpreted relative to the preceding one. This option
365 is similar to using -f directory/SConstruct, but -f does not search
366 for any of the predefined SConstruct names in the specified
367 directory. See also options -u, -U and -D to change the SConstruct
368 search behavior when this option is used.
369 -D
371 Works exactly the same way as the -u option except for the way
372 default targets are handled. When this option is used and no
373 targets are specified on the command line, all default targets are
374 built, whether or not they are below the current directory.
375 --debug=type[,type...]
377 Debug the build process. type specifies the kind of debugging info
378 to emit. Multiple types may be specified, separated by commas. The
379 following types are recognized:
380 action-timestamps
382 Prints additional time profiling information. For each command,
383 shows the absolute start and end times. This may be useful in
384 debugging parallel builds. Implies the --debug=time option.
385 Available since scons 3.1.
387 count
389 Print how many objects are created of the various classes used
390 internally by SCons before and after reading the SConscript
391 files and before and after building targets. This is not
392 supported when SCons is executed with the Python -O (optimized)
393 option or when the SCons modules have been compiled with
394 optimization (that is, when executing from *.pyo files).
395 duplicate
397 Print a line for each unlink/relink (or copy) of a variant file
398 from its source file. Includes debugging info for unlinking
399 stale variant files, as well as unlinking old targets before
400 building them.
401 explain
403 Print an explanation of why scons is deciding to (re-)build the
404 targets it selects for building.
405 findlibs
407 Instruct the scanner that searches for libraries to print a
408 message about each potential library name it is searching for,
409 and about the actual libraries it finds.
410 includes
412 Print the include tree after each top-level target is built.
413 This is generally used to find out what files are included by
414 the sources of a given derived file:
415 $ scons --debug=includes foo.o
417 memoizer
419 Prints a summary of hits and misses using the Memoizer, an
420 internal subsystem that counts how often SCons uses cached
421 values in memory instead of recomputing them each time they're
422 needed.
423 memory
425 Prints how much memory SCons uses before and after reading the
426 SConscript files and before and after building targets.
427 objects
429 Prints a list of the various objects of the various classes
430 used internally by SCons.
431 pdb
433 Re-run scons under the control of the pdb Python debugger.
434 prepare
436 Print a line each time any target (internal or external) is
437 prepared for building. scons prints this for each target it
438 considers, even if that target is up to date (see also
439 --debug=explain). This can help debug problems with targets
440 that aren't being built; it shows whether scons is at least
441 considering them or not.
442 presub
444 Print the raw command line used to build each target before the
445 construction environment variables are substituted. Also shows
446 which targets are being built by this command. Output looks
447 something like this:
448 $ scons --debug=presub
450 Building myprog.o with action(s):
451 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
452 ...
453 stacktrace
455 Prints an internal Python stack trace when encountering an
456 otherwise unexplained error.
457 time
459 Prints various time profiling information:
460 • The time spent executing each individual build command
462 • The total build time (time SCons ran from beginning to end)
464 • The total time spent reading and executing SConscript files
466 • The total time SCons itself spent running (that is, not
468 counting reading and executing SConscript files)
469 • The total time spent executing all build commands
471 • The elapsed wall-clock time spent executing those build
473 commands
474 • The time spent processing each file passed to the
476 SConscript function
477 (When scons is executed without the -j option, the elapsed
479 wall-clock time will typically be slightly longer than the
480 total time spent executing all the build commands, due to the
481 SCons processing that takes place in between executing each
482 command. When scons is executed with the -j option, and your
483 build configuration allows good parallelization, the elapsed
484 wall-clock time should be significantly smaller than the total
485 time spent executing all the build commands, since multiple
486 build commands and intervening SCons processing should take
487 place in parallel.)
488 --diskcheck=type
491 Enable specific checks for whether or not there is a file on disk
492 where the SCons configuration expects a directory (or vice versa)
493 when searching for source and include files. type can be an
494 available diskcheck type or the special tokens all or none. A
495 comma-separated string can be used to select multiple checks. The
496 default setting is all.
497 Current available checks are:
499 match
501 to check that files and directories on disk match SCons'
502 expected configuration.
503 Disabling some or all of these checks can provide a performance
505 boost for large configurations, or when the configuration will
506 check for files and/or directories across networked or shared file
507 systems, at the slight increased risk of an incorrect build or of
508 not handling errors gracefully.
509 --duplicate=ORDER
511 There are three ways to duplicate files in a build tree: hard
512 links, soft (symbolic) links and copies. The default policy is to
513 prefer hard links to soft links to copies. You can specify a
514 different policy with this option. ORDER must be one of
515 hard-soft-copy (the default), soft-hard-copy, hard-copy, soft-copy
516 or copy. SCons will attempt to duplicate files using the
517 mechanisms in the specified order.
518 --enable-virtualenv
520 Import virtualenv-related variables to SCons.
521 --experimental=feature
523 Enable experimental features and/or tools. feature can be an
524 available feature name or the special tokens all or none. A
525 comma-separated string can be used to select multiple features. The
526 default setting is none.
527 Current available features are: ninja.
529 Caution
531 No Support offered for any features or tools enabled by this
532 flag.
533 Available since scons 4.2.
534 -f file, --file=file, --makefile=file, --sconstruct=file
536 Use file as the initial SConscript file. Multiple -f options may be
537 specified, in which case scons will read all of the specified
538 files.
539 -h, --help
541 Print a local help message for this project, if one is defined in
542 the SConscript files (see the Help function), plus a line that
543 refers to the standard SCons help message. If no local help message
544 is defined, prints the standard SCons help message (as for the -H
545 option) plus help for any local options defined through AddOption.
546 Exits after displaying the appropriate message.
547 Note that use of this option requires SCons to process the
549 SConscript files, so syntax errors may cause the help message not
550 to be displayed.
551 --hash-chunksize=KILOBYTES
553 Set the block size used when computing content signatures to
554 KILOBYTES. This value determines the size of the chunks which are
555 read in at once when computing signature hashes. Files below that
556 size are fully stored in memory before performing the signature
557 computation while bigger files are read in block-by-block. A huge
558 block-size leads to high memory consumption while a very small
559 block-size slows down the build considerably.
560 The default value is to use a chunk size of 64 kilobytes, which
562 should be appropriate for most uses.
563 Available since scons 4.2.
565 --hash-format=ALGORITHM
567 Set the hashing algorithm used by SCons to ALGORITHM. This value
568 determines the hashing algorithm used in generating content
569 signatures or CacheDir keys.
570 The supported list of values are: md5, sha1, and sha256. However,
572 the Python interpreter used to run SCons must have the
573 corresponding support available in the hashlib module to use the
574 specified algorithm.
575 Specifying this value changes the name of the SConsign database.
577 For example, --hash-format=sha256 will create a SConsign database
578 with name .sconsign_sha256.dblite.
579 If this option is not specified, a the first supported hash format
581 found is selected. Typically this is MD5, however, if you are on a
582 FIPS-compliant system and using a version of Python less than 3.9,
583 SHA1 or SHA256 will be chosen as the default. Python 3.9 and
584 onwards clients will always default to MD5, even in FIPS mode,
585 unless otherwise specified with the --hash-format option.
586 For MD5 databases (either explicitly specified with
588 --hash-format=md5 or defaulted), the SConsign database
589 is.sconsign.dblite. The newer SHA1 and SHA256 selections meanwhile
590 store their databases to .sconsign_algorithmname.dblite
591 Available since scons 4.2.
593 -H, --help-options
595 Print the standard help message about SCons command-line options
596 and exit.
597 -i, --ignore-errors
599 Ignore all errors from commands executed to rebuild files.
600 -I directory, --include-dir=directory
602 Specifies a directory to search for imported Python modules. If
603 several -I options are used, the directories are searched in the
604 order specified.
605 --ignore-virtualenv
607 Suppress importing virtualenv-related variables to SCons.
608 --implicit-cache
610 Cache implicit dependencies. This causes scons to use the implicit
611 (scanned) dependencies from the last time it was run instead of
612 scanning the files for implicit dependencies. This can
613 significantly speed up SCons, but with the following limitations:
614 scons will not detect changes to implicit dependency search paths
616 (e.g. CPPPATH, LIBPATH) that would ordinarily cause different
617 versions of same-named files to be used.
618 scons will miss changes in the implicit dependencies in cases where
620 a new implicit dependency is added earlier in the implicit
621 dependency search path (e.g. CPPPATH, LIBPATH) than a current
622 implicit dependency with the same name.
623 --implicit-deps-changed
625 Forces SCons to ignore the cached implicit dependencies. This
626 causes the implicit dependencies to be rescanned and recached. This
627 implies --implicit-cache.
628 --implicit-deps-unchanged
630 Force SCons to ignore changes in the implicit dependencies. This
631 causes cached implicit dependencies to always be used. This implies
632 --implicit-cache.
633 --install-sandbox=sandbox_path
635 When using the Install builders, prepend sandbox_path to the
636 installation paths such that all installed files will be placed
637 under that directory. This option is unavailable if one of Install,
638 InstallAs or InstallVersionedLib is not used in the SConscript
639 files.
640 --interactive
642 Starts SCons in interactive mode. The SConscript files are read
643 once and a scons>>> prompt is printed. Targets may now be rebuilt
644 by typing commands at interactive prompt without having to re-read
645 the SConscript files and re-initialize the dependency graph from
646 scratch.
647 SCons interactive mode supports the following commands:
649 build [OPTIONS] [TARGETS] ...
651 Builds the specified TARGETS (and their dependencies) with the
652 specified SCons command-line OPTIONS. b and scons are synonyms
653 for build.
654 The following SCons command-line options affect the build
656 command:
657 --cache-debug=FILE
659 --cache-disable, --no-cache
660 --cache-force, --cache-populate
661 --cache-readonly
662 --cache-show
663 --debug=TYPE
664 -i, --ignore-errors
665 -j N, --jobs=N
666 -k, --keep-going
667 -n, --no-exec, --just-print, --dry-run, --recon
668 -Q
669 -s, --silent, --quiet
670 --taskmastertrace=FILE
671 --tree=OPTIONS
672 Any other SCons command-line options that are specified do not
674 cause errors but have no effect on the build command (mainly
675 because they affect how the SConscript files are read, which
676 only happens once at the beginning of interactive mode).
677 clean [OPTIONS] [TARGETS] ...
679 Cleans the specified TARGETS (and their dependencies) with the
680 specified OPTIONS. c is a synonym. This command is itself a
681 synonym for build --clean
682 exit
684 Exits SCons interactive mode. You can also exit by terminating
685 input (Ctrl+D UNIX or Linux systems, (Ctrl+Z on Windows
686 systems).
687 help [COMMAND]
689 Provides a help message about the commands available in SCons
690 interactive mode. If COMMAND is specified, h and ? are
691 synonyms.
692 shell [COMMANDLINE]
694 Executes the specified COMMANDLINE in a subshell. If no
695 COMMANDLINE is specified, executes the interactive command
696 interpreter specified in the SHELL environment variable (on
697 UNIX and Linux systems) or the COMSPEC environment variable (on
698 Windows systems). sh and ! are synonyms.
699 version
701 Prints SCons version information.
702 An empty line repeats the last typed command. Command-line editing
704 can be used if the readline module is available.
705 $ scons --interactive
707 scons: Reading SConscript files ...
708 scons: done reading SConscript files.
709 scons>>> build -n prog
710 scons>>> exit
711 -j N, --jobs=N
713 Specifies the maximum number of comcurrent jobs (commands) to run.
714 If there is more than one -j option, the last one is effective.
715 -k, --keep-going
717 Continue as much as possible after an error. The target that failed
718 and those that depend on it will not be remade, but other targets
719 specified on the command line will still be processed.
720 -m
722 Ignored for compatibility with non-GNU versions of Make.
723 --max-drift=SECONDS
725 Set the maximum expected drift in the modification time of files to
726 SECONDS. This value determines how long a file must be unmodified
727 before its cached content signature will be used instead of
728 calculating a new content signature (MD5 checksum) of the file's
729 contents. The default value is 2 days, which means a file must have
730 a modification time of at least two days ago in order to have its
731 cached content signature used. A negative value means to never
732 cache the content signature and to ignore the cached value if there
733 already is one. A value of 0 means to always use the cached
734 signature, no matter how old the file is.
735 --md5-chunksize=KILOBYTES
737 A deprecated synonym for --hash-chunksize.
738 Deprecated since scons 4.2.
740 -n, --no-exec, --just-print, --dry-run, --recon
742 Set no execute mode. Print the commands that would be executed to
743 build any out-of-date target files, but do not execute the
744 commands.
745 The output is a best effort, as SCons cannot always precisely
747 determine what would be built. For example, if a file is generated
748 by a builder action that is later used in the build, that file is
749 not available to scan for dependencies on an unbuilt tree, or may
750 contain out of date information in a built tree.
751 Work which is done directly in Python code in SConscript files, as
753 opposed to work done by builder actions during the build phase,
754 will still be carried out. If it is important to avoid some such
755 work from taking place in no execute mode, it should be protected.
756 An SConscript file can determine which mode is active by querying
757 GetOption, as in the call if GetOption("no_exec"):
758 --no-site-dir
760 Prevents the automatic addition of the standard site_scons dirs to
761 sys.path. Also prevents loading the site_scons/site_init.py modules
762 if they exist, and prevents adding their site_scons/site_tools dirs
763 to the toolpath.
764 --package-type=type
766 The type or types of package to create when using the Package
767 builder. In the case of multiple types, type should be a
768 comma-separated string; SCons will try to build for all of those
769 packages. Note this option is only available if the packaging tool
770 has been enabled.
771 --profile=file
773 Run SCons under the Python profiler and save the results in the
774 specified file. The results may be analyzed using the Python pstats
775 module.
776 -q, --question
778 Do not run any commands, or print anything. Just return an exit
779 status that is zero if the specified targets are already up to
780 date, non-zero otherwise.
781 -Q
783 Quiets SCons status messages about reading SConscript files,
784 building targets and entering directories. Commands that are
785 executed to rebuild target files are still printed.
786 --random
788 Build dependencies in a random order. This is useful when building
789 multiple trees simultaneously with caching enabled, to prevent
790 multiple builds from simultaneously trying to build or retrieve the
791 same target files.
792 -s, --silent, --quiet
794 Silent. Do not print commands that are executed to rebuild target
795 files. Also suppresses SCons status messages.
796 -S, --no-keep-going, --stop
798 Ignored for compatibility with GNU Make
799 --site-dir=dir
801 Uses the named dir as the site directory rather than the default
802 site_scons directories. This directory will be prepended to
803 sys.path, the module dir/site_init.py will be loaded if it exists,
804 and dir/site_tools will be added to the default toolpath.
805 The default set of site_scons directories used when --site-dir is
807 not specified depends on the system platform, as follows.
808 Directories are examined in the order given, from most generic to
809 most specific, so the last-executed site_init.py file is the most
810 specific one (which gives it the chance to override everything
811 else), and the directories are prepended to the paths, again so the
812 last directory examined comes first in the resulting path.
813 Windows:
815 %ALLUSERSPROFILE/Application Data/scons/site_scons
817 %USERPROFILE%/Local Settings/Application Data/scons/site_scons
818 %APPDATA%/scons/site_scons
819 %HOME%/.scons/site_scons
820 ./site_scons
821 Mac OS X:
823 /Library/Application Support/SCons/site_scons
825 /opt/local/share/scons/site_scons (for MacPorts)
826 /sw/share/scons/site_scons (for Fink)
827 $HOME/Library/Application Support/SCons/site_scons
828 $HOME/.scons/site_scons
829 ./site_scons
830 Solaris:
832 /opt/sfw/scons/site_scons
834 /usr/share/scons/site_scons
835 $HOME/.scons/site_scons
836 ./site_scons
837 Linux, HPUX, and other Posix-like systems:
839 /usr/share/scons/site_scons
841 $HOME/.scons/site_scons
842 ./site_scons
843 --stack-size=KILOBYTES
845 Set the size stack used to run threads to KILOBYTES. This value
846 determines the stack size of the threads used to run jobs. These
847 threads execute the actions of the builders for the nodes that are
848 out-of-date. This option has no effect unless the number of
849 concurrent build jobs is larger than one (as set by -j N or
850 --jobs=N on the command line or SetOption in a script).
851 Using a stack size that is too small may cause stack overflow
853 errors. This usually shows up as segmentation faults that cause
854 scons to abort before building anything. Using a stack size that is
855 too large will cause scons to use more memory than required and may
856 slow down the entire build process. The default value is to use a
857 stack size of 256 kilobytes, which should be appropriate for most
858 uses. You should not need to increase this value unless you
859 encounter stack overflow errors.
860 -t, --touch
862 Ignored for compatibility with GNU Make. (Touching a file to make
863 it appear up-to-date is unnecessary when using scons.)
864 --taskmastertrace=file
866 Prints trace information to the specified file about how the
867 internal Taskmaster object evaluates and controls the order in
868 which Nodes are built. A file name of - may be used to specify the
869 standard output.
870 --tree=type[,type...]
872 Prints a tree of the dependencies after each top-level target is
873 built. This prints out some or all of the tree, in various formats,
874 depending on the type specified:
875 all
877 Print the entire dependency tree after each top-level target is
878 built. This prints out the complete dependency tree, including
879 implicit dependencies and ignored dependencies.
880 derived
882 Restricts the tree output to only derived (target) files, not
883 source files.
884 linedraw
886 Draw the tree output using Unicode line-drawing characters
887 instead of plain ASCII text. This option acts as a modifier to
888 the selected type(s). If specified alone, without any type, it
889 behaves as if all had been specified.
890 Available since scons 4.0.
892 status
894 Prints status information for each displayed node.
895 prune
897 Prunes the tree to avoid repeating dependency information for
898 nodes that have already been displayed. Any node that has
899 already been displayed will have its name printed in [square
900 brackets], as an indication that the dependencies for that node
901 can be found by searching for the relevant output higher up in
902 the tree.
903 Multiple type choices may be specified, separated by commas:
905 # Prints only derived files, with status information:
907 scons --tree=derived,status
908 # Prints all dependencies of target, with status information
910 # and pruning dependencies of already-visited Nodes:
911 scons --tree=all,prune,status target
912 -u, --up, --search-up
914 Walks up the directory structure until an SConstruct, Sconstruct,
915 sconstruct, SConstruct.py, Sconstruct.py or sconstruct.py file is
916 found, and uses that as the top of the directory tree. If no
917 targets are specified on the command line, only targets at or below
918 the current directory will be built.
919 -U
921 Works exactly the same way as the -u option except for the way
922 default targets are handled. When this option is used and no
923 targets are specified on the command line, all default targets that
924 are defined in the SConscript(s) in the current directory are
925 built, regardless of what directory the resultant targets end up
926 in.
927 -v, --version
929 Print the scons version, copyright information, list of authors,
930 and any other relevant information. Then exit.
931 -w, --print-directory
933 Print a message containing the working directory before and after
934 other processing.
935 --no-print-directory
937 Turn off -w, even if it was turned on implicitly.
938 --warn=type, --warn=no-type
940 Enable or disable (with the prefix "no-") warnings (--warning is a
941 synonym). type specifies the type of warnings to be enabled or
942 disabled:
943 all
945 All warnings.
946 cache-version
948 Warnings about the derived-file cache directory specified by
949 CacheDir not using the latest configuration information. These
950 warnings are enabled by default.
951 cache-write-error
953 Warnings about errors trying to write a copy of a built file to
954 a specified derived-file cache specified by CacheDir. These
955 warnings are disabled by default.
956 corrupt-sconsign
958 Warnings about unfamiliar signature data in .sconsign files.
959 These warnings are enabled by default.
960 dependency
962 Warnings about dependencies. These warnings are disabled by
963 default.
964 deprecated
966 Warnings about use of currently deprecated features. These
967 warnings are enabled by default. Not all deprecation warnings
968 can be disabled with the --warn=no-deprecated option as some
969 deprecated features which are late in the deprecation cycle may
970 have been designated as mandatory warnings, and these will
971 still display. Warnings for certain deprecated features may
972 also be enabled or disabled individually; see below.
973 duplicate-environment
975 Warnings about attempts to specify a build of a target with two
976 different construction environments that use the same action.
977 These warnings are enabled by default.
978 fortran-cxx-mix
980 Warnings about linking Fortran and C++ object files in a single
981 executable, which can yield unpredictable behavior with some
982 compilers.
983 future-deprecated
985 Warnings about features that will be deprecated in the future.
986 Such warnings are disabled by default. Enabling future
987 deprecation warnings is recommended for projects that
988 redistribute SCons configurations for other users to build, so
989 that the project can be warned as soon as possible about
990 to-be-deprecated features that may require changes to the
991 configuration.
992 link
994 Warnings about link steps.
995 misleading-keywords
997 Warnings about the use of two commonly misspelled keywords
998 targets and sources to Builder calls. The correct spelling is
999 the singular form, even though target and source can themselves
1000 refer to lists of names or nodes.
1001 tool-qt-deprecated
1003 Warnings about the qt tool being deprecated. These warnings are
1004 disabled by default for the first phase of deprecation. Enable
1005 to be reminded about use of this tool module. Available since
1006 SCons 4.3.
1007 missing-sconscript
1009 Warnings about missing SConscript files. These warnings are
1010 enabled by default.
1011 no-object-count
1013 Warnings about the --debug=object feature not working when
1014 scons is run with the Python -O option or from optimized Python
1015 (.pyo) modules.
1016 no-parallel-support
1018 Warnings about the version of Python not being able to support
1019 parallel builds when the -j option is used. These warnings are
1020 enabled by default.
1021 python-version
1023 Warnings about running SCons with a deprecated version of
1024 Python. These warnings are enabled by default.
1025 reserved-variable
1027 Warnings about attempts to set the reserved construction
1028 variable names $CHANGED_SOURCES, $CHANGED_TARGETS, $TARGET,
1029 $TARGETS, $SOURCE, $SOURCES, $UNCHANGED_SOURCES or
1030 $UNCHANGED_TARGETS. These warnings are disabled by default.
1031 stack-size
1033 Warnings about requests to set the stack size that could not be
1034 honored. These warnings are enabled by default.
1035 target_not_build
1037 Warnings about a build rule not building the expected targets.
1038 These warnings are disabled by default.
1039 -Y repository, --repository=repository, --srcdir=repository
1042 Search the specified repository for any input and target files not
1043 found in the local directory hierarchy. Multiple -Y options may be
1044 specified, in which case the repositories are searched in the order
1045 specified.
1046
1048 SConscript Files
1049 The build configuration is described by one or more files, known as
1050 SConscript files. There must be at least one file for a valid build
1051 (scons will quit if it does not find one). scons by default looks for
1052 this file by the name SConstruct in the directory from which you run
1053 scons, though if necessary, also looks for alternative file names
1054 Sconstruct, sconstruct, SConstruct.py, Sconstruct.py and sconstruct.py
1055 in that order. A different file name (which can include a pathname
1056 part) may be specified via the -f option. Except for the SConstruct
1057 file, these files are not searched for automatically; you add
1058 additional configuration files to the build by calling the SConscript
1059 function. This allows parts of the build to be conditionally included
1060 or excluded at run-time depending on how scons is invoked.
1061 Each SConscript file in a build configuration is invoked independently
1063 in a separate context. This provides necessary isolation so that
1064 different parts of the build don't accidentally step on each other. You
1065 have to be explicit about sharing information, by using the Export
1066 function or the exports argument to the SConscript function, as well as
1067 the Return function in a called SConscript file, and comsume shared
1068 information by using the Import function.
1069 The following sections describe the various SCons facilities that can
1071 be used in SConscript files. Quick links:
1072 Construction Environments
1073 Tools
1074 Builder Methods
1075 Methods and Functions to do Things
1076 SConscript Variables
1077 Construction Variables
1078 Configure Contexts
1079 Command-Line Construction Variables
1080 Node Objects
1081 Construction Environments
1083 A Construction Environment is the basic means by which you communicate
1084 build information to SCons. A new construction environment is created
1085 using the Environment function:
1086 env = Environment()
1088 Construction environment attributes called Construction Variables may
1090 be set either by specifying them as keyword arguments when the object
1091 is created or by assigning them a value after the object is created.
1092 These two are nominally equivalent:
1093 env = Environment(FOO='foo')
1095 env['FOO'] = 'foo'
1096 Note that certain settings which affect tool detection are referenced
1098 only when the tools are initializided, so you either need either to
1099 supply them as part of the call to Environment, or defer tool
1100 initialization. For example, initializing the Microsoft Visual C++
1101 version you wish to use:
1102 # initializes msvc to v14.1
1104 env = Environment(MSVC_VERSION="14.1")
1105 env = Environment()
1107 # msvc tool was initialized to default, does not reinitialize
1108 env['MSVC_VERSION'] = "14.1"
1109 env = Environment(tools=[])
1111 env['MSVC_VERSION'] = "14.1"
1112 # msvc tool initialization was deferred, so will pick up new value
1113 env.Tool('default')
1114 As a convenience, construction variables may also be set or modified by
1116 the parse_flags keyword argument during object creation, which has the
1117 effect of the env.MergeFlags method being applied to the argument value
1118 after all other processing is completed. This is useful either if the
1119 exact content of the flags is unknown (for example, read from a control
1120 file) or if the flags need to be distributed to a number of
1121 construction variables. env.ParseFlags describes how these arguments
1122 are distributed to construction variables.
1123 env = Environment(parse_flags='-Iinclude -DEBUG -lm')
1125 This example adds 'include' to the CPPPATH construction variable,
1127 'EBUG' to CPPDEFINES, and 'm' to LIBS.
1128 An existing construction environment can be duplicated by calling the
1130 env.Clone method. Without arguments, it will be a copy with the same
1131 settings. Otherwise, env.Clone takes the same arguments as Environment,
1132 and uses the arguments to create a modified copy.
1133 SCons provides a special construction environment called the Default
1135 Environment. The default environment is used only for global functions,
1136 that is, construction activities called without the context of a
1137 regular construction environment. See DefaultEnvironment for more
1138 information.
1139 By default, a new construction environment is initialized with a set of
1141 builder methods and construction variables that are appropriate for the
1142 current platform. The optional platform keyword argument may be used to
1143 specify that the construction environment should be initialized for a
1144 different platform:
1145 env = Environment(platform='cygwin')
1147 Specifying a platform initializes the appropriate construction
1149 variables in the environment to use and generate file names with
1150 prefixes and suffixes appropriate for that platform.
1151 Note that the win32 platform adds the SystemDrive and SystemRoot
1153 variables from the user's external environment to the construction
1154 environment's ENV dictionary. This is so that any executed commands
1155 that use sockets to connect with other systems will work on Windows
1156 systems.
1157 The platform argument may be a string value representing one of the
1159 pre-defined platforms (aix, cygwin, darwin, hpux, irix, os2, posix,
1160 sunos or win32), or it may be be a callable platform object returned by
1161 a call to Platform selecting a pre-defined platform, or it may be a
1162 user-supplied callable, in which case the Environment method will call
1163 it to update the new construction environment:
1164 def my_platform(env):
1166 env['VAR'] = 'xyzzy'
1167 env = Environment(platform=my_platform)
1169 Note that supplying a non-default platform or custom fuction for
1171 initialization may bypass settings that should happen for the host
1172 system and should be used with care. It is most useful in the case
1173 where the platform is an alternative for the one that would be
1174 auto-detected, such as platform="cygwin" on a system which would
1175 otherwise identify as win32.
1176 The optional tools and toolpath keyword arguments affect the way tools
1178 available to the environment are initialized. See the section called
1179 “Tools” for details.
1180 The optional variables keyword argument allows passing a Variables
1182 object which will be used in the initialization of the construction
1183 environment See the section called “Command-Line Construction
1184 Variables” for details.
1185 Tools
1187 SCons has a large number of predefined tools (more properly, tool
1188 specifications) which are used to help initialize the construction
1189 environment. An SCons tool is only responsible for setup. For example,
1190 if the SConscript file declares the need to construct an object file
1191 from a C-language source file by calling the Object builder, then a
1192 tool representing an available C compiler needs to have run first, to
1193 set up that builder and all the construction variables it needs in the
1194 associated construction environment; the tool itself is not called in
1195 the process of the build. Normally this happens invisibly: scons has
1196 per-platform lists of default tools, and it runs through those tools,
1197 calling the ones which are actually applicable, skipping those where
1198 necessary programs are not installed on the build system, or other
1199 preconditions are not met.
1200 A specific set of tools with which to initialize an environment when
1202 creating it may be specified using the optional keyword argument tools,
1203 which takes a list of tool names. This is useful to override the
1204 defaults, to specify non-default built-in tools, and to supply added
1205 tools:
1206 env = Environment(tools=['msvc', 'lex'])
1208 Tools can also be directly called by using the Tool method (see below).
1210 The tools argument overrides the default tool list, it does not add to
1212 it, so be sure to include all the tools you need. For example if you
1213 are building a c/c++ program you must specify a tool for at least a
1214 compiler and a linker, as in tools=['clang', 'link']. The tool name
1215 'default' can be used to retain the default list.
1216 If no tools argument is specified, or if tools includes 'default', then
1218 scons will auto-detect usable tools, using the execution environment
1219 value of PATH (that is, env['ENV']['PATH'] - the external evironment
1220 PATH from os.environ is not used) for looking up any backing programs,
1221 and the platform name in effect to determine the default tools for that
1222 platform. Changing the PATH variable after the construction environment
1223 is constructed will not cause the tools to be re-detected.
1224 Additional tools can be added to a project either by placing them in a
1226 site_tools subdirectory of a site directory, or in a custom location
1227 specified to scons by giving the toolpath keyword argument. toolpath
1228 also takes a list as its value:
1229 env = Environment(tools=['default', 'foo'], toolpath=['tools'])
1231 This looks for a tool specification module foo.py in directory tools
1233 and in the standard locations, as well as using the ordinary default
1234 tools for the platform.
1235 Directories specified via toolpath are prepended to the existing tool
1237 path. The default tool path is any site_tools directories, so tools in
1238 a specified toolpath take priority, followed by tools in a site_tools
1239 directory, followed by built-in tools. For example, adding a tool
1240 specification module gcc.py to the toolpath directory would override
1241 the built-in gcc tool. The tool path is stored in the environment and
1242 will be used by subsequent calls to the Tool method, as well as by
1243 env.Clone.
1244 base = Environment(toolpath=['custom_path'])
1246 derived = base.Clone(tools=['custom_tool'])
1247 derived.CustomBuilder()
1248 A tool specification module must include two functions:
1250 generate(env, **kwargs)
1252 Modifies the environment referenced by env to set up variables so
1253 that the facilities represented by the tool can be executed. It may
1254 use any keyword arguments that the user supplies in kwargs to vary
1255 its initialization.
1256 exists(env)
1258 Return True if the tool can be called in the context of env.
1259 Usually this means looking up one or more known programs using the
1260 PATH from the supplied env, but the tool can make the "exists"
1261 decision in any way it chooses.
1262 Note
1264 At the moment, user-added tools do not automatically have their
1265 exists function called. As a result, it is recommended that the
1266 generate function be defensively coded - that is, do not rely on
1267 any necessary existence checks already having been performed. This
1268 is expected to be a temporary limitation, and the exists function
1269 should still be provided.
1270 The elements of the tools list may also be functions or callable
1272 objects, in which case the Environment method will call those objects
1273 to update the new construction environment (see Tool for more details):
1274 def my_tool(env):
1276 env['XYZZY'] = 'xyzzy'
1277 env = Environment(tools=[my_tool])
1279 The individual elements of the tools list may also themselves be lists
1281 or tuples of the form (toolname, kw_dict). SCons searches for the
1282 toolname specification file as described above, and passes kw_dict,
1283 which must be a dictionary, as keyword arguments to the tool's generate
1284 function. The generate function can use the arguments to modify the
1285 tool's behavior by setting up the environment in different ways or
1286 otherwise changing its initialization.
1287 # in tools/my_tool.py:
1289 def generate(env, **kwargs):
1290 # Sets MY_TOOL to the value of keyword 'arg1' '1' if not supplied
1291 env['MY_TOOL'] = kwargs.get('arg1', '1')
1292 def exists(env):
1294 return True
1295 # in SConstruct:
1297 env = Environment(tools=['default', ('my_tool', {'arg1': 'abc'})],
1298 toolpath=['tools'])
1299 The tool specification (my_tool in the example) can use the PLATFORM
1301 variable from the construction environment it is passed to customize
1302 the tool for different platforms.
1303 Tools can be "nested" - that is, they can be located within a
1305 subdirectory in the toolpath. A nested tool name uses a dot to
1306 represent a directory separator
1307 # namespaced builder
1309 env = Environment(ENV=os.environ.copy(), tools=['SubDir1.SubDir2.SomeTool'])
1310 env.SomeTool(targets, sources)
1311 # Search Paths
1313 # SCons\Tool\SubDir1\SubDir2\SomeTool.py
1314 # SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
1315 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
1316 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
1317 SCons supports the following tool specifications out of the box:
1319 386asm
1321 Sets construction variables for the 386ASM assembler for the Phar
1322 Lap ETS embedded operating system.
1323 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1325 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1327 aixc++
1329 Sets construction variables for the IMB xlc / Visual Age C++
1330 compiler.
1331 Sets: $CXX, $CXXVERSION, $SHCXX, $SHOBJSUFFIX.
1333 aixcc
1335 Sets construction variables for the IBM xlc / Visual Age C
1336 compiler.
1337 Sets: $CC, $CCVERSION, $SHCC.
1339 aixf77
1341 Sets construction variables for the IBM Visual Age f77 Fortran
1342 compiler.
1343 Sets: $F77, $SHF77.
1345 aixlink
1347 Sets construction variables for the IBM Visual Age linker.
1348 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1350 applelink
1352 Sets construction variables for the Apple linker (similar to the
1353 GNU linker).
1354 Sets: $APPLELINK_COMPATIBILITY_VERSION, $APPLELINK_CURRENT_VERSION,
1356 $APPLELINK_NO_COMPATIBILITY_VERSION, $APPLELINK_NO_CURRENT_VERSION,
1357 $FRAMEWORKPATHPREFIX, $LDMODULECOM, $LDMODULEFLAGS,
1358 $LDMODULEPREFIX, $LDMODULESUFFIX, $LINKCOM, $SHLINKCOM,
1359 $SHLINKFLAGS, $_APPLELINK_COMPATIBILITY_VERSION,
1360 $_APPLELINK_CURRENT_VERSION, $_FRAMEWORKPATH, $_FRAMEWORKS.
1361 Uses: $FRAMEWORKSFLAGS.
1363 ar
1365 Sets construction variables for the ar library archiver.
1366 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $RANLIB,
1368 $RANLIBCOM, $RANLIBFLAGS.
1369 as
1371 Sets construction variables for the as assembler.
1372 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1374 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1376 bcc32
1378 Sets construction variables for the bcc32 compiler.
1379 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1381 $CPPDEFSUFFIX, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS,
1382 $SHCFLAGS, $SHOBJSUFFIX.
1383 Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS.
1385 cc
1387 Sets construction variables for generic POSIX C compilers.
1388 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1390 $CPPDEFSUFFIX, $FRAMEWORKPATH, $FRAMEWORKS, $INCPREFIX, $INCSUFFIX,
1391 $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX.
1392 Uses: $CCCOMSTR, $PLATFORM, $SHCCCOMSTR.
1394 clang
1396 Set construction variables for the Clang C compiler.
1397 Sets: $CC, $CCVERSION, $SHCCFLAGS.
1399 clangxx
1401 Set construction variables for the Clang C++ compiler.
1402 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX,
1404 $STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME.
1405 compilation_db
1407 Sets up CompilationDatabase builder which generates a clang tooling
1408 compatible compilation database.
1409 Sets: $COMPILATIONDB_COMSTR, $COMPILATIONDB_PATH_FILTER,
1411 $COMPILATIONDB_USE_ABSPATH.
1412 cvf
1414 Sets construction variables for the Compaq Visual Fortran compiler.
1415 Sets: $FORTRAN, $FORTRANCOM, $FORTRANMODDIR, $FORTRANMODDIRPREFIX,
1417 $FORTRANMODDIRSUFFIX, $FORTRANPPCOM, $OBJSUFFIX, $SHFORTRANCOM,
1418 $SHFORTRANPPCOM.
1419 Uses: $CPPFLAGS, $FORTRANFLAGS, $SHFORTRANFLAGS, $_CPPDEFFLAGS,
1421 $_FORTRANINCFLAGS, $_FORTRANMODFLAG.
1422 cXX
1424 Sets construction variables for generic POSIX C++ compilers.
1425 Sets: $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX,
1427 $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJSUFFIX, $SHCXX, $SHCXXCOM,
1428 $SHCXXFLAGS, $SHOBJSUFFIX.
1429 Uses: $CXXCOMSTR, $SHCXXCOMSTR.
1431 cyglink
1433 Set construction variables for cygwin linker/loader.
1434 Sets: $IMPLIBPREFIX, $IMPLIBSUFFIX, $LDMODULEVERSIONFLAGS,
1436 $LINKFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBPREFIX, $SHLIBSUFFIX,
1437 $SHLIBVERSIONFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1438 $_LDMODULEVERSIONFLAGS, $_SHLIBVERSIONFLAGS.
1439 default
1441 Sets construction variables for a default list of Tool modules. Use
1442 default in the tools list to retain the original defaults, since
1443 the tools parameter is treated as a literal statement of the tools
1444 to be made available in that construction environment, not an
1445 addition.
1446 The list of tools selected by default is not static, but is
1448 dependent both on the platform and on the software installed on the
1449 platform. Some tools will not initialize if an underlying command
1450 is not found, and some tools are selected from a list of choices on
1451 a first-found basis. The finished tool list can be examined by
1452 inspecting the $TOOLS construction variable in the construction
1453 environment.
1454 On all platforms, the tools from the following list are selected if
1456 their respective conditions are met: filesystem;, wix, lex, yacc,
1457 rpcgen, swig, jar, javac, javah, rmic, dvipdf, dvips, gs, tex,
1458 latex, pdflatex, pdftex, tar, zip, textfile.
1459 On Linux systems, the default tools list selects (first-found): a C
1461 compiler from gcc, intelc, icc, cc; a C++ compiler from g++,
1462 intelc, icc, cXX; an assembler from gas, nasm, masm; a linker from
1463 gnulink, ilink; a Fortran compiler from gfortran, g77, ifort, ifl,
1464 f95, f90, f77; and a static archiver ar. It also selects all found
1465 from the list m4 rpm.
1466 On Windows systems, the default tools list selects (first-found): a
1468 C compiler from msvc, mingw, gcc, intelc, icl, icc, cc, bcc32; a
1469 C++ compiler from msvc, intelc, icc, g++, cXX, bcc32; an assembler
1470 from masm, nasm, gas, 386asm; a linker from mslink, gnulink, ilink,
1471 linkloc, ilink32; a Fortran compiler from gfortran, g77, ifl, cvf,
1472 f95, f90, fortran; and a static archiver from mslib, ar, tlib; It
1473 also selects all found from the list msvs, midl.
1474 On MacOS systems, the default tools list selects (first-found): a C
1476 compiler from gcc, cc; a C++ compiler from g++, cXX; an assembler
1477 as; a linker from applelink, gnulink; a Fortran compiler from
1478 gfortran, f95, f90, g77; and a static archiver ar. It also selects
1479 all found from the list m4, rpm.
1480 Default lists for other platforms can be found by examining the
1482 scons source code (see SCons/Tool/__init__.py).
1483 dmd
1485 Sets construction variables for D language compiler DMD.
1486 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1488 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1489 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1490 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1491 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1492 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1493 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1494 $SHDLINKCOM, $SHDLINKFLAGS.
1495 docbook
1497 This tool tries to make working with Docbook in SCons a little
1498 easier. It provides several toolchains for creating different
1499 output formats, like HTML or PDF. Contained in the package is a
1500 distribution of the Docbook XSL stylesheets as of version 1.76.1.
1501 As long as you don't specify your own stylesheets for
1502 customization, these official versions are picked as
1503 default...which should reduce the inevitable setup hassles for you.
1504 Implicit dependencies to images and XIncludes are detected
1506 automatically if you meet the HTML requirements. The additional
1507 stylesheet utils/xmldepend.xsl by Paul DuBois is used for this
1508 purpose.
1509 Note, that there is no support for XML catalog resolving offered!
1511 This tool calls the XSLT processors and PDF renderers with the
1512 stylesheets you specified, that's it. The rest lies in your hands
1513 and you still have to know what you're doing when resolving names
1514 via a catalog.
1515 For activating the tool "docbook", you have to add its name to the
1517 Environment constructor, like this
1518 env = Environment(tools=['docbook'])
1520 On its startup, the docbook tool tries to find a required xsltproc
1522 processor, and a PDF renderer, e.g. fop. So make sure that these
1523 are added to your system's environment PATH and can be called
1524 directly without specifying their full path.
1525 For the most basic processing of Docbook to HTML, you need to have
1527 installed
1528 • the Python lxml binding to libxml2, or
1530 • a standalone XSLT processor, currently detected are xsltproc,
1532 saxon, saxon-xslt and xalan.
1533 Rendering to PDF requires you to have one of the applications fop
1535 or xep installed.
1536 Creating a HTML or PDF document is very simple and straightforward.
1538 Say
1539 env = Environment(tools=['docbook'])
1541 env.DocbookHtml('manual.html', 'manual.xml')
1542 env.DocbookPdf('manual.pdf', 'manual.xml')
1543 to get both outputs from your XML source manual.xml. As a shortcut,
1545 you can give the stem of the filenames alone, like this:
1546 env = Environment(tools=['docbook'])
1548 env.DocbookHtml('manual')
1549 env.DocbookPdf('manual')
1550 and get the same result. Target and source lists are also
1552 supported:
1553 env = Environment(tools=['docbook'])
1555 env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])
1556 or even
1558 env = Environment(tools=['docbook'])
1560 env.DocbookHtml(['manual','reference'])
1561 Important
1564 Whenever you leave out the list of sources, you may not specify
1565 a file extension! The Tool uses the given names as file stems,
1566 and adds the suffixes for target and source files accordingly.
1567 The rules given above are valid for the Builders DocbookHtml,
1568 DocbookPdf, DocbookEpub, DocbookSlidesPdf and DocbookXInclude. For
1569 the DocbookMan transformation you can specify a target name, but
1570 the actual output names are automatically set from the refname
1571 entries in your XML source.
1572 The Builders DocbookHtmlChunked, DocbookHtmlhelp and
1574 DocbookSlidesHtml are special, in that:
1575 1. they create a large set of files, where the exact names and
1577 their number depend on the content of the source file, and
1578 2. the main target is always named index.html, i.e. the output
1580 name for the XSL transformation is not picked up by the
1581 stylesheets.
1582 As a result, there is simply no use in specifying a target HTML
1584 name. So the basic syntax for these builders is always:
1585 env = Environment(tools=['docbook'])
1587 env.DocbookHtmlhelp('manual')
1588 If you want to use a specific XSL file, you can set the additional
1590 xsl parameter to your Builder call as follows:
1591 env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl')
1593 Since this may get tedious if you always use the same local naming
1595 for your customized XSL files, e.g. html.xsl for HTML and pdf.xsl
1596 for PDF output, a set of variables for setting the default XSL name
1597 is provided. These are:
1598 DOCBOOK_DEFAULT_XSL_HTML
1600 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
1601 DOCBOOK_DEFAULT_XSL_HTMLHELP
1602 DOCBOOK_DEFAULT_XSL_PDF
1603 DOCBOOK_DEFAULT_XSL_EPUB
1604 DOCBOOK_DEFAULT_XSL_MAN
1605 DOCBOOK_DEFAULT_XSL_SLIDESPDF
1606 DOCBOOK_DEFAULT_XSL_SLIDESHTML
1607 and you can set them when constructing your environment:
1609 env = Environment(
1611 tools=['docbook'],
1612 DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
1613 DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl',
1614 )
1615 env.DocbookHtml('manual') # now uses html.xsl
1616 Sets: $DOCBOOK_DEFAULT_XSL_EPUB, $DOCBOOK_DEFAULT_XSL_HTML,
1618 $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED, $DOCBOOK_DEFAULT_XSL_HTMLHELP,
1619 $DOCBOOK_DEFAULT_XSL_MAN, $DOCBOOK_DEFAULT_XSL_PDF,
1620 $DOCBOOK_DEFAULT_XSL_SLIDESHTML, $DOCBOOK_DEFAULT_XSL_SLIDESPDF,
1621 $DOCBOOK_FOP, $DOCBOOK_FOPCOM, $DOCBOOK_FOPFLAGS, $DOCBOOK_XMLLINT,
1622 $DOCBOOK_XMLLINTCOM, $DOCBOOK_XMLLINTFLAGS, $DOCBOOK_XSLTPROC,
1623 $DOCBOOK_XSLTPROCCOM, $DOCBOOK_XSLTPROCFLAGS,
1624 $DOCBOOK_XSLTPROCPARAMS.
1625 Uses: $DOCBOOK_FOPCOMSTR, $DOCBOOK_XMLLINTCOMSTR,
1627 $DOCBOOK_XSLTPROCCOMSTR.
1628 dvi
1630 Attaches the DVI builder to the construction environment.
1631 dvipdf
1633 Sets construction variables for the dvipdf utility.
1634 Sets: $DVIPDF, $DVIPDFCOM, $DVIPDFFLAGS.
1636 Uses: $DVIPDFCOMSTR.
1638 dvips
1640 Sets construction variables for the dvips utility.
1641 Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX.
1643 Uses: $PSCOMSTR.
1645 f03
1647 Set construction variables for generic POSIX Fortran 03 compilers.
1648 Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM,
1650 $SHF03FLAGS, $SHF03PPCOM, $_F03INCFLAGS.
1651 Uses: $F03COMSTR, $F03PPCOMSTR, $SHF03COMSTR, $SHF03PPCOMSTR.
1653 f08
1655 Set construction variables for generic POSIX Fortran 08 compilers.
1656 Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM,
1658 $SHF08FLAGS, $SHF08PPCOM, $_F08INCFLAGS.
1659 Uses: $F08COMSTR, $F08PPCOMSTR, $SHF08COMSTR, $SHF08PPCOMSTR.
1661 f77
1663 Set construction variables for generic POSIX Fortran 77 compilers.
1664 Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM,
1666 $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHF77,
1667 $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM,
1668 $SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS.
1669 Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMSTR, $FORTRANPPCOMSTR,
1671 $SHF77COMSTR, $SHF77PPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANPPCOMSTR.
1672 f90
1674 Set construction variables for generic POSIX Fortran 90 compilers.
1675 Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM,
1677 $SHF90FLAGS, $SHF90PPCOM, $_F90INCFLAGS.
1678 Uses: $F90COMSTR, $F90PPCOMSTR, $SHF90COMSTR, $SHF90PPCOMSTR.
1680 f95
1682 Set construction variables for generic POSIX Fortran 95 compilers.
1683 Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM,
1685 $SHF95FLAGS, $SHF95PPCOM, $_F95INCFLAGS.
1686 Uses: $F95COMSTR, $F95PPCOMSTR, $SHF95COMSTR, $SHF95PPCOMSTR.
1688 fortran
1690 Set construction variables for generic POSIX Fortran compilers.
1691 Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN,
1693 $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM.
1694 Uses: $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SHFORTRANCOMSTR,
1696 $SHFORTRANPPCOMSTR.
1697 g++
1699 Set construction variables for the g++ C++ compiler.
1700 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX.
1702 g77
1704 Set construction variables for the g77 Fortran compiler. Calls the
1705 f77 Tool module to set variables.
1706 gas
1708 Sets construction variables for the gas assembler. Calls the as
1709 tool.
1710 Sets: $AS.
1712 gcc
1714 Set construction variables for the gcc C compiler.
1715 Sets: $CC, $CCVERSION, $SHCCFLAGS.
1717 gdc
1719 Sets construction variables for the D language compiler GDC.
1720 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1722 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1723 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1724 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1725 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1726 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1727 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1728 $SHDLINKCOM, $SHDLINKFLAGS.
1729 gettext
1731 This is actually a toolset, which supports internationalization and
1732 localization of software being constructed with SCons. The toolset
1733 loads following tools:
1734 • xgettext - to extract internationalized messages from source
1738 code to POT file(s),
1739 • msginit - may be optionally used to initialize PO files,
1741 • msgmerge - to update PO files, that already contain translated
1743 messages,
1744 • msgfmt - to compile textual PO file to binary installable MO
1746 file.
1747 When you enable gettext, it internally loads all abovementioned
1749 tools, so you're encouraged to see their individual documentation.
1750 Each of the above tools provides its own builder(s) which may be
1752 used to perform particular activities related to software
1753 internationalization. You may be however interested in top-level
1754 Translate builder.
1755 To use gettext tools add 'gettext' tool to your environment:
1757 env = Environment( tools = ['default', 'gettext'] )
1759 gfortran
1761 Sets construction variables for the GNU F95/F2003 GNU compiler.
1762 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1764 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1765 gnulink
1767 Set construction variables for GNU linker/loader.
1768 Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX,
1770 $SHLIBVERSIONFLAGS, $SHLINKFLAGS, $_LDMODULESONAME, $_SHLIBSONAME.
1771 gs
1773 This Tool sets the required construction variables for working with
1774 the Ghostscript software. It also registers an appropriate Action
1775 with the PDF Builder, such that the conversion from PS/EPS to PDF
1776 happens automatically for the TeX/LaTeX toolchain. Finally, it adds
1777 an explicit Gs Builder for Ghostscript to the environment.
1778 Sets: $GS, $GSCOM, $GSFLAGS.
1780 Uses: $GSCOMSTR.
1782 hpc++
1784 Set construction variables for the compilers aCC on HP/UX systems.
1785 hpcc
1787 Set construction variables for aCC compilers on HP/UX systems.
1788 Calls the cXX tool for additional variables.
1789 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS.
1791 hplink
1793 Sets construction variables for the linker on HP/UX systems.
1794 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1796 icc
1798 Sets construction variables for the icc compiler on OS/2 systems.
1799 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1801 $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX.
1802 Uses: $CCFLAGS, $CFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1804 icl
1806 Sets construction variables for the Intel C/C++ compiler. Calls the
1807 intelc Tool module to set its variables.
1808 ifl
1810 Sets construction variables for the Intel Fortran compiler.
1811 Sets: $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHFORTRANCOM,
1813 $SHFORTRANPPCOM.
1814 Uses: $CPPFLAGS, $FORTRANFLAGS, $_CPPDEFFLAGS, $_FORTRANINCFLAGS.
1816 ifort
1818 Sets construction variables for newer versions of the Intel Fortran
1819 compiler for Linux.
1820 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1822 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1823 ilink
1825 Sets construction variables for the ilink linker on OS/2 systems.
1826 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1828 $LINK, $LINKCOM, $LINKFLAGS.
1829 ilink32
1831 Sets construction variables for the Borland ilink32 linker.
1832 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1834 $LINK, $LINKCOM, $LINKFLAGS.
1835 install
1837 Sets construction variables for file and directory installation.
1838 Sets: $INSTALL, $INSTALLSTR.
1840 intelc
1842 Sets construction variables for the Intel C/C++ compiler (Linux and
1843 Windows, version 7 and later). Calls the gcc or msvc (on Linux and
1844 Windows, respectively) tool to set underlying variables.
1845 Sets: $AR, $CC, $CXX, $INTEL_C_COMPILER_VERSION, $LINK.
1847 jar
1849 Sets construction variables for the jar utility.
1850 Sets: $JAR, $JARCOM, $JARFLAGS, $JARSUFFIX.
1852 Uses: $JARCOMSTR.
1854 javac
1856 Sets construction variables for the javac compiler.
1857 Sets: $JAVABOOTCLASSPATH, $JAVAC, $JAVACCOM, $JAVACFLAGS,
1859 $JAVACLASSPATH, $JAVACLASSSUFFIX, $JAVAINCLUDES, $JAVASOURCEPATH,
1860 $JAVASUFFIX.
1861 Uses: $JAVACCOMSTR.
1863 javah
1865 Sets construction variables for the javah tool.
1866 Sets: $JAVACLASSSUFFIX, $JAVAH, $JAVAHCOM, $JAVAHFLAGS.
1868 Uses: $JAVACLASSPATH, $JAVAHCOMSTR.
1870 latex
1872 Sets construction variables for the latex utility.
1873 Sets: $LATEX, $LATEXCOM, $LATEXFLAGS.
1875 Uses: $LATEXCOMSTR.
1877 ldc
1879 Sets construction variables for the D language compiler LDC2.
1880 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1882 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1883 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1884 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1885 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1886 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DVERPREFIX, $DVERSIONS,
1887 $DVERSUFFIX, $SHDC, $SHDCOM, $SHDLIBVERSIONFLAGS, $SHDLINK,
1888 $SHDLINKCOM, $SHDLINKFLAGS.
1889 lex
1891 Sets construction variables for the lex lexical analyser.
1892 Sets: $LEX, $LEXCOM, $LEXFLAGS, $LEXUNISTD.
1894 Uses: $LEXCOMSTR.
1896 link
1898 Sets construction variables for generic POSIX linkers. This is a
1899 "smart" linker tool which selects a compiler to complete the
1900 linking based on the types of source files.
1901 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS,
1903 $LDMODULENOVERSIONSYMLINKS, $LDMODULEPREFIX, $LDMODULESUFFIX,
1904 $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREFIX,
1905 $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM,
1906 $LINKFLAGS, $SHLIBSUFFIX, $SHLINK, $SHLINKCOM, $SHLINKFLAGS,
1907 $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS.
1908 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $SHLINKCOMSTR.
1910 linkloc
1912 Sets construction variables for the LinkLoc linker for the Phar Lap
1913 ETS embedded operating system.
1914 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1916 $LINK, $LINKCOM, $LINKFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
1917 Uses: $LINKCOMSTR, $SHLINKCOMSTR.
1919 m4
1921 Sets construction variables for the m4 macro processor.
1922 Sets: $M4, $M4COM, $M4FLAGS.
1924 Uses: $M4COMSTR.
1926 masm
1928 Sets construction variables for the Microsoft assembler.
1929 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1931 Uses: $ASCOMSTR, $ASPPCOMSTR, $CPPFLAGS, $_CPPDEFFLAGS,
1933 $_CPPINCFLAGS.
1934 midl
1936 Sets construction variables for the Microsoft IDL compiler.
1937 Sets: $MIDL, $MIDLCOM, $MIDLFLAGS.
1939 Uses: $MIDLCOMSTR.
1941 mingw
1943 Sets construction variables for MinGW (Minimal Gnu on Windows).
1944 Sets: $AS, $CC, $CXX, $LDMODULECOM, $LIBPREFIX, $LIBSUFFIX,
1946 $OBJSUFFIX, $RC, $RCCOM, $RCFLAGS, $RCINCFLAGS, $RCINCPREFIX,
1947 $RCINCSUFFIX, $SHCCFLAGS, $SHCXXFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1948 $SHOBJSUFFIX, $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX.
1949 Uses: $RCCOMSTR, $SHLINKCOMSTR.
1951 msgfmt
1953 This scons tool is a part of scons gettext toolset. It provides
1954 scons interface to msgfmt(1) command, which generates binary
1955 message catalog (MO) from a textual translation description (PO).
1956 Sets: $MOSUFFIX, $MSGFMT, $MSGFMTCOM, $MSGFMTCOMSTR, $MSGFMTFLAGS,
1958 $POSUFFIX.
1959 Uses: $LINGUAS_FILE.
1961 msginit
1963 This scons tool is a part of scons gettext toolset. It provides
1964 scons interface to msginit(1) program, which creates new PO file,
1965 initializing the meta information with values from user's
1966 environment (or options).
1967 Sets: $MSGINIT, $MSGINITCOM, $MSGINITCOMSTR, $MSGINITFLAGS,
1969 $POAUTOINIT, $POCREATE_ALIAS, $POSUFFIX, $POTSUFFIX,
1970 $_MSGINITLOCALE.
1971 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1973 msgmerge
1975 This scons tool is a part of scons gettext toolset. It provides
1976 scons interface to msgmerge(1) command, which merges two Uniform
1977 style .po files together.
1978 Sets: $MSGMERGE, $MSGMERGECOM, $MSGMERGECOMSTR, $MSGMERGEFLAGS,
1980 $POSUFFIX, $POTSUFFIX, $POUPDATE_ALIAS.
1981 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1983 mslib
1985 Sets construction variables for the Microsoft mslib library
1986 archiver.
1987 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
1989 Uses: $ARCOMSTR.
1991 mslink
1993 Sets construction variables for the Microsoft linker.
1994 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX,
1996 $LDMODULESUFFIX, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
1997 $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $REGSVR, $REGSVRCOM,
1998 $REGSVRFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS, $WINDOWSDEFPREFIX,
1999 $WINDOWSDEFSUFFIX, $WINDOWSEXPPREFIX, $WINDOWSEXPSUFFIX,
2000 $WINDOWSPROGMANIFESTPREFIX, $WINDOWSPROGMANIFESTSUFFIX,
2001 $WINDOWSSHLIBMANIFESTPREFIX, $WINDOWSSHLIBMANIFESTSUFFIX,
2002 $WINDOWS_INSERT_DEF.
2003 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $REGSVRCOMSTR, $SHLINKCOMSTR.
2005 mssdk
2007 Sets variables for Microsoft Platform SDK and/or Windows SDK. Note
2008 that unlike most other Tool modules, mssdk does not set
2009 construction variables, but sets the environment variables in the
2010 environment SCons uses to execute the Microsoft toolchain:
2011 %INCLUDE%, %LIB%, %LIBPATH% and %PATH%.
2012 Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION.
2014 msvc
2016 Sets construction variables for the Microsoft Visual C/C++
2017 compiler.
2018 Sets: $BUILDERS, $CC, $CCCOM, $CCFLAGS, $CCPCHFLAGS, $CCPDBFLAGS,
2020 $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM,
2021 $CXXFILESUFFIX, $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJPREFIX,
2022 $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM, $RCFLAGS, $SHCC,
2023 $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS,
2024 $SHOBJPREFIX, $SHOBJSUFFIX.
2025 Uses: $CCCOMSTR, $CXXCOMSTR, $PCH, $PCHSTOP, $PDB, $SHCCCOMSTR,
2027 $SHCXXCOMSTR.
2028 msvs
2030 Sets construction variables for Microsoft Visual Studio.
2031 Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM,
2033 $MSVSREBUILDCOM, $MSVSSCONS, $MSVSSCONSCOM, $MSVSSCONSCRIPT,
2034 $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM.
2035 mwcc
2037 Sets construction variables for the Metrowerks CodeWarrior
2038 compiler.
2039 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
2041 $CXX, $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX,
2042 $MWCW_VERSION, $MWCW_VERSIONS, $SHCC, $SHCCCOM, $SHCCFLAGS,
2043 $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS.
2044 Uses: $CCCOMSTR, $CXXCOMSTR, $SHCCCOMSTR, $SHCXXCOMSTR.
2046 mwld
2048 Sets construction variables for the Metrowerks CodeWarrior linker.
2049 Sets: $AR, $ARCOM, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
2051 $LIBLINKSUFFIX, $LINK, $LINKCOM, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
2052 nasm
2054 Sets construction variables for the nasm Netwide Assembler.
2055 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
2057 Uses: $ASCOMSTR, $ASPPCOMSTR.
2059 ninja
2061 Sets up Ninja builder which generates a ninja build file, and then
2062 optionally runs ninja.
2063 Note
2065 This is an experimental feature.
2066 This functionality is subject to change and/or removal without
2068 deprecation cycle.
2069 Sets: $IMPLICIT_COMMAND_DEPENDENCIES, $NINJA_ALIAS_NAME,
2070 $NINJA_COMPDB_EXPAND, $NINJA_DIR, $NINJA_DISABLE_AUTO_RUN,
2071 $NINJA_ENV_VAR_CACHE, $NINJA_FILE_NAME, $NINJA_FORCE_SCONS_BUILD,
2072 $NINJA_GENERATED_SOURCE_SUFFIXES, $NINJA_MSVC_DEPS_PREFIX,
2073 $NINJA_POOL, $NINJA_REGENERATE_DEPS, $NINJA_SYNTAX,
2074 $_NINJA_REGENERATE_DEPS_FUNC, $__NINJA_NO.
2075 Uses: $AR, $ARCOM, $ARFLAGS, $CC, $CCCOM, $CCFLAGS, $CXX, $CXXCOM,
2077 $ESCAPE, $LINK, $LINKCOM, $PLATFORM, $PRINT_CMD_LINE_FUNC,
2078 $PROGSUFFIX, $RANLIB, $RANLIBCOM, $SHCCCOM, $SHCXXCOM, $SHLINK,
2079 $SHLINKCOM.
2080 packaging
2082 Sets construction variables for the Package Builder. If this tool
2083 is enabled, the --package-type command-line option is also enabled.
2084 pdf
2086 Sets construction variables for the Portable Document Format
2087 builder.
2088 Sets: $PDFPREFIX, $PDFSUFFIX.
2090 pdflatex
2092 Sets construction variables for the pdflatex utility.
2093 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS.
2095 Uses: $PDFLATEXCOMSTR.
2097 pdftex
2099 Sets construction variables for the pdftex utility.
2100 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS,
2102 $PDFTEX, $PDFTEXCOM, $PDFTEXFLAGS.
2103 Uses: $PDFLATEXCOMSTR, $PDFTEXCOMSTR.
2105 python
2107 Loads the Python source scanner into the invoking environment. When
2108 loaded, the scanner will attempt to find implicit dependencies for
2109 any Python source files in the list of sources provided to an
2110 Action that uses this environment.
2111 Available since scons 4.0..
2113 qt
2115 Sets construction variables for building Qt3 applications.
2116 Note
2118 This tool is only suitable for building targeted to Qt3, which
2119 is obsolete (the tool is deprecated since 4.3). There are
2120 contributed tools for Qt4 and Qt5, see
2121 https://github.com/SCons/scons-contrib[1]. Qt4 has also passed
2122 end of life for standard support (in Dec 2015).
2123 Note paths for these construction variables are assembled using the
2124 os.path.join method so they will have the appropriate separator at
2125 runtime, but are listed here in the various entries only with the
2126 '/' separator for simplicity.
2127 In addition, the construction variables $CPPPATH, $LIBPATH and
2129 $LIBS may be modified and the variables $PROGEMITTER, $SHLIBEMITTER
2130 and $LIBEMITTER are modified. Because the build-performance is
2131 affected when using this tool, you have to explicitly specify it at
2132 Environment creation:
2133 Environment(tools=['default','qt'])
2135 The qt tool supports the following operations:
2137 Automatic moc file generation from header files. You do not have
2140 to specify moc files explicitly, the tool does it for you. However,
2141 there are a few preconditions to do so: Your header file must have
2142 the same filebase as your implementation file and must stay in the
2143 same directory. It must have one of the suffixes .h, .hpp, .H,
2144 .hxx, .hh. You can turn off automatic moc file generation by
2145 setting $QT_AUTOSCAN to False. See also the corresponding Moc
2146 Builder.
2147 Automatic moc file generation from C++ files. As described in the
2150 Qt documentation, include the moc file at the end of the C++ file.
2151 Note that you have to include the file, which is generated by the
2152 transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by
2153 default <basename>.mo. A warning is generated after building the
2154 moc file if you do not include the correct file. If you are using
2155 VariantDir, you may need to specify duplicate=True. You can turn
2156 off automatic moc file generation by setting $QT_AUTOSCAN to False.
2157 See also the corresponding Moc Builder.
2158 Automatic handling of .ui files. The implementation files
2161 generated from .ui files are handled much the same as yacc or lex
2162 files. Each .ui file given as a source of Program, Library or
2163 SharedLibrary will generate three files: the declaration file, the
2164 implementation file and a moc file. Because there are also
2165 generated headers, you may need to specify duplicate=True in calls
2166 to VariantDir. See also the corresponding Uic Builder.
2167 Sets: $QTDIR, $QT_AUTOSCAN, $QT_BINPATH, $QT_CPPPATH, $QT_LIB,
2169 $QT_LIBPATH, $QT_MOC, $QT_MOCCXXPREFIX, $QT_MOCCXXSUFFIX,
2170 $QT_MOCFROMCXXCOM, $QT_MOCFROMCXXFLAGS, $QT_MOCFROMHCOM,
2171 $QT_MOCFROMHFLAGS, $QT_MOCHPREFIX, $QT_MOCHSUFFIX, $QT_UIC,
2172 $QT_UICCOM, $QT_UICDECLFLAGS, $QT_UICDECLPREFIX, $QT_UICDECLSUFFIX,
2173 $QT_UICIMPLFLAGS, $QT_UICIMPLPREFIX, $QT_UICIMPLSUFFIX,
2174 $QT_UISUFFIX.
2175 Uses: $QTDIR.
2177 rmic
2179 Sets construction variables for the rmic utility.
2180 Sets: $JAVACLASSSUFFIX, $RMIC, $RMICCOM, $RMICFLAGS.
2182 Uses: $RMICCOMSTR.
2184 rpcgen
2186 Sets construction variables for building with RPCGEN.
2187 Sets: $RPCGEN, $RPCGENCLIENTFLAGS, $RPCGENFLAGS,
2189 $RPCGENHEADERFLAGS, $RPCGENSERVICEFLAGS, $RPCGENXDRFLAGS.
2190 sgiar
2192 Sets construction variables for the SGI library archiver.
2193 Sets: $AR, $ARCOMSTR, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $SHLINK,
2195 $SHLINKFLAGS.
2196 Uses: $ARCOMSTR, $SHLINKCOMSTR.
2198 sgic++
2200 Sets construction variables for the SGI C++ compiler.
2201 Sets: $CXX, $CXXFLAGS, $SHCXX, $SHOBJSUFFIX.
2203 sgicc
2205 Sets construction variables for the SGI C compiler.
2206 Sets: $CXX, $SHOBJSUFFIX.
2208 sgilink
2210 Sets construction variables for the SGI linker.
2211 Sets: $LINK, $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2213 sunar
2215 Sets construction variables for the Sun library archiver.
2216 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2218 Uses: $ARCOMSTR.
2220 sunc++
2222 Sets construction variables for the Sun C++ compiler.
2223 Sets: $CXX, $CXXVERSION, $SHCXX, $SHCXXFLAGS, $SHOBJPREFIX,
2225 $SHOBJSUFFIX.
2226 suncc
2228 Sets construction variables for the Sun C compiler.
2229 Sets: $CXX, $SHCCFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.
2231 sunf77
2233 Set construction variables for the Sun f77 Fortran compiler.
2234 Sets: $F77, $FORTRAN, $SHF77, $SHF77FLAGS, $SHFORTRAN,
2236 $SHFORTRANFLAGS.
2237 sunf90
2239 Set construction variables for the Sun f90 Fortran compiler.
2240 Sets: $F90, $FORTRAN, $SHF90, $SHF90FLAGS, $SHFORTRAN,
2242 $SHFORTRANFLAGS.
2243 sunf95
2245 Set construction variables for the Sun f95 Fortran compiler.
2246 Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN,
2248 $SHFORTRANFLAGS.
2249 sunlink
2251 Sets construction variables for the Sun linker.
2252 Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2254 swig
2256 Sets construction variables for the SWIG interface generator.
2257 Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX,
2259 $SWIGDIRECTORSUFFIX, $SWIGFLAGS, $SWIGINCPREFIX, $SWIGINCSUFFIX,
2260 $SWIGPATH, $SWIGVERSION, $_SWIGINCFLAGS.
2261 Uses: $SWIGCOMSTR.
2263 tar
2265 Sets construction variables for the tar archiver.
2266 Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX.
2268 Uses: $TARCOMSTR.
2270 tex
2272 Sets construction variables for the TeX formatter and typesetter.
2273 Sets: $BIBTEX, $BIBTEXCOM, $BIBTEXFLAGS, $LATEX, $LATEXCOM,
2275 $LATEXFLAGS, $MAKEINDEX, $MAKEINDEXCOM, $MAKEINDEXFLAGS, $TEX,
2276 $TEXCOM, $TEXFLAGS.
2277 Uses: $BIBTEXCOMSTR, $LATEXCOMSTR, $MAKEINDEXCOMSTR, $TEXCOMSTR.
2279 textfile
2281 Set construction variables for the Textfile and Substfile builders.
2282 Sets: $LINESEPARATOR, $SUBSTFILEPREFIX, $SUBSTFILESUFFIX,
2284 $TEXTFILEPREFIX, $TEXTFILESUFFIX.
2285 Uses: $SUBST_DICT.
2287 tlib
2289 Sets construction variables for the Borlan tib library archiver.
2290 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2292 Uses: $ARCOMSTR.
2294 xgettext
2296 This scons tool is a part of scons gettext toolset. It provides
2297 scons interface to xgettext(1) program, which extracts
2298 internationalized messages from source code. The tool provides
2299 POTUpdate builder to make PO Template files.
2300 Sets: $POTSUFFIX, $POTUPDATE_ALIAS, $XGETTEXTCOM, $XGETTEXTCOMSTR,
2302 $XGETTEXTFLAGS, $XGETTEXTFROM, $XGETTEXTFROMPREFIX,
2303 $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPATHPREFIX,
2304 $XGETTEXTPATHSUFFIX, $_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS,
2305 $_XGETTEXTPATHFLAGS.
2306 Uses: $POTDOMAIN.
2308 yacc
2310 Sets construction variables for the yacc parse generator.
2311 Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX,
2313 $YACCHXXFILESUFFIX, $YACCVCGFILESUFFIX.
2314 Uses: $YACCCOMSTR.
2316 zip
2318 Sets construction variables for the zip archiver.
2319 Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX.
2321 Uses: $ZIPCOMSTR.
2323 Builder Methods
2325 You tell scons what to build by calling Builders, functions which take
2326 particular action(s) to produce a particular result type
2327 (conventionally described by the builder name such as Program) when
2328 given source files of a particular type. Calling a builder defines one
2329 or more targets to the build system; whether the targets are actually
2330 built on a given invocation is determined by command-line options,
2331 target selection rules, and whether SCons determines the target(s) are
2332 out of date.
2333 SCons defines a number of builders, and you can also write your own.
2335 Builders are attached to a construction environment as methods, and the
2336 available builder methods are listed as key-value pairs in the BUILDERS
2337 attribute of the construction environment. The available builders can
2338 be displayed like this for debugging purposes:
2339 env = Environment()
2341 print("Builders:", list(env['BUILDERS']))
2342 Builder methods take two required arguments: target and source. Either
2344 can be passed as a scalar or as a list. The target and source arguments
2345 can be specified either as positional arguments, in which case target
2346 comes first, or as keyword arguments, using target= and source=.
2347 Although both arguments are nominally required, if there is a single
2348 source and the target can be inferred the target argument can be
2349 omitted (see below). Builder methods also take a variety of keyword
2350 arguments, described below.
2351 The builder may add other targets beyond those requested if indicated
2353 by an Emitter (see the section called “Builder Objects” and, for
2354 example, $PROGEMITTER for more information).
2355 Because long lists of file names can lead to a lot of quoting, scons
2357 supplies a Split global function and a same-named environment method
2358 that splits a single string into a list, using strings of white-space
2359 characters as the delimiter. (similar to the Python string split
2360 method, but succeeds even if the input isn't a string.)
2361 The following are equivalent examples of calling the Program builder
2363 method:
2364 env.Program('bar', ['bar.c', 'foo.c'])
2366 env.Program('bar', Split('bar.c foo.c'))
2367 env.Program('bar', env.Split('bar.c foo.c'))
2368 env.Program(source=['bar.c', 'foo.c'], target='bar')
2369 env.Program(target='bar', source=Split('bar.c foo.c'))
2370 env.Program(target='bar', source=env.Split('bar.c foo.c'))
2371 env.Program('bar', source='bar.c foo.c'.split())
2372 Python follows the POSIX pathname convention for path strings: if a
2374 string begins with the operating system pathname separator (on Windows
2375 both the slash and backslash separator work, and any leading drive
2376 specifier is ignored for the determination) it is considered an
2377 absolute path, otherwise it is a relative path. If the path string
2378 contains no separator characters, it is searched for as a file in the
2379 current directory. If it contains separator characters, the search
2380 follows down from the starting point, which is the top of the directory
2381 tree for an absolute path and the current directory for a relative
2382 path.
2383 scons recognizes a third way to specify path strings: if the string
2385 begins with the # character it is top-relative - it works like a
2386 relative path but the search follows down from the directory containing
2387 the top-level SConstruct rather than from the current directory. The #
2388 is allowed to be followed by a pathname separator, which is ignored if
2389 found in that position. Top-relative paths only work in places where
2390 scons will interpret the path (see some examples below). To be used in
2391 other contexts the string will need to be converted to a relative or
2392 absolute path first.
2393 target and source can be absolute, relative, or top-relative. Relative
2395 pathnames are searched considering the directory of the SConscript file
2396 currently being processed as the "current directory".
2397 Examples:
2399 # The comments describing the targets that will be built
2401 # assume these calls are in a SConscript file in the
2402 # a subdirectory named "subdir".
2403 # Builds the program "subdir/foo" from "subdir/foo.c":
2405 env.Program('foo', 'foo.c')
2406 # Builds the program "/tmp/bar" from "subdir/bar.c":
2408 env.Program('/tmp/bar', 'bar.c')
2409 # An initial '#' or '#/' are equivalent; the following
2411 # calls build the programs "foo" and "bar" (in the
2412 # top-level SConstruct directory) from "subdir/foo.c" and
2413 # "subdir/bar.c", respectively:
2414 env.Program('#foo', 'foo.c')
2415 env.Program('#/bar', 'bar.c')
2416 # Builds the program "other/foo" (relative to the top-level
2418 # SConstruct directory) from "subdir/foo.c":
2419 env.Program('#other/foo', 'foo.c')
2420 # This will not work, only SCons interfaces understand '#',
2422 # os.path.exists is pure Python:
2423 if os.path.exists('#inc/foo.h'):
2424 env.Append(CPPPATH='#inc')
2425 When the target shares the same base name as the source and only the
2427 suffix varies, and if the builder method has a suffix defined for the
2428 target file type, then the target argument may be omitted completely,
2429 and scons will deduce the target file name from the source file name.
2430 The following examples all build the executable program bar (on POSIX
2431 systems) or bar.exe (on Windows systems) from the bar.c source file:
2432 env.Program(target='bar', source='bar.c')
2434 env.Program('bar', source='bar.c')
2435 env.Program(source='bar.c')
2436 env.Program('bar.c')
2437 As a convenience, a srcdir keyword argument may be specified when
2439 calling a Builder. When specified, all source file strings that are not
2440 absolute paths or top-relative paths will be interpreted relative to
2441 the specified srcdir. The following example will build the build/prog
2442 (or build/prog.exe on Windows) program from the files src/f1.c and
2443 src/f2.c:
2444 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
2446 Keyword arguments that are not specifically recognized are treated as
2448 construction variable overrides, which replace or add those variables
2449 on a limited basis. These overrides will only be in effect when
2450 building the target of the builder call, and will not affect other
2451 parts of the build. For example, if you want to specify some libraries
2452 needed by just one program:
2453 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
2455 or generate a shared library with a non-standard suffix:
2457 env.SharedLibrary(
2459 target='word',
2460 source='word.cpp',
2461 SHLIBSUFFIX='.ocx',
2462 LIBSUFFIXES=['.ocx'],
2463 )
2464 Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
2466 if you want scons to search automatically for dependencies on the
2467 non-standard library names; see the descriptions below of these
2468 variables for more information.
2469 The optional parse_flags keyword argument is recognized by builders.
2471 This works similarly to the env.MergeFlags method, where the argument
2472 value is broken into individual settings and merged into the
2473 appropriate construction variables.
2474 env.Program('hello', 'hello.c', parse_flags='-Iinclude -DEBUG -lm')
2476 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
2478 to LIBS.
2479 Although the builder methods defined by scons are, in fact, methods of
2481 a construction environment object, many may also be called without an
2482 explicit environment:
2483 Program('hello', 'hello.c')
2485 SharedLibrary('word', 'word.cpp')
2486 If called this way, methods will internally use the default environment
2488 that consists of the tools and values that scons has determined are
2489 appropriate for the local system.
2490 Builder methods that can be called without an explicit environment
2492 (indicated in the listing of builders without a leading env.) may be
2493 called from custom Python modules that you import into an SConscript
2494 file by adding the following to the Python module:
2495 from SCons.Script import *
2497 Builder methods return a NodeList, a list-like object whose elements
2499 are Nodes, SCons' internal representation of build targets or sources.
2500 See the section called “File and Directory Nodes” for more information.
2501 The returned NodeList object can be passed to other builder methods as
2502 source(s) or passed to any SCons function or method where a filename
2503 would normally be accepted.
2504 For example, to add a specific preprocessor define when compiling one
2506 specific object file but not the others:
2507 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2509 env.Program("prog", ['foo.c', bar_obj_list, 'main.c'])
2510 Using a Node as in this example makes for a more portable build by
2512 avoiding having to specify a platform-specific object suffix when
2513 calling the Program builder method.
2514 The NodeList object is also convenient to pass to the Default function,
2516 for the same reason of avoiding a platform-specific name:
2517 tgt = env.Program("prog", ["foo.c", "bar.c", "main.c"])
2519 Default(tgt)
2520 Builder calls will automatically "flatten" lists passed as source and
2522 target, so they are free to contain elements which are themselves
2523 lists, such as bar_obj_list returned by the StaticObject call above. If
2524 you need to manipulate a list of lists returned by builders directly in
2525 Python code, you can either build a new list by hand:
2526 foo = Object('foo.c')
2528 bar = Object('bar.c')
2529 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2530 for obj in objects:
2531 print(str(obj))
2532 Or you can use the Flatten function supplied by scons to create a list
2534 containing just the Nodes, which may be more convenient:
2535 foo = Object('foo.c')
2537 bar = Object('bar.c')
2538 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2539 for obj in objects:
2540 print(str(obj))
2541 SCons builder calls return a list-like object, not an actual Python
2543 list, so it is not appropriate to use the Python add operator (+ or +=)
2544 to append builder results to a Python list. Because the list and the
2545 object are different types, Python will not update the original list in
2546 place, but will instead create a new NodeList object containing the
2547 concatenation of the list elements and the builder results. This will
2548 cause problems for any other Python variables in your SCons
2549 configuration that still hold on to a reference to the original list.
2550 Instead, use the Python list extend method to make sure the list is
2551 updated in-place. Example:
2552 object_files = []
2554 # Do NOT use += here:
2556 # object_files += Object('bar.c')
2557 #
2558 # It will not update the object_files list in place.
2559 #
2560 # Instead, use the list extend method:
2561 object_files.extend(Object('bar.c'))
2562 The path name for a Node's file may be used by passing the Node to
2564 Python's builtin str function:
2565 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2567 print("The path to bar_obj is:", str(bar_obj_list[0]))
2568 Note that because the Builder call returns a NodeList, you have to
2570 access the first element in the list, (bar_obj_list[0] in the example)
2571 to get at the Node that actually represents the object file.
2572 Builder calls support a chdir keyword argument that specifies that the
2574 Builder's action(s) should be executed after changing directory. If the
2575 chdir argument is a string or a directory Node, scons will change to
2576 the specified directory. If the chdir is not a string or Node and is
2577 non-zero, then scons will change to the target file's directory.
2578 # scons will change to the "sub" subdirectory
2580 # before executing the "cp" command.
2581 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2582 "cp dir/foo.in dir/foo.out",
2583 chdir='sub')
2584 # Because chdir is not a string, scons will change to the
2586 # target's directory ("sub/dir") before executing the
2587 # "cp" command.
2588 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2589 "cp foo.in foo.out",
2590 chdir=1)
2591 Note that SCons will not automatically modify its expansion of
2593 construction variables like $TARGET and $SOURCE when using the chdir
2594 keyword argument--that is, the expanded file names will still be
2595 relative to the top-level directory where SConstruct was found, and
2596 consequently incorrect relative to the chdir directory. If you use the
2597 chdir keyword argument, you will typically need to supply a different
2598 command line using expansions like ${TARGET.file} and ${SOURCE.file} to
2599 use just the filename portion of the targets and source.
2600 When trying to handle errors that may occur in a builder method,
2602 consider that the corresponding Action is executed at a different time
2603 than the SConscript file statement calling the builder. It is not
2604 useful to wrap a builder call in a try block, since success in the
2605 builder call is not the same as the builder itself succeeding. If
2606 necessary, a Builder's Action should be coded to exit with a useful
2607 exception message indicating the problem in the SConscript files -
2608 programmatically recovering from build errors is rarely useful.
2609 scons predefines the following builder methods. Depending on the setup
2611 of a particular construction environment and on the type and software
2612 installation status of the underlying system, not all builders may be
2613 available to that construction environment.
2614 CFile(), env.CFile()
2616 Builds a C source file given a lex (.l) or yacc (.y) input file.
2617 The suffix specified by the $CFILESUFFIX construction variable (.c
2618 by default) is automatically added to the target if it is not
2619 already present. Example:
2620 # builds foo.c
2622 env.CFile(target = 'foo.c', source = 'foo.l')
2623 # builds bar.c
2624 env.CFile(target = 'bar', source = 'bar.y')
2625 Command(), env.Command()
2627 The Command "Builder" is actually a function that looks like a
2628 Builder, but takes a required third argument, which is the action
2629 to take to construct the target from the source, used for "one-off"
2630 builds where a full builder is not needed. Thus it does not follow
2631 the builder calling rules described at the start of this section.
2632 See instead the Command function description for the calling syntax
2633 and details.
2634 CompilationDatabase(), env.CompilationDatabase()
2636 CompilationDatabase is a special builder which adds a target to
2638 create a JSON formatted compilation database compatible with clang
2639 tooling (see the LLVM specification[2]). This database is suitable
2640 for consumption by various tools and editors who can use it to
2641 obtain build and dependency information which otherwise would be
2642 internal to SCons. The builder does not require any source files to
2643 be specified, rather it arranges to emit information about all of
2644 the C, C++ and assembler source/output pairs identified in the
2645 build that are not excluded by the optional filter
2646 $COMPILATIONDB_PATH_FILTER. The target is subject to the usual
2647 SCons target selection rules.
2648 If called with no arguments, the builder will default to a target
2650 name of compile_commands.json.
2651 If called with a single positional argument, scons will "deduce"
2653 the target name from that source argument, giving it the same name,
2654 and then ignore the source. This is the usual way to call the
2655 builder if a non-default target name is wanted.
2656 If called with either the target= or source= keyword arguments, the
2658 value of the argument is taken as the target name. If called with
2659 both, the target= value is used and source= is ignored. If called
2660 with multiple sources, the source list will be ignored, since there
2661 is no way to deduce what the intent was; in this case the default
2662 target name will be used.
2663 Note
2665 You must load the compilation_db tool prior to specifying any
2666 part of your build or some source/output files will not show up
2667 in the compilation database.
2668 Available since scons 4.0.
2669 CXXFile(), env.CXXFile()
2671 Builds a C++ source file given a lex (.ll) or yacc (.yy) input
2672 file. The suffix specified by the $CXXFILESUFFIX construction
2673 variable (.cc by default) is automatically added to the target if
2674 it is not already present. Example:
2675 # builds foo.cc
2677 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
2678 # builds bar.cc
2679 env.CXXFile(target = 'bar', source = 'bar.yy')
2680 DocbookEpub(), env.DocbookEpub()
2682 A pseudo-Builder, providing a Docbook toolchain for EPUB output.
2683 env = Environment(tools=['docbook'])
2685 env.DocbookEpub('manual.epub', 'manual.xml')
2686 or simply
2688 env = Environment(tools=['docbook'])
2690 env.DocbookEpub('manual')
2691 DocbookHtml(), env.DocbookHtml()
2693 A pseudo-Builder, providing a Docbook toolchain for HTML output.
2694 env = Environment(tools=['docbook'])
2696 env.DocbookHtml('manual.html', 'manual.xml')
2697 or simply
2699 env = Environment(tools=['docbook'])
2701 env.DocbookHtml('manual')
2702 DocbookHtmlChunked(), env.DocbookHtmlChunked()
2704 A pseudo-Builder providing a Docbook toolchain for chunked HTML
2705 output. It supports the base.dir parameter. The chunkfast.xsl file
2706 (requires "EXSLT") is used as the default stylesheet. Basic syntax:
2707 env = Environment(tools=['docbook'])
2709 env.DocbookHtmlChunked('manual')
2710 where manual.xml is the input file.
2712 If you use the root.filename parameter in your own stylesheets you
2714 have to specify the new target name. This ensures that the
2715 dependencies get correct, especially for the cleanup via “scons
2716 -c”:
2717 env = Environment(tools=['docbook'])
2719 env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
2720 Some basic support for the base.dir parameter is provided. You can
2722 add the base_dir keyword to your Builder call, and the given prefix
2723 gets prepended to all the created filenames:
2724 env = Environment(tools=['docbook'])
2726 env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
2727 Make sure that you don't forget the trailing slash for the base
2729 folder, else your files get renamed only!
2730 DocbookHtmlhelp(), env.DocbookHtmlhelp()
2732 A pseudo-Builder, providing a Docbook toolchain for HTMLHELP
2733 output. Its basic syntax is:
2734 env = Environment(tools=['docbook'])
2736 env.DocbookHtmlhelp('manual')
2737 where manual.xml is the input file.
2739 If you use the root.filename parameter in your own stylesheets you
2741 have to specify the new target name. This ensures that the
2742 dependencies get correct, especially for the cleanup via “scons
2743 -c”:
2744 env = Environment(tools=['docbook'])
2746 env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
2747 Some basic support for the base.dir parameter is provided. You can
2749 add the base_dir keyword to your Builder call, and the given prefix
2750 gets prepended to all the created filenames:
2751 env = Environment(tools=['docbook'])
2753 env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
2754 Make sure that you don't forget the trailing slash for the base
2756 folder, else your files get renamed only!
2757 DocbookMan(), env.DocbookMan()
2759 A pseudo-Builder, providing a Docbook toolchain for Man page
2760 output. Its basic syntax is:
2761 env = Environment(tools=['docbook'])
2763 env.DocbookMan('manual')
2764 where manual.xml is the input file. Note, that you can specify a
2766 target name, but the actual output names are automatically set from
2767 the refname entries in your XML source.
2768 DocbookPdf(), env.DocbookPdf()
2770 A pseudo-Builder, providing a Docbook toolchain for PDF output.
2771 env = Environment(tools=['docbook'])
2773 env.DocbookPdf('manual.pdf', 'manual.xml')
2774 or simply
2776 env = Environment(tools=['docbook'])
2778 env.DocbookPdf('manual')
2779 DocbookSlidesHtml(), env.DocbookSlidesHtml()
2781 A pseudo-Builder, providing a Docbook toolchain for HTML slides
2782 output.
2783 env = Environment(tools=['docbook'])
2785 env.DocbookSlidesHtml('manual')
2786 If you use the titlefoil.html parameter in your own stylesheets you
2788 have to give the new target name. This ensures that the
2789 dependencies get correct, especially for the cleanup via “scons
2790 -c”:
2791 env = Environment(tools=['docbook'])
2793 env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
2794 Some basic support for the base.dir parameter is provided. You can
2796 add the base_dir keyword to your Builder call, and the given prefix
2797 gets prepended to all the created filenames:
2798 env = Environment(tools=['docbook'])
2800 env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
2801 Make sure that you don't forget the trailing slash for the base
2803 folder, else your files get renamed only!
2804 DocbookSlidesPdf(), env.DocbookSlidesPdf()
2806 A pseudo-Builder, providing a Docbook toolchain for PDF slides
2807 output.
2808 env = Environment(tools=['docbook'])
2810 env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
2811 or simply
2813 env = Environment(tools=['docbook'])
2815 env.DocbookSlidesPdf('manual')
2816 DocbookXInclude(), env.DocbookXInclude()
2818 A pseudo-Builder, for resolving XIncludes in a separate processing
2819 step.
2820 env = Environment(tools=['docbook'])
2822 env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
2823 DocbookXslt(), env.DocbookXslt()
2825 A pseudo-Builder, applying a given XSL transformation to the input
2826 file.
2827 env = Environment(tools=['docbook'])
2829 env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
2830 Note, that this builder requires the xsl parameter to be set.
2832 DVI(), env.DVI()
2834 Builds a .dvi file from a .tex, .ltx or .latex input file. If the
2835 source file suffix is .tex, scons will examine the contents of the
2836 file; if the string \documentclass or \documentstyle is found, the
2837 file is assumed to be a LaTeX file and the target is built by
2838 invoking the $LATEXCOM command line; otherwise, the $TEXCOM command
2839 line is used. If the file is a LaTeX file, the DVI builder method
2840 will also examine the contents of the .aux file and invoke the
2841 $BIBTEX command line if the string bibdata is found, start
2842 $MAKEINDEX to generate an index if a .ind file is found and will
2843 examine the contents .log file and re-run the $LATEXCOM command if
2844 the log file says it is necessary.
2845 The suffix .dvi (hard-coded within TeX itself) is automatically
2847 added to the target if it is not already present. Examples:
2848 # builds from aaa.tex
2850 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
2851 # builds bbb.dvi
2852 env.DVI(target = 'bbb', source = 'bbb.ltx')
2853 # builds from ccc.latex
2854 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
2855 Gs(), env.Gs()
2857 A Builder for explicitly calling the gs executable. Depending on
2858 the underlying OS, the different names gs, gsos2 and gswin32c are
2859 tried.
2860 env = Environment(tools=['gs'])
2862 env.Gs(
2863 'cover.jpg',
2864 'scons-scons.pdf',
2865 GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q',
2866 )
2867 Install(), env.Install()
2869 Installs one or more source files or directories in the specified
2870 target, which must be a directory. The names of the specified
2871 source files or directories remain the same within the destination
2872 directory. The sources may be given as a string or as a node
2873 returned by a builder.
2874 env.Install(target='/usr/local/bin', source=['foo', 'bar'])
2876 Note that if target paths chosen for the Install builder (and the
2878 related InstallAs and InstallVersionedLib builders) are outside the
2879 project tree, such as in the example above, they may not be
2880 selected for "building" by default, since in the absence of other
2881 instructions scons builds targets that are underneath the top
2882 directory (the directory that contains the SConstruct file, usually
2883 the current directory). Use command line targets or the Default
2884 function in this case.
2885 If the --install-sandbox command line option is given, the target
2887 directory will be prefixed by the directory path specified. This is
2888 useful to test installs without installing to a "live" location in
2889 the system.
2890 See also FindInstalledFiles. For more thoughts on installation, see
2892 the User Guide (particularly the section on Command-Line Targets
2893 and the chapters on Installing Files and on Alias Targets).
2894 InstallAs(), env.InstallAs()
2896 Installs one or more source files or directories to specific names,
2897 allowing changing a file or directory name as part of the
2898 installation. It is an error if the target and source arguments
2899 list different numbers of files or directories.
2900 env.InstallAs(target='/usr/local/bin/foo',
2902 source='foo_debug')
2903 env.InstallAs(target=['../lib/libfoo.a', '../lib/libbar.a'],
2904 source=['libFOO.a', 'libBAR.a'])
2905 See the note under Install.
2907 InstallVersionedLib(), env.InstallVersionedLib()
2909 Installs a versioned shared library. The symlinks appropriate to
2910 the architecture will be generated based on symlinks of the source
2911 library.
2912 env.InstallVersionedLib(target='/usr/local/bin/foo',
2914 source='libxyz.1.5.2.so')
2915 See the note under Install.
2917 Jar(), env.Jar()
2919 Builds a Java archive (.jar) file from the specified list of
2920 sources. Any directories in the source list will be searched for
2921 .class files). Any .java files in the source list will be compiled
2922 to .class files by calling the Java Builder.
2923 If the $JARCHDIR value is set, the jar command will change to the
2925 specified directory using the -C option. If $JARCHDIR is not set
2926 explicitly, SCons will use the top of any subdirectory tree in
2927 which Java .class were built by the Java Builder.
2928 If the contents any of the source files begin with the string
2930 Manifest-Version, the file is assumed to be a manifest and is
2931 passed to the jar command with the m option set.
2932 env.Jar(target = 'foo.jar', source = 'classes')
2934 env.Jar(target = 'bar.jar',
2936 source = ['bar1.java', 'bar2.java'])
2937 Java(), env.Java()
2939 Builds one or more Java class files. The sources may be any
2940 combination of explicit .java files, or directory trees which will
2941 be scanned for .java files.
2942 SCons will parse each source .java file to find the classes
2944 (including inner classes) defined within that file, and from that
2945 figure out the target .class files that will be created. The class
2946 files will be placed underneath the specified target directory.
2947 SCons will also search each Java file for the Java package name,
2949 which it assumes can be found on a line beginning with the string
2950 package in the first column; the resulting .class files will be
2951 placed in a directory reflecting the specified package name. For
2952 example, the file Foo.java defining a single public Foo class and
2953 containing a package name of sub.dir will generate a corresponding
2954 sub/dir/Foo.class class file.
2955 Examples:
2957 env.Java(target = 'classes', source = 'src')
2959 env.Java(target = 'classes', source = ['src1', 'src2'])
2960 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
2961 Java source files can use the native encoding for the underlying
2964 OS. Since SCons compiles in simple ASCII mode by default, the
2965 compiler will generate warnings about unmappable characters, which
2966 may lead to errors as the file is processed further. In this case,
2967 the user must specify the LANG environment variable to tell the
2968 compiler what encoding is used. For portibility, it's best if the
2969 encoding is hard-coded so that the compile will work if it is done
2970 on a system with a different encoding.
2971 env = Environment()
2973 env['ENV']['LANG'] = 'en_GB.UTF-8'
2974 JavaH(), env.JavaH()
2977 Builds C header and source files for implementing Java native
2978 methods. The target can be either a directory in which the header
2979 files will be written, or a header file name which will contain all
2980 of the definitions. The source can be the names of .class files,
2981 the names of .java files to be compiled into .class files by
2982 calling the Java builder method, or the objects returned from the
2983 Java builder method.
2984 If the construction variable $JAVACLASSDIR is set, either in the
2986 environment or in the call to the JavaH builder method itself, then
2987 the value of the variable will be stripped from the beginning of
2988 any .class file names.
2989 Examples:
2991 # builds java_native.h
2993 classes = env.Java(target="classdir", source="src")
2994 env.JavaH(target="java_native.h", source=classes)
2995 # builds include/package_foo.h and include/package_bar.h
2997 env.JavaH(target="include", source=["package/foo.class", "package/bar.class"])
2998 # builds export/foo.h and export/bar.h
3000 env.JavaH(
3001 target="export",
3002 source=["classes/foo.class", "classes/bar.class"],
3003 JAVACLASSDIR="classes",
3004 )
3005 Note
3007 Java versions starting with 10.0 no longer use the javah
3008 command for generating JNI headers/sources, and indeed have
3009 removed the command entirely (see Java Enhancement Proposal JEP
3010 313[3]), making this tool harder to use for that purpose.
3011 SCons may autodiscover a javah belonging to an older release if
3012 there are multiple Java versions on the system, which will lead
3013 to incorrect results. To use with a newer Java, override the
3014 default values of $JAVAH (to contain the path to the javac) and
3015 $JAVAHFLAGS (to contain at least a -h flag) and note that
3016 generating headers with javac requires supplying source .java
3017 files only, not .class files.
3018 Library(), env.Library()
3020 A synonym for the StaticLibrary builder method.
3021 LoadableModule(), env.LoadableModule()
3023 On most systems, this is the same as SharedLibrary. On Mac OS X
3024 (Darwin) platforms, this creates a loadable module bundle.
3025 M4(), env.M4()
3027 Builds an output file from an M4 input file. This uses a default
3028 $M4FLAGS value of -E, which considers all warnings to be fatal and
3029 stops on the first warning when using the GNU version of m4.
3030 Example:
3031 env.M4(target = 'foo.c', source = 'foo.c.m4')
3033 Moc(), env.Moc()
3035 Builds an output file from a moc input file. moc input files are
3036 either header files or C++ files. This builder is only available
3037 after using the tool qt. See the $QTDIR variable for more
3038 information. Example:
3039 env.Moc('foo.h') # generates moc_foo.cc
3041 env.Moc('foo.cpp') # generates foo.moc
3042 MOFiles(), env.MOFiles()
3044 This builder belongs to msgfmt tool. The builder compiles PO files
3045 to MO files.
3046 Example 1. Create pl.mo and en.mo by compiling pl.po and en.po:
3049 # ...
3051 env.MOFiles(['pl', 'en'])
3052 Example 2. Compile files for languages defined in LINGUAS file:
3055 # ...
3057 env.MOFiles(LINGUAS_FILE = 1)
3058 Example 3. Create pl.mo and en.mo by compiling pl.po and en.po plus
3061 files for languages defined in LINGUAS file:
3062 # ...
3064 env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
3065 Example 4. Compile files for languages defined in LINGUAS file
3068 (another version):
3069 # ...
3071 env['LINGUAS_FILE'] = 1
3072 env.MOFiles()
3073 MSVSProject(), env.MSVSProject()
3075 Builds a Microsoft Visual Studio project file, and by default
3076 builds a solution file as well.
3077 This builds a Visual Studio project file, based on the version of
3079 Visual Studio that is configured (either the latest installed
3080 version, or the version specified by $MSVS_VERSION in the
3081 Environment constructor). For Visual Studio 6, it will generate a
3082 .dsp file. For Visual Studio 7, 8, and 9, it will generate a
3083 .vcproj file. For Visual Studio 10 and later, it will generate a
3084 .vcxproj file.
3085 By default, this also generates a solution file for the specified
3087 project, a .dsw file for Visual Studio 6 or a .sln file for Visual
3088 Studio 7 and later. This behavior may be disabled by specifying
3089 auto_build_solution=0 when you call MSVSProject, in which case you
3090 presumably want to build the solution file(s) by calling the
3091 MSVSSolution Builder (see below).
3092 The MSVSProject builder takes several lists of filenames to be
3094 placed into the project file. These are currently limited to srcs,
3095 incs, localincs, resources, and misc. These are pretty
3096 self-explanatory, but it should be noted that these lists are added
3097 to the $SOURCES construction variable as strings, NOT as SCons File
3098 Nodes. This is because they represent file names to be added to the
3099 project file, not the source files used to build the project file.
3100 The above filename lists are all optional, although at least one
3102 must be specified for the resulting project file to be non-empty.
3103 In addition to the above lists of values, the following values may
3105 be specified:
3106 target
3108 The name of the target .dsp or .vcproj file. The correct suffix
3109 for the version of Visual Studio must be used, but the
3110 $MSVSPROJECTSUFFIX construction variable will be defined to the
3111 correct value (see example below).
3112 variant
3114 The name of this particular variant. For Visual Studio 7
3115 projects, this can also be a list of variant names. These are
3116 typically things like "Debug" or "Release", but really can be
3117 anything you want. For Visual Studio 7 projects, they may also
3118 specify a target platform separated from the variant name by a
3119 | (vertical pipe) character: Debug|Xbox. The default target
3120 platform is Win32. Multiple calls to MSVSProject with different
3121 variants are allowed; all variants will be added to the project
3122 file with their appropriate build targets and sources.
3123 cmdargs
3125 Additional command line arguments for the different variants.
3126 The number of cmdargs entries must match the number of variant
3127 entries, or be empty (not specified). If you give only one, it
3128 will automatically be propagated to all variants.
3129 cppdefines
3131 Preprocessor definitions for the different variants. The number
3132 of cppdefines entries must match the number of variant entries,
3133 or be empty (not specified). If you give only one, it will
3134 automatically be propagated to all variants. If you don't give
3135 this parameter, SCons will use the invoking environment's
3136 CPPDEFINES entry for all variants.
3137 cppflags
3139 Compiler flags for the different variants. If a /std:c++ flag
3140 is found then /Zc:__cplusplus is appended to the flags if not
3141 already found, this ensures that intellisense uses the /std:c++
3142 switch. The number of cppflags entries must match the number of
3143 variant entries, or be empty (not specified). If you give only
3144 one, it will automatically be propagated to all variants. If
3145 you don't give this parameter, SCons will combine the invoking
3146 environment's CCFLAGS, CXXFLAGS, CPPFLAGS entries for all
3147 variants.
3148 cpppaths
3150 Compiler include paths for the different variants. The number
3151 of cpppaths entries must match the number of variant entries,
3152 or be empty (not specified). If you give only one, it will
3153 automatically be propagated to all variants. If you don't give
3154 this parameter, SCons will use the invoking environment's
3155 CPPPATH entry for all variants.
3156 buildtarget
3158 An optional string, node, or list of strings or nodes (one per
3159 build variant), to tell the Visual Studio debugger what output
3160 target to use in what build variant. The number of buildtarget
3161 entries must match the number of variant entries.
3162 runfile
3164 The name of the file that Visual Studio 7 and later will run
3165 and debug. This appears as the value of the Output field in the
3166 resulting Visual Studio project file. If this is not specified,
3167 the default is the same as the specified buildtarget value.
3168 Note that because SCons always executes its build commands from the
3170 directory in which the SConstruct file is located, if you generate
3171 a project file in a different directory than the SConstruct
3172 directory, users will not be able to double-click on the file name
3173 in compilation error messages displayed in the Visual Studio
3174 console output window. This can be remedied by adding the Visual
3175 C/C++ /FC compiler option to the $CCFLAGS variable so that the
3176 compiler will print the full path name of any files that cause
3177 compilation errors.
3178 Example usage:
3180 barsrcs = ['bar.cpp']
3182 barincs = ['bar.h']
3183 barlocalincs = ['StdAfx.h']
3184 barresources = ['bar.rc','resource.h']
3185 barmisc = ['bar_readme.txt']
3186 dll = env.SharedLibrary(target='bar.dll',
3188 source=barsrcs)
3189 buildtarget = [s for s in dll if str(s).endswith('dll')]
3190 env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
3191 srcs=barsrcs,
3192 incs=barincs,
3193 localincs=barlocalincs,
3194 resources=barresources,
3195 misc=barmisc,
3196 buildtarget=buildtarget,
3197 variant='Release')
3198 Starting with version 2.4 of SCons it is also possible to specify
3201 the optional argument DebugSettings, which creates files for
3202 debugging under Visual Studio:
3203 DebugSettings
3205 A dictionary of debug settings that get written to the
3206 .vcproj.user or the .vcxproj.user file, depending on the
3207 version installed. As it is done for cmdargs (see above), you
3208 can specify a DebugSettings dictionary per variant. If you give
3209 only one, it will be propagated to all variants.
3210 Currently, only Visual Studio v9.0 and Visual Studio version v11
3212 are implemented, for other versions no file is generated. To
3213 generate the user file, you just need to add a DebugSettings
3214 dictionary to the environment with the right parameters for your
3215 MSVS version. If the dictionary is empty, or does not contain any
3216 good value, no file will be generated.
3217 Following is a more contrived example, involving the setup of a
3219 project for variants and DebugSettings:
3220 # Assuming you store your defaults in a file
3222 vars = Variables('variables.py')
3223 msvcver = vars.args.get('vc', '9')
3224 # Check command args to force one Microsoft Visual Studio version
3226 if msvcver == '9' or msvcver == '11':
3227 env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False)
3228 else:
3229 env = Environment()
3230 AddOption('--userfile', action='store_true', dest='userfile', default=False,
3232 help="Create Visual Studio Project user file")
3233 #
3235 # 1. Configure your Debug Setting dictionary with options you want in the list
3236 # of allowed options, for instance if you want to create a user file to launch
3237 # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
3238 #
3239 V9DebugSettings = {
3240 'Command':'c:\\myapp\\using\\thisdll.exe',
3241 'WorkingDirectory': 'c:\\myapp\\using\\',
3242 'CommandArguments': '-p password',
3243 # 'Attach':'false',
3244 # 'DebuggerType':'3',
3245 # 'Remote':'1',
3246 # 'RemoteMachine': None,
3247 # 'RemoteCommand': None,
3248 # 'HttpUrl': None,
3249 # 'PDBPath': None,
3250 # 'SQLDebugging': None,
3251 # 'Environment': '',
3252 # 'EnvironmentMerge':'true',
3253 # 'DebuggerFlavor': None,
3254 # 'MPIRunCommand': None,
3255 # 'MPIRunArguments': None,
3256 # 'MPIRunWorkingDirectory': None,
3257 # 'ApplicationCommand': None,
3258 # 'ApplicationArguments': None,
3259 # 'ShimCommand': None,
3260 # 'MPIAcceptMode': None,
3261 # 'MPIAcceptFilter': None,
3262 }
3263 #
3265 # 2. Because there are a lot of different options depending on the Microsoft
3266 # Visual Studio version, if you use more than one version you have to
3267 # define a dictionary per version, for instance if you want to create a user
3268 # file to launch a specific application for testing your dll with Microsoft
3269 # Visual Studio 2012 (v11):
3270 #
3271 V10DebugSettings = {
3272 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
3273 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
3274 'LocalDebuggerCommandArguments': '-p password',
3275 # 'LocalDebuggerEnvironment': None,
3276 # 'DebuggerFlavor': 'WindowsLocalDebugger',
3277 # 'LocalDebuggerAttach': None,
3278 # 'LocalDebuggerDebuggerType': None,
3279 # 'LocalDebuggerMergeEnvironment': None,
3280 # 'LocalDebuggerSQLDebugging': None,
3281 # 'RemoteDebuggerCommand': None,
3282 # 'RemoteDebuggerCommandArguments': None,
3283 # 'RemoteDebuggerWorkingDirectory': None,
3284 # 'RemoteDebuggerServerName': None,
3285 # 'RemoteDebuggerConnection': None,
3286 # 'RemoteDebuggerDebuggerType': None,
3287 # 'RemoteDebuggerAttach': None,
3288 # 'RemoteDebuggerSQLDebugging': None,
3289 # 'DeploymentDirectory': None,
3290 # 'AdditionalFiles': None,
3291 # 'RemoteDebuggerDeployDebugCppRuntime': None,
3292 # 'WebBrowserDebuggerHttpUrl': None,
3293 # 'WebBrowserDebuggerDebuggerType': None,
3294 # 'WebServiceDebuggerHttpUrl': None,
3295 # 'WebServiceDebuggerDebuggerType': None,
3296 # 'WebServiceDebuggerSQLDebugging': None,
3297 }
3298 #
3300 # 3. Select the dictionary you want depending on the version of visual Studio
3301 # Files you want to generate.
3302 #
3303 if not env.GetOption('userfile'):
3304 dbgSettings = None
3305 elif env.get('MSVC_VERSION', None) == '9.0':
3306 dbgSettings = V9DebugSettings
3307 elif env.get('MSVC_VERSION', None) == '11.0':
3308 dbgSettings = V10DebugSettings
3309 else:
3310 dbgSettings = None
3311 #
3313 # 4. Add the dictionary to the DebugSettings keyword.
3314 #
3315 barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
3316 barincs = ['targetver.h']
3317 barlocalincs = ['StdAfx.h']
3318 barresources = ['bar.rc','resource.h']
3319 barmisc = ['ReadMe.txt']
3320 dll = env.SharedLibrary(target='bar.dll',
3322 source=barsrcs)
3323 env.MSVSProject(target='Bar' + env['MSVSPROJECTSUFFIX'],
3325 srcs=barsrcs,
3326 incs=barincs,
3327 localincs=barlocalincs,
3328 resources=barresources,
3329 misc=barmisc,
3330 buildtarget=[dll[0]] * 2,
3331 variant=('Debug|Win32', 'Release|Win32'),
3332 cmdargs='vc=%s' % msvcver,
3333 DebugSettings=(dbgSettings, {}))
3334 MSVSSolution(), env.MSVSSolution()
3337 Builds a Microsoft Visual Studio solution file.
3338 This builds a Visual Studio solution file, based on the version of
3340 Visual Studio that is configured (either the latest installed
3341 version, or the version specified by $MSVS_VERSION in the
3342 construction environment). For Visual Studio 6, it will generate a
3343 .dsw file. For Visual Studio 7 (.NET), it will generate a .sln
3344 file.
3345 The following values must be specified:
3347 target
3349 The name of the target .dsw or .sln file. The correct suffix
3350 for the version of Visual Studio must be used, but the value
3351 $MSVSSOLUTIONSUFFIX will be defined to the correct value (see
3352 example below).
3353 variant
3355 The name of this particular variant, or a list of variant names
3356 (the latter is only supported for MSVS 7 solutions). These are
3357 typically things like "Debug" or "Release", but really can be
3358 anything you want. For MSVS 7 they may also specify target
3359 platform, like this "Debug|Xbox". Default platform is Win32.
3360 projects
3362 A list of project file names, or Project nodes returned by
3363 calls to the MSVSProject Builder, to be placed into the
3364 solution file. It should be noted that these file names are NOT
3365 added to the $SOURCES environment variable in form of files,
3366 but rather as strings. This is because they represent file
3367 names to be added to the solution file, not the source files
3368 used to build the solution file.
3369 Example Usage:
3371 env.MSVSSolution(
3373 target="Bar" + env["MSVSSOLUTIONSUFFIX"],
3374 projects=["bar" + env["MSVSPROJECTSUFFIX"]],
3375 variant="Release",
3376 )
3377 Ninja(), env.Ninja()
3380 Ninja is a special builder which adds a target to create a ninja
3382 build file. The builder does not require any source files to be
3383 specified.
3384 Note
3386 This is an experimental feature. To enable it you must use one
3387 of the following methods
3388 # On the command line
3390 --experimental=ninja
3391 # Or in your SConstruct
3393 SetOption('experimental', 'ninja')
3394 This functionality is subject to change and/or removal without
3397 deprecation cycle.
3398 To use this tool you must install pypi's ninja package[4]. This
3400 can be done via pip install ninja
3401 If called with no arguments, the builder will default to a target
3402 name of ninja.build.
3403 If called with a single positional argument, scons will "deduce"
3405 the target name from that source argument, giving it the same name,
3406 and then ignore the source. This is the usual way to call the
3407 builder if a non-default target name is wanted.
3408 If called with either the target= or source= keyword arguments, the
3410 value of the argument is taken as the target name. If called with
3411 both, the target= value is used and source= is ignored. If called
3412 with multiple sources, the source list will be ignored, since there
3413 is no way to deduce what the intent was; in this case the default
3414 target name will be used.
3415 Available since scons 4.2.
3418 Object(), env.Object()
3420 A synonym for the StaticObject builder method.
3421 Package(), env.Package()
3423 Builds software distribution packages. A package is a container
3424 format which includes files to install along with metadata.
3425 Packaging is optional, and must be enabled by specifying the
3426 packaging tool. For example:
3427 env = Environment(tools=['default', 'packaging'])
3429 SCons can build packages in a number of well known packaging
3432 formats. The target package type may be selected with the the
3433 $PACKAGETYPE construction variable or the --package-type command
3434 line option. The package type may be a list, in which case SCons
3435 will attempt to build packages for each type in the list. Example:
3436 env.Package(PACKAGETYPE=['src_zip', 'src_targz'], ...other args...)
3438 The currently supported packagers are:
3440 ┌───────────┬────────────────────────────┐
3442 │msi │ Microsoft Installer │
3443 │ │ package │
3444 ├───────────┼────────────────────────────┤
3445 │rpm │ RPM Package Manger package │
3446 ├───────────┼────────────────────────────┤
3447 │ipkg │ Itsy Package Management │
3448 │ │ package │
3449 ├───────────┼────────────────────────────┤
3450 │tarbz2 │ bzip2-compressed tar file │
3451 ├───────────┼────────────────────────────┤
3452 │targz │ gzip-compressed tar file │
3453 ├───────────┼────────────────────────────┤
3454 │tarxz │ xz-compressed tar file │
3455 ├───────────┼────────────────────────────┤
3456 │zip │ zip file │
3457 ├───────────┼────────────────────────────┤
3458 │src_tarbz2 │ bzip2-compressed tar file │
3459 │ │ suitable as source to │
3460 │ │ another packager │
3461 ├───────────┼────────────────────────────┤
3462 │src_targz │ gzip-compressed tar file │
3463 │ │ suitable as source to │
3464 │ │ another packager │
3465 ├───────────┼────────────────────────────┤
3466 │src_tarxz │ xz-compressed tar file │
3467 │ │ suitable as source to │
3468 │ │ another packager │
3469 ├───────────┼────────────────────────────┤
3470 │src_zip │ zip file suitable as │
3471 │ │ source to another packager │
3472 └───────────┴────────────────────────────┘
3473 The file list to include in the package may be specified with the
3474 source keyword argument. If omitted, the FindInstalledFiles
3475 function is called behind the scenes to select all files that have
3476 an Install, InstallAs or InstallVersionedLib Builder attached. If
3477 the target keyword argument is omitted, the target name(s) will be
3478 deduced from the package type(s).
3479 The metadata comes partly from attributes of the files to be
3481 packaged, and partly from packaging tags. Tags can be passed as
3482 keyword arguments to the Package builder call, and may also be
3483 attached to files (or more accurately, Nodes representing files)
3484 with the Tag function. Some package-level tags are mandatory, and
3485 will lead to errors if omitted. The mandatory tags vary depending
3486 on the package type.
3487 While packaging, the builder uses a temporary location named by the
3489 value of the $PACKAGEROOT variable - the package sources are copied
3490 there before packaging.
3491 Packaging example:
3493 env = Environment(tools=["default", "packaging"])
3495 env.Install("/bin/", "my_program")
3496 env.Package(
3497 NAME="foo",
3498 VERSION="1.2.3",
3499 PACKAGEVERSION=0,
3500 PACKAGETYPE="rpm",
3501 LICENSE="gpl",
3502 SUMMARY="balalalalal",
3503 DESCRIPTION="this should be really really long",
3504 X_RPM_GROUP="Application/fu",
3505 SOURCE_URL="https://foo.org/foo-1.2.3.tar.gz",
3506 )
3507 In this example, the target /bin/my_program created by the Install
3509 call would not be built by default since it is not under the
3510 project top directory. However, since no source is specified to the
3511 Package builder, it is selected for packaging by the default
3512 sources rule. Since packaging is done using $PACKAGEROOT, no write
3513 is actually done to the system's /bin directory, and the target
3514 will be selected since after rebasing to underneath $PACKAGEROOT it
3515 is now under the top directory of the project.
3516 PCH(), env.PCH()
3518 Builds a Microsoft Visual C++ precompiled header. Calling this
3519 builder returns a list of two targets: the PCH as the first
3520 element, and the object file as the second element. Normally the
3521 object file is ignored. This builder is only provided when
3522 Microsoft Visual C++ is being used as the compiler. The PCH builder
3523 is generally used in conjunction with the $PCH construction
3524 variable to force object files to use the precompiled header:
3525 env['PCH'] = env.PCH('StdAfx.cpp')[0]
3527 PDF(), env.PDF()
3529 Builds a .pdf file from a .dvi input file (or, by extension, a
3530 .tex, .ltx, or .latex input file). The suffix specified by the
3531 $PDFSUFFIX construction variable (.pdf by default) is added
3532 automatically to the target if it is not already present. Example:
3533 # builds from aaa.tex
3535 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
3536 # builds bbb.pdf from bbb.dvi
3537 env.PDF(target = 'bbb', source = 'bbb.dvi')
3538 POInit(), env.POInit()
3540 This builder belongs to msginit tool. The builder initializes
3541 missing PO file(s) if $POAUTOINIT is set. If $POAUTOINIT is not set
3542 (default), POInit prints instruction for user (that is supposed to
3543 be a translator), telling how the PO file should be initialized. In
3544 normal projects you should not use POInit and use POUpdate instead.
3545 POUpdate chooses intelligently between msgmerge(1) and msginit(1).
3546 POInit always uses msginit(1) and should be regarded as builder for
3547 special purposes or for temporary use (e.g. for quick, one time
3548 initialization of a bunch of PO files) or for tests.
3549 Target nodes defined through POInit are not built by default
3551 (they're Ignored from '.' node) but are added to special Alias
3552 ('po-create' by default). The alias name may be changed through the
3553 $POCREATE_ALIAS construction variable. All PO files defined through
3554 POInit may be easily initialized by scons po-create.
3555 Example 1. Initialize en.po and pl.po from messages.pot:
3558 # ...
3560 env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
3561 Example 2. Initialize en.po and pl.po from foo.pot:
3564 # ...
3566 env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
3567 Example 3. Initialize en.po and pl.po from foo.pot but using
3570 $POTDOMAIN construction variable:
3571 # ...
3573 env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
3574 Example 4. Initialize PO files for languages defined in LINGUAS
3577 file. The files will be initialized from template messages.pot:
3578 # ...
3580 env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3581 Example 5. Initialize en.po and pl.pl PO files plus files for
3584 languages defined in LINGUAS file. The files will be initialized
3585 from template messages.pot:
3586 # ...
3588 env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
3589 Example 6. You may preconfigure your environment first, and then
3592 initialize PO files:
3593 # ...
3595 env['POAUTOINIT'] = 1
3596 env['LINGUAS_FILE'] = 1
3597 env['POTDOMAIN'] = 'foo'
3598 env.POInit()
3599 which has same efect as:
3601 # ...
3603 env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
3604 PostScript(), env.PostScript()
3606 Builds a .ps file from a .dvi input file (or, by extension, a .tex,
3607 .ltx, or .latex input file). The suffix specified by the $PSSUFFIX
3608 construction variable (.ps by default) is added automatically to
3609 the target if it is not already present. Example:
3610 # builds from aaa.tex
3612 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
3613 # builds bbb.ps from bbb.dvi
3614 env.PostScript(target = 'bbb', source = 'bbb.dvi')
3615 POTUpdate(), env.POTUpdate()
3617 The builder belongs to xgettext tool. The builder updates target
3618 POT file if exists or creates one if it doesn't. The node is not
3619 built by default (i.e. it is Ignored from '.'), but only on demand
3620 (i.e. when given POT file is required or when special alias is
3621 invoked). This builder adds its targe node (messages.pot, say) to a
3622 special alias (pot-update by default, see $POTUPDATE_ALIAS) so you
3623 can update/create them easily with scons pot-update. The file is
3624 not written until there is no real change in internationalized
3625 messages (or in comments that enter POT file).
3626 Note
3629 You may see xgettext(1) being invoked by the xgettext tool even
3630 if there is no real change in internationalized messages (so
3631 the POT file is not being updated). This happens every time a
3632 source file has changed. In such case we invoke xgettext(1) and
3633 compare its output with the content of POT file to decide
3634 whether the file should be updated or not.
3635 Example 1. Let's create po/ directory and place following
3638 SConstruct script there:
3639 # SConstruct in 'po/' subdir
3641 env = Environment( tools = ['default', 'xgettext'] )
3642 env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
3643 env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
3644 Then invoke scons few times:
3646 user@host:$ scons # Does not create foo.pot nor bar.pot
3648 user@host:$ scons foo.pot # Updates or creates foo.pot
3649 user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
3650 user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
3651 the results shall be as the comments above say.
3653 Example 2. The POTUpdate builder may be used with no target
3656 specified, in which case default target messages.pot will be used.
3657 The default target may also be overridden by setting $POTDOMAIN
3658 construction variable or providing it as an override to POTUpdate
3659 builder:
3660 # SConstruct script
3663 env = Environment( tools = ['default', 'xgettext'] )
3664 env['POTDOMAIN'] = "foo"
3665 env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
3666 env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
3667 Example 3. The sources may be specified within separate file, for
3670 example POTFILES.in:
3671 # POTFILES.in in 'po/' subdirectory
3674 ../a.cpp
3675 ../b.cpp
3676 # end of file
3677 The name of the file (POTFILES.in) containing the list of sources
3679 is provided via $XGETTEXTFROM:
3680 # SConstruct file in 'po/' subdirectory
3683 env = Environment( tools = ['default', 'xgettext'] )
3684 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
3685 Example 4. You may use $XGETTEXTPATH to define source search path.
3688 Assume, for example, that you have files a.cpp, b.cpp,
3689 po/SConstruct, po/POTFILES.in. Then your POT-related files could
3690 look as below:
3691 # POTFILES.in in 'po/' subdirectory
3693 a.cpp
3694 b.cpp
3695 # end of file
3696 # SConstruct file in 'po/' subdirectory
3698 env = Environment( tools = ['default', 'xgettext'] )
3699 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
3700 Example 5. Multiple search directories may be defined within a
3703 list, i.e. XGETTEXTPATH = ['dir1', 'dir2', ...]. The order in the
3704 list determines the search order of source files. The path to the
3705 first file found is used.
3706 Let's create 0/1/po/SConstruct script:
3708 # SConstruct file in '0/1/po/' subdirectory
3710 env = Environment( tools = ['default', 'xgettext'] )
3711 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
3712 and 0/1/po/POTFILES.in:
3714 # POTFILES.in in '0/1/po/' subdirectory
3716 a.cpp
3717 # end of file
3718 Write two *.cpp files, the first one is 0/a.cpp:
3720 /* 0/a.cpp */
3722 gettext("Hello from ../../a.cpp")
3723 and the second is 0/1/a.cpp:
3725 /* 0/1/a.cpp */
3727 gettext("Hello from ../a.cpp")
3728 then run scons. You'll obtain 0/1/po/messages.pot with the message
3730 "Hello from ../a.cpp". When you reverse order in $XGETTEXTFOM, i.e.
3731 when you write SConscript as
3732 # SConstruct file in '0/1/po/' subdirectory
3734 env = Environment( tools = ['default', 'xgettext'] )
3735 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
3736 then the messages.pot will contain msgid "Hello from ../../a.cpp"
3738 line and not msgid "Hello from ../a.cpp".
3739 POUpdate(), env.POUpdate()
3741 The builder belongs to msgmerge tool. The builder updates PO files
3742 with msgmerge(1), or initializes missing PO files as described in
3743 documentation of msginit tool and POInit builder (see also
3744 $POAUTOINIT). Note, that POUpdate does not add its targets to
3745 po-create alias as POInit does.
3746 Target nodes defined through POUpdate are not built by default
3748 (they're Ignored from '.' node). Instead, they are added
3749 automatically to special Alias ('po-update' by default). The alias
3750 name may be changed through the $POUPDATE_ALIAS construction
3751 variable. You can easily update PO files in your project by scons
3752 po-update.
3753 Example 1. Update en.po and pl.po from messages.pot template (see
3756 also $POTDOMAIN), assuming that the later one exists or there is
3757 rule to build it (see POTUpdate):
3758 # ...
3760 env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
3761 Example 2. Update en.po and pl.po from foo.pot template:
3764 # ...
3766 env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
3767 Example 3. Update en.po and pl.po from foo.pot (another version):
3770 # ...
3772 env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
3773 Example 4. Update files for languages defined in LINGUAS file. The
3776 files are updated from messages.pot template:
3777 # ...
3779 env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3780 Example 5. Same as above, but update from foo.pot template:
3783 # ...
3785 env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
3786 Example 6. Update en.po and pl.po plus files for languages defined
3789 in LINGUAS file. The files are updated from messages.pot template:
3790 # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
3792 env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
3793 Example 7. Use $POAUTOINIT to automatically initialize PO file if
3796 it doesn't exist:
3797 # ...
3799 env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
3800 Example 8. Update PO files for languages defined in LINGUAS file.
3803 The files are updated from foo.pot template. All necessary settings
3804 are pre-configured via environment.
3805 # ...
3807 env['POAUTOINIT'] = 1
3808 env['LINGUAS_FILE'] = 1
3809 env['POTDOMAIN'] = 'foo'
3810 env.POUpdate()
3811 Program(), env.Program()
3813 Builds an executable given one or more object files or C, C++, D,
3814 or Fortran source files. If any C, C++, D or Fortran source files
3815 are specified, then they will be automatically compiled to object
3816 files using the Object builder method; see that builder method's
3817 description for a list of legal source file suffixes and how they
3818 are interpreted. The target executable file prefix, specified by
3819 the $PROGPREFIX construction variable (nothing by default), and
3820 suffix, specified by the $PROGSUFFIX construction variable (by
3821 default, .exe on Windows systems, nothing on POSIX systems), are
3822 automatically added to the target if not already present. Example:
3823 env.Program(target='foo', source=['foo.o', 'bar.c', 'baz.f'])
3825 ProgramAllAtOnce(), env.ProgramAllAtOnce()
3827 Builds an executable from D sources without first creating
3828 individual objects for each file.
3829 D sources can be compiled file-by-file as C and C++ source are, and
3831 D is integrated into the scons Object and Program builders for this
3832 model of build. D codes can though do whole source meta-programming
3833 (some of the testing frameworks do this). For this it is imperative
3834 that all sources are compiled and linked in a single call to the D
3835 compiler. This builder serves that purpose.
3836 env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
3838 This command will compile the modules mod_a, mod_b, and mod_c in a
3841 single compilation process without first creating object files for
3842 the modules. Some of the D compilers will create executable.o
3843 others will not.
3844 RES(), env.RES()
3846 Builds a Microsoft Visual C++ resource file. This builder method is
3847 only provided when Microsoft Visual C++ or MinGW is being used as
3848 the compiler. The .res (or .o for MinGW) suffix is added to the
3849 target name if no other suffix is given. The source file is scanned
3850 for implicit dependencies as though it were a C file. Example:
3851 env.RES('resource.rc')
3853 RMIC(), env.RMIC()
3855 Builds stub and skeleton class files for remote objects from Java
3856 .class files. The target is a directory relative to which the stub
3857 and skeleton class files will be written. The source can be the
3858 names of .class files, or the objects return from the Java builder
3859 method.
3860 If the construction variable $JAVACLASSDIR is set, either in the
3862 environment or in the call to the RMIC builder method itself, then
3863 the value of the variable will be stripped from the beginning of
3864 any .class file names.
3865 classes = env.Java(target = 'classdir', source = 'src')
3867 env.RMIC(target = 'outdir1', source = classes)
3868 env.RMIC(target = 'outdir2',
3870 source = ['package/foo.class', 'package/bar.class'])
3871 env.RMIC(target = 'outdir3',
3873 source = ['classes/foo.class', 'classes/bar.class'],
3874 JAVACLASSDIR = 'classes')
3875 RPCGenClient(), env.RPCGenClient()
3877 Generates an RPC client stub (_clnt.c) file from a specified RPC
3878 (.x) source file. Because rpcgen only builds output files in the
3879 local directory, the command will be executed in the source file's
3880 directory by default.
3881 # Builds src/rpcif_clnt.c
3883 env.RPCGenClient('src/rpcif.x')
3884 RPCGenHeader(), env.RPCGenHeader()
3886 Generates an RPC header (.h) file from a specified RPC (.x) source
3887 file. Because rpcgen only builds output files in the local
3888 directory, the command will be executed in the source file's
3889 directory by default.
3890 # Builds src/rpcif.h
3892 env.RPCGenHeader('src/rpcif.x')
3893 RPCGenService(), env.RPCGenService()
3895 Generates an RPC server-skeleton (_svc.c) file from a specified RPC
3896 (.x) source file. Because rpcgen only builds output files in the
3897 local directory, the command will be executed in the source file's
3898 directory by default.
3899 # Builds src/rpcif_svc.c
3901 env.RPCGenClient('src/rpcif.x')
3902 RPCGenXDR(), env.RPCGenXDR()
3904 Generates an RPC XDR routine (_xdr.c) file from a specified RPC
3905 (.x) source file. Because rpcgen only builds output files in the
3906 local directory, the command will be executed in the source file's
3907 directory by default.
3908 # Builds src/rpcif_xdr.c
3910 env.RPCGenClient('src/rpcif.x')
3911 SharedLibrary(), env.SharedLibrary()
3913 Builds a shared library (.so on a POSIX system, .dll on Windows)
3914 given one or more object files or C, C++, D or Fortran source
3915 files. If any source files are given, then they will be
3916 automatically compiled to object files. The target library file
3917 prefix, specified by the $SHLIBPREFIX construction variable (by
3918 default, lib on POSIX systems, nothing on Windows systems), and
3919 suffix, specified by the $SHLIBSUFFIX construction variable (by
3920 default, .dll on Windows systems, .so on POSIX systems), are
3921 automatically added to the target if not already present. Example:
3922 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'])
3924 On Windows systems, the SharedLibrary builder method will always
3926 build an import library (.lib) in addition to the shared library
3927 (.dll), adding a .lib library with the same basename if there is
3928 not already a .lib file explicitly listed in the targets.
3929 On Cygwin systems, the SharedLibrary builder method will always
3931 build an import library (.dll.a) in addition to the shared library
3932 (.dll), adding a .dll.a library with the same basename if there is
3933 not already a .dll.a file explicitly listed in the targets.
3934 Any object files listed in the source must have been built for a
3936 shared library (that is, using the SharedObject builder method).
3937 scons will raise an error if there is any mismatch.
3938 On some platforms, there is a distinction between a shared library
3940 (loaded automatically by the system to resolve external references)
3941 and a loadable module (explicitly loaded by user action). For
3942 maximum portability, use the LoadableModule builder for the latter.
3943 When the $SHLIBVERSION construction variable is defined, a
3945 versioned shared library is created. This modifies $SHLINKFLAGS as
3946 required, adds the version number to the library name, and creates
3947 any symbolic links that are needed.
3948 env.SharedLibrary(target='bar', source=['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
3950 On a POSIX system, versions with a single token create exactly one
3952 symlink: libbar.so.6 would have symlink libbar.so only. On a POSIX
3953 system, versions with two or more tokens create exactly two
3954 symlinks: libbar.so.2.3.1 would have symlinks libbar.so and
3955 libbar.so.2; on a Darwin (OSX) system the library would be
3956 libbar.2.3.1.dylib and the link would be libbar.dylib.
3957 On Windows systems, specifying register=1 will cause the .dll to be
3959 registered after it is built. The command that is run is determined
3960 by the $REGSVR construction variable (regsvr32 by default), and the
3961 flags passed are determined by $REGSVRFLAGS. By default,
3962 $REGSVRFLAGS includes the /s option, to prevent dialogs from
3963 popping up and requiring user attention when it is run. If you
3964 change $REGSVRFLAGS, be sure to include the /s option. For example,
3965 env.SharedLibrary(target='bar', source=['bar.cxx', 'foo.obj'], register=1)
3967 will register bar.dll as a COM object when it is done linking it.
3969 SharedObject(), env.SharedObject()
3971 Builds an object file intended for inclusion in a shared library.
3972 Source files must have one of the same set of extensions specified
3973 above for the StaticObject builder method. On some platforms
3974 building a shared object requires additional compiler option (e.g.
3975 -fPIC for gcc) in addition to those needed to build a normal
3976 (static) object, but on some platforms there is no difference
3977 between a shared object and a normal (static) one. When there is a
3978 difference, SCons will only allow shared objects to be linked into
3979 a shared library, and will use a different suffix for shared
3980 objects. On platforms where there is no difference, SCons will
3981 allow both normal (static) and shared objects to be linked into a
3982 shared library, and will use the same suffix for shared and normal
3983 (static) objects. The target object file prefix, specified by the
3984 $SHOBJPREFIX construction variable (by default, the same as
3985 $OBJPREFIX), and suffix, specified by the $SHOBJSUFFIX construction
3986 variable, are automatically added to the target if not already
3987 present. Examples:
3988 env.SharedObject(target='ddd', source='ddd.c')
3990 env.SharedObject(target='eee.o', source='eee.cpp')
3991 env.SharedObject(target='fff.obj', source='fff.for')
3992 Note that the source files will be scanned according to the suffix
3994 mappings in the SourceFileScanner object. See the manpage section
3995 "Scanner Objects" for more information.
3996 StaticLibrary(), env.StaticLibrary()
3998 Builds a static library given one or more object files or C, C++, D
3999 or Fortran source files. If any source files are given, then they
4000 will be automatically compiled to object files. The static library
4001 file prefix, specified by the $LIBPREFIX construction variable (by
4002 default, lib on POSIX systems, nothing on Windows systems), and
4003 suffix, specified by the $LIBSUFFIX construction variable (by
4004 default, .lib on Windows systems, .a on POSIX systems), are
4005 automatically added to the target if not already present. Example:
4006 env.StaticLibrary(target='bar', source=['bar.c', 'foo.o'])
4008 Any object files listed in the source must have been built for a
4010 static library (that is, using the StaticObject builder method).
4011 scons will raise an error if there is any mismatch.
4012 StaticObject(), env.StaticObject()
4014 Builds a static object file from one or more C, C++, D, or Fortran
4015 source files. Source files must have one of the following
4016 extensions:
4017 .asm assembly language file
4019 .ASM assembly language file
4020 .c C file
4021 .C Windows: C file
4022 POSIX: C++ file
4023 .cc C++ file
4024 .cpp C++ file
4025 .cxx C++ file
4026 .cxx C++ file
4027 .c++ C++ file
4028 .C++ C++ file
4029 .d D file
4030 .f Fortran file
4031 .F Windows: Fortran file
4032 POSIX: Fortran file + C pre-processor
4033 .for Fortran file
4034 .FOR Fortran file
4035 .fpp Fortran file + C pre-processor
4036 .FPP Fortran file + C pre-processor
4037 .m Object C file
4038 .mm Object C++ file
4039 .s assembly language file
4040 .S Windows: assembly language file
4041 ARM: CodeSourcery Sourcery Lite
4042 .sx assembly language file + C pre-processor
4043 POSIX: assembly language file + C pre-processor
4044 .spp assembly language file + C pre-processor
4045 .SPP assembly language file + C pre-processor
4046 The target object file prefix, specified by the $OBJPREFIX
4048 construction variable (nothing by default), and suffix, specified
4049 by the $OBJSUFFIX construction variable (.obj on Windows systems,
4050 .o on POSIX systems), are automatically added to the target if not
4051 already present. Examples:
4052 env.StaticObject(target='aaa', source='aaa.c')
4054 env.StaticObject(target='bbb.o', source='bbb.c++')
4055 env.StaticObject(target='ccc.obj', source='ccc.f')
4056 Note that the source files will be scanned according to the suffix
4058 mappings in the SourceFileScanner object. See the manpage section
4059 "Scanner Objects" for more information.
4060 Substfile(), env.Substfile()
4062 The Substfile builder creates a single text file from a template
4063 consisting of a file or set of files (or nodes), replacing text
4064 using the $SUBST_DICT construction variable (if set). If a set,
4065 they are concatenated into the target file using the value of the
4066 $LINESEPARATOR construction variable as a separator between
4067 contents; the separator is not emitted after the contents of the
4068 last file. Nested lists of source files are flattened. See also
4069 Textfile.
4070 If a single source file name is specified and has a .in suffix, the
4072 suffix is stripped and the remainder of the name is used as the
4073 default target name.
4074 The prefix and suffix specified by the $SUBSTFILEPREFIX and
4076 $SUBSTFILESUFFIX construction variables (an empty string by default
4077 in both cases) are automatically added to the target if they are
4078 not already present.
4079 If a construction variable named $SUBST_DICT is present, it may be
4081 either a Python dictionary or a sequence of (key, value) tuples. If
4082 it is a dictionary it is converted into a list of tuples with
4083 unspecified order, so if one key is a prefix of another key or if
4084 one substitution could be further expanded by another subsitition,
4085 it is unpredictable whether the expansion will occur.
4086 Any occurrences of a key in the source are replaced by the
4088 corresponding value, which may be a Python callable function or a
4089 string. If the value is a callable, it is called with no arguments
4090 to get a string. Strings are subst-expanded and the result replaces
4091 the key.
4092 env = Environment(tools=['default'])
4094 env['prefix'] = '/usr/bin'
4096 script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
4097 env.Substfile('script.in', SUBST_DICT=script_dict)
4098 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
4100 env.Substfile('config.h.in', conf_dict, SUBST_DICT=conf_dict)
4101 # UNPREDICTABLE - one key is a prefix of another
4103 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
4104 env.Substfile('foo.in', SUBST_DICT=bad_foo)
4105 # PREDICTABLE - keys are applied longest first
4107 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
4108 env.Substfile('foo.in', SUBST_DICT=good_foo)
4109 # UNPREDICTABLE - one substitution could be futher expanded
4111 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
4112 env.Substfile('bar.in', SUBST_DICT=bad_bar)
4113 # PREDICTABLE - substitutions are expanded in order
4115 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
4116 env.Substfile('bar.in', SUBST_DICT=good_bar)
4117 # the SUBST_DICT may be in common (and not an override)
4119 substutions = {}
4120 subst = Environment(tools=['textfile'], SUBST_DICT=substitutions)
4121 substitutions['@foo@'] = 'foo'
4122 subst['SUBST_DICT']['@bar@'] = 'bar'
4123 subst.Substfile(
4124 'pgm1.c',
4125 [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm1.in"],
4126 )
4127 subst.Substfile(
4128 'pgm2.c',
4129 [Value('#include "@foo@.h"'), Value('#include "@bar@.h"'), "common.in", "pgm2.in"],
4130 )
4131 Tar(), env.Tar()
4134 Builds a tar archive of the specified files and/or directories.
4135 Unlike most builder methods, the Tar builder method may be called
4136 multiple times for a given target; each additional call adds to the
4137 list of entries that will be built into the archive. Any source
4138 directories will be scanned for changes to any on-disk files,
4139 regardless of whether or not scons knows about them from other
4140 Builder or function calls.
4141 env.Tar('src.tar', 'src')
4143 # Create the stuff.tar file.
4145 env.Tar('stuff', ['subdir1', 'subdir2'])
4146 # Also add "another" to the stuff.tar file.
4147 env.Tar('stuff', 'another')
4148 # Set TARFLAGS to create a gzip-filtered archive.
4150 env = Environment(TARFLAGS = '-c -z')
4151 env.Tar('foo.tar.gz', 'foo')
4152 # Also set the suffix to .tgz.
4154 env = Environment(TARFLAGS = '-c -z',
4155 TARSUFFIX = '.tgz')
4156 env.Tar('foo')
4157 Textfile(), env.Textfile()
4159 The Textfile builder generates a single text file from a template
4160 consisting of a list of strings, replacing text using the
4161 $SUBST_DICT construction variable (if set) - see Substfile for a
4162 description of replacement. The strings will be separated in the
4163 target file using the value of the $LINESEPARATOR construction
4164 variable; the line separator is not emitted after the last string.
4165 Nested lists of source strings are flattened. Source strings need
4166 not literally be Python strings: they can be Nodes or Python
4167 objects that convert cleanly to Value nodes
4168 The prefix and suffix specified by the $TEXTFILEPREFIX and
4170 $TEXTFILESUFFIX construction variables (by default an empty string
4171 and .txt, respectively) are automatically added to the target if
4172 they are not already present. Examples:
4173 # builds/writes foo.txt
4175 env.Textfile(target='foo.txt', source=['Goethe', 42, 'Schiller'])
4176 # builds/writes bar.txt
4178 env.Textfile(target='bar', source=['lalala', 'tanteratei'], LINESEPARATOR='|*')
4179 # nested lists are flattened automatically
4181 env.Textfile(target='blob', source=['lalala', ['Goethe', 42, 'Schiller'], 'tanteratei'])
4182 # files may be used as input by wraping them in File()
4184 env.Textfile(
4185 target='concat', # concatenate files with a marker between
4186 source=[File('concat1'), File('concat2')],
4187 LINESEPARATOR='====================\n',
4188 )
4189 Results:
4191 foo.txt
4193 Goethe
4195 42
4196 Schiller
4197 bar.txt
4199 lalala|*tanteratei
4201 blob.txt
4203 lalala
4205 Goethe
4206 42
4207 Schiller
4208 tanteratei
4209 Translate(), env.Translate()
4211 This pseudo-builder belongs to gettext toolset. The builder
4212 extracts internationalized messages from source files, updates POT
4213 template (if necessary) and then updates PO translations (if
4214 necessary). If $POAUTOINIT is set, missing PO files will be
4215 automatically created (i.e. without translator person
4216 intervention). The variables $LINGUAS_FILE and $POTDOMAIN are taken
4217 into acount too. All other construction variables used by
4218 POTUpdate, and POUpdate work here too.
4219 Example 1. The simplest way is to specify input files and output
4222 languages inline in a SCons script when invoking Translate
4223 # SConscript in 'po/' directory
4225 env = Environment( tools = ["default", "gettext"] )
4226 env['POAUTOINIT'] = 1
4227 env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
4228 Example 2. If you wish, you may also stick to conventional style
4231 known from autotools, i.e. using POTFILES.in and LINGUAS files
4232 # LINGUAS
4234 en pl
4235 #end
4236 # POTFILES.in
4238 a.cpp
4239 b.cpp
4240 # end
4241 # SConscript
4243 env = Environment( tools = ["default", "gettext"] )
4244 env['POAUTOINIT'] = 1
4245 env['XGETTEXTPATH'] = ['../']
4246 env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
4247 The last approach is perhaps the recommended one. It allows easily
4249 split internationalization/localization onto separate SCons
4250 scripts, where a script in source tree is responsible for
4251 translations (from sources to PO files) and script(s) under variant
4252 directories are responsible for compilation of PO to MO files to
4253 and for installation of MO files. The "gluing factor" synchronizing
4254 these two scripts is then the content of LINGUAS file. Note, that
4255 the updated POT and PO files are usually going to be committed back
4256 to the repository, so they must be updated within the source
4257 directory (and not in variant directories). Additionaly, the file
4258 listing of po/ directory contains LINGUAS file, so the source tree
4259 looks familiar to translators, and they may work with the project
4260 in their usual way.
4261 Example 3. Let's prepare a development tree as below
4264 project/
4266 + SConstruct
4267 + build/
4268 + src/
4269 + po/
4270 + SConscript
4271 + SConscript.i18n
4272 + POTFILES.in
4273 + LINGUAS
4274 with build being variant directory. Write the top-level SConstruct
4276 script as follows
4277 # SConstruct
4279 env = Environment( tools = ["default", "gettext"] )
4280 VariantDir('build', 'src', duplicate = 0)
4281 env['POAUTOINIT'] = 1
4282 SConscript('src/po/SConscript.i18n', exports = 'env')
4283 SConscript('build/po/SConscript', exports = 'env')
4284 the src/po/SConscript.i18n as
4286 # src/po/SConscript.i18n
4288 Import('env')
4289 env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
4290 and the src/po/SConscript
4292 # src/po/SConscript
4294 Import('env')
4295 env.MOFiles(LINGUAS_FILE = 1)
4296 Such setup produces POT and PO files under source tree in src/po/
4298 and binary MO files under variant tree in build/po/. This way the
4299 POT and PO files are separated from other output files, which must
4300 not be committed back to source repositories (e.g. MO files).
4301 Note
4304 In above example, the PO files are not updated, nor created
4305 automatically when you issue scons '.' command. The files must
4306 be updated (created) by hand via scons po-update and then MO
4307 files can be compiled by running scons '.'.
4308 TypeLibrary(), env.TypeLibrary()
4310 Builds a Windows type library (.tlb) file from an input IDL file
4311 (.idl). In addition, it will build the associated interface stub
4312 and proxy source files, naming them according to the base name of
4313 the .idl file. For example,
4314 env.TypeLibrary(source="foo.idl")
4316 Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c files.
4318 Uic(), env.Uic()
4320 Builds a header file, an implementation file and a moc file from an
4321 ui file. and returns the corresponding nodes in the that order.
4322 This builder is only available after using the tool qt. Note: you
4323 can specify .ui files directly as source files to the Program,
4324 Library and SharedLibrary builders without using this builder.
4325 Using this builder lets you override the standard naming
4326 conventions (be careful: prefixes are always prepended to names of
4327 built files; if you don't want prefixes, you may set them to ``).
4328 See the $QTDIR variable for more information. Example:
4329 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
4331 env.Uic(
4332 target=Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
4333 source='foo.ui'
4334 ) # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
4335 Zip(), env.Zip()
4337 Builds a zip archive of the specified files and/or directories.
4338 Unlike most builder methods, the Zip builder method may be called
4339 multiple times for a given target; each additional call adds to the
4340 list of entries that will be built into the archive. Any source
4341 directories will be scanned for changes to any on-disk files,
4342 regardless of whether or not scons knows about them from other
4343 Builder or function calls.
4344 env.Zip('src.zip', 'src')
4346 # Create the stuff.zip file.
4348 env.Zip('stuff', ['subdir1', 'subdir2'])
4349 # Also add "another" to the stuff.tar file.
4350 env.Zip('stuff', 'another')
4351 All targets of builder methods automatically depend on their sources.
4353 An explicit dependency can be specified using the env.Depends method of
4354 a construction environment (see below).
4355 In addition, scons automatically scans source files for various
4357 programming languages, so the dependencies do not need to be specified
4358 explicitly. By default, SCons can C source files, C++ source files,
4359 Fortran source files with .F (POSIX systems only), .fpp, or .FPP file
4360 extensions, and assembly language files with .S (POSIX systems only),
4361 .spp, or .SPP files extensions for C preprocessor dependencies. SCons
4362 also has default support for scanning D source files, You can also
4363 write your own Scanners to add support for additional source file
4364 types. These can be added to the default Scanner object used by the
4365 Object, StaticObject and SharedObject Builders by adding them to the
4366 SourceFileScanner object. See the section called “Scanner Objects” for
4367 more information about defining your own Scanner objects and using the
4368 SourceFileScanner object.
4369 Methods and Functions To Do Things
4371 In addition to Builder methods, scons provides a number of other
4372 construction environment methods and global functions to manipulate the
4373 build configuration.
4374 Usually, a construction environment method and global function with the
4376 same name both exist for convenience. In the following list, the global
4377 function is documented in this style:
4378 Function(arguments, [optional arguments])
4380 and the construction environment method looks like:
4382 env.Function(arguments, [optional arguments])
4384 If the function can be called both ways, then both forms are listed.
4386 The global function and same-named construction environment method
4388 provide almost identical functionality, with a couple of exceptions.
4389 First, many of the construction environment methods affect only that
4390 construction environment, while the global function has a global
4391 effect. Second, where appropriate, calling the functionality through a
4392 construction environment will substitute construction variables into
4393 any supplied string arguments, while the global function doesn't have
4394 the context of a construction environment to pick variables from, so it
4395 cannot perform the substitution. For example:
4396 Default('$FOO')
4398 env = Environment(FOO='foo')
4400 env.Default('$FOO')
4401 In the above example, the call to the global Default function will add
4403 a target named $FOO to the list of default targets, while the call to
4404 the env.Default construction environment method will expand the value
4405 and add a target named foo to the list of default targets. For more on
4406 construction variable expansion, see the next section on construction
4407 variables.
4408 Global functions may be called from custom Python modules that you
4410 import into an SConscript file by adding the following import to the
4411 Python module:
4412 from SCons.Script import *
4414 Construction environment methods and global functions provided by scons
4416 include:
4417 Action(action, [output, [var, ...]] [key=value, ...]),
4419 env.Action(action, [output, [var, ...]] [key=value, ...])
4420 A factory function to create an Action object for the specified
4421 action. See the manpage section "Action Objects" for a complete
4422 explanation of the arguments and behavior.
4423 Note that the env.Action form of the invocation will expand
4425 construction variables in any argument strings, including the
4426 action argument, at the time it is called using the construction
4427 variables in the env construction environment through which
4428 env.Action was called. The Action global function form delays all
4429 variable expansion until the Action object is actually used.
4430 AddMethod(object, function, [name]), env.AddMethod(function, [name])
4432 Adds function to an object as a method. function will be called
4433 with an instance object as the first argument as for other methods.
4434 If name is given, it is used as the name of the new method, else
4435 the name of function is used.
4436 When the global function AddMethod is called, the object to add the
4438 method to must be passed as the first argument; typically this will
4439 be Environment, in order to create a method which applies to all
4440 construction environments subsequently constructed. When called
4441 using the env.AddMethod form, the method is added to the specified
4442 construction environment only. Added methods propagate through
4443 env.Clone calls.
4444 Examples:
4446 # Function to add must accept an instance argument.
4448 # The Python convention is to call this 'self'.
4449 def my_method(self, arg):
4450 print("my_method() got", arg)
4451 # Use the global function to add a method to the Environment class:
4453 AddMethod(Environment, my_method)
4454 env = Environment()
4455 env.my_method('arg')
4456 # Use the optional name argument to set the name of the method:
4458 env.AddMethod(my_method, 'other_method_name')
4459 env.other_method_name('another arg')
4460 AddOption(arguments)
4462 Adds a local (project-specific) command-line option. arguments are
4463 the same as those supported by the add_option method in the
4464 standard Python library module optparse, with a few additional
4465 capabilities noted below. See the documentation for optparse for a
4466 thorough discussion of its option-processing capabities.
4467 In addition to the arguments and values supported by the optparse
4469 add_option method, AddOption allows setting the nargs keyword value
4470 to a string consisting of a question mark ('?') to indicate that
4471 the option argument for that option string is optional. If the
4472 option string is present on the command line but has no matching
4473 option argument, the value of the const keyword argument is
4474 produced as the value of the option. If the option string is
4475 omitted from the command line, the value of the default keyword
4476 argument is produced, as usual; if there is no default keyword
4477 argument in the AddOption call, None is produced.
4478 optparse recognizes abbreviations of long option names, as long as
4481 they can be unambiguously resolved. For example, if add_option is
4482 called to define a --devicename option, it will recognize --device,
4483 --dev and so forth as long as there is no other option which could
4484 also match to the same abbreviation. Options added via AddOption do
4485 not support the automatic recognition of abbreviations. Instead, to
4486 allow specific abbreviations, include them as synonyms in the
4487 AddOption call itself.
4488 Once a new command-line option has been added with AddOption, the
4490 option value may be accessed using GetOption or env.GetOption.
4491 SetOption is not currently supported for options added with
4492 AddOption.
4493 Help text for an option is a combination of the string supplied in
4495 the help keyword argument to AddOption and information collected
4496 from the other keyword arguments. Such help is displayed if the -h
4497 command line option is used (but not with -H). Help for all local
4498 options is displayed under the separate heading Local Options. The
4499 options are unsorted - they will appear in the help text in the
4500 order in which the AddOption calls occur.
4501 Example:
4503 AddOption(
4505 '--prefix',
4506 dest='prefix',
4507 nargs=1,
4508 type='string',
4509 action='store',
4510 metavar='DIR',
4511 help='installation prefix',
4512 )
4513 env = Environment(PREFIX=GetOption('prefix'))
4514 For that example, the following help text would be produced:
4516 Local Options:
4518 --prefix=DIR installation prefix
4519 Help text for local options may be unavailable if the Help function
4521 has been called, see the Help documentation for details.
4522 Note
4524 As an artifact of the internal implementation, the behavior of
4525 options added by AddOption which take option arguments is
4526 undefined if whitespace (rather than an = sign) is used as the
4527 separator on the command line. Users should avoid such usage;
4528 it is recommended to add a note to this effect to project
4529 documentation if the situation is likely to arise. In addition,
4530 if the nargs keyword is used to specify more than one following
4531 option argument (that is, with a value of 2 or greater), such
4532 arguments would necessarily be whitespace separated, triggering
4533 the issue. Developers should not use AddOption this way. Future
4534 versions of SCons will likely forbid such usage.
4535 AddPostAction(target, action), env.AddPostAction(target, action)
4537 Arranges for the specified action to be performed after the
4538 specified target has been built. The specified action(s) may be an
4539 Action object, or anything that can be converted into an Action
4540 object See the manpage section "Action Objects" for a complete
4541 explanation.
4542 When multiple targets are supplied, the action may be called
4544 multiple times, once after each action that generates one or more
4545 targets in the list.
4546 AddPreAction(target, action), env.AddPreAction(target, action)
4548 Arranges for the specified action to be performed before the
4549 specified target is built. The specified action(s) may be an Action
4550 object, or anything that can be converted into an Action object See
4551 the manpage section "Action Objects" for a complete explanation.
4552 When multiple targets are specified, the action(s) may be called
4554 multiple times, once before each action that generates one or more
4555 targets in the list.
4556 Note that if any of the targets are built in multiple steps, the
4558 action will be invoked just before the "final" action that
4559 specifically generates the specified target(s). For example, when
4560 building an executable program from a specified source .c file via
4561 an intermediate object file:
4562 foo = Program('foo.c')
4564 AddPreAction(foo, 'pre_action')
4565 The specified pre_action would be executed before scons calls the
4567 link command that actually generates the executable program binary
4568 foo, not before compiling the foo.c file into an object file.
4569 Alias(alias, [targets, [action]]), env.Alias(alias, [targets,
4571 [action]])
4572 Creates one or more phony targets that expand to one or more other
4573 targets. An optional action (command) or list of actions can be
4574 specified that will be executed whenever the any of the alias
4575 targets are out-of-date. Returns the Node object representing the
4576 alias, which exists outside of any file system. This Node object,
4577 or the alias name, may be used as a dependency of any other target,
4578 including another alias. Alias can be called multiple times for
4579 the same alias to add additional targets to the alias, or
4580 additional actions to the list for this alias. Aliases are global
4581 even if set through the construction environment method.
4582 Examples:
4584 Alias('install')
4586 Alias('install', '/usr/bin')
4587 Alias(['install', 'install-lib'], '/usr/local/lib')
4588 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
4590 env.Alias('install', ['/usr/local/man'])
4591 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
4593 AllowSubstExceptions([exception, ...])
4595 Specifies the exceptions that will be allowed when expanding
4596 construction variables. By default, any construction variable
4597 expansions that generate a NameError or IndexError exception will
4598 expand to a '' (an empty string) and not cause scons to fail. All
4599 exceptions not in the specified list will generate an error message
4600 and terminate processing.
4601 If AllowSubstExceptions is called multiple times, each call
4603 completely overwrites the previous list of allowed exceptions.
4604 Example:
4606 # Requires that all construction variable names exist.
4608 # (You may wish to do this if you want to enforce strictly
4609 # that all construction variables must be defined before use.)
4610 AllowSubstExceptions()
4611 # Also allow a string containing a zero-division expansion
4613 # like '${1 / 0}' to evalute to ''.
4614 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
4615 AlwaysBuild(target, ...), env.AlwaysBuild(target, ...)
4617 Marks each given target so that it is always assumed to be out of
4618 date, and will always be rebuilt if needed. Note, however, that
4619 AlwaysBuild does not add its target(s) to the default target list,
4620 so the targets will only be built if they are specified on the
4621 command line, or are a dependent of a target specified on the
4622 command line--but they will always be built if so specified.
4623 Multiple targets can be passed in to a single call to AlwaysBuild.
4624 env.Append(key=val, [...])
4626 Intelligently append values to construction variables in the
4627 construction environment named by env. The construction variables
4628 and values to add to them are passed as key=val pairs (Python
4629 keyword arguments). env.Append is designed to allow adding values
4630 without normally having to know the data type of an existing
4631 construction variable. Regular Python syntax can also be used to
4632 manipulate the construction variable, but for that you must know
4633 the type of the construction variable: for example, different
4634 Python syntax is needed to combine a list of values with a single
4635 string value, or vice versa. Some pre-defined construction
4636 variables do have type expectations based on how SCons will use
4637 them, for example $CPPDEFINES is normally a string or a list of
4638 strings, but can be a string, a list of strings, a list of tuples,
4639 or a dictionary, while $LIBEMITTER would expect a callable or list
4640 of callables, and $BUILDERS would expect a mapping type. Consult
4641 the documentation for the various construction variables for more
4642 details.
4643 The following descriptions apply to both the append and prepend
4645 functions, the only difference being the insertion point of the
4646 added values.
4647 If env. does not have a construction variable indicated by key, val
4649 is added to the environment under that key as-is.
4650 val can be almost any type, and SCons will combine it with an
4653 existing value into an appropriate type, but there are a few
4654 special cases to be aware of. When two strings are combined, the
4655 result is normally a new string, with the caller responsible for
4656 supplying any needed separation. The exception to this is the
4657 construction variable $CPPDEFINES, in which each item will be
4658 postprocessed by adding a prefix and/or suffix, so the contents are
4659 treated as a list of strings, that is, adding a string will result
4660 in a separate string entry, not a combined string. For $CPPDEFINES
4661 as well as for $LIBS, and the various *PATH variables, SCons will
4662 supply the compiler-specific syntax (e.g. adding a -D or /D prefix
4663 for $CPPDEFINES), so this syntax should be omitted when adding
4664 values to these variables. Example (gcc syntax shown in the
4665 expansion of CPPDEFINES):
4666 env = Environment(CXXFLAGS="-std=c11", CPPDEFINES="RELEASE")
4668 print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['CPPDEFINES']))
4669 # notice including a leading space in CXXFLAGS value
4670 env.Append(CXXFLAGS=" -O", CPPDEFINES="EXTRA")
4671 print("CXXFLAGS={}, CPPDEFINES={}".format(env['CXXFLAGS'], env['CPPDEFINES']))
4672 print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFLAGS")))
4673 $ scons -Q
4675 CXXFLAGS=-std=c11, CPPDEFINES=RELEASE
4676 CXXFLAGS=-std=c11 -O, CPPDEFINES=['RELEASE', 'EXTRA']
4677 CPPDEFINES will expand to -DRELEASE -DEXTRA
4678 scons: `.' is up to date.
4679 Because $CPPDEFINES is intended to describe C/C++ pre-processor
4681 macro definitions, it accepts additional syntax. Preprocessor
4682 macros can be valued, or un-valued, as in -DBAR=1 or -DFOO. The
4683 macro can be be supplied as a complete string including the value,
4684 or as a tuple (or list) of macro, value, or as a dictionary.
4685 Example (again gcc syntax in the expanded defines):
4686 env = Environment(CPPDEFINES="FOO")
4688 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4689 env.Append(CPPDEFINES="BAR=1")
4690 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4691 env.Append(CPPDEFINES=("OTHER", 2))
4692 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4693 env.Append(CPPDEFINES={"EXTRA": "arg"})
4694 print("CPPDEFINES={}".format(env['CPPDEFINES']))
4695 print("CPPDEFINES will expand to {}".format(env.subst("$_CPPDEFFLAGS")))
4696 $ scons -Q
4698 CPPDEFINES=FOO
4699 CPPDEFINES=['FOO', 'BAR=1']
4700 CPPDEFINES=['FOO', 'BAR=1', ('OTHER', 2)]
4701 CPPDEFINES=['FOO', 'BAR=1', ('OTHER', 2), {'EXTRA': 'arg'}]
4702 CPPDEFINES will expand to -DFOO -DBAR=1 -DOTHER=2 -DEXTRA=arg
4703 scons: `.' is up to date.
4704 Adding a string val to a dictonary construction variable will enter
4706 val as the key in the dict, and None as its value. Using a tuple
4707 type to supply a key + value only works for the special case of
4708 $CPPDEFINES described above.
4709 Although most combinations of types work without needing to know
4711 the details, some combinations do not make sense and a Python
4712 exception will be raised.
4713 When using env.Append to modify construction variables which are
4715 path specifications (conventionally, the names of such end in
4716 PATH), it is recommended to add the values as a list of strings,
4717 even if there is only a single string to add. The same goes for
4718 adding library names to $LIBS.
4719 env.Append(CPPPATH=["#/include"])
4721 See also env.AppendUnique, env.Prepend and env.PrependUnique.
4723 env.AppendENVPath(name, newpath, [envname, sep, delete_existing=False])
4725 Append new path elements to the given path in the specified
4726 external environment ($ENV by default). This will only add any
4727 particular path once (leaving the last one it encounters and
4728 ignoring the rest, to preserve path order), and to help assure
4729 this, will normalize all paths (using os.path.normpath and
4730 os.path.normcase). This can also handle the case where the given
4731 old path variable is a list instead of a string, in which case a
4732 list will be returned instead of a string.
4733 If delete_existing is False, then adding a path that already exists
4735 will not move it to the end; it will stay where it is in the list.
4736 Example:
4738 print('before:', env['ENV']['INCLUDE'])
4740 include_path = '/foo/bar:/foo'
4741 env.AppendENVPath('INCLUDE', include_path)
4742 print('after:', env['ENV']['INCLUDE'])
4743 Yields:
4745 before: /foo:/biz
4747 after: /biz:/foo/bar:/foo
4748 env.AppendUnique(key=val, [...], delete_existing=False)
4750 Append values to construction variables in the current construction
4751 environment, maintaining uniqueness. Works like env.Append (see for
4752 details), except that values already present in the construction
4753 variable will not be added again. If delete_existing is True, the
4754 existing matching value is first removed, and the requested value
4755 is added, having the effect of moving such values to the end.
4756 Example:
4758 env.AppendUnique(CCFLAGS='-g', FOO=['foo.yyy'])
4760 See also env.Append, env.Prepend and env.PrependUnique.
4762 Builder(action, [arguments]), env.Builder(action, [arguments])
4764 Creates a Builder object for the specified action. See the manpage
4765 section "Builder Objects" for a complete explanation of the
4766 arguments and behavior.
4767 Note that the env.Builder() form of the invocation will expand
4769 construction variables in any arguments strings, including the
4770 action argument, at the time it is called using the construction
4771 variables in the env construction environment through which
4772 env.Builder was called. The Builder form delays all variable
4773 expansion until after the Builder object is actually called.
4774 CacheDir(cache_dir, custom_class=None), env.CacheDir(cache_dir,
4776 custom_class=None)
4777 Direct scons to maintain a derived-file cache in cache_dir. The
4778 derived files in the cache will be shared among all the builds
4779 specifying the same cache_dir. Specifying a cache_dir of None
4780 disables derived file caching.
4781 When specifying a custom_class which should be a class type which
4783 is a subclass of SCons.CacheDir.CacheDir, SCons will internally
4784 invoke this class to use for performing caching operations. This
4785 argument is optional and if left to default None, will use the
4786 default SCons.CacheDir.CacheDir class.
4787 Calling the environment method env.CacheDir limits the effect to
4789 targets built through the specified construction environment.
4790 Calling the global function CacheDir sets a global default that
4791 will be used by all targets built through construction environments
4792 that do not set up environment-specific caching by calling
4793 env.CacheDir.
4794 When derived-file caching is being used and scons finds a derived
4796 file that needs to be rebuilt, it will first look in the cache to
4797 see if a file with matching build signature exists (indicating the
4798 input file(s) and build action(s) were identical to those for the
4799 current target), and if so, will retrieve the file from the cache.
4800 scons will report Retrieved `file' from cache instead of the normal
4801 build message. If the derived file is not present in the cache,
4802 scons will build it and then place a copy of the built file in the
4803 cache, identified by its build signature, for future use.
4804 The Retrieved `file' from cache messages are useful for human
4806 consumption, but less so when comparing log files between scons
4807 runs which will show differences that are noisy and not actually
4808 significant. To disable, use the --cache-show option. With this
4809 option, scons will print the action that would have been used to
4810 build the file without considering cache retrieval.
4811 Derived-file caching may be disabled for any invocation of scons by
4813 giving the --cache-disable command line option. Cache updating may
4814 be disabled, leaving cache fetching enabled, by giving the
4815 --cache-readonly.
4816 If the --cache-force option is used, scons will place a copy of all
4818 derived files in the cache, even if they already existed and were
4819 not built by this invocation. This is useful to populate a cache
4820 the first time a cache_dir is used for a build, or to bring a cache
4821 up to date after a build with cache updating disabled
4822 (--cache-disable or --cache-readonly) has been done.
4823 The NoCache method can be used to disable caching of specific
4825 files. This can be useful if inputs and/or outputs of some tool are
4826 impossible to predict or prohibitively large.
4827 Clean(targets, files_or_dirs), env.Clean(targets, files_or_dirs)
4829 This specifies a list of files or directories which should be
4830 removed whenever the targets are specified with the -c command line
4831 option. The specified targets may be a list or an individual
4832 target. Multiple calls to Clean are legal, and create new targets
4833 or add files and directories to the clean list for the specified
4834 targets.
4835 Multiple files or directories should be specified either as
4837 separate arguments to the Clean method, or as a list. Clean will
4838 also accept the return value of any of the construction environment
4839 Builder methods. Examples:
4840 The related NoClean function overrides calling Clean for the same
4842 target, and any targets passed to both functions will not be
4843 removed by the -c option.
4844 Examples:
4846 Clean('foo', ['bar', 'baz'])
4848 Clean('dist', env.Program('hello', 'hello.c'))
4849 Clean(['foo', 'bar'], 'something_else_to_clean')
4850 In this example, installing the project creates a subdirectory for
4852 the documentation. This statement causes the subdirectory to be
4853 removed if the project is deinstalled.
4854 Clean(docdir, os.path.join(docdir, projectname))
4856 env.Clone([key=val, ...])
4858 Returns a separate copy of a construction environment. If there are
4859 any keyword arguments specified, they are added to the returned
4860 copy, overwriting any existing values for the keywords.
4861 Example:
4863 env2 = env.Clone()
4865 env3 = env.Clone(CCFLAGS='-g')
4866 Additionally, a list of tools and a toolpath may be specified, as
4868 in the Environment constructor:
4869 def MyTool(env):
4871 env['FOO'] = 'bar'
4872 env4 = env.Clone(tools=['msvc', MyTool])
4874 The parse_flags keyword argument is also recognized to allow
4876 merging command-line style arguments into the appropriate
4877 construction variables (see env.MergeFlags).
4878 # create an environment for compiling programs that use wxWidgets
4880 wx_env = env.Clone(parse_flags='!wx-config --cflags --cxxflags')
4881 Command(target, source, action, [key=val, ...]), env.Command(target,
4883 source, action, [key=val, ...])
4884 Executes a specific action (or list of actions) to build a target
4885 file or files from a source file or files. This is more convenient
4886 than defining a separate Builder object for a single special-case
4887 build.
4888 The Command function accepts source_scanner, target_scanner,
4890 source_factory, and target_factory keyword arguments. These
4891 arguments can be used to specify a Scanner object that will be used
4892 to apply a custom scanner for a source or target. For example, the
4893 global DirScanner object can be used if any of the sources will be
4894 directories that must be scanned on-disk for changes to files that
4895 aren't already specified in other Builder of function calls. The
4896 *_factory arguments take a factory function that Command will use
4897 to turn any sources or targets specified as strings into SCons
4898 Nodes. See the manpage section "Builder Objects" for more
4899 information about how these arguments work in a Builder.
4900 Any other keyword arguments specified override any same-named
4902 existing construction variables.
4903 An action can be an external command, specified as a string, or a
4905 callable Python object; see the manpage section "Action Objects"
4906 for more complete information. Also note that a string specifying
4907 an external command may be preceded by an at-sign (@) to suppress
4908 printing the command in question, or by a hyphen (-) to ignore the
4909 exit status of the external command.
4910 Examples:
4912 env.Command(
4914 target='foo.out',
4915 source='foo.in',
4916 action="$FOO_BUILD < $SOURCES > $TARGET"
4917 )
4918 env.Command(
4920 target='bar.out',
4921 source='bar.in',
4922 action=["rm -f $TARGET", "$BAR_BUILD < $SOURCES > $TARGET"],
4923 ENV={'PATH': '/usr/local/bin/'},
4924 )
4925 import os
4928 def rename(env, target, source):
4929 os.rename('.tmp', str(target[0]))
4930 env.Command(
4933 target='baz.out',
4934 source='baz.in',
4935 action=["$BAZ_BUILD < $SOURCES > .tmp", rename],
4936 )
4937 Note that the Command function will usually assume, by default,
4939 that the specified targets and/or sources are Files, if no other
4940 part of the configuration identifies what type of entries they are.
4941 If necessary, you can explicitly specify that targets or source
4942 nodes should be treated as directories by using the Dir or env.Dir
4943 functions.
4944 Examples:
4946 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
4948 env['DISTDIR'] = 'destination/directory'
4950 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
4951 Also note that SCons will usually automatically create any
4953 directory necessary to hold a target file, so you normally don't
4954 need to create directories by hand.
4955 Configure(env, [custom_tests, conf_dir, log_file, config_h]),
4957 env.Configure([custom_tests, conf_dir, log_file, config_h])
4958 Creates a Configure object for integrated functionality similar to
4959 GNU autoconf. See the manpage section "Configure Contexts" for a
4960 complete explanation of the arguments and behavior.
4961 Decider(function), env.Decider(function)
4963 Specifies that all up-to-date decisions for targets built through
4964 this construction environment will be handled by the specified
4965 function. function can be the name of a function or one of the
4966 following strings that specify the predefined decision function
4967 that will be applied:
4968 "timestamp-newer"
4970 Specifies that a target shall be considered out of date and
4971 rebuilt if the dependency's timestamp is newer than the target
4972 file's timestamp. This is the behavior of the classic Make
4973 utility, and make can be used a synonym for timestamp-newer.
4974 "timestamp-match"
4976 Specifies that a target shall be considered out of date and
4977 rebuilt if the dependency's timestamp is different than the
4978 timestamp recorded the last time the target was built. This
4979 provides behavior very similar to the classic Make utility (in
4980 particular, files are not opened up so that their contents can
4981 be checksummed) except that the target will also be rebuilt if
4982 a dependency file has been restored to a version with an
4983 earlier timestamp, such as can happen when restoring files from
4984 backup archives.
4985 "content"
4987 Specifies that a target shall be considered out of date and
4988 rebuilt if the dependency's content has changed since the last
4989 time the target was built, as determined be performing an
4990 checksum on the dependency's contents and comparing it to the
4991 checksum recorded the last time the target was built. MD5 can
4992 be used as a synonym for content, but it is deprecated.
4993 "content-timestamp"
4995 Specifies that a target shall be considered out of date and
4996 rebuilt if the dependency's content has changed since the last
4997 time the target was built, except that dependencies with a
4998 timestamp that matches the last time the target was rebuilt
4999 will be assumed to be up-to-date and not rebuilt. This provides
5000 behavior very similar to the content behavior of always
5001 checksumming file contents, with an optimization of not
5002 checking the contents of files whose timestamps haven't
5003 changed. The drawback is that SCons will not detect if a file's
5004 content has changed but its timestamp is the same, as might
5005 happen in an automated script that runs a build, updates a
5006 file, and runs the build again, all within a single second.
5007 MD5-timestamp can be used as a synonym for content-timestamp,
5008 but it is deprecated.
5009 Examples:
5011 # Use exact timestamp matches by default.
5013 Decider('timestamp-match')
5014 # Use hash content signatures for any targets built
5016 # with the attached construction environment.
5017 env.Decider('content')
5018 In addition to the above already-available functions, the function
5020 argument may be a Python function you supply. Such a function must
5021 accept the following four arguments:
5022 dependency
5024 The Node (file) which should cause the target to be rebuilt if
5025 it has "changed" since the last tme target was built.
5026 target
5028 The Node (file) being built. In the normal case, this is what
5029 should get rebuilt if the dependency has "changed."
5030 prev_ni
5032 Stored information about the state of the dependency the last
5033 time the target was built. This can be consulted to match
5034 various file characteristics such as the timestamp, size, or
5035 content signature.
5036 repo_node
5038 If set, use this Node instead of the one specified by
5039 dependency to determine if the dependency has changed. This
5040 argument is optional so should be written as a default argument
5041 (typically it would be written as repo_node=None). A caller
5042 will normally only set this if the target only exists in a
5043 Repository.
5044 The function should return a value which evaluates True if the
5046 dependency has "changed" since the last time the target was built
5047 (indicating that the target should be rebuilt), and a value which
5048 evaluates False otherwise (indicating that the target should not be
5049 rebuilt). Note that the decision can be made using whatever
5050 criteria are appopriate. Ignoring some or all of the function
5051 arguments is perfectly normal.
5052 Example:
5054 def my_decider(dependency, target, prev_ni, repo_node=None):
5056 return not os.path.exists(str(target))
5057 env.Decider(my_decider)
5059 Default(target[, ...]), env.Default(target[, ...])
5061 Specify default targets to the SCons target selection mechanism.
5062 Any call to Default will cause SCons to use the defined default
5063 target list instead of its built-in algorithm for determining
5064 default targets (see the manpage section "Target Selection").
5065 target may be one or more strings, a list of strings, a NodeList as
5068 returned by a Builder, or None. A string target may be the name of
5069 a file or directory, or a target previously defined by a call to
5070 Alias (defining the alias later will still create the alias, but it
5071 will not be recognized as a default). Calls to Default are
5072 additive. A target of None will clear any existing default target
5073 list; subsequent calls to Default will add to the (now empty)
5074 default target list like normal.
5075 Both forms of this call affect the same global list of default
5077 targets; the construction environment method applies construction
5078 variable expansion to the targets.
5079 The current list of targets added using Default is available in the
5081 DEFAULT_TARGETS list (see below).
5082 Examples:
5084 Default('foo', 'bar', 'baz')
5086 env.Default(['a', 'b', 'c'])
5087 hello = env.Program('hello', 'hello.c')
5088 env.Default(hello)
5089 DefaultEnvironment([**kwargs])
5091 Instantiates and returns the default construction environment
5092 object. The default environment is used internally by SCons in
5093 order to execute many of the global functions in this list (that
5094 is, those not called as methods of a specific construction
5095 environment). It is not mandatory to call DefaultEnvironment: the
5096 default environment will be instantiated automatically when the
5097 build phase begins if the function has not been called, however
5098 calling it explicitly gives the opportunity to affect and examine
5099 the contents of the default environment.
5100 The default environment is a singleton, so the keyword arguments
5102 affect it only on the first call, on subsequent calls the
5103 already-constructed object is returned and any keyword arguments
5104 are silently ignored. The default environment can be modified after
5105 instantiation in the same way as any construction environment.
5106 Modifying the default environment has no effect on the construction
5107 environment constructed by an Environment or Clone call.
5108 Depends(target, dependency), env.Depends(target, dependency)
5110 Specifies an explicit dependency; the target will be rebuilt
5111 whenever the dependency has changed. Both the specified target and
5112 dependency can be a string (usually the path name of a file or
5113 directory) or Node objects, or a list of strings or Node objects
5114 (such as returned by a Builder call). This should only be necessary
5115 for cases where the dependency is not caught by a Scanner for the
5116 file.
5117 Example:
5119 env.Depends('foo', 'other-input-file-for-foo')
5121 mylib = env.Library('mylib.c')
5123 installed_lib = env.Install('lib', mylib)
5124 bar = env.Program('bar.c')
5125 # Arrange for the library to be copied into the installation
5127 # directory before trying to build the "bar" program.
5128 # (Note that this is for example only. A "real" library
5129 # dependency would normally be configured through the $LIBS
5130 # and $LIBPATH variables, not using an env.Depends() call.)
5131 env.Depends(bar, installed_lib)
5133 env.Detect(progs)
5135 Find an executable from one or more choices: progs may be a string
5136 or a list of strings. Returns the first value from progs that was
5137 found, or None. Executable is searched by checking the paths
5138 specified by env['ENV']['PATH']. On Windows systems, additionally
5139 applies the filename suffixes found in env['ENV']['PATHEXT'] but
5140 will not include any such extension in the return value.
5141 env.Detect is a wrapper around env.WhereIs.
5142 env.Dictionary([vars])
5144 Returns a dictionary object containing the construction variables
5145 in the construction environment. If there are any arguments
5146 specified, the values of the specified construction variables are
5147 returned as a string (if one argument) or as a list of strings.
5148 Example:
5150 cvars = env.Dictionary()
5152 cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
5153 Dir(name, [directory]), env.Dir(name, [directory])
5155 Returns Directory Node(s). A Directory Node is an object that
5156 represents a directory. name can be a relative or absolute path or
5157 a list of such paths. directory is an optional directory that will
5158 be used as the parent directory. If no directory is specified, the
5159 current script's directory is used as the parent.
5160 If name is a single pathname, the corresponding node is returned.
5162 If name is a list, SCons returns a list of nodes. Construction
5163 variables are expanded in name.
5164 Directory Nodes can be used anywhere you would supply a string as a
5166 directory name to a Builder method or function. Directory Nodes
5167 have attributes and methods that are useful in many situations; see
5168 manpage section "File and Directory Nodes" for more information.
5169 env.Dump([key], [format])
5171 Serializes construction variables to a string. The method supports
5172 the following formats specified by format:
5173 pretty
5175 Returns a pretty printed representation of the environment (if
5176 format is not specified, this is the default).
5177 json
5179 Returns a JSON-formatted string representation of the
5180 environment.
5181 If key is None (the default) the entire dictionary of construction
5183 variables is serialized. If supplied, it is taken as the name of a
5184 construction variable whose value is serialized.
5185 This SConstruct:
5187 env=Environment()
5189 print(env.Dump('CCCOM'))
5190 will print:
5192 '$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
5194 While this SConstruct:
5196 env = Environment()
5198 print(env.Dump())
5199 will print:
5201 { 'AR': 'ar',
5203 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
5204 'ARFLAGS': ['r'],
5205 'AS': 'as',
5206 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
5207 'ASFLAGS': [],
5208 ...
5209 EnsurePythonVersion(major, minor), env.EnsurePythonVersion(major,
5211 minor)
5212 Ensure that the Python version is at least major.minor. This
5213 function will print out an error message and exit SCons with a
5214 non-zero exit code if the actual Python version is not late enough.
5215 Example:
5217 EnsurePythonVersion(2,2)
5219 EnsureSConsVersion(major, minor, [revision]),
5221 env.EnsureSConsVersion(major, minor, [revision])
5222 Ensure that the SCons version is at least major.minor, or
5223 major.minor.revision. if revision is specified. This function will
5224 print out an error message and exit SCons with a non-zero exit code
5225 if the actual SCons version is not late enough.
5226 Examples:
5228 EnsureSConsVersion(0,14)
5230 EnsureSConsVersion(0,96,90)
5232 Environment([key=value, ...]), env.Environment([key=value, ...])
5234 Return a new construction environment initialized with the
5235 specified key=value pairs. The keyword arguments parse_flags,
5236 platform, toolpath, tools and variables are also specially
5237 recognized. See the manpage section "Construction Environments" for
5238 more details.
5239 Execute(action, [strfunction, varlist]), env.Execute(action,
5241 [strfunction, varlist])
5242 Executes an Action object. The specified action may be an Action
5243 object (see manpage section "Action Objects" for an explanation of
5244 behavior), or it may be a command-line string, list of commands, or
5245 executable Python function, each of which will be converted into an
5246 Action object and then executed. Any additional arguments to
5247 Execute (strfunction, varlist) are passed on to the Action factory
5248 function which actually creates the Action object. The exit value
5249 of the command or return value of the Python function will be
5250 returned.
5251 Note that scons will print an error message if the executed action
5253 fails--that is, exits with or returns a non-zero value. scons will
5254 not, however, automatically terminate the build if the specified
5255 action fails. If you want the build to stop in response to a failed
5256 Execute call, you must explicitly check for a non-zero return
5257 value:
5258 Execute(Copy('file.out', 'file.in'))
5260 if Execute("mkdir sub/dir/ectory"):
5262 # The mkdir failed, don't try to build.
5263 Exit(1)
5264 Exit([value]), env.Exit([value])
5266 This tells scons to exit immediately with the specified value. A
5267 default exit value of 0 (zero) is used if no value is specified.
5268 Export([vars...], [key=value...]), env.Export([vars...],
5270 [key=value...])
5271 Exports variables from the current SConscript file to a global
5272 collection where they can be imported by other SConscript files.
5273 vars may be one or more strings representing variable names to be
5274 exported. If a string contains whitespace, it is split into
5275 separate strings, as if multiple string arguments had been given. A
5276 vars argument may also be a dictionary, which can be used to map
5277 variables to different names when exported. Keyword arguments can
5278 be used to provide names and their values.
5279 Export calls are cumulative. Specifying a previously exported
5282 variable will overwrite the earlier value. Both local variables and
5283 global variables can be exported.
5284 Examples:
5286 env = Environment()
5288 # Make env available for all SConscript files to Import().
5289 Export("env")
5290 package = 'my_name'
5292 # Make env and package available for all SConscript files:.
5293 Export("env", "package")
5294 # Make env and package available for all SConscript files:
5296 Export(["env", "package"])
5297 # Make env available using the name debug:
5299 Export(debug=env)
5300 # Make env available using the name debug:
5302 Export({"debug": env})
5303 Note that the SConscript function supports an exports argument that
5305 allows exporting a variable or set of variables to a specific
5306 SConscript file or files. See the description below.
5307 File(name, [directory]), env.File(name, [directory])
5309 Returns File Node(s). A File Node is an object that represents a
5310 file. name can be a relative or absolute path or a list of such
5311 paths. directory is an optional directory that will be used as the
5312 parent directory. If no directory is specified, the current
5313 script's directory is used as the parent.
5314 If name is a single pathname, the corresponding node is returned.
5316 If name is a list, SCons returns a list of nodes. Construction
5317 variables are expanded in name.
5318 File Nodes can be used anywhere you would supply a string as a file
5320 name to a Builder method or function. File Nodes have attributes
5321 and methods that are useful in many situations; see manpage section
5322 "File and Directory Nodes" for more information.
5323 FindFile(file, dirs), env.FindFile(file, dirs)
5325 Search for file in the path specified by dirs. dirs may be a list
5326 of directory names or a single directory name. In addition to
5327 searching for files that exist in the filesystem, this function
5328 also searches for derived files that have not yet been built.
5329 Example:
5331 foo = env.FindFile('foo', ['dir1', 'dir2'])
5333 FindInstalledFiles(), env.FindInstalledFiles()
5335 Returns the list of targets set up by the Install or InstallAs
5336 builders.
5337 This function serves as a convenient method to select the contents
5339 of a binary package.
5340 Example:
5342 Install('/bin', ['executable_a', 'executable_b'])
5344 # will return the file node list
5346 # ['/bin/executable_a', '/bin/executable_b']
5347 FindInstalledFiles()
5348 Install('/lib', ['some_library'])
5350 # will return the file node list
5352 # ['/bin/executable_a', '/bin/executable_b', '/lib/some_library']
5353 FindInstalledFiles()
5354 FindPathDirs(variable)
5356 Returns a function (actually a callable Python object) intended to
5357 be used as the path_function of a Scanner object. The returned
5358 object will look up the specified variable in a construction
5359 environment and treat the construction variable's value as a list
5360 of directory paths that should be searched (like $CPPPATH,
5361 $LIBPATH, etc.).
5362 Note that use of FindPathDirs is generally preferable to writing
5364 your own path_function for the following reasons: 1) The returned
5365 list will contain all appropriate directories found in source trees
5366 (when VariantDir is used) or in code repositories (when Repository
5367 or the -Y option are used). 2) scons will identify expansions of
5368 variable that evaluate to the same list of directories as, in fact,
5369 the same list, and avoid re-scanning the directories for files,
5370 when possible.
5371 Example:
5373 def my_scan(node, env, path, arg):
5375 # Code to scan file contents goes here...
5376 return include_files
5377 scanner = Scanner(name = 'myscanner',
5379 function = my_scan,
5380 path_function = FindPathDirs('MYPATH'))
5381 FindSourceFiles(node='"."'), env.FindSourceFiles(node='"."')
5383 Returns the list of nodes which serve as the source of the built
5384 files. It does so by inspecting the dependency tree starting at the
5385 optional argument node which defaults to the '"."'-node. It will
5386 then return all leaves of node. These are all children which have
5387 no further children.
5388 This function is a convenient method to select the contents of a
5390 Source Package.
5391 Example:
5393 Program('src/main_a.c')
5395 Program('src/main_b.c')
5396 Program('main_c.c')
5397 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
5399 FindSourceFiles()
5400 # returns ['src/main_b.c', 'src/main_a.c' ]
5402 FindSourceFiles('src')
5403 As you can see build support files (SConstruct in the above
5405 example) will also be returned by this function.
5406 Flatten(sequence), env.Flatten(sequence)
5408 Takes a sequence (that is, a Python list or tuple) that may contain
5409 nested sequences and returns a flattened list containing all of the
5410 individual elements in any sequence. This can be helpful for
5411 collecting the lists returned by calls to Builders; other Builders
5412 will automatically flatten lists specified as input, but direct
5413 Python manipulation of these lists does not.
5414 Examples:
5416 foo = Object('foo.c')
5418 bar = Object('bar.c')
5419 # Because `foo' and `bar' are lists returned by the Object() Builder,
5421 # `objects' will be a list containing nested lists:
5422 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
5423 # Passing such a list to another Builder is all right because
5425 # the Builder will flatten the list automatically:
5426 Program(source = objects)
5427 # If you need to manipulate the list directly using Python, you need to
5429 # call Flatten() yourself, or otherwise handle nested lists:
5430 for object in Flatten(objects):
5431 print(str(object))
5432 GetBuildFailures()
5434 Returns a list of exceptions for the actions that failed while
5435 attempting to build targets. Each element in the returned list is a
5436 BuildError object with the following attributes that record various
5437 aspects of the build failure:
5438 .node The node that was being built when the build failure
5441 occurred.
5442 .status The numeric exit status returned by the command or Python
5445 function that failed when trying to build the specified Node.
5446 .errstr The SCons error string describing the build failure. (This
5449 is often a generic message like "Error 2" to indicate that an
5450 executed command exited with a status of 2.)
5451 .filename The name of the file or directory that actually caused
5454 the failure. This may be different from the .node attribute. For
5455 example, if an attempt to build a target named sub/dir/target fails
5456 because the sub/dir directory could not be created, then the .node
5457 attribute will be sub/dir/target but the .filename attribute will
5458 be sub/dir.
5459 .executor The SCons Executor object for the target Node being
5462 built. This can be used to retrieve the construction environment
5463 used for the failed action.
5464 .action The actual SCons Action object that failed. This will be
5467 one specific action out of the possible list of actions that would
5468 have been executed to build the target.
5469 .command The actual expanded command that was executed and failed,
5472 after expansion of $TARGET, $SOURCE, and other construction
5473 variables.
5474 Note that the GetBuildFailures function will always return an empty
5476 list until any build failure has occurred, which means that
5477 GetBuildFailures will always return an empty list while the
5478 SConscript files are being read. Its primary intended use is for
5479 functions that will be executed before SCons exits by passing them
5480 to the standard Python atexit.register() function. Example:
5481 import atexit
5483 def print_build_failures():
5485 from SCons.Script import GetBuildFailures
5486 for bf in GetBuildFailures():
5487 print("%s failed: %s" % (bf.node, bf.errstr))
5488 atexit.register(print_build_failures)
5490 GetBuildPath(file, [...]), env.GetBuildPath(file, [...])
5492 Returns the scons path name (or names) for the specified file (or
5493 files). The specified file or files may be scons Nodes or strings
5494 representing path names.
5495 GetLaunchDir(), env.GetLaunchDir()
5497 Returns the absolute path name of the directory from which scons
5498 was initially invoked. This can be useful when using the -u, -U or
5499 -D options, which internally change to the directory in which the
5500 SConstruct file is found.
5501 GetOption(name), env.GetOption(name)
5503 This function provides a way to query the value of options which
5504 can be set via the command line or using the SetOption function.
5505 name can be an entry from the following table, which shows the
5508 corresponding command line arguments that could affect the value.
5509 name can be also be the destination variable name from a
5510 project-specific option added using the AddOption function, as long
5511 as the addition happens prior to the GetOption call in the
5512 SConscript files.
5513 ┌────────────────────────┬───────────────────────────┬────────────────────┐
5515 │Query name │ Command-line │ Notes │
5516 │ │ options │ │
5517 ├────────────────────────┼───────────────────────────┼────────────────────┤
5518 │cache_debug │ --cache-debug │ │
5519 ├────────────────────────┼───────────────────────────┼────────────────────┤
5520 │cache_disable │ --cache-disable, │ │
5521 │ │ --no-cache │ │
5522 ├────────────────────────┼───────────────────────────┼────────────────────┤
5523 │cache_force │ --cache-force, │ │
5524 │ │ --cache-populate │ │
5525 ├────────────────────────┼───────────────────────────┼────────────────────┤
5526 │cache_readonly │ --cache-readonly │ │
5527 ├────────────────────────┼───────────────────────────┼────────────────────┤
5528 │cache_show │ --cache-show │ │
5529 ├────────────────────────┼───────────────────────────┼────────────────────┤
5530 │clean │ -c, │ │
5531 │ │ --clean, │ │
5532 │ │ --remove │ │
5533 ├────────────────────────┼───────────────────────────┼────────────────────┤
5534 │climb_up │ -D │ │
5535 │ │ -U │ │
5536 │ │ -u │ │
5537 │ │ --up │ │
5538 │ │ --search_up │ │
5539 ├────────────────────────┼───────────────────────────┼────────────────────┤
5540 │config │ --config │ │
5541 ├────────────────────────┼───────────────────────────┼────────────────────┤
5542 │debug │ --debug │ │
5543 ├────────────────────────┼───────────────────────────┼────────────────────┤
5544 │directory │ -C, --directory │ │
5545 ├────────────────────────┼───────────────────────────┼────────────────────┤
5546 │diskcheck │ --diskcheck │ │
5547 ├────────────────────────┼───────────────────────────┼────────────────────┤
5548 │duplicate │ --duplicate │ │
5549 ├────────────────────────┼───────────────────────────┼────────────────────┤
5550 │enable_virtualenv │ --enable-virtualenv │ │
5551 ├────────────────────────┼───────────────────────────┼────────────────────┤
5552 │experimental │ --experimental │ since 4.2 │
5553 ├────────────────────────┼───────────────────────────┼────────────────────┤
5554 │file │ -f, │ │
5555 │ │ --file, │ │
5556 │ │ --makefile, │ │
5557 │ │ --sconstruct │ │
5558 ├────────────────────────┼───────────────────────────┼────────────────────┤
5559 │hash_format │ --hash-format │ since 4.2 │
5560 ├────────────────────────┼───────────────────────────┼────────────────────┤
5561 │help │ -h, --help │ │
5562 ├────────────────────────┼───────────────────────────┼────────────────────┤
5563 │ignore_errors │ -i, --ignore-errors │ │
5564 ├────────────────────────┼───────────────────────────┼────────────────────┤
5565 │ignore_virtualenv │ --ignore-virtualenv │ │
5566 ├────────────────────────┼───────────────────────────┼────────────────────┤
5567 │implicit_cache │ --implicit-cache │ │
5568 ├────────────────────────┼───────────────────────────┼────────────────────┤
5569 │implicit_deps_changed │ --implicit-deps-changed │ │
5570 ├────────────────────────┼───────────────────────────┼────────────────────┤
5571 │implicit_deps_unchanged │ --implicit-deps-unchanged │ │
5572 ├────────────────────────┼───────────────────────────┼────────────────────┤
5573 │include_dir │ -I, --include-dir │ │
5574 ├────────────────────────┼───────────────────────────┼────────────────────┤
5575 │install_sandbox │ --install-sandbox │ Available only if │
5576 │ │ │ the install tool │
5577 │ │ │ has been called │
5578 ├────────────────────────┼───────────────────────────┼────────────────────┤
5579 │keep_going │ -k, --keep-going │ │
5580 ├────────────────────────┼───────────────────────────┼────────────────────┤
5581 │max_drift │ --max-drift │ │
5582 ├────────────────────────┼───────────────────────────┼────────────────────┤
5583 │md5_chunksize │ --hash-chunksize, │ --hash-chunksize │
5584 │ │ --md5-chunksize │ since 4.2 │
5585 ├────────────────────────┼───────────────────────────┼────────────────────┤
5586 │no_exec │ -n, │ │
5587 │ │ --no-exec, │ │
5588 │ │ --just-print, │ │
5589 │ │ --dry-run, │ │
5590 │ │ --recon │ │
5591 ├────────────────────────┼───────────────────────────┼────────────────────┤
5592 │no_progress │ -Q │ │
5593 ├────────────────────────┼───────────────────────────┼────────────────────┤
5594 │num_jobs │ -j, --jobs │ │
5595 ├────────────────────────┼───────────────────────────┼────────────────────┤
5596 │package_type │ --package-type │ Available only if │
5597 │ │ │ the packaging tool │
5598 │ │ │ has been called │
5599 ├────────────────────────┼───────────────────────────┼────────────────────┤
5600 │profile_file │ --profile │ │
5601 ├────────────────────────┼───────────────────────────┼────────────────────┤
5602 │question │ -q, --question │ │
5603 ├────────────────────────┼───────────────────────────┼────────────────────┤
5604 │random │ --random │ │
5605 ├────────────────────────┼───────────────────────────┼────────────────────┤
5606 │repository │ -Y, │ │
5607 │ │ --repository, │ │
5608 │ │ --srcdir │ │
5609 ├────────────────────────┼───────────────────────────┼────────────────────┤
5610 │silent │ -s, │ │
5611 │ │ --silent, │ │
5612 │ │ --quiet │ │
5613 ├────────────────────────┼───────────────────────────┼────────────────────┤
5614 │site_dir │ --site-dir, --no-site-dir │ │
5615 ├────────────────────────┼───────────────────────────┼────────────────────┤
5616 │stack_size │ --stack-size │ │
5617 ├────────────────────────┼───────────────────────────┼────────────────────┤
5618 │taskmastertrace_file │ --taskmastertrace │ │
5619 ├────────────────────────┼───────────────────────────┼────────────────────┤
5620 │tree_printers │ --tree │ │
5621 ├────────────────────────┼───────────────────────────┼────────────────────┤
5622 │warn │ --warn, --warning │ │
5623 └────────────────────────┴───────────────────────────┴────────────────────┘
5624 See the documentation for the corresponding command line option for
5625 information about each specific option.
5626 Glob(pattern, [ondisk, source, strings, exclude]), env.Glob(pattern,
5628 [ondisk, source, strings, exclude])
5629 Returns Nodes (or strings) that match the specified pattern,
5630 relative to the directory of the current SConscript file. The
5631 evironment method form (env.Glob) performs string substition on
5632 pattern and returns whatever matches the resulting expanded
5633 pattern.
5634 The specified pattern uses Unix shell style metacharacters for
5636 matching:
5637 * matches everything
5639 ? matches any single character
5640 [seq] matches any character in seq
5641 [!seq] matches any char not in seq
5642 If the first character of a filename is a dot, it must be matched
5644 explicitly. Character matches do not span directory separators.
5645 The Glob knows about repositories (see the Repository function) and
5647 source directories (see the VariantDir function) and returns a Node
5648 (or string, if so configured) in the local (SConscript) directory
5649 if a matching Node is found anywhere in a corresponding repository
5650 or source directory.
5651 The ondisk argument may be set to a value which evaluates False to
5653 disable the search for matches on disk, thereby only returning
5654 matches among already-configured File or Dir Nodes. The default
5655 behavior is to return corresponding Nodes for any on-disk matches
5656 found.
5657 The source argument may be set to a value which evaluates True to
5659 specify that, when the local directory is a VariantDir, the
5660 returned Nodes should be from the corresponding source directory,
5661 not the local directory.
5662 The strings argument may be set to a value which evaluates True to
5664 have the Glob function return strings, not Nodes, that represent
5665 the matched files or directories. The returned strings will be
5666 relative to the local (SConscript) directory. (Note that This may
5667 make it easier to perform arbitrary manipulation of file names, but
5668 if the returned strings are passed to a different SConscript file,
5669 any Node translation will be relative to the other SConscript
5670 directory, not the original SConscript directory.)
5671 The exclude argument may be set to a pattern or a list of patterns
5673 (following the same Unix shell semantics) which must be filtered
5674 out of returned elements. Elements matching a least one pattern of
5675 this list will be excluded.
5676 Examples:
5678 Program("foo", Glob("*.c"))
5680 Zip("/tmp/everything", Glob(".??*") + Glob("*"))
5681 sources = Glob("*.cpp", exclude=["os_*_specific_*.cpp"]) + \
5682 Glob( "os_%s_specific_*.cpp" % currentOS)
5683 Help(text, append=False), env.Help(text, append=False)
5685 Specifies a local help message to be printed if the -h argument is
5686 given to scons. Subsequent calls to Help append text to the
5687 previously defined local help text.
5688 For the first call to Help only, if append is False (the default)
5690 any local help message generated through AddOption calls is
5691 replaced. If append is True, text is appended to the existing help
5692 text.
5693 Ignore(target, dependency), env.Ignore(target, dependency)
5695 The specified dependency file(s) will be ignored when deciding if
5696 the target file(s) need to be rebuilt.
5697 You can also use Ignore to remove a target from the default build.
5699 In order to do this you must specify the directory the target will
5700 be built in as the target, and the file you want to skip building
5701 as the dependency.
5702 Note that this will only remove the dependencies listed from the
5704 files built by default. It will still be built if that dependency
5705 is needed by another object being built. See the third and forth
5706 examples below.
5707 Examples:
5709 env.Ignore('foo', 'foo.c')
5711 env.Ignore('bar', ['bar1.h', 'bar2.h'])
5712 env.Ignore('.', 'foobar.obj')
5713 env.Ignore('bar', 'bar/foobar.obj')
5714 Import(vars...), env.Import(vars...)
5716 Imports variables into the current SConscript file. vars must be
5717 strings representing names of variables which have been previously
5718 exported either by the Export function or by the exports argument
5719 to SConscript. Variables exported by SConscript take precedence.
5720 Multiple variable names can be passed to Import as separate
5721 arguments or as words in a space-separated string. The wildcard "*"
5722 can be used to import all available variables.
5723 Examples:
5725 Import("env")
5727 Import("env", "variable")
5728 Import(["env", "variable"])
5729 Import("*")
5730 Literal(string), env.Literal(string)
5732 The specified string will be preserved as-is and not have
5733 construction variables expanded.
5734 Local(targets), env.Local(targets)
5736 The specified targets will have copies made in the local tree, even
5737 if an already up-to-date copy exists in a repository. Returns a
5738 list of the target Node or Nodes.
5739 env.MergeFlags(arg, [unique])
5741 Merges values from arg into construction variables in the current
5742 construction environment. If arg is not a dictionary, it is
5743 converted to one by calling env.ParseFlags on the argument before
5744 the values are merged. Note that arg must be a single value, so
5745 multiple strings must be passed in as a list, not as separate
5746 arguments to env.MergeFlags.
5747 By default, duplicate values are eliminated; you can, however,
5749 specify unique=False to allow duplicate values to be added. When
5750 eliminating duplicate values, any construction variables that end
5751 with the string PATH keep the left-most unique value. All other
5752 construction variables keep the right-most unique value.
5753 Examples:
5755 # Add an optimization flag to $CCFLAGS.
5757 env.MergeFlags('-O3')
5758 # Combine the flags returned from running pkg-config with an optimization
5760 # flag and merge the result into the construction variables.
5761 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
5762 # Combine an optimization flag with the flags returned from running pkg-config
5764 # twice and merge the result into the construction variables.
5765 env.MergeFlags(['-O3',
5766 '!pkg-config gtk+-2.0 --cflags --libs',
5767 '!pkg-config libpng12 --cflags --libs'])
5768 NoCache(target, ...), env.NoCache(target, ...)
5770 Specifies a list of files which should not be cached whenever the
5771 CacheDir method has been activated. The specified targets may be a
5772 list or an individual target.
5773 Multiple files should be specified either as separate arguments to
5775 the NoCache method, or as a list. NoCache will also accept the
5776 return value of any of the construction environment Builder
5777 methods.
5778 Calling NoCache on directories and other non-File Node types has no
5780 effect because only File Nodes are cached.
5781 Examples:
5783 NoCache('foo.elf')
5785 NoCache(env.Program('hello', 'hello.c'))
5786 NoClean(target, ...), env.NoClean(target, ...)
5788 Specifies a list of files or directories which should not be
5789 removed whenever the targets (or their dependencies) are specified
5790 with the -c command line option. The specified targets may be a
5791 list or an individual target. Multiple calls to NoClean are legal,
5792 and prevent each specified target from being removed by calls to
5793 the -c option.
5794 Multiple files or directories should be specified either as
5796 separate arguments to the NoClean method, or as a list. NoClean
5797 will also accept the return value of any of the construction
5798 environment Builder methods.
5799 Calling NoClean for a target overrides calling Clean for the same
5801 target, and any targets passed to both functions will not be
5802 removed by the -c option.
5803 Examples:
5805 NoClean('foo.elf')
5807 NoClean(env.Program('hello', 'hello.c'))
5808 env.ParseConfig(command, [function, unique])
5810 Updates the current construction environment with the values
5811 extracted from the output from running external command, by calling
5812 a helper function function which understands the output of command.
5813 command may be a string or a list of strings representing the
5814 command and its arguments. If function is not given, env.MergeFlags
5815 is used. By default, duplicate values are not added to any
5816 construction variables; you can specify unique=False to allow
5817 duplicate values to be added.
5818 If env.MergeFlags is used, it expects a response in the style of a
5820 *-config command typical of the POSIX programming environment (for
5821 example, gtk-config) and adds the options to the appropriate
5822 construction variables. Interpreted options and the construction
5823 variables they affect are as specified for the env.ParseFlags
5824 method (which env.MergeFlags calls). See that method's description
5825 for a table of options and corresponding construction variables.
5826 If env.MergeFlags cannot interpret the results of command, you can
5828 suppply a custom function to do so. function must accept three
5829 arguments: the construction environment to modify, the string
5830 returned by running command, and the optional unique flag.
5831 ParseDepends(filename, [must_exist, only_one]),
5833 env.ParseDepends(filename, [must_exist, only_one])
5834 Parses the contents of the specified filename as a list of
5835 dependencies in the style of Make or mkdep, and explicitly
5836 establishes all of the listed dependencies.
5837 By default, it is not an error if the specified filename does not
5839 exist. The optional must_exist argument may be set to a non-zero
5840 value to have scons throw an exception and generate an error if the
5841 file does not exist, or is otherwise inaccessible.
5842 The optional only_one argument may be set to a non-zero value to
5844 have scons thrown an exception and generate an error if the file
5845 contains dependency information for more than one target. This can
5846 provide a small sanity check for files intended to be generated by,
5847 for example, the gcc -M flag, which should typically only write
5848 dependency information for one output file into a corresponding .d
5849 file.
5850 The filename and all of the files listed therein will be
5852 interpreted relative to the directory of the SConscript file which
5853 calls the ParseDepends function.
5854 env.ParseFlags(flags, ...)
5856 Parses one or more strings containing typical command-line flags
5857 for GCC tool chains and returns a dictionary with the flag values
5858 separated into the appropriate SCons construction variables. This
5859 is intended as a companion to the env.MergeFlags method, but allows
5860 for the values in the returned dictionary to be modified, if
5861 necessary, before merging them into the construction environment.
5862 (Note that env.MergeFlags will call this method if its argument is
5863 not a dictionary, so it is usually not necessary to call
5864 env.ParseFlags directly unless you want to manipulate the values.)
5865 If the first character in any string is an exclamation mark (!),
5867 the rest of the string is executed as a command, and the output
5868 from the command is parsed as GCC tool chain command-line flags and
5869 added to the resulting dictionary.
5870 Flag values are translated accordig to the prefix found, and added
5872 to the following construction variables:
5873 -arch CCFLAGS, LINKFLAGS
5875 -D CPPDEFINES
5876 -framework FRAMEWORKS
5877 -frameworkdir= FRAMEWORKPATH
5878 -fmerge-all-constants CCFLAGS, LINKFLAGS
5879 -fopenmp CCFLAGS, LINKFLAGS
5880 -include CCFLAGS
5881 -imacros CCFLAGS
5882 -isysroot CCFLAGS, LINKFLAGS
5883 -isystem CCFLAGS
5884 -iquote CCFLAGS
5885 -idirafter CCFLAGS
5886 -I CPPPATH
5887 -l LIBS
5888 -L LIBPATH
5889 -mno-cygwin CCFLAGS, LINKFLAGS
5890 -mwindows LINKFLAGS
5891 -openmp CCFLAGS, LINKFLAGS
5892 -pthread CCFLAGS, LINKFLAGS
5893 -std= CFLAGS
5894 -Wa, ASFLAGS, CCFLAGS
5895 -Wl,-rpath= RPATH
5896 -Wl,-R, RPATH
5897 -Wl,-R RPATH
5898 -Wl, LINKFLAGS
5899 -Wp, CPPFLAGS
5900 - CCFLAGS
5901 + CCFLAGS, LINKFLAGS
5902 Any other strings not associated with options are assumed to be the
5904 names of libraries and added to the $LIBS construction variable.
5905 Examples (all of which produce the same result):
5907 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
5909 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
5910 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
5911 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
5912 Platform(plat), env.Platform(plat)
5914 When called as a global function, returns a callable platform
5915 object selected by plat (defaults to the detected platform for the
5916 current system) that can be used to initialize a construction
5917 environment by passing it as the platform keyword argument to the
5918 Environment function.
5919 Example:
5921 env = Environment(platform=Platform('win32'))
5923 When called as a method of an environment, calls the platform
5925 object indicated by plat to update that environment.
5926 env.Platform('posix')
5928 See the manpage section "Construction Environments" for more
5930 details.
5931 Precious(target, ...), env.Precious(target, ...)
5933 Marks each given target as precious so it is not deleted before it
5934 is rebuilt. Normally scons deletes a target before building it.
5935 Multiple targets can be passed in to a single call to Precious.
5936 env.Prepend(key=val, [...])
5938 Prepend values to construction variables in the current
5939 construction environment, Works like env.Append (see for details),
5940 except that values are added to the front, rather than the end, of
5941 any existing value of the construction variable
5942 Example:
5944 env.Prepend(CCFLAGS='-g ', FOO=['foo.yyy'])
5946 See also env.Append, env.AppendUnique and env.PrependUnique.
5948 env.PrependENVPath(name, newpath, [envname, sep, delete_existing])
5950 Prepend new path elements to the given path in the specified
5951 external environment ($ENV by default). This will only add any
5952 particular path once (leaving the first one it encounters and
5953 ignoring the rest, to preserve path order), and to help assure
5954 this, will normalize all paths (using os.path.normpath and
5955 os.path.normcase). This can also handle the case where the given
5956 old path variable is a list instead of a string, in which case a
5957 list will be returned instead of a string.
5958 If delete_existing is False, then adding a path that already exists
5960 will not move it to the beginning; it will stay where it is in the
5961 list.
5962 Example:
5964 print('before:', env['ENV']['INCLUDE'])
5966 include_path = '/foo/bar:/foo'
5967 env.PrependENVPath('INCLUDE', include_path)
5968 print('after:', env['ENV']['INCLUDE'])
5969 Yields:
5971 before: /biz:/foo
5973 after: /foo/bar:/foo:/biz
5974 env.PrependUnique(key=val, delete_existing=False, [...])
5976 Prepend values to construction variables in the current
5977 construction environment, maintaining uniqueness. Works like
5978 env.Append (see for details), except that values are added to the
5979 front, rather than the end, of any existing value of the the
5980 construction variable, and values already present in the
5981 construction variable will not be added again. If delete_existing
5982 is True, the existing matching value is first removed, and the
5983 requested value is inserted, having the effect of moving such
5984 values to the front.
5985 Example:
5987 env.PrependUnique(CCFLAGS='-g', FOO=['foo.yyy'])
5989 See also env.Append, env.AppendUnique and env.Prepend.
5991 Progress(callable, [interval]), Progress(string, [interval, file,
5993 overwrite]), Progress(list_of_strings, [interval, file, overwrite])
5994 Allows SCons to show progress made during the build by displaying a
5995 string or calling a function while evaluating Nodes (e.g. files).
5996 If the first specified argument is a Python callable (a function or
5998 an object that has a __call__ method), the function will be called
5999 once every interval times a Node is evaluated (default 1). The
6000 callable will be passed the evaluated Node as its only argument.
6001 (For future compatibility, it's a good idea to also add *args and
6002 **kwargs as arguments to your function or method signatures. This
6003 will prevent the code from breaking if SCons ever changes the
6004 interface to call the function with additional arguments in the
6005 future.)
6006 An example of a simple custom progress function that prints a
6008 string containing the Node name every 10 Nodes:
6009 def my_progress_function(node, *args, **kwargs):
6011 print('Evaluating node %s!' % node)
6012 Progress(my_progress_function, interval=10)
6013 A more complicated example of a custom progress display object that
6015 prints a string containing a count every 100 evaluated Nodes. Note
6016 the use of \r (a carriage return) at the end so that the string
6017 will overwrite itself on a display:
6018 import sys
6020 class ProgressCounter(object):
6021 count = 0
6022 def __call__(self, node, *args, **kw):
6023 self.count += 100
6024 sys.stderr.write('Evaluated %s nodes\r' % self.count)
6025 Progress(ProgressCounter(), interval=100)
6027 If the first argument to Progress is a string or list of strings,
6029 it is taken as text to be displayed every interval evaluated Nodes.
6030 If the first argument is a list of strings, then each string in the
6031 list will be displayed in rotating fashion every interval evaluated
6032 Nodes.
6033 The default is to print the string on standard output. An alternate
6035 output stream may be specified with the file keyword argument,
6036 which the caller must pass already opened.
6037 The following will print a series of dots on the error output, one
6039 dot for every 100 evaluated Nodes:
6040 import sys
6042 Progress('.', interval=100, file=sys.stderr)
6043 If the string contains the verbatim substring $TARGET;, it will be
6045 replaced with the Node. Note that, for performance reasons, this is
6046 not a regular SCons variable substition, so you can not use other
6047 variables or use curly braces. The following example will print the
6048 name of every evaluated Node, using a carriage return) (\r) to
6049 cause each line to overwritten by the next line, and the overwrite
6050 keyword argument (default False) to make sure the
6051 previously-printed file name is overwritten with blank spaces:
6052 import sys
6054 Progress('$TARGET\r', overwrite=True)
6055 A list of strings can be used to implement a "spinner" on the
6057 user's screen as follows, changing every five evaluated Nodes:
6058 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
6060 Pseudo(target, ...), env.Pseudo(target, ...)
6062 This indicates that each given target should not be created by the
6063 build rule, and if the target is created, an error will be
6064 generated. This is similar to the gnu make .PHONY target. However,
6065 in the vast majority of cases, an Alias is more appropriate.
6066 Multiple targets can be passed in to a single call to Pseudo.
6067 PyPackageDir(modulename), env.PyPackageDir(modulename)
6069 This returns a Directory Node similar to Dir. The python module /
6070 package is looked up and if located the directory is returned for
6071 the location. modulename Is a named python package / module to
6072 lookup the directory for it's location.
6073 If modulename is a list, SCons returns a list of Dir nodes.
6075 Construction variables are expanded in modulename.
6076 env.Replace(key=val, [...])
6078 Replaces construction variables in the Environment with the
6079 specified keyword arguments.
6080 Example:
6082 env.Replace(CCFLAGS='-g', FOO='foo.xxx')
6084 Repository(directory), env.Repository(directory)
6086 Specifies that directory is a repository to be searched for files.
6087 Multiple calls to Repository are legal, and each one adds to the
6088 list of repositories that will be searched.
6089 To scons, a repository is a copy of the source tree, from the
6091 top-level directory on down, which may contain both source files
6092 and derived files that can be used to build targets in the local
6093 source tree. The canonical example would be an official source tree
6094 maintained by an integrator. If the repository contains derived
6095 files, then the derived files should have been built using scons,
6096 so that the repository contains the necessary signature information
6097 to allow scons to figure out when it is appropriate to use the
6098 repository copy of a derived file, instead of building one locally.
6099 Note that if an up-to-date derived file already exists in a
6101 repository, scons will not make a copy in the local directory tree.
6102 In order to guarantee that a local copy will be made, use the Local
6103 method.
6104 Requires(target, prerequisite), env.Requires(target, prerequisite)
6106 Specifies an order-only relationship between the specified target
6107 file(s) and the specified prerequisite file(s). The prerequisite
6108 file(s) will be (re)built, if necessary, before the target file(s),
6109 but the target file(s) do not actually depend on the prerequisites
6110 and will not be rebuilt simply because the prerequisite file(s)
6111 change.
6112 Example:
6114 env.Requires('foo', 'file-that-must-be-built-before-foo')
6116 Return([vars..., stop=True])
6118 Return to the calling SConscript, optionally returning the values
6119 of variables named in vars. Multiple strings contaning variable
6120 names may be passed to Return. A string containing white space is
6121 split into individual variable names. Returns the value if one
6122 variable is specified, else returns a tuple of values. Returns an
6123 empty tuple if vars is omitted.
6124 By default Return stops processing the current SConscript and
6126 returns immediately. The optional stop keyword argument may be set
6127 to a false value to continue processing the rest of the SConscript
6128 file after the Return call (this was the default behavior prior to
6129 SCons 0.98.) However, the values returned are still the values of
6130 the variables in the named vars at the point Return was called.
6131 Examples:
6133 # Returns no values (evaluates False)
6135 Return()
6136 # Returns the value of the 'foo' Python variable.
6138 Return("foo")
6139 # Returns the values of the Python variables 'foo' and 'bar'.
6141 Return("foo", "bar")
6142 # Returns the values of Python variables 'val1' and 'val2'.
6144 Return('val1 val2')
6145 Scanner(function, [name, argument, skeys, path_function, node_class,
6147 node_factory, scan_check, recursive]), env.Scanner(function, [name,
6148 argument, skeys, path_function, node_class, node_factory, scan_check,
6149 recursive])
6150 Creates a Scanner object for the specified function. See manpage
6151 section "Scanner Objects" for a complete explanation of the
6152 arguments and behavior.
6153 SConscript(scripts, [exports, variant_dir, duplicate, must_exist]),
6155 env.SConscript(scripts, [exports, variant_dir, duplicate, must_exist]),
6156 SConscript(dirs=subdirs, [name=script, exports, variant_dir, duplicate,
6157 must_exist]), env.SConscript(dirs=subdirs, [name=script, exports,
6158 variant_dir, duplicate, must_exist])
6159 Execute one or more subsidiary SConscript (configuration) files.
6160 There are two ways to call the SConscript function.
6161 The first calling style is to explicitly specify one or more
6163 scripts as the first argument. A single script may be specified as
6164 a string; multiple scripts must be specified as a list (either
6165 explicitly or as created by a function like Split). Examples:
6166 SConscript('SConscript') # run SConscript in the current directory
6168 SConscript('src/SConscript') # run SConscript in the src directory
6169 SConscript(['src/SConscript', 'doc/SConscript'])
6170 config = SConscript('MyConfig.py')
6171 The second way to call SConscript is to specify a list of
6173 (sub)directory names as a dirs=subdirs keyword argument. In this
6174 case, scons will execute a subsidiary configuration file named
6175 SConscript in each of the specified directories. You may specify a
6176 name other than SConscript by supplying an optional name=script
6177 keyword argument. The first three examples below have the same
6178 effect as the first three examples above:
6179 SConscript(dirs='.') # run SConscript in the current directory
6181 SConscript(dirs='src') # run SConscript in the src directory
6182 SConscript(dirs=['src', 'doc'])
6183 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
6184 The optional exports argument provides a string or list of strings
6186 representing variable names, or a dictionary of named values, to
6187 export. These variables are locally exported only to the called
6188 SConscript file(s) and do not affect the global pool of variables
6189 managed by the Export function. The subsidiary SConscript files
6190 must use the Import function to import the variables. Examples:
6191 foo = SConscript('sub/SConscript', exports='env')
6193 SConscript('dir/SConscript', exports=['env', 'variable'])
6194 SConscript(dirs='subdir', exports='env variable')
6195 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
6196 If the optional variant_dir argument is present, it causes an
6198 effect equivalent to the VariantDir function. The variant_dir
6199 argument is interpreted relative to the directory of the calling
6200 SConscript file. The optional duplicate argument is interpreted as
6201 for VariantDir. If variant_dir is omitted, the duplicate argument
6202 is ignored. See the description of VariantDir below for additional
6203 details and restrictions.
6204 If variant_dir is present, the source directory is the directory in
6206 which the SConscript file resides and the SConscript file is
6207 evaluated as if it were in the variant_dir directory:
6208 SConscript('src/SConscript', variant_dir='build')
6210 is equivalent to
6212 VariantDir('build', 'src')
6214 SConscript('build/SConscript')
6215 This later paradigm is often used when the sources are in the same
6217 directory as the SConstruct:
6218 SConscript('SConscript', variant_dir='build')
6220 is equivalent to
6222 VariantDir('build', '.')
6224 SConscript('build/SConscript')
6225 If the optional must_exist is True, causes an exception to be
6229 raised if a requested SConscript file is not found. The current
6230 default is False, causing only a warning to be emitted, but this
6231 default is deprecated (since 3.1). For scripts which truly intend
6232 to be optional, transition to explicitly supplying must_exist=False
6233 to the SConscript call.
6234 Here are some composite examples:
6236 # collect the configuration information and use it to build src and doc
6238 shared_info = SConscript('MyConfig.py')
6239 SConscript('src/SConscript', exports='shared_info')
6240 SConscript('doc/SConscript', exports='shared_info')
6241 # build debugging and production versions. SConscript
6243 # can use Dir('.').path to determine variant.
6244 SConscript('SConscript', variant_dir='debug', duplicate=0)
6245 SConscript('SConscript', variant_dir='prod', duplicate=0)
6246 # build debugging and production versions. SConscript
6248 # is passed flags to use.
6249 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
6250 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
6251 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
6252 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
6253 # build common documentation and compile for different architectures
6255 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
6256 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
6257 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
6258 SConscript returns the values of any variables named by the
6261 executed SConscript(s) in arguments to the Return function (see
6262 above for details). If a single SConscript call causes multiple
6263 scripts to be executed, the return value is a tuple containing the
6264 returns of all of the scripts. If an executed script does not
6265 explicitly call Return, it returns None.
6266 SConscriptChdir(value), env.SConscriptChdir(value)
6268 By default, scons changes its working directory to the directory in
6269 which each subsidiary SConscript file lives. This behavior may be
6270 disabled by specifying either:
6271 SConscriptChdir(0)
6273 env.SConscriptChdir(0)
6274 in which case scons will stay in the top-level directory while
6276 reading all SConscript files. (This may be necessary when building
6277 from repositories, when all the directories in which SConscript
6278 files may be found don't necessarily exist locally.) You may enable
6279 and disable this ability by calling SConscriptChdir() multiple
6280 times.
6281 Example:
6283 env = Environment()
6285 SConscriptChdir(0)
6286 SConscript('foo/SConscript') # will not chdir to foo
6287 env.SConscriptChdir(1)
6288 SConscript('bar/SConscript') # will chdir to bar
6289 SConsignFile([name, dbm_module]), env.SConsignFile([name, dbm_module])
6291 Specify where to store the SCons file signature database, and which
6292 database format to use. This may be useful to specify alternate
6293 database files and/or file locations for different types of builds.
6294 The optional name argument is the base name of the database
6296 file(s). If not an absolute path name, these are placed relative to
6297 the directory containing the top-level SConstruct file. The default
6298 is .sconsign. The actual database file(s) stored on disk may have
6299 an appropriate suffix appended by the chosen dbm_module
6300 The optional dbm_module argument specifies which Python database
6302 module to use for reading/writing the file. The module must be
6303 imported first; then the imported module name is passed as the
6304 argument. The default is a custom SCons.dblite module that uses
6305 pickled Python data structures, which works on all Python versions.
6306 See documentation of the Python dbm module for other available
6307 types.
6308 If called with no arguments, the database will default to
6310 .sconsign.dblite in the top directory of the project, which is also
6311 the default if if SConsignFile is not called.
6312 The setting is global, so the only difference between the global
6314 function and the environment method form is variable expansion on
6315 name. There should only be one active call to this function/method
6316 in a given build setup.
6317 If name is set to None, scons will store file signatures in a
6319 separate .sconsign file in each directory, not in a single combined
6320 database file. This is a backwards-compatibility meaure to support
6321 what was the default behavior prior to SCons 0.97 (i.e. before
6322 2008). Use of this mode is discouraged and may be deprecated in a
6323 future SCons release.
6324 Examples:
6326 # Explicitly stores signatures in ".sconsign.dblite"
6328 # in the top-level SConstruct directory (the default behavior).
6329 SConsignFile()
6330 # Stores signatures in the file "etc/scons-signatures"
6332 # relative to the top-level SConstruct directory.
6333 # SCons will add a database suffix to this name.
6334 SConsignFile("etc/scons-signatures")
6335 # Stores signatures in the specified absolute file name.
6337 # SCons will add a database suffix to this name.
6338 SConsignFile("/home/me/SCons/signatures")
6339 # Stores signatures in a separate .sconsign file
6341 # in each directory.
6342 SConsignFile(None)
6343 # Stores signatures in a GNU dbm format .sconsign file
6345 import dbm.gnu
6346 SConsignFile(dbm_module=dbm.gnu)
6347 env.SetDefault(key=val, [...])
6349 Sets construction variables to default values specified with the
6350 keyword arguments if (and only if) the variables are not already
6351 set. The following statements are equivalent:
6352 env.SetDefault(FOO='foo')
6354 if 'FOO' not in env:
6355 env['FOO'] = 'foo'
6356 SetOption(name, value), env.SetOption(name, value)
6358 Sets scons option variable name to value. These options are all
6359 also settable via command-line options but the variable name may
6360 differ from the command-line option name - see the table for
6361 correspondences. A value set via command-line option will take
6362 precedence over one set with SetOption, which allows setting a
6363 project default in the scripts and temporarily overriding it via
6364 command line. SetOption calls can also be placed in the
6365 site_init.py file.
6366 See the documentation in the manpage for the corresponding command
6368 line option for information about each specific option. The value
6369 parameter is mandatory, for option values which are boolean in
6370 nature (that is, the command line option does not take an argument)
6371 use a value which evaluates to true (e.g. True, 1) or false (e.g.
6372 False, 0).
6373 Options which affect the reading and processing of SConscript files
6375 are not settable using SetOption since those files must be read in
6376 order to find the SetOption call in the first place.
6377 The settable variables with their associated command-line options
6379 are:
6380 ┌────────────────────────┬───────────────────────────┬─────────────────────┐
6382 │Settable name │ Command-line │ Notes │
6383 │ │ options │ │
6384 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6385 │clean │ -c, │ │
6386 │ │ --clean, │ │
6387 │ │ --remove │ │
6388 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6389 │diskcheck │ --diskcheck │ │
6390 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6391 │duplicate │ --duplicate │ │
6392 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6393 │experimental │ --experimental │ since 4.2 │
6394 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6395 │hash_chunksize │ --hash-chunksize │ Actually sets │
6396 │ │ │ md5_chunksize. │
6397 │ │ │ since 4.2 │
6398 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6399 │hash_format │ --hash-format │ since 4.2 │
6400 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6401 │help │ -h, --help │ │
6402 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6403 │implicit_cache │ --implicit-cache │ │
6404 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6405 │implicit_deps_changed │ --implicit-deps-changed │ Also sets │
6406 │ │ │ implicit_cache. │
6407 │ │ │ (settable since │
6408 │ │ │ 4.2) │
6409 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6410 │implicit_deps_unchanged │ --implicit-deps-unchanged │ Also sets │
6411 │ │ │ implicit_cache. │
6412 │ │ │ (settable since │
6413 │ │ │ 4.2) │
6414 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6415 │max_drift │ --max-drift │ │
6416 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6417 │md5_chunksize │ --md5-chunksize │ │
6418 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6419 │no_exec │ -n, │ │
6420 │ │ --no-exec, │ │
6421 │ │ --just-print, │ │
6422 │ │ --dry-run, │ │
6423 │ │ --recon │ │
6424 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6425 │no_progress │ -Q │ See │
6426 │ │ │ [5] │
6427 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6428 │num_jobs │ -j, --jobs │ │
6429 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6430 │random │ --random │ │
6431 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6432 │silent │ -s, │ │
6433 │ │ --silent, │ │
6434 │ │ --quiet │ │
6435 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6436 │stack_size │ --stack-size │ │
6437 ├────────────────────────┼───────────────────────────┼─────────────────────┤
6438 │warn │ --warn │ │
6439 ├────────────────────────┴───────────────────────────┴─────────────────────┤
6440 │---- │
6441 │[a] If no_progress is set via SetOption in an SConscript │
6442 │file (but not if set in a site_init.py file) there will │
6443 │still be an initial status message about reading │
6444 │SConscript files since SCons has to start reading them │
6445 │before it can see the SetOption. │
6446 └──────────────────────────────────────────────────────────────────────────┘
6447 Example:
6448 SetOption('max_drift', 0)
6450 SideEffect(side_effect, target), env.SideEffect(side_effect, target)
6452 Declares side_effect as a side effect of building target. Both
6453 side_effect and target can be a list, a file name, or a node. A
6454 side effect is a target file that is created or updated as a side
6455 effect of building other targets. For example, a Windows PDB file
6456 is created as a side effect of building the .obj files for a static
6457 library, and various log files are created updated as side effects
6458 of various TeX commands. If a target is a side effect of multiple
6459 build commands, scons will ensure that only one set of commands is
6460 executed at a time. Consequently, you only need to use this method
6461 for side-effect targets that are built as a result of multiple
6462 build commands.
6463 Because multiple build commands may update the same side effect
6465 file, by default the side_effect target is not automatically
6466 removed when the target is removed by the -c option. (Note,
6467 however, that the side_effect might be removed as part of cleaning
6468 the directory in which it lives.) If you want to make sure the
6469 side_effect is cleaned whenever a specific target is cleaned, you
6470 must specify this explicitly with the Clean or env.Clean function.
6471 This function returns the list of side effect Node objects that
6473 were successfully added. If the list of side effects contained any
6474 side effects that had already been added, they are not added and
6475 included in the returned list.
6476 Split(arg), env.Split(arg)
6478 If arg is a string, splits on whitespace and returns a list of
6479 strings without whitespace. This mode is the most common case, and
6480 can be used to split a list of filenames (for example) rather than
6481 having to type them as a list of individually quoted words. If arg
6482 is a list or tuple returns the list or tuple unchanged. If arg is
6483 any other type of object, returns a list containing just the
6484 object. These non-string cases do not actually do any spliting, but
6485 allow an argument variable to be passed to Split without having to
6486 first check its type.
6487 Example:
6489 files = Split("f1.c f2.c f3.c")
6491 files = env.Split("f4.c f5.c f6.c")
6492 files = Split("""
6493 f7.c
6494 f8.c
6495 f9.c
6496 """)
6497 env.subst(input, [raw, target, source, conv])
6499 Performs construction variable interpolation on input, which can be
6500 a string or a sequence.
6501 By default, leading or trailing white space will be removed from
6503 the result, and all sequences of white space will be compressed to
6504 a single space character. Additionally, any $( and $) character
6505 sequences will be stripped from the returned string, The optional
6506 raw argument may be set to 1 if you want to preserve white space
6507 and $(-$) sequences. The raw argument may be set to 2 if you want
6508 to additionally discard all characters between any $( and $) pairs
6509 (as is done for signature calculation).
6510 If the input is a sequence (list or tuple), the individual elements
6512 of the sequence will be expanded, and the results will be returned
6513 as a list.
6514 The optional target and source keyword arguments must be set to
6516 lists of target and source nodes, respectively, if you want the
6517 $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for
6518 expansion. This is usually necessary if you are calling env.subst
6519 from within a Python function used as an SCons action.
6520 Returned string values or sequence elements are converted to their
6522 string representation by default. The optional conv argument may
6523 specify a conversion function that will be used in place of the
6524 default. For example, if you want Python objects (including SCons
6525 Nodes) to be returned as Python objects, you can use a Python
6526 lambda expression to pass in an unnamed function that simply
6527 returns its unconverted argument.
6528 Example:
6530 print(env.subst("The C compiler is: $CC"))
6532 def compile(target, source, env):
6534 sourceDir = env.subst(
6535 "${SOURCE.srcdir}",
6536 target=target,
6537 source=source
6538 )
6539 source_nodes = env.subst('$EXPAND_TO_NODELIST', conv=lambda x: x)
6541 Tag(node, tags)
6543 Annotates file or directory Nodes with information about how the
6544 Package Builder should package those files or directories. All
6545 Node-level tags are optional.
6546 Examples:
6548 # makes sure the built library will be installed with 644 file access mode
6550 Tag(Library('lib.c'), UNIX_ATTR="0o644")
6551 # marks file2.txt to be a documentation file
6553 Tag('file2.txt', DOC)
6554 Tool(name, [toolpath, **kwargs]), env.Tool(name, [toolpath, **kwargs])
6556 Locates the tool specification module name and returns a callable
6557 tool object for that tool. The tool module is searched for in
6558 standard locations and in any paths specified by the optional
6559 toolpath parameter. The standard locations are SCons' own internal
6560 path for tools plus the toolpath, if any (see the Tools section in
6561 the manual page for more details). Any additional keyword arguments
6562 kwargs are passed to the tool module's generate function during
6563 tool object construction.
6564 When called, the tool object updates a construction environment
6566 with construction variables and arranges any other initialization
6567 needed to use the mechanisms that tool describes.
6568 When the env.Tool form is used, the tool object is automatically
6570 called to update env and the value of tool is appended to the
6571 $TOOLS construction variable in that environment.
6572 Examples:
6574 env.Tool('gcc')
6576 env.Tool('opengl', toolpath=['build/tools'])
6577 When the global function Tool form is used, the tool object is
6579 constructed but not called, as it lacks the context of an
6580 environment to update. The tool object can be passed to an
6581 Environment or Clone call as part of the tools keyword argument, in
6582 which case the tool is applied to the environment being
6583 constructed, or it can be called directly, in which case a
6584 construction environment to update must be passed as the argument.
6585 Either approach will also update the $TOOLS construction variable.
6586 Examples:
6588 env = Environment(tools=[Tool('msvc')])
6590 env = Environment()
6592 msvctool = Tool('msvc')
6593 msvctool(env) # adds 'msvc' to the TOOLS variable
6594 gltool = Tool('opengl', toolpath = ['tools'])
6595 gltool(env) # adds 'opengl' to the TOOLS variable
6596 Changed in SCons 4.2: env.Tool now returns the tool object,
6599 previously it did not return (i.e. returned None).
6600 Value(value, [built_value], [name]), env.Value(value, [built_value],
6602 [name])
6603 Returns a Node object representing the specified Python value.
6604 Value Nodes can be used as dependencies of targets. If the result
6605 of calling str(value) changes between SCons runs, any targets
6606 depending on Value(value) will be rebuilt. (This is true even when
6607 using timestamps to decide if files are up-to-date.) When using
6608 timestamp source signatures, Value Nodes' timestamps are equal to
6609 the system time when the Node is created. name can be provided as
6610 an alternative name for the resulting Value node; this is advised
6611 if the value parameter can't be converted to a string.
6612 The returned Value Node object has a write() method that can be
6614 used to "build" a Value Node by setting a new value. The optional
6615 built_value argument can be specified when the Value Node is
6616 created to indicate the Node should already be considered "built."
6617 There is a corresponding read() method that will return the built
6618 value of the Node.
6619 Examples:
6621 env = Environment()
6623 def create(target, source, env):
6625 # A function that will write a 'prefix=$SOURCE'
6626 # string into the file name specified as the
6627 # $TARGET.
6628 with open(str(target[0]), 'wb') as f:
6629 f.write('prefix=' + source[0].get_contents())
6630 # Fetch the prefix= argument, if any, from the command
6632 # line, and use /usr/local as the default.
6633 prefix = ARGUMENTS.get('prefix', '/usr/local')
6634 # Attach a .Config() builder for the above function action
6636 # to the construction environment.
6637 env['BUILDERS']['Config'] = Builder(action = create)
6638 env.Config(target = 'package-config', source = Value(prefix))
6639 def build_value(target, source, env):
6641 # A function that "builds" a Python Value by updating
6642 # the the Python value with the contents of the file
6643 # specified as the source of the Builder call ($SOURCE).
6644 target[0].write(source[0].get_contents())
6645 output = env.Value('before')
6647 input = env.Value('after')
6648 # Attach a .UpdateValue() builder for the above function
6650 # action to the construction environment.
6651 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6652 env.UpdateValue(target = Value(output), source = Value(input))
6653 VariantDir(variant_dir, src_dir, [duplicate]),
6655 env.VariantDir(variant_dir, src_dir, [duplicate])
6656 Sets up an alternate build location. When building in the
6657 variant_dir, SCons backfills as needed with files from src_dir to
6658 create a complete build directory. VariantDir can be called
6659 multiple times with the same src_dir to set up multiple builds with
6660 different options (variants).
6661 The variant location must be in or underneath the project top
6663 directory, and src_dir may not be underneath variant_dir.
6664 By default, SCons physically duplicates the source files and
6666 SConscript files as needed into the variant tree. Thus, a build
6667 performed in the variant tree is guaranteed to be identical to a
6668 build performed in the source tree even if intermediate source
6669 files are generated during the build, or if preprocessors or other
6670 scanners search for included files relative to the source file, or
6671 if individual compilers or other invoked tools are hard-coded to
6672 put derived files in the same directory as source files. Only the
6673 files SCons calculates are needed for the build are duplicated into
6674 variant_dir.
6675 If possible on the platform, the duplication is performed by
6677 linking rather than copying. This behavior is affected by the
6678 --duplicate command-line option.
6679 Duplicating the source files may be disabled by setting the
6681 duplicate argument to False. This will cause SCons to invoke
6682 Builders using the path names of source files in src_dir and the
6683 path names of derived files within variant_dir. This is more
6684 efficient than duplicate=True, and is safe for most builds; revert
6685 to True if it causes problems.
6686 VariantDir works most naturally with used with a subsidiary
6689 SConscript file. The subsidiary SConscript file is called as if it
6690 were in variant_dir, regardless of the value of duplicate. This is
6691 how you tell scons which variant of a source tree to build:
6692 # run src/SConscript in two variant directories
6694 VariantDir('build/variant1', 'src')
6695 SConscript('build/variant1/SConscript')
6696 VariantDir('build/variant2', 'src')
6697 SConscript('build/variant2/SConscript')
6698 See also the SConscript function, described above, for another way
6700 to specify a variant directory in conjunction with calling a
6701 subsidiary SConscript file.
6702 Examples:
6704 # use names in the build directory, not the source directory
6706 VariantDir('build', 'src', duplicate=0)
6707 Program('build/prog', 'build/source.c')
6708 # this builds both the source and docs in a separate subtree
6710 VariantDir('build', '.', duplicate=0)
6711 SConscript(dirs=['build/src','build/doc'])
6712 # same as previous example, but only uses SConscript
6714 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6715 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6716 WhereIs(program, [path, pathext, reject]), env.WhereIs(program, [path,
6718 pathext, reject])
6719 Searches for the specified executable program, returning the full
6720 path to the program or None.
6721 When called as a construction environment method, searches the
6723 paths in the path keyword argument, or if None (the default) the
6724 paths listed in the construction environment (env['ENV']['PATH']).
6725 The external environment's path list (os.environ['PATH']) is used
6726 as a fallback if the key env['ENV']['PATH'] does not exist.
6727 On Windows systems, searches for executable programs with any of
6729 the file extensions listed in the pathext keyword argument, or if
6730 None (the default) the pathname extensions listed in the
6731 construction environment (env['ENV']['PATHEXT']). The external
6732 environment's pathname extensions list (os.environ['PATHEXT']) is
6733 used as a fallback if the key env['ENV']['PATHEXT'] does not exist.
6734 When called as a global function, uses the external environment's
6736 path os.environ['PATH'] and path extensions os.environ['PATHEXT'],
6737 respectively, if path and pathext are None.
6738 Will not select any path name or names in the optional reject list.
6740 SConscript Variables
6742 In addition to the global functions and methods, scons supports a
6743 number of variables that can be used in SConscript files to affect how
6744 you want the build to be performed.
6745 ARGLIST
6747 A list of the keyword=value arguments specified on the command
6748 line. Each element in the list is a tuple containing the argument.
6749 The separate keyword and value elements of the tuple can be
6750 accessed by subscripting for elements [0] and [1] of the tuple, or,
6751 more readably, by using tuple unpacking. Example:
6752 print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
6754 print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
6755 key, value = ARGLIST[2]
6756 print("third keyword, value =", key, value)
6757 for key, value in ARGLIST:
6758 # process key and value
6759 ARGUMENTS
6761 A dictionary of all the keyword=value arguments specified on the
6762 command line. The dictionary is not in order, and if a given
6763 keyword has more than one value assigned to it on the command line,
6764 the last (right-most) value is the one in the ARGUMENTS dictionary.
6765 Example:
6767 if ARGUMENTS.get('debug', 0):
6769 env = Environment(CCFLAGS='-g')
6770 else:
6771 env = Environment()
6772 BUILD_TARGETS
6774 A list of the targets which scons has been asked to build. The
6775 contents will be either those targets listed on the command line,
6776 or, if none, those targets set via calls to the Default function.
6777 It does not contain any dependent targets that scons selects for
6778 building as a result of making the sure the specified targets are
6779 up to date, if those targets did not appear on the command line.
6780 The list is empty if neither command line targets or Default calls
6781 are present.
6782 The elements of this list may be strings or nodes, so you should
6784 run the list through the Python str function to make sure any Node
6785 path names are converted to strings.
6786 Because this list may be taken from the list of targets specified
6788 using the Default function, the contents of the list may change on
6789 each successive call to Default. See the DEFAULT_TARGETS list,
6790 below, for additional information.
6791 Example:
6793 if 'foo' in BUILD_TARGETS:
6795 print("Don't forget to test the `foo' program!")
6796 if 'special/program' in BUILD_TARGETS:
6797 SConscript('special')
6798 COMMAND_LINE_TARGETS
6800 A list of the targets explicitly specified on the command line. If
6801 there are command line targets, this list will have the same
6802 contents as BUILD_TARGETS. If there are no targets specified on the
6803 command line, the list is empty. The elements of this list are
6804 strings. This can be used, for example, to take specific actions
6805 only when certain targets are explicitly being built.
6806 Example:
6808 if 'foo' in COMMAND_LINE_TARGETS:
6810 print("Don't forget to test the `foo' program!")
6811 if 'special/program' in COMMAND_LINE_TARGETS:
6812 SConscript('special')
6813 DEFAULT_TARGETS
6815 A list of the target nodes that have been specified using the
6816 Default function. If there are no command line targets, this list
6817 will have the same contents as BUILD_TARGETS. Since the elements of
6818 the list are nodes, you need to call the Python str function on
6819 them to get the path name for each Node.
6820 Example:
6822 print(str(DEFAULT_TARGETS[0]))
6824 if 'foo' in [str(t) for t in DEFAULT_TARGETS]:
6825 print("Don't forget to test the `foo' program!")
6826 The contents of the DEFAULT_TARGETS list change on on each
6828 successive call to the Default function:
6829 print([str(t) for t in DEFAULT_TARGETS]) # originally []
6831 Default('foo')
6832 print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo']
6833 Default('bar')
6834 print([str(t) for t in DEFAULT_TARGETS]) # now a node ['foo', 'bar']
6835 Default(None)
6836 print([str(t) for t in DEFAULT_TARGETS]) # back to []
6837 Consequently, be sure to use DEFAULT_TARGETS only after you've made
6839 all of your Default() calls, or else simply be careful of the order
6840 of these statements in your SConscript files so that you don't look
6841 for a specific default target before it's actually been added to
6842 the list.
6843 These variables may be accessed from custom Python modules that you
6845 import into an SConscript file by adding the following to the Python
6846 module:
6847 from SCons.Script import *
6849 Construction Variables
6851 A construction environment has an associated dictionary of construction
6852 variables that are used by built-in or user-supplied build rules.
6853 Construction variable naming must follow the same rules as Python
6854 identifier naming: the initial character must be an underscore or
6855 letter, followed by any number of underscores, letters, or digits. A
6856 construction environment is not a Python dictionary itself, but it can
6857 be indexed like one to access a construction variable:
6858 env["CC"] = "cc"
6860 flags = env.get("CPPDEFINES", [])
6861 Construction variables can also be retrieved and set by using the
6863 Dictionary method of the construction environment to create an actual
6864 dictionary:
6865 cvars = env.Dictionary()
6867 cvars["CC"] = "cc"
6868 Construction variables can also be passed to the construction
6870 environment constructor:
6871 env = Environment(CC="cc")
6873 or when copying a construction environment using the Clone method:
6875 env2 = env.Clone(CC="cl.exe")
6877 Construction variables can also be supplied as keyword arguments to a
6879 builder, in which case those settings affect only the work done by that
6880 builder call, and not the construction environment as a whole. This
6881 concept is called an override:
6882 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
6884 A number of useful construction variables are automatically defined by
6886 scons for each supported platform, and you can modify these or define
6887 any additional construction variables for your own use, taking care not
6888 to overwrite ones which SCons is using. The following is a list of the
6889 possible automatically defined construction variables.
6890 Note the actual list available at execution time will never include all
6892 of these, as the ones detected as not being useful (wrong platform,
6893 necessary external command or files not installed, etc.) will not be
6894 set up. Correct build setups should be resilient to the possible
6895 absence of certain construction variables before using them, for
6896 example by using a Python dictionary get method to retrieve the value
6897 and taking alternative action if the return indicates the variable is
6898 unset. The env.Dump method can be called to examine the construction
6899 variables set in a particular environment.
6900 __LDMODULEVERSIONFLAGS
6902 This construction variable automatically introduces
6903 $_LDMODULEVERSIONFLAGS if $LDMODULEVERSION is set. Othervise it
6904 evaluates to an empty string.
6905 __NINJA_NO
6907 Internal flag. Used to tell SCons whether or not to try to import
6908 pypi's ninja python package. This is set to True when being called
6909 by Ninja?
6910 __SHLIBVERSIONFLAGS
6912 This construction variable automatically introduces
6913 $_SHLIBVERSIONFLAGS if $SHLIBVERSION is set. Othervise it evaluates
6914 to an empty string.
6915 APPLELINK_COMPATIBILITY_VERSION
6917 On Mac OS X this is used to set the linker flag:
6918 -compatibility_version
6919 The value is specified as X[.Y[.Z]] where X is between 1 and 65535,
6921 Y can be omitted or between 1 and 255, Z can be omitted or between
6922 1 and 255. This value will be derived from $SHLIBVERSION if not
6923 specified. The lowest digit will be dropped and replaced by a 0.
6924 If the $APPLELINK_NO_COMPATIBILITY_VERSION is set then no
6926 -compatibility_version will be output.
6927 See MacOS's ld manpage for more details
6929 _APPLELINK_COMPATIBILITY_VERSION
6931 A macro (by default a generator function) used to create the linker
6932 flags to specify apple's linker's -compatibility_version flag. The
6933 default generator uses $APPLELINK_COMPATIBILITY_VERSION and
6934 $APPLELINK_NO_COMPATIBILITY_VERSION and $SHLIBVERSION to determine
6935 the correct flag.
6936 APPLELINK_CURRENT_VERSION
6938 On Mac OS X this is used to set the linker flag: -current_version
6939 The value is specified as X[.Y[.Z]] where X is between 1 and 65535,
6941 Y can be omitted or between 1 and 255, Z can be omitted or between
6942 1 and 255. This value will be set to $SHLIBVERSION if not
6943 specified.
6944 If the $APPLELINK_NO_CURRENT_VERSION is set then no
6946 -current_version will be output.
6947 See MacOS's ld manpage for more details
6949 _APPLELINK_CURRENT_VERSION
6951 A macro (by default a generator function) used to create the linker
6952 flags to specify apple's linker's -current_version flag. The
6953 default generator uses $APPLELINK_CURRENT_VERSION and
6954 $APPLELINK_NO_CURRENT_VERSION and $SHLIBVERSION to determine the
6955 correct flag.
6956 APPLELINK_NO_COMPATIBILITY_VERSION
6958 Set this to any True (1|True|non-empty string) value to disable
6959 adding -compatibility_version flag when generating versioned shared
6960 libraries.
6961 This overrides $APPLELINK_COMPATIBILITY_VERSION.
6963 APPLELINK_NO_CURRENT_VERSION
6965 Set this to any True (1|True|non-empty string) value to disable
6966 adding -current_version flag when generating versioned shared
6967 libraries.
6968 This overrides $APPLELINK_CURRENT_VERSION.
6970 AR
6972 The static library archiver.
6973 ARCHITECTURE
6975 Specifies the system architecture for which the package is being
6976 built. The default is the system architecture of the machine on
6977 which SCons is running. This is used to fill in the Architecture:
6978 field in an Ipkg control file, and the BuildArch: field in the RPM
6979 .spec file, as well as forming part of the name of a generated RPM
6980 package file.
6981 See the Package builder.
6983 ARCOM
6985 The command line used to generate a static library from object
6986 files.
6987 ARCOMSTR
6989 The string displayed when a static library is generated from object
6990 files. If this is not set, then $ARCOM (the command line) is
6991 displayed.
6992 env = Environment(ARCOMSTR = "Archiving $TARGET")
6994 ARFLAGS
6996 General options passed to the static library archiver.
6997 AS
6999 The assembler.
7000 ASCOM
7002 The command line used to generate an object file from an
7003 assembly-language source file.
7004 ASCOMSTR
7006 The string displayed when an object file is generated from an
7007 assembly-language source file. If this is not set, then $ASCOM (the
7008 command line) is displayed.
7009 env = Environment(ASCOMSTR = "Assembling $TARGET")
7011 ASFLAGS
7013 General options passed to the assembler.
7014 ASPPCOM
7016 The command line used to assemble an assembly-language source file
7017 into an object file after first running the file through the C
7018 preprocessor. Any options specified in the $ASFLAGS and $CPPFLAGS
7019 construction variables are included on this command line.
7020 ASPPCOMSTR
7022 The string displayed when an object file is generated from an
7023 assembly-language source file after first running the file through
7024 the C preprocessor. If this is not set, then $ASPPCOM (the command
7025 line) is displayed.
7026 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
7028 ASPPFLAGS
7030 General options when an assembling an assembly-language source file
7031 into an object file after first running the file through the C
7032 preprocessor. The default is to use the value of $ASFLAGS.
7033 BIBTEX
7035 The bibliography generator for the TeX formatter and typesetter and
7036 the LaTeX structured formatter and typesetter.
7037 BIBTEXCOM
7039 The command line used to call the bibliography generator for the
7040 TeX formatter and typesetter and the LaTeX structured formatter and
7041 typesetter.
7042 BIBTEXCOMSTR
7044 The string displayed when generating a bibliography for TeX or
7045 LaTeX. If this is not set, then $BIBTEXCOM (the command line) is
7046 displayed.
7047 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
7049 BIBTEXFLAGS
7051 General options passed to the bibliography generator for the TeX
7052 formatter and typesetter and the LaTeX structured formatter and
7053 typesetter.
7054 BUILDERS
7056 A dictionary mapping the names of the builders available through
7057 the construction environment to underlying Builder objects. Custom
7058 builders need to be added to this to make them available.
7059 A platform-dependent default list of builders such as Program,
7061 Library etc. is used to populate this construction variable when
7062 the construction environment is initialized via the
7063 presence/absence of the tools those builders depend on. $BUILDERS
7064 can be examined to learn which builders will actually be available
7065 at run-time.
7066 Note that if you initialize this construction variable through
7068 assignment when the construction environment is created, that value
7069 for $BUILDERS will override any defaults:
7070 bld = Builder(action='foobuild < $SOURCE > $TARGET')
7072 env = Environment(BUILDERS={'NewBuilder': bld})
7073 To instead use a new Builder object in addition to the default
7075 Builders, add your new Builder object like this:
7076 env = Environment()
7078 env.Append(BUILDERS={'NewBuilder': bld})
7079 or this:
7081 env = Environment()
7083 env['BUILDERS']['NewBuilder'] = bld
7084 CACHEDIR_CLASS
7086 The class type that SCons should use when instantiating a new
7087 CacheDir for the given environment. It must be a subclass of the
7088 SCons.CacheDir.CacheDir class.
7089 CC
7091 The C compiler.
7092 CCCOM
7094 The command line used to compile a C source file to a (static)
7095 object file. Any options specified in the $CFLAGS, $CCFLAGS and
7096 $CPPFLAGS construction variables are included on this command line.
7097 See also $SHCCCOM for compiling to shared objects.
7098 CCCOMSTR
7100 If set, the string displayed when a C source file is compiled to a
7101 (static) object file. If not set, then $CCCOM (the command line) is
7102 displayed. See also $SHCCCOMSTR for compiling to shared objects.
7103 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
7105 CCFLAGS
7107 General options that are passed to the C and C++ compilers. See
7108 also $SHCCFLAGS for compiling to shared objects.
7109 CCPCHFLAGS
7111 Options added to the compiler command line to support building with
7112 precompiled headers. The default value expands expands to the
7113 appropriate Microsoft Visual C++ command-line options when the $PCH
7114 construction variable is set.
7115 CCPDBFLAGS
7117 Options added to the compiler command line to support storing
7118 debugging information in a Microsoft Visual C++ PDB file. The
7119 default value expands expands to appropriate Microsoft Visual C++
7120 command-line options when the $PDB construction variable is set.
7121 The Visual C++ compiler option that SCons uses by default to
7123 generate PDB information is /Z7. This works correctly with parallel
7124 (-j) builds because it embeds the debug information in the
7125 intermediate object files, as opposed to sharing a single PDB file
7126 between multiple object files. This is also the only way to get
7127 debug information embedded into a static library. Using the /Zi
7128 instead may yield improved link-time performance, although parallel
7129 builds will no longer work.
7130 You can generate PDB files with the /Zi switch by overriding the
7132 default $CCPDBFLAGS variable as follows:
7133 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
7135 An alternative would be to use the /Zi to put the debugging
7137 information in a separate .pdb file for each object file by
7138 overriding the $CCPDBFLAGS variable as follows:
7139 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
7141 CCVERSION
7143 The version number of the C compiler. This may or may not be set,
7144 depending on the specific C compiler being used.
7145 CFILESUFFIX
7147 The suffix for C source files. This is used by the internal CFile
7148 builder when generating C files from Lex (.l) or YACC (.y) input
7149 files. The default suffix, of course, is .c (lower case). On
7150 case-insensitive systems (like Windows), SCons also treats .C
7151 (upper case) files as C files.
7152 CFLAGS
7154 General options that are passed to the C compiler (C only; not
7155 C++). See also $SHCFLAGS for compiling to shared objects.
7156 CHANGE_SPECFILE
7158 A hook for modifying the file that controls the packaging build
7159 (the .spec for RPM, the control for Ipkg, the .wxs for MSI). If
7160 set, the function will be called after the SCons template for the
7161 file has been written.
7162 See the Package builder.
7164 CHANGED_SOURCES
7166 A reserved variable name that may not be set or used in a
7167 construction environment. (See the manpage section "Variable
7168 Substitution" for more information).
7169 CHANGED_TARGETS
7171 A reserved variable name that may not be set or used in a
7172 construction environment. (See the manpage section "Variable
7173 Substitution" for more information).
7174 CHANGELOG
7176 The name of a file containing the change log text to be included in
7177 the package. This is included as the %changelog section of the RPM
7178 .spec file.
7179 See the Package builder.
7181 COMPILATIONDB_COMSTR
7183 The string displayed when the CompilationDatabase builder's action
7184 is run.
7185 COMPILATIONDB_PATH_FILTER
7187 A string which instructs CompilationDatabase to only include
7188 entries where the output member matches the pattern in the filter
7189 string using fnmatch, which uses glob style wildcards.
7190 The default value is an empty string '', which disables filtering.
7192 COMPILATIONDB_USE_ABSPATH
7194 A boolean flag to instruct CompilationDatabase whether to write the
7195 file and output members in the compilation database using absolute
7196 or relative paths.
7197 The default value is False (use relative paths)
7199 _concat
7201 A function used to produce variables like $_CPPINCFLAGS. It takes
7202 four mandatory arguments, and up to 4 additional optional
7203 arguments: 1) a prefix to concatenate onto each element, 2) a list
7204 of elements, 3) a suffix to concatenate onto each element, 4) an
7205 environment for variable interpolation, 5) an optional function
7206 that will be called to transform the list before concatenation, 6)
7207 an optionally specified target (Can use TARGET), 7) an optionally
7208 specified source (Can use SOURCE), 8) optional affect_signature
7209 flag which will wrap non-empty returned value with $( and $) to
7210 indicate the contents should not affect the signature of the
7211 generated command line.
7212 env['_CPPINCFLAGS'] = '${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs, TARGET, SOURCE, affect_signature=False)}'
7214 CONFIGUREDIR
7217 The name of the directory in which Configure context test files are
7218 written. The default is .sconf_temp in the top-level directory
7219 containing the SConstruct file.
7220 CONFIGURELOG
7222 The name of the Configure context log file. The default is
7223 config.log in the top-level directory containing the SConstruct
7224 file.
7225 _CPPDEFFLAGS
7227 An automatically-generated construction variable containing the C
7228 preprocessor command-line options to define values. The value of
7229 $_CPPDEFFLAGS is created by respectively prepending and appending
7230 $CPPDEFPREFIX and $CPPDEFSUFFIX to each definition in $CPPDEFINES.
7231 CPPDEFINES
7233 A platform independent specification of C preprocessor macro
7234 definitions. The definitions will be added to command lines through
7235 the automatically-generated $_CPPDEFFLAGS construction variable
7236 (see above), which is constructed according to the type of value of
7237 $CPPDEFINES:
7238 If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and
7240 $CPPDEFSUFFIX construction variables will be respectively prepended
7241 and appended to each definition in $CPPDEFINES.
7242 # Will add -Dxyz to POSIX compiler command lines,
7244 # and /Dxyz to Microsoft Visual C++ command lines.
7245 env = Environment(CPPDEFINES='xyz')
7246 If $CPPDEFINES is a list, the values of the $CPPDEFPREFIX and
7248 $CPPDEFSUFFIX construction variables will be respectively prepended
7249 and appended to each element in the list. If any element is a list
7250 or tuple, then the first item is the name being defined and the
7251 second item is its value:
7252 # Will add -DB=2 -DA to POSIX compiler command lines,
7254 # and /DB=2 /DA to Microsoft Visual C++ command lines.
7255 env = Environment(CPPDEFINES=[('B', 2), 'A'])
7256 If $CPPDEFINES is a dictionary, the values of the $CPPDEFPREFIX and
7258 $CPPDEFSUFFIX construction variables will be respectively prepended
7259 and appended to each item from the dictionary. The key of each
7260 dictionary item is a name being defined to the dictionary item's
7261 corresponding value; if the value is None, then the name is defined
7262 without an explicit value. Note that the resulting flags are sorted
7263 by keyword to ensure that the order of the options on the command
7264 line is consistent each time scons is run.
7265 # Will add -DA -DB=2 to POSIX compiler command lines,
7267 # and /DA /DB=2 to Microsoft Visual C++ command lines.
7268 env = Environment(CPPDEFINES={'B':2, 'A':None})
7269 CPPDEFPREFIX
7271 The prefix used to specify preprocessor macro definitions on the C
7272 compiler command line. This will be prepended to each definition in
7273 the $CPPDEFINES construction variable when the $_CPPDEFFLAGS
7274 variable is automatically generated.
7275 CPPDEFSUFFIX
7277 The suffix used to specify preprocessor macro definitions on the C
7278 compiler command line. This will be appended to each definition in
7279 the $CPPDEFINES construction variable when the $_CPPDEFFLAGS
7280 variable is automatically generated.
7281 CPPFLAGS
7283 User-specified C preprocessor options. These will be included in
7284 any command that uses the C preprocessor, including not just
7285 compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
7286 $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
7287 $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
7288 compile a Fortran source file, and the $ASPPCOM command line used
7289 to assemble an assembly language source file, after first running
7290 each file through the C preprocessor. Note that this variable does
7291 not contain -I (or similar) include search path options that scons
7292 generates automatically from $CPPPATH. See $_CPPINCFLAGS, below,
7293 for the variable that expands to those options.
7294 _CPPINCFLAGS
7296 An automatically-generated construction variable containing the C
7297 preprocessor command-line options for specifying directories to be
7298 searched for include files. The value of $_CPPINCFLAGS is created
7299 by respectively prepending and appending $INCPREFIX and $INCSUFFIX
7300 to each directory in $CPPPATH.
7301 CPPPATH
7303 The list of directories that the C preprocessor will search for
7304 include directories. The C/C++ implicit dependency scanner will
7305 search these directories for include files. In general it's not
7306 advised to put include directory directives directly into $CCFLAGS
7307 or $CXXFLAGS as the result will be non-portable and the directories
7308 will not be searched by the dependency scanner. $CPPPATH should be
7309 a list of path strings, or a single string, not a pathname list
7310 joined by Python's os.sep.
7311 Note: directory names in $CPPPATH will be looked-up relative to the
7313 directory of the SConscript file when they are used in a command.
7314 To force scons to look-up a directory relative to the root of the
7315 source tree use the # prefix:
7316 env = Environment(CPPPATH='#/include')
7318 The directory look-up can also be forced using the Dir function:
7320 include = Dir('include')
7322 env = Environment(CPPPATH=include)
7323 The directory list will be added to command lines through the
7325 automatically-generated $_CPPINCFLAGS construction variable, which
7326 is constructed by respectively prepending and appending the values
7327 of the $INCPREFIX and $INCSUFFIX construction variables to each
7328 directory in $CPPPATH. Any command lines you define that need the
7329 $CPPPATH directory list should include $_CPPINCFLAGS:
7330 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
7332 CPPSUFFIXES
7334 The list of suffixes of files that will be scanned for C
7335 preprocessor implicit dependencies (#include lines). The default
7336 list is:
7337 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
7339 ".h", ".H", ".hxx", ".hpp", ".hh",
7340 ".F", ".fpp", ".FPP",
7341 ".m", ".mm",
7342 ".S", ".spp", ".SPP"]
7343 CXX
7345 The C++ compiler. See also $SHCXX for compiling to shared objects..
7346 CXXCOM
7348 The command line used to compile a C++ source file to an object
7349 file. Any options specified in the $CXXFLAGS and $CPPFLAGS
7350 construction variables are included on this command line. See also
7351 $SHCXXCOM for compiling to shared objects..
7352 CXXCOMSTR
7354 If set, the string displayed when a C++ source file is compiled to
7355 a (static) object file. If not set, then $CXXCOM (the command line)
7356 is displayed. See also $SHCXXCOMSTR for compiling to shared
7357 objects..
7358 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
7360 CXXFILESUFFIX
7362 The suffix for C++ source files. This is used by the internal
7363 CXXFile builder when generating C++ files from Lex (.ll) or YACC
7364 (.yy) input files. The default suffix is .cc. SCons also treats
7365 files with the suffixes .cpp, .cxx, .c++, and .C++ as C++ files,
7366 and files with .mm suffixes as Objective C++ files. On
7367 case-sensitive systems (Linux, UNIX, and other POSIX-alikes), SCons
7368 also treats .C (upper case) files as C++ files.
7369 CXXFLAGS
7371 General options that are passed to the C++ compiler. By default,
7372 this includes the value of $CCFLAGS, so that setting $CCFLAGS
7373 affects both C and C++ compilation. If you want to add C++-specific
7374 flags, you must set or override the value of $CXXFLAGS. See also
7375 $SHCXXFLAGS for compiling to shared objects..
7376 CXXVERSION
7378 The version number of the C++ compiler. This may or may not be set,
7379 depending on the specific C++ compiler being used.
7380 DC
7382 The D compiler to use. See also $SHDC for compiling to shared
7383 objects.
7384 DCOM
7386 The command line used to compile a D file to an object file. Any
7387 options specified in the $DFLAGS construction variable is included
7388 on this command line. See also $SHDCOM for compiling to shared
7389 objects.
7390 DCOMSTR
7392 If set, the string displayed when a D source file is compiled to a
7393 (static) object file. If not set, then $DCOM (the command line) is
7394 displayed. See also $SHDCOMSTR for compiling to shared objects.
7395 DDEBUG
7397 List of debug tags to enable when compiling.
7398 DDEBUGPREFIX
7400 DDEBUGPREFIX.
7401 DDEBUGSUFFIX
7403 DDEBUGSUFFIX.
7404 DESCRIPTION
7406 A long description of the project being packaged. This is included
7407 in the relevant section of the file that controls the packaging
7408 build.
7409 See the Package builder.
7411 DESCRIPTION_lang
7413 A language-specific long description for the specified lang. This
7414 is used to populate a %description -l section of an RPM .spec file.
7415 See the Package builder.
7417 DFILESUFFIX
7419 DFILESUFFIX.
7420 DFLAGPREFIX
7422 DFLAGPREFIX.
7423 DFLAGS
7425 General options that are passed to the D compiler.
7426 DFLAGSUFFIX
7428 DFLAGSUFFIX.
7429 DINCPREFIX
7431 DINCPREFIX.
7432 DINCSUFFIX
7434 DLIBFLAGSUFFIX.
7435 Dir
7437 A function that converts a string into a Dir instance relative to
7438 the target being built.
7439 Dirs
7441 A function that converts a list of strings into a list of Dir
7442 instances relative to the target being built.
7443 DLIB
7445 Name of the lib tool to use for D codes.
7446 DLIBCOM
7448 The command line to use when creating libraries.
7449 DLIBDIRPREFIX
7451 DLIBLINKPREFIX.
7452 DLIBDIRSUFFIX
7454 DLIBLINKSUFFIX.
7455 DLIBFLAGPREFIX
7457 DLIBFLAGPREFIX.
7458 DLIBFLAGSUFFIX
7460 DLIBFLAGSUFFIX.
7461 DLIBLINKPREFIX
7463 DLIBLINKPREFIX.
7464 DLIBLINKSUFFIX
7466 DLIBLINKSUFFIX.
7467 DLINK
7469 Name of the linker to use for linking systems including D sources.
7470 See also $SHDLINK for linking shared objects.
7471 DLINKCOM
7473 The command line to use when linking systems including D sources.
7474 See also $SHDLINKCOM for linking shared objects.
7475 DLINKFLAGPREFIX
7477 DLINKFLAGPREFIX.
7478 DLINKFLAGS
7480 List of linker flags. See also $SHDLINKFLAGS for linking shared
7481 objects.
7482 DLINKFLAGSUFFIX
7484 DLINKFLAGSUFFIX.
7485 DOCBOOK_DEFAULT_XSL_EPUB
7487 The default XSLT file for the DocbookEpub builder within the
7488 current environment, if no other XSLT gets specified via keyword.
7489 DOCBOOK_DEFAULT_XSL_HTML
7491 The default XSLT file for the DocbookHtml builder within the
7492 current environment, if no other XSLT gets specified via keyword.
7493 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
7495 The default XSLT file for the DocbookHtmlChunked builder within the
7496 current environment, if no other XSLT gets specified via keyword.
7497 DOCBOOK_DEFAULT_XSL_HTMLHELP
7499 The default XSLT file for the DocbookHtmlhelp builder within the
7500 current environment, if no other XSLT gets specified via keyword.
7501 DOCBOOK_DEFAULT_XSL_MAN
7503 The default XSLT file for the DocbookMan builder within the current
7504 environment, if no other XSLT gets specified via keyword.
7505 DOCBOOK_DEFAULT_XSL_PDF
7507 The default XSLT file for the DocbookPdf builder within the current
7508 environment, if no other XSLT gets specified via keyword.
7509 DOCBOOK_DEFAULT_XSL_SLIDESHTML
7511 The default XSLT file for the DocbookSlidesHtml builder within the
7512 current environment, if no other XSLT gets specified via keyword.
7513 DOCBOOK_DEFAULT_XSL_SLIDESPDF
7515 The default XSLT file for the DocbookSlidesPdf builder within the
7516 current environment, if no other XSLT gets specified via keyword.
7517 DOCBOOK_FOP
7519 The path to the PDF renderer fop or xep, if one of them is
7520 installed (fop gets checked first).
7521 DOCBOOK_FOPCOM
7523 The full command-line for the PDF renderer fop or xep.
7524 DOCBOOK_FOPCOMSTR
7526 The string displayed when a renderer like fop or xep is used to
7527 create PDF output from an XML file.
7528 DOCBOOK_FOPFLAGS
7530 Additonal command-line flags for the PDF renderer fop or xep.
7531 DOCBOOK_XMLLINT
7533 The path to the external executable xmllint, if it's installed.
7534 Note, that this is only used as last fallback for resolving
7535 XIncludes, if no lxml Python binding can be imported in the current
7536 system.
7537 DOCBOOK_XMLLINTCOM
7539 The full command-line for the external executable xmllint.
7540 DOCBOOK_XMLLINTCOMSTR
7542 The string displayed when xmllint is used to resolve XIncludes for
7543 a given XML file.
7544 DOCBOOK_XMLLINTFLAGS
7546 Additonal command-line flags for the external executable xmllint.
7547 DOCBOOK_XSLTPROC
7549 The path to the external executable xsltproc (or saxon, xalan), if
7550 one of them is installed. Note, that this is only used as last
7551 fallback for XSL transformations, if no lxml Python binding can be
7552 imported in the current system.
7553 DOCBOOK_XSLTPROCCOM
7555 The full command-line for the external executable xsltproc (or
7556 saxon, xalan).
7557 DOCBOOK_XSLTPROCCOMSTR
7559 The string displayed when xsltproc is used to transform an XML file
7560 via a given XSLT stylesheet.
7561 DOCBOOK_XSLTPROCFLAGS
7563 Additonal command-line flags for the external executable xsltproc
7564 (or saxon, xalan).
7565 DOCBOOK_XSLTPROCPARAMS
7567 Additonal parameters that are not intended for the XSLT processor
7568 executable, but the XSL processing itself. By default, they get
7569 appended at the end of the command line for saxon and saxon-xslt,
7570 respectively.
7571 DPATH
7573 List of paths to search for import modules.
7574 DRPATHPREFIX
7576 DRPATHPREFIX.
7577 DRPATHSUFFIX
7579 DRPATHSUFFIX.
7580 DSUFFIXES
7582 The list of suffixes of files that will be scanned for imported D
7583 package files. The default list is ['.d'].
7584 DVERPREFIX
7586 DVERPREFIX.
7587 DVERSIONS
7589 List of version tags to enable when compiling.
7590 DVERSUFFIX
7592 DVERSUFFIX.
7593 DVIPDF
7595 The TeX DVI file to PDF file converter.
7596 DVIPDFCOM
7598 The command line used to convert TeX DVI files into a PDF file.
7599 DVIPDFCOMSTR
7601 The string displayed when a TeX DVI file is converted into a PDF
7602 file. If this is not set, then $DVIPDFCOM (the command line) is
7603 displayed.
7604 DVIPDFFLAGS
7606 General options passed to the TeX DVI file to PDF file converter.
7607 DVIPS
7609 The TeX DVI file to PostScript converter.
7610 DVIPSFLAGS
7612 General options passed to the TeX DVI file to PostScript converter.
7613 ENV
7615 A dictionary of environment variables to use when invoking
7616 commands. When $ENV is used in a command all list values will be
7617 joined using the path separator and any other non-string values
7618 will simply be coerced to a string. Note that, by default, scons
7619 does not propagate the environment in effect when you execute scons
7620 to the commands used to build target files. This is so that builds
7621 will be guaranteed repeatable regardless of the environment
7622 variables set at the time scons is invoked.
7623 If you want to propagate your environment variables to the commands
7625 executed to build target files, you must do so explicitly:
7626 import os
7628 env = Environment(ENV=os.environ.copy())
7629 Note that you can choose only to propagate certain environment
7631 variables. A common example is the system PATH environment
7632 variable, so that scons uses the same utilities as the invoking
7633 shell (or other process):
7634 import os
7636 env = Environment(ENV={'PATH': os.environ['PATH']})
7637 ESCAPE
7639 A function that will be called to escape shell special characters
7640 in command lines. The function should take one argument: the
7641 command line string to escape; and should return the escaped
7642 command line.
7643 F03
7645 The Fortran 03 compiler. You should normally set the $FORTRAN
7646 variable, which specifies the default Fortran compiler for all
7647 Fortran versions. You only need to set $F03 if you need to use a
7648 specific compiler or compiler version for Fortran 03 files.
7649 F03COM
7651 The command line used to compile a Fortran 03 source file to an
7652 object file. You only need to set $F03COM if you need to use a
7653 specific command line for Fortran 03 files. You should normally set
7654 the $FORTRANCOM variable, which specifies the default command line
7655 for all Fortran versions.
7656 F03COMSTR
7658 If set, the string displayed when a Fortran 03 source file is
7659 compiled to an object file. If not set, then $F03COM or $FORTRANCOM
7660 (the command line) is displayed.
7661 F03FILESUFFIXES
7663 The list of file extensions for which the F03 dialect will be used.
7664 By default, this is ['.f03']
7665 F03FLAGS
7667 General user-specified options that are passed to the Fortran 03
7668 compiler. Note that this variable does not contain -I (or similar)
7669 include search path options that scons generates automatically from
7670 $F03PATH. See $_F03INCFLAGS below, for the variable that expands to
7671 those options. You only need to set $F03FLAGS if you need to define
7672 specific user options for Fortran 03 files. You should normally set
7673 the $FORTRANFLAGS variable, which specifies the user-specified
7674 options passed to the default Fortran compiler for all Fortran
7675 versions.
7676 _F03INCFLAGS
7678 An automatically-generated construction variable containing the
7679 Fortran 03 compiler command-line options for specifying directories
7680 to be searched for include files. The value of $_F03INCFLAGS is
7681 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7682 end of each directory in $F03PATH.
7683 F03PATH
7685 The list of directories that the Fortran 03 compiler will search
7686 for include directories. The implicit dependency scanner will
7687 search these directories for include files. Don't explicitly put
7688 include directory arguments in $F03FLAGS because the result will be
7689 non-portable and the directories will not be searched by the
7690 dependency scanner. Note: directory names in $F03PATH will be
7691 looked-up relative to the SConscript directory when they are used
7692 in a command. To force scons to look-up a directory relative to the
7693 root of the source tree use #: You only need to set $F03PATH if you
7694 need to define a specific include path for Fortran 03 files. You
7695 should normally set the $FORTRANPATH variable, which specifies the
7696 include path for the default Fortran compiler for all Fortran
7697 versions.
7698 env = Environment(F03PATH='#/include')
7700 The directory look-up can also be forced using the Dir() function:
7702 include = Dir('include')
7704 env = Environment(F03PATH=include)
7705 The directory list will be added to command lines through the
7707 automatically-generated $_F03INCFLAGS construction variable, which
7708 is constructed by appending the values of the $INCPREFIX and
7709 $INCSUFFIX construction variables to the beginning and end of each
7710 directory in $F03PATH. Any command lines you define that need the
7711 F03PATH directory list should include $_F03INCFLAGS:
7712 env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
7714 F03PPCOM
7716 The command line used to compile a Fortran 03 source file to an
7717 object file after first running the file through the C
7718 preprocessor. Any options specified in the $F03FLAGS and $CPPFLAGS
7719 construction variables are included on this command line. You only
7720 need to set $F03PPCOM if you need to use a specific C-preprocessor
7721 command line for Fortran 03 files. You should normally set the
7722 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7723 command line for all Fortran versions.
7724 F03PPCOMSTR
7726 If set, the string displayed when a Fortran 03 source file is
7727 compiled to an object file after first running the file through the
7728 C preprocessor. If not set, then $F03PPCOM or $FORTRANPPCOM (the
7729 command line) is displayed.
7730 F03PPFILESUFFIXES
7732 The list of file extensions for which the compilation +
7733 preprocessor pass for F03 dialect will be used. By default, this is
7734 empty.
7735 F08
7737 The Fortran 08 compiler. You should normally set the $FORTRAN
7738 variable, which specifies the default Fortran compiler for all
7739 Fortran versions. You only need to set $F08 if you need to use a
7740 specific compiler or compiler version for Fortran 08 files.
7741 F08COM
7743 The command line used to compile a Fortran 08 source file to an
7744 object file. You only need to set $F08COM if you need to use a
7745 specific command line for Fortran 08 files. You should normally set
7746 the $FORTRANCOM variable, which specifies the default command line
7747 for all Fortran versions.
7748 F08COMSTR
7750 If set, the string displayed when a Fortran 08 source file is
7751 compiled to an object file. If not set, then $F08COM or $FORTRANCOM
7752 (the command line) is displayed.
7753 F08FILESUFFIXES
7755 The list of file extensions for which the F08 dialect will be used.
7756 By default, this is ['.f08']
7757 F08FLAGS
7759 General user-specified options that are passed to the Fortran 08
7760 compiler. Note that this variable does not contain -I (or similar)
7761 include search path options that scons generates automatically from
7762 $F08PATH. See $_F08INCFLAGS below, for the variable that expands to
7763 those options. You only need to set $F08FLAGS if you need to define
7764 specific user options for Fortran 08 files. You should normally set
7765 the $FORTRANFLAGS variable, which specifies the user-specified
7766 options passed to the default Fortran compiler for all Fortran
7767 versions.
7768 _F08INCFLAGS
7770 An automatically-generated construction variable containing the
7771 Fortran 08 compiler command-line options for specifying directories
7772 to be searched for include files. The value of $_F08INCFLAGS is
7773 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7774 end of each directory in $F08PATH.
7775 F08PATH
7777 The list of directories that the Fortran 08 compiler will search
7778 for include directories. The implicit dependency scanner will
7779 search these directories for include files. Don't explicitly put
7780 include directory arguments in $F08FLAGS because the result will be
7781 non-portable and the directories will not be searched by the
7782 dependency scanner. Note: directory names in $F08PATH will be
7783 looked-up relative to the SConscript directory when they are used
7784 in a command. To force scons to look-up a directory relative to the
7785 root of the source tree use #: You only need to set $F08PATH if you
7786 need to define a specific include path for Fortran 08 files. You
7787 should normally set the $FORTRANPATH variable, which specifies the
7788 include path for the default Fortran compiler for all Fortran
7789 versions.
7790 env = Environment(F08PATH='#/include')
7792 The directory look-up can also be forced using the Dir() function:
7794 include = Dir('include')
7796 env = Environment(F08PATH=include)
7797 The directory list will be added to command lines through the
7799 automatically-generated $_F08INCFLAGS construction variable, which
7800 is constructed by appending the values of the $INCPREFIX and
7801 $INCSUFFIX construction variables to the beginning and end of each
7802 directory in $F08PATH. Any command lines you define that need the
7803 F08PATH directory list should include $_F08INCFLAGS:
7804 env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
7806 F08PPCOM
7808 The command line used to compile a Fortran 08 source file to an
7809 object file after first running the file through the C
7810 preprocessor. Any options specified in the $F08FLAGS and $CPPFLAGS
7811 construction variables are included on this command line. You only
7812 need to set $F08PPCOM if you need to use a specific C-preprocessor
7813 command line for Fortran 08 files. You should normally set the
7814 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7815 command line for all Fortran versions.
7816 F08PPCOMSTR
7818 If set, the string displayed when a Fortran 08 source file is
7819 compiled to an object file after first running the file through the
7820 C preprocessor. If not set, then $F08PPCOM or $FORTRANPPCOM (the
7821 command line) is displayed.
7822 F08PPFILESUFFIXES
7824 The list of file extensions for which the compilation +
7825 preprocessor pass for F08 dialect will be used. By default, this is
7826 empty.
7827 F77
7829 The Fortran 77 compiler. You should normally set the $FORTRAN
7830 variable, which specifies the default Fortran compiler for all
7831 Fortran versions. You only need to set $F77 if you need to use a
7832 specific compiler or compiler version for Fortran 77 files.
7833 F77COM
7835 The command line used to compile a Fortran 77 source file to an
7836 object file. You only need to set $F77COM if you need to use a
7837 specific command line for Fortran 77 files. You should normally set
7838 the $FORTRANCOM variable, which specifies the default command line
7839 for all Fortran versions.
7840 F77COMSTR
7842 If set, the string displayed when a Fortran 77 source file is
7843 compiled to an object file. If not set, then $F77COM or $FORTRANCOM
7844 (the command line) is displayed.
7845 F77FILESUFFIXES
7847 The list of file extensions for which the F77 dialect will be used.
7848 By default, this is ['.f77']
7849 F77FLAGS
7851 General user-specified options that are passed to the Fortran 77
7852 compiler. Note that this variable does not contain -I (or similar)
7853 include search path options that scons generates automatically from
7854 $F77PATH. See $_F77INCFLAGS below, for the variable that expands to
7855 those options. You only need to set $F77FLAGS if you need to define
7856 specific user options for Fortran 77 files. You should normally set
7857 the $FORTRANFLAGS variable, which specifies the user-specified
7858 options passed to the default Fortran compiler for all Fortran
7859 versions.
7860 _F77INCFLAGS
7862 An automatically-generated construction variable containing the
7863 Fortran 77 compiler command-line options for specifying directories
7864 to be searched for include files. The value of $_F77INCFLAGS is
7865 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7866 end of each directory in $F77PATH.
7867 F77PATH
7869 The list of directories that the Fortran 77 compiler will search
7870 for include directories. The implicit dependency scanner will
7871 search these directories for include files. Don't explicitly put
7872 include directory arguments in $F77FLAGS because the result will be
7873 non-portable and the directories will not be searched by the
7874 dependency scanner. Note: directory names in $F77PATH will be
7875 looked-up relative to the SConscript directory when they are used
7876 in a command. To force scons to look-up a directory relative to the
7877 root of the source tree use #: You only need to set $F77PATH if you
7878 need to define a specific include path for Fortran 77 files. You
7879 should normally set the $FORTRANPATH variable, which specifies the
7880 include path for the default Fortran compiler for all Fortran
7881 versions.
7882 env = Environment(F77PATH='#/include')
7884 The directory look-up can also be forced using the Dir() function:
7886 include = Dir('include')
7888 env = Environment(F77PATH=include)
7889 The directory list will be added to command lines through the
7891 automatically-generated $_F77INCFLAGS construction variable, which
7892 is constructed by appending the values of the $INCPREFIX and
7893 $INCSUFFIX construction variables to the beginning and end of each
7894 directory in $F77PATH. Any command lines you define that need the
7895 F77PATH directory list should include $_F77INCFLAGS:
7896 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
7898 F77PPCOM
7900 The command line used to compile a Fortran 77 source file to an
7901 object file after first running the file through the C
7902 preprocessor. Any options specified in the $F77FLAGS and $CPPFLAGS
7903 construction variables are included on this command line. You only
7904 need to set $F77PPCOM if you need to use a specific C-preprocessor
7905 command line for Fortran 77 files. You should normally set the
7906 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7907 command line for all Fortran versions.
7908 F77PPCOMSTR
7910 If set, the string displayed when a Fortran 77 source file is
7911 compiled to an object file after first running the file through the
7912 C preprocessor. If not set, then $F77PPCOM or $FORTRANPPCOM (the
7913 command line) is displayed.
7914 F77PPFILESUFFIXES
7916 The list of file extensions for which the compilation +
7917 preprocessor pass for F77 dialect will be used. By default, this is
7918 empty.
7919 F90
7921 The Fortran 90 compiler. You should normally set the $FORTRAN
7922 variable, which specifies the default Fortran compiler for all
7923 Fortran versions. You only need to set $F90 if you need to use a
7924 specific compiler or compiler version for Fortran 90 files.
7925 F90COM
7927 The command line used to compile a Fortran 90 source file to an
7928 object file. You only need to set $F90COM if you need to use a
7929 specific command line for Fortran 90 files. You should normally set
7930 the $FORTRANCOM variable, which specifies the default command line
7931 for all Fortran versions.
7932 F90COMSTR
7934 If set, the string displayed when a Fortran 90 source file is
7935 compiled to an object file. If not set, then $F90COM or $FORTRANCOM
7936 (the command line) is displayed.
7937 F90FILESUFFIXES
7939 The list of file extensions for which the F90 dialect will be used.
7940 By default, this is ['.f90']
7941 F90FLAGS
7943 General user-specified options that are passed to the Fortran 90
7944 compiler. Note that this variable does not contain -I (or similar)
7945 include search path options that scons generates automatically from
7946 $F90PATH. See $_F90INCFLAGS below, for the variable that expands to
7947 those options. You only need to set $F90FLAGS if you need to define
7948 specific user options for Fortran 90 files. You should normally set
7949 the $FORTRANFLAGS variable, which specifies the user-specified
7950 options passed to the default Fortran compiler for all Fortran
7951 versions.
7952 _F90INCFLAGS
7954 An automatically-generated construction variable containing the
7955 Fortran 90 compiler command-line options for specifying directories
7956 to be searched for include files. The value of $_F90INCFLAGS is
7957 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7958 end of each directory in $F90PATH.
7959 F90PATH
7961 The list of directories that the Fortran 90 compiler will search
7962 for include directories. The implicit dependency scanner will
7963 search these directories for include files. Don't explicitly put
7964 include directory arguments in $F90FLAGS because the result will be
7965 non-portable and the directories will not be searched by the
7966 dependency scanner. Note: directory names in $F90PATH will be
7967 looked-up relative to the SConscript directory when they are used
7968 in a command. To force scons to look-up a directory relative to the
7969 root of the source tree use #: You only need to set $F90PATH if you
7970 need to define a specific include path for Fortran 90 files. You
7971 should normally set the $FORTRANPATH variable, which specifies the
7972 include path for the default Fortran compiler for all Fortran
7973 versions.
7974 env = Environment(F90PATH='#/include')
7976 The directory look-up can also be forced using the Dir() function:
7978 include = Dir('include')
7980 env = Environment(F90PATH=include)
7981 The directory list will be added to command lines through the
7983 automatically-generated $_F90INCFLAGS construction variable, which
7984 is constructed by appending the values of the $INCPREFIX and
7985 $INCSUFFIX construction variables to the beginning and end of each
7986 directory in $F90PATH. Any command lines you define that need the
7987 F90PATH directory list should include $_F90INCFLAGS:
7988 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
7990 F90PPCOM
7992 The command line used to compile a Fortran 90 source file to an
7993 object file after first running the file through the C
7994 preprocessor. Any options specified in the $F90FLAGS and $CPPFLAGS
7995 construction variables are included on this command line. You only
7996 need to set $F90PPCOM if you need to use a specific C-preprocessor
7997 command line for Fortran 90 files. You should normally set the
7998 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7999 command line for all Fortran versions.
8000 F90PPCOMSTR
8002 If set, the string displayed when a Fortran 90 source file is
8003 compiled after first running the file through the C preprocessor.
8004 If not set, then $F90PPCOM or $FORTRANPPCOM (the command line) is
8005 displayed.
8006 F90PPFILESUFFIXES
8008 The list of file extensions for which the compilation +
8009 preprocessor pass for F90 dialect will be used. By default, this is
8010 empty.
8011 F95
8013 The Fortran 95 compiler. You should normally set the $FORTRAN
8014 variable, which specifies the default Fortran compiler for all
8015 Fortran versions. You only need to set $F95 if you need to use a
8016 specific compiler or compiler version for Fortran 95 files.
8017 F95COM
8019 The command line used to compile a Fortran 95 source file to an
8020 object file. You only need to set $F95COM if you need to use a
8021 specific command line for Fortran 95 files. You should normally set
8022 the $FORTRANCOM variable, which specifies the default command line
8023 for all Fortran versions.
8024 F95COMSTR
8026 If set, the string displayed when a Fortran 95 source file is
8027 compiled to an object file. If not set, then $F95COM or $FORTRANCOM
8028 (the command line) is displayed.
8029 F95FILESUFFIXES
8031 The list of file extensions for which the F95 dialect will be used.
8032 By default, this is ['.f95']
8033 F95FLAGS
8035 General user-specified options that are passed to the Fortran 95
8036 compiler. Note that this variable does not contain -I (or similar)
8037 include search path options that scons generates automatically from
8038 $F95PATH. See $_F95INCFLAGS below, for the variable that expands to
8039 those options. You only need to set $F95FLAGS if you need to define
8040 specific user options for Fortran 95 files. You should normally set
8041 the $FORTRANFLAGS variable, which specifies the user-specified
8042 options passed to the default Fortran compiler for all Fortran
8043 versions.
8044 _F95INCFLAGS
8046 An automatically-generated construction variable containing the
8047 Fortran 95 compiler command-line options for specifying directories
8048 to be searched for include files. The value of $_F95INCFLAGS is
8049 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
8050 end of each directory in $F95PATH.
8051 F95PATH
8053 The list of directories that the Fortran 95 compiler will search
8054 for include directories. The implicit dependency scanner will
8055 search these directories for include files. Don't explicitly put
8056 include directory arguments in $F95FLAGS because the result will be
8057 non-portable and the directories will not be searched by the
8058 dependency scanner. Note: directory names in $F95PATH will be
8059 looked-up relative to the SConscript directory when they are used
8060 in a command. To force scons to look-up a directory relative to the
8061 root of the source tree use #: You only need to set $F95PATH if you
8062 need to define a specific include path for Fortran 95 files. You
8063 should normally set the $FORTRANPATH variable, which specifies the
8064 include path for the default Fortran compiler for all Fortran
8065 versions.
8066 env = Environment(F95PATH='#/include')
8068 The directory look-up can also be forced using the Dir() function:
8070 include = Dir('include')
8072 env = Environment(F95PATH=include)
8073 The directory list will be added to command lines through the
8075 automatically-generated $_F95INCFLAGS construction variable, which
8076 is constructed by appending the values of the $INCPREFIX and
8077 $INCSUFFIX construction variables to the beginning and end of each
8078 directory in $F95PATH. Any command lines you define that need the
8079 F95PATH directory list should include $_F95INCFLAGS:
8080 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
8082 F95PPCOM
8084 The command line used to compile a Fortran 95 source file to an
8085 object file after first running the file through the C
8086 preprocessor. Any options specified in the $F95FLAGS and $CPPFLAGS
8087 construction variables are included on this command line. You only
8088 need to set $F95PPCOM if you need to use a specific C-preprocessor
8089 command line for Fortran 95 files. You should normally set the
8090 $FORTRANPPCOM variable, which specifies the default C-preprocessor
8091 command line for all Fortran versions.
8092 F95PPCOMSTR
8094 If set, the string displayed when a Fortran 95 source file is
8095 compiled to an object file after first running the file through the
8096 C preprocessor. If not set, then $F95PPCOM or $FORTRANPPCOM (the
8097 command line) is displayed.
8098 F95PPFILESUFFIXES
8100 The list of file extensions for which the compilation +
8101 preprocessor pass for F95 dialect will be used. By default, this is
8102 empty.
8103 File
8105 A function that converts a string into a File instance relative to
8106 the target being built.
8107 FORTRAN
8109 The default Fortran compiler for all versions of Fortran.
8110 FORTRANCOM
8112 The command line used to compile a Fortran source file to an object
8113 file. By default, any options specified in the $FORTRANFLAGS,
8114 $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
8115 construction variables are included on this command line.
8116 FORTRANCOMSTR
8118 If set, the string displayed when a Fortran source file is compiled
8119 to an object file. If not set, then $FORTRANCOM (the command line)
8120 is displayed.
8121 FORTRANFILESUFFIXES
8123 The list of file extensions for which the FORTRAN dialect will be
8124 used. By default, this is ['.f', '.for', '.ftn']
8125 FORTRANFLAGS
8127 General user-specified options that are passed to the Fortran
8128 compiler. Note that this variable does not contain -I (or similar)
8129 include or module search path options that scons generates
8130 automatically from $FORTRANPATH. See $_FORTRANINCFLAGS and
8131 $_FORTRANMODFLAG, below, for the variables that expand those
8132 options.
8133 _FORTRANINCFLAGS
8135 An automatically-generated construction variable containing the
8136 Fortran compiler command-line options for specifying directories to
8137 be searched for include files and module files. The value of
8138 $_FORTRANINCFLAGS is created by respectively prepending and
8139 appending $INCPREFIX and $INCSUFFIX to the beginning and end of
8140 each directory in $FORTRANPATH.
8141 FORTRANMODDIR
8143 Directory location where the Fortran compiler should place any
8144 module files it generates. This variable is empty, by default. Some
8145 Fortran compilers will internally append this directory in the
8146 search path for module files, as well.
8147 FORTRANMODDIRPREFIX
8149 The prefix used to specify a module directory on the Fortran
8150 compiler command line. This will be prepended to the beginning of
8151 the directory in the $FORTRANMODDIR construction variables when the
8152 $_FORTRANMODFLAG variables is automatically generated.
8153 FORTRANMODDIRSUFFIX
8155 The suffix used to specify a module directory on the Fortran
8156 compiler command line. This will be appended to the end of the
8157 directory in the $FORTRANMODDIR construction variables when the
8158 $_FORTRANMODFLAG variables is automatically generated.
8159 _FORTRANMODFLAG
8161 An automatically-generated construction variable containing the
8162 Fortran compiler command-line option for specifying the directory
8163 location where the Fortran compiler should place any module files
8164 that happen to get generated during compilation. The value of
8165 $_FORTRANMODFLAG is created by respectively prepending and
8166 appending $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the
8167 beginning and end of the directory in $FORTRANMODDIR.
8168 FORTRANMODPREFIX
8170 The module file prefix used by the Fortran compiler. SCons assumes
8171 that the Fortran compiler follows the quasi-standard naming
8172 convention for module files of module_name.mod. As a result, this
8173 variable is left empty, by default. For situations in which the
8174 compiler does not necessarily follow the normal convention, the
8175 user may use this variable. Its value will be appended to every
8176 module file name as scons attempts to resolve dependencies.
8177 FORTRANMODSUFFIX
8179 The module file suffix used by the Fortran compiler. SCons assumes
8180 that the Fortran compiler follows the quasi-standard naming
8181 convention for module files of module_name.mod. As a result, this
8182 variable is set to ".mod", by default. For situations in which the
8183 compiler does not necessarily follow the normal convention, the
8184 user may use this variable. Its value will be appended to every
8185 module file name as scons attempts to resolve dependencies.
8186 FORTRANPATH
8188 The list of directories that the Fortran compiler will search for
8189 include files and (for some compilers) module files. The Fortran
8190 implicit dependency scanner will search these directories for
8191 include files (but not module files since they are autogenerated
8192 and, as such, may not actually exist at the time the scan takes
8193 place). Don't explicitly put include directory arguments in
8194 FORTRANFLAGS because the result will be non-portable and the
8195 directories will not be searched by the dependency scanner. Note:
8196 directory names in FORTRANPATH will be looked-up relative to the
8197 SConscript directory when they are used in a command. To force
8198 scons to look-up a directory relative to the root of the source
8199 tree use #:
8200 env = Environment(FORTRANPATH='#/include')
8202 The directory look-up can also be forced using the Dir() function:
8204 include = Dir('include')
8206 env = Environment(FORTRANPATH=include)
8207 The directory list will be added to command lines through the
8209 automatically-generated $_FORTRANINCFLAGS construction variable,
8210 which is constructed by respectively prepending and appending the
8211 values of the $INCPREFIX and $INCSUFFIX construction variables to
8212 the beginning and end of each directory in $FORTRANPATH. Any
8213 command lines you define that need the FORTRANPATH directory list
8214 should include $_FORTRANINCFLAGS:
8215 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
8217 FORTRANPPCOM
8219 The command line used to compile a Fortran source file to an object
8220 file after first running the file through the C preprocessor. By
8221 default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
8222 $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction
8223 variables are included on this command line.
8224 FORTRANPPCOMSTR
8226 If set, the string displayed when a Fortran source file is compiled
8227 to an object file after first running the file through the C
8228 preprocessor. If not set, then $FORTRANPPCOM (the command line) is
8229 displayed.
8230 FORTRANPPFILESUFFIXES
8232 The list of file extensions for which the compilation +
8233 preprocessor pass for FORTRAN dialect will be used. By default,
8234 this is ['.fpp', '.FPP']
8235 FORTRANSUFFIXES
8237 The list of suffixes of files that will be scanned for Fortran
8238 implicit dependencies (INCLUDE lines and USE statements). The
8239 default list is:
8240 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
8242 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
8243 FRAMEWORKPATH
8245 On Mac OS X with gcc, a list containing the paths to search for
8246 frameworks. Used by the compiler to find framework-style includes
8247 like #include <Fmwk/Header.h>. Used by the linker to find
8248 user-specified frameworks when linking (see $FRAMEWORKS). For
8249 example:
8250 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
8252 will add
8255 ... -Fmyframeworkdir
8257 to the compiler and linker command lines.
8260 _FRAMEWORKPATH
8262 On Mac OS X with gcc, an automatically-generated construction
8263 variable containing the linker command-line options corresponding
8264 to $FRAMEWORKPATH.
8265 FRAMEWORKPATHPREFIX
8267 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH
8268 entries. (see $FRAMEWORKPATH). The default value is -F.
8269 FRAMEWORKPREFIX
8271 On Mac OS X with gcc, the prefix to be used for linking in
8272 frameworks (see $FRAMEWORKS). The default value is -framework.
8273 FRAMEWORKS
8275 On Mac OS X with gcc, a list of the framework names to be linked
8276 into a program or shared library or bundle. The default value is
8277 the empty list. For example:
8278 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
8280 _FRAMEWORKS
8283 On Mac OS X with gcc, an automatically-generated construction
8284 variable containing the linker command-line options for linking
8285 with FRAMEWORKS.
8286 FRAMEWORKSFLAGS
8288 On Mac OS X with gcc, general user-supplied frameworks options to
8289 be added at the end of a command line building a loadable module.
8290 (This has been largely superseded by the $FRAMEWORKPATH,
8291 $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS variables
8292 described above.)
8293 GS
8295 The Ghostscript program used to, for example, convert PostScript to
8296 PDF files.
8297 GSCOM
8299 The full Ghostscript command line used for the conversion process.
8300 Its default value is “$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES”.
8301 GSCOMSTR
8303 The string displayed when Ghostscript is called for the conversion
8304 process. If this is not set (the default), then $GSCOM (the command
8305 line) is displayed.
8306 GSFLAGS
8308 General options passed to the Ghostscript program, when converting
8309 PostScript to PDF files for example. Its default value is
8310 “-dNOPAUSE -dBATCH -sDEVICE=pdfwrite”
8311 HOST_ARCH
8313 The name of the host hardware architecture used to create this
8314 construction environment. The platform code sets this when
8315 initializing (see $PLATFORM and the platform argument to
8316 Environment). Note the detected name of the architecture may not be
8317 identical to that returned by the Python platform.machine method.
8318 On the win32 platform, if the Microsoft Visual C++ compiler is
8320 available, msvc tool setup is done using $HOST_ARCH and
8321 $TARGET_ARCH. Changing the values at any later time will not cause
8322 the tool to be reinitialized. Valid host arch values are x86 and
8323 arm for 32-bit hosts and amd64 and x86_64 for 64-bit hosts.
8324 Should be considered immutable. $HOST_ARCH is not currently used
8326 by other platforms, but the option is reserved to do so in future
8327 HOST_OS
8329 The name of the host operating system for the platform used to
8330 create this construction environment. The platform code sets this
8331 when initializing (see $PLATFORM and the platform argument to
8332 Environment).
8333 Should be considered immutable. $HOST_OS is not currently used by
8335 SCons, but the option is reserved to do so in future
8336 IDLSUFFIXES
8338 The list of suffixes of files that will be scanned for IDL implicit
8339 dependencies (#include or import lines). The default list is:
8340 [".idl", ".IDL"]
8342 IMPLIBNOVERSIONSYMLINKS
8344 Used to override $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS
8345 when creating versioned import library for a shared
8346 library/loadable module. If not defined, then
8347 $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS is used to
8348 determine whether to disable symlink generation or not.
8349 IMPLIBPREFIX
8351 The prefix used for import library names. For example, cygwin uses
8352 import libraries (libfoo.dll.a) in pair with dynamic libraries
8353 (cygfoo.dll). The cyglink linker sets $IMPLIBPREFIX to 'lib' and
8354 $SHLIBPREFIX to 'cyg'.
8355 IMPLIBSUFFIX
8357 The suffix used for import library names. For example, cygwin uses
8358 import libraries (libfoo.dll.a) in pair with dynamic libraries
8359 (cygfoo.dll). The cyglink linker sets $IMPLIBSUFFIX to '.dll.a' and
8360 $SHLIBSUFFIX to '.dll'.
8361 IMPLIBVERSION
8363 Used to override $SHLIBVERSION/$LDMODULEVERSION when generating
8364 versioned import library for a shared library/loadable module. If
8365 undefined, the $SHLIBVERSION/$LDMODULEVERSION is used to determine
8366 the version of versioned import library.
8367 IMPLICIT_COMMAND_DEPENDENCIES
8369 Controls whether or not SCons will add implicit dependencies for
8370 the commands executed to build targets.
8371 By default, SCons will add to each target an implicit dependency on
8373 the command represented by the first argument of any command line
8374 it executes (which is typically the command itself). By setting
8375 such a dependency, SCons can determine that a target should be
8376 rebuilt if the command changes, such as when a compiler is upgraded
8377 to a new version. The specific file for the dependency is found by
8378 searching the PATH variable in the ENV dictionary in the
8379 construction environment used to execute the command. The default
8380 is the same as setting the construction variable
8381 $IMPLICIT_COMMAND_DEPENDENCIES to a True-like value (“true”, “yes”,
8382 or “1” - but not a number greater than one, as that has a different
8383 meaning).
8384 Action strings can be segmented by the use of an AND operator, &&.
8386 In a segemented string, each segment is a separate “command line”,
8387 these are run sequentially until one fails or the entire sequence
8388 has been executed. If an action string is segmented, then the
8389 selected behavior of $IMPLICIT_COMMAND_DEPENDENCIES is applied to
8390 each segment.
8391 If $IMPLICIT_COMMAND_DEPENDENCIES is set to a False-like value
8393 (“none”, “false”, “no”, “0”, etc.), then the implicit dependency
8394 will not be added to the targets built with that construction
8395 environment.
8396 If $IMPLICIT_COMMAND_DEPENDENCIES is set to “2” or higher, then
8398 that number of arguments in the command line will be scanned for
8399 relative or absolute paths. If any are present, they will be added
8400 as implicit dependencies to the targets built with that
8401 construction environment. The first argument in the command line
8402 will be searched for using the PATH variable in the ENV dictionary
8403 in the construction environment used to execute the command. The
8404 other arguments will only be found if they are absolute paths or
8405 valid paths relative to the working directory.
8406 If $IMPLICIT_COMMAND_DEPENDENCIES is set to “all”, then all
8408 arguments in the command line will be scanned for relative or
8409 absolute paths. If any are present, they will be added as implicit
8410 dependencies to the targets built with that construction
8411 environment. The first argument in the command line will be
8412 searched for using the PATH variable in the ENV dictionary in the
8413 construction environment used to execute the command. The other
8414 arguments will only be found if they are absolute paths or valid
8415 paths relative to the working directory.
8416 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES=False)
8418 INCPREFIX
8420 The prefix used to specify an include directory on the C compiler
8421 command line. This will be prepended to each directory in the
8422 $CPPPATH and $FORTRANPATH construction variables when the
8423 $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically
8424 generated.
8425 INCSUFFIX
8427 The suffix used to specify an include directory on the C compiler
8428 command line. This will be appended to each directory in the
8429 $CPPPATH and $FORTRANPATH construction variables when the
8430 $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically
8431 generated.
8432 INSTALL
8434 A function to be called to install a file into a destination file
8435 name. The default function copies the file into the destination
8436 (and sets the destination file's mode and permission bits to match
8437 the source file's). The function takes the following arguments:
8438 def install(dest, source, env):
8440 dest is the path name of the destination file. source is the path
8443 name of the source file. env is the construction environment (a
8444 dictionary of construction values) in force for this file
8445 installation.
8446 INSTALLSTR
8448 The string displayed when a file is installed into a destination
8449 file name. The default is:
8450 Install file: "$SOURCE" as "$TARGET"
8452 INTEL_C_COMPILER_VERSION
8454 Set by the intelc Tool to the major version number of the Intel C
8455 compiler selected for use.
8456 JAR
8458 The Java archive tool.
8459 JARCHDIR
8461 The directory to which the Java archive tool should change (using
8462 the -C option).
8463 JARCOM
8465 The command line used to call the Java archive tool.
8466 JARCOMSTR
8468 The string displayed when the Java archive tool is called If this
8469 is not set, then $JARCOM (the command line) is displayed.
8470 env = Environment(JARCOMSTR="JARchiving $SOURCES into $TARGET")
8472 JARFLAGS
8474 General options passed to the Java archive tool. By default this is
8475 set to cf to create the necessary jar file.
8476 JARSUFFIX
8478 The suffix for Java archives: .jar by default.
8479 JAVABOOTCLASSPATH
8481 Specifies the list of directories that will be added to the javac
8482 command line via the -bootclasspath option. The individual
8483 directory names will be separated by the operating system's path
8484 separate character (: on UNIX/Linux/POSIX, ; on Windows).
8485 JAVAC
8487 The Java compiler.
8488 JAVACCOM
8490 The command line used to compile a directory tree containing Java
8491 source files to corresponding Java class files. Any options
8492 specified in the $JAVACFLAGS construction variable are included on
8493 this command line.
8494 JAVACCOMSTR
8496 The string displayed when compiling a directory tree of Java source
8497 files to corresponding Java class files. If this is not set, then
8498 $JAVACCOM (the command line) is displayed.
8499 env = Environment(JAVACCOMSTR="Compiling class files $TARGETS from $SOURCES")
8501 JAVACFLAGS
8504 General options that are passed to the Java compiler.
8505 JAVACLASSDIR
8507 The directory in which Java class files may be found. This is
8508 stripped from the beginning of any Java .class file names supplied
8509 to the JavaH builder.
8510 JAVACLASSPATH
8512 Specifies the list of directories that will be searched for Java
8513 .class file. The directories in this list will be added to the
8514 javac and javah command lines via the -classpath option. The
8515 individual directory names will be separated by the operating
8516 system's path separate character (: on UNIX/Linux/POSIX, ; on
8517 Windows).
8518 Note that this currently just adds the specified directory via the
8520 -classpath option. SCons does not currently search the
8521 $JAVACLASSPATH directories for dependency .class files.
8522 JAVACLASSSUFFIX
8524 The suffix for Java class files; .class by default.
8525 JAVAH
8527 The Java generator for C header and stub files.
8528 JAVAHCOM
8530 The command line used to generate C header and stub files from Java
8531 classes. Any options specified in the $JAVAHFLAGS construction
8532 variable are included on this command line.
8533 JAVAHCOMSTR
8535 The string displayed when C header and stub files are generated
8536 from Java classes. If this is not set, then $JAVAHCOM (the command
8537 line) is displayed.
8538 env = Environment(JAVAHCOMSTR="Generating header/stub file(s) $TARGETS from $SOURCES")
8540 JAVAHFLAGS
8542 General options passed to the C header and stub file generator for
8543 Java classes.
8544 JAVAINCLUDES
8546 Include path for Java header files (such as jni.h)
8547 JAVASOURCEPATH
8549 Specifies the list of directories that will be searched for input
8550 .java file. The directories in this list will be added to the javac
8551 command line via the -sourcepath option. The individual directory
8552 names will be separated by the operating system's path separate
8553 character (: on UNIX/Linux/POSIX, ; on Windows).
8554 Note that this currently just adds the specified directory via the
8556 -sourcepath option. SCons does not currently search the
8557 $JAVASOURCEPATH directories for dependency .java files.
8558 JAVASUFFIX
8560 The suffix for Java files; .java by default.
8561 JAVAVERSION
8563 Specifies the Java version being used by the Java builder. Set this
8564 to specify the version of Java targeted by the javac compiler. This
8565 is sometimes necessary because Java 1.5 changed the file names that
8566 are created for nested anonymous inner classes, which can cause a
8567 mismatch with the files that SCons expects will be generated by the
8568 javac compiler. Setting $JAVAVERSION to a version greater than 1.4
8569 makes SCons realize that a build with such a compiler is actually
8570 up to date. The default is 1.4.
8571 While this is not primarily intended for selecting one version of
8573 the Java compiler vs. another, it does have that effect on the
8574 Windows platform. A more precise approach is to set $JAVAC (and
8575 related construction variables for related utilities) to the path
8576 to the specific Java compiler you want, if that is not the default
8577 compiler. On non-Windows platforms, the alternatives system may
8578 provide a way to adjust the default Java compiler without having to
8579 specify explicit paths.
8580 LATEX
8582 The LaTeX structured formatter and typesetter.
8583 LATEXCOM
8585 The command line used to call the LaTeX structured formatter and
8586 typesetter.
8587 LATEXCOMSTR
8589 The string displayed when calling the LaTeX structured formatter
8590 and typesetter. If this is not set, then $LATEXCOM (the command
8591 line) is displayed.
8592 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
8594 LATEXFLAGS
8596 General options passed to the LaTeX structured formatter and
8597 typesetter.
8598 LATEXRETRIES
8600 The maximum number of times that LaTeX will be re-run if the .log
8601 generated by the $LATEXCOM command indicates that there are
8602 undefined references. The default is to try to resolve undefined
8603 references by re-running LaTeX up to three times.
8604 LATEXSUFFIXES
8606 The list of suffixes of files that will be scanned for LaTeX
8607 implicit dependencies (\include or \import files). The default list
8608 is:
8609 [".tex", ".ltx", ".latex"]
8611 LDMODULE
8613 The linker for building loadable modules. By default, this is the
8614 same as $SHLINK.
8615 LDMODULECOM
8617 The command line for building loadable modules. On Mac OS X, this
8618 uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
8619 On other systems, this is the same as $SHLINK.
8620 LDMODULECOMSTR
8622 If set, the string displayed when building loadable modules. If not
8623 set, then $LDMODULECOM (the command line) is displayed.
8624 LDMODULEEMITTER
8626 Contains the emitter specification for the LoadableModule builder.
8627 The manpage section "Builder Objects" contains general information
8628 on specifying emitters.
8629 LDMODULEFLAGS
8631 General user options passed to the linker for building loadable
8632 modules.
8633 LDMODULENOVERSIONSYMLINKS
8635 Instructs the LoadableModule builder to not automatically create
8636 symlinks for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS
8637 LDMODULEPREFIX
8639 The prefix used for loadable module file names. On Mac OS X, this
8640 is null; on other systems, this is the same as $SHLIBPREFIX.
8641 _LDMODULESONAME
8643 A macro that automatically generates loadable module's SONAME based
8644 on $TARGET, $LDMODULEVERSION and $LDMODULESUFFIX. Used by
8645 LoadableModule builder when the linker tool supports SONAME (e.g.
8646 gnulink).
8647 LDMODULESUFFIX
8649 The suffix used for loadable module file names. On Mac OS X, this
8650 is null; on other systems, this is the same as $SHLIBSUFFIX.
8651 LDMODULEVERSION
8653 When this construction variable is defined, a versioned loadable
8654 module is created by LoadableModule builder. This activates the
8655 $_LDMODULEVERSIONFLAGS and thus modifies the $LDMODULECOM as
8656 required, adds the version number to the library name, and creates
8657 the symlinks that are needed. $LDMODULEVERSION versions should
8658 exist in the same format as $SHLIBVERSION.
8659 _LDMODULEVERSIONFLAGS
8661 This macro automatically introduces extra flags to $LDMODULECOM
8662 when building versioned LoadableModule (that is when
8663 $LDMODULEVERSION is set). _LDMODULEVERSIONFLAGS usually adds
8664 $SHLIBVERSIONFLAGS and some extra dynamically generated options
8665 (such as -Wl,-soname=$_LDMODULESONAME). It is unused by plain
8666 (unversioned) loadable modules.
8667 LDMODULEVERSIONFLAGS
8669 Extra flags added to $LDMODULECOM when building versioned
8670 LoadableModule. These flags are only used when $LDMODULEVERSION is
8671 set.
8672 LEX
8674 The lexical analyzer generator.
8675 LEXCOM
8677 The command line used to call the lexical analyzer generator to
8678 generate a source file.
8679 LEXCOMSTR
8681 The string displayed when generating a source file using the
8682 lexical analyzer generator. If this is not set, then $LEXCOM (the
8683 command line) is displayed.
8684 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
8686 LEXFLAGS
8688 General options passed to the lexical analyzer generator.
8689 LEXUNISTD
8691 Used only on windows environments to set a lex flag to prevent
8692 'unistd.h' from being included. The default value is '--nounistd'.
8693 _LIBDIRFLAGS
8695 An automatically-generated construction variable containing the
8696 linker command-line options for specifying directories to be
8697 searched for library. The value of $_LIBDIRFLAGS is created by
8698 respectively prepending and appending $LIBDIRPREFIX and
8699 $LIBDIRSUFFIX to each directory in $LIBPATH.
8700 LIBDIRPREFIX
8702 The prefix used to specify a library directory on the linker
8703 command line. This will be prepended to each directory in the
8704 $LIBPATH construction variable when the $_LIBDIRFLAGS variable is
8705 automatically generated.
8706 LIBDIRSUFFIX
8708 The suffix used to specify a library directory on the linker
8709 command line. This will be appended to each directory in the
8710 $LIBPATH construction variable when the $_LIBDIRFLAGS variable is
8711 automatically generated.
8712 LIBEMITTER
8714 Contains the emitter specification for the StaticLibrary builder.
8715 The manpage section "Builder Objects" contains general information
8716 on specifying emitters.
8717 _LIBFLAGS
8719 An automatically-generated construction variable containing the
8720 linker command-line options for specifying libraries to be linked
8721 with the resulting target. The value of $_LIBFLAGS is created by
8722 respectively prepending and appending $LIBLINKPREFIX and
8723 $LIBLINKSUFFIX to each filename in $LIBS.
8724 LIBLINKPREFIX
8726 The prefix used to specify a library to link on the linker command
8727 line. This will be prepended to each library in the $LIBS
8728 construction variable when the $_LIBFLAGS variable is automatically
8729 generated.
8730 LIBLINKSUFFIX
8732 The suffix used to specify a library to link on the linker command
8733 line. This will be appended to each library in the $LIBS
8734 construction variable when the $_LIBFLAGS variable is automatically
8735 generated.
8736 LIBPATH
8738 The list of directories that will be searched for libraries
8739 specified by the $LIBS construction variable. $LIBPATH should be a
8740 list of path strings, or a single string, not a pathname list
8741 joined by Python's os.sep.
8742 Do not put library search directives directly into $LINKFLAGS or
8744 $SHLINKFLAGS as the result will be non-portable.
8745 Note: directory names in $LIBPATH will be looked-up relative to the
8747 directory of the SConscript file when they are used in a command.
8748 To force scons to look-up a directory relative to the root of the
8749 source tree use the # prefix:
8750 env = Environment(LIBPATH='#/libs')
8752 The directory look-up can also be forced using the Dir function:
8754 libs = Dir('libs')
8756 env = Environment(LIBPATH=libs)
8757 The directory list will be added to command lines through the
8759 automatically-generated $_LIBDIRFLAGS construction variable, which
8760 is constructed by respectively prepending and appending the values
8761 of the $LIBDIRPREFIX and $LIBDIRSUFFIX construction variables to
8762 each directory in $LIBPATH. Any command lines you define that need
8763 the $LIBPATH directory list should include $_LIBDIRFLAGS:
8764 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8766 LIBPREFIX
8768 The prefix used for (static) library file names. A default value is
8769 set for each platform (posix, win32, os2, etc.), but the value is
8770 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8771 etc.) to reflect the names of the libraries they create.
8772 LIBPREFIXES
8774 A list of all legal prefixes for library file names. When searching
8775 for library dependencies, SCons will look for files with these
8776 prefixes, the base library name, and suffixes from the $LIBSUFFIXES
8777 list.
8778 LIBS
8780 A list of one or more libraries that will be added to the link line
8781 for linking with any executable program, shared library, or
8782 loadable module created by the construction environment or
8783 override.
8784 String-valued library names should include only the library base
8786 names, without prefixes such as lib or suffixes such as .so or
8787 .dll. The library list will be added to command lines through the
8788 automatically-generated $_LIBFLAGS construction variable which is
8789 constructed by respectively prepending and appending the values of
8790 the $LIBLINKPREFIX and $LIBLINKSUFFIX construction variables to
8791 each library name in $LIBS. Library name strings should not include
8792 a path component, instead the compiler will be directed to look for
8793 libraries in the paths specified by $LIBPATH.
8794 Any command lines you define that need the $LIBS library list
8796 should include $_LIBFLAGS:
8797 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8799 If you add a File object to the $LIBS list, the name of that file
8801 will be added to $_LIBFLAGS, and thus to the link line, as-is,
8802 without $LIBLINKPREFIX or $LIBLINKSUFFIX. For example:
8803 env.Append(LIBS=File('/tmp/mylib.so'))
8805 In all cases, scons will add dependencies from the executable
8807 program to all the libraries in this list.
8808 LIBSUFFIX
8810 The suffix used for (static) library file names. A default value is
8811 set for each platform (posix, win32, os2, etc.), but the value is
8812 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8813 etc.) to reflect the names of the libraries they create.
8814 LIBSUFFIXES
8816 A list of all legal suffixes for library file names. When searching
8817 for library dependencies, SCons will look for files with prefixes
8818 from the $LIBPREFIXES list, the base library name, and these
8819 suffixes.
8820 LICENSE
8822 The abbreviated name, preferably the SPDX code, of the license
8823 under which this project is released (GPL-3.0, LGPL-2.1,
8824 BSD-2-Clause etc.). See
8825 http://www.opensource.org/licenses/alphabetical[6] for a list of
8826 license names and SPDX codes.
8827 See the Package builder.
8829 LINESEPARATOR
8831 The separator used by the Substfile and Textfile builders. This
8832 value is used between sources when constructing the target. It
8833 defaults to the current system line separator.
8834 LINGUAS_FILE
8836 The $LINGUAS_FILE defines file(s) containing list of additional
8837 linguas to be processed by POInit, POUpdate or MOFiles builders. It
8838 also affects Translate builder. If the variable contains a string,
8839 it defines name of the list file. The $LINGUAS_FILE may be a list
8840 of file names as well. If $LINGUAS_FILE is set to True (or non-zero
8841 numeric value), the list will be read from default file named
8842 LINGUAS.
8843 LINK
8845 The linker. See also $SHLINK for linking shared objects.
8846 On POSIX systems (those using the link tool), you should normally
8848 not change this value as it defaults to a "smart" linker tool which
8849 selects a compiler driver matching the type of source files in use.
8850 So for example, if you set $CXX to a specific compiler name, and
8851 are compiling C++ sources, the smartlink function will
8852 automatically select the same compiler for linking.
8853 LINKCOM
8855 The command line used to link object files into an executable. See
8856 also $SHLINKCOM for linking shared objects.
8857 LINKCOMSTR
8859 If set, the string displayed when object files are linked into an
8860 executable. If not set, then $LINKCOM (the command line) is
8861 displayed. See also $SHLINKCOMSTR. for linking shared objects.
8862 env = Environment(LINKCOMSTR = "Linking $TARGET")
8864 LINKFLAGS
8866 General user options passed to the linker. Note that this variable
8867 should not contain -l (or similar) options for linking with the
8868 libraries listed in $LIBS, nor -L (or similar) library search path
8869 options that scons generates automatically from $LIBPATH. See
8870 $_LIBFLAGS above, for the variable that expands to library-link
8871 options, and $_LIBDIRFLAGS above, for the variable that expands to
8872 library search path options. See also $SHLINKFLAGS. for linking
8873 shared objects.
8874 M4
8876 The M4 macro preprocessor.
8877 M4COM
8879 The command line used to pass files through the M4 macro
8880 preprocessor.
8881 M4COMSTR
8883 The string displayed when a file is passed through the M4 macro
8884 preprocessor. If this is not set, then $M4COM (the command line) is
8885 displayed.
8886 M4FLAGS
8888 General options passed to the M4 macro preprocessor.
8889 MAKEINDEX
8891 The makeindex generator for the TeX formatter and typesetter and
8892 the LaTeX structured formatter and typesetter.
8893 MAKEINDEXCOM
8895 The command line used to call the makeindex generator for the TeX
8896 formatter and typesetter and the LaTeX structured formatter and
8897 typesetter.
8898 MAKEINDEXCOMSTR
8900 The string displayed when calling the makeindex generator for the
8901 TeX formatter and typesetter and the LaTeX structured formatter and
8902 typesetter. If this is not set, then $MAKEINDEXCOM (the command
8903 line) is displayed.
8904 MAKEINDEXFLAGS
8906 General options passed to the makeindex generator for the TeX
8907 formatter and typesetter and the LaTeX structured formatter and
8908 typesetter.
8909 MAXLINELENGTH
8911 The maximum number of characters allowed on an external command
8912 line. On Win32 systems, link lines longer than this many characters
8913 are linked via a temporary file name.
8914 MIDL
8916 The Microsoft IDL compiler.
8917 MIDLCOM
8919 The command line used to pass files to the Microsoft IDL compiler.
8920 MIDLCOMSTR
8922 The string displayed when the Microsoft IDL compiler is called. If
8923 this is not set, then $MIDLCOM (the command line) is displayed.
8924 MIDLFLAGS
8926 General options passed to the Microsoft IDL compiler.
8927 MOSUFFIX
8929 Suffix used for MO files (default: '.mo'). See msgfmt tool and
8930 MOFiles builder.
8931 MSGFMT
8933 Absolute path to msgfmt(1) binary, found by Detect(). See msgfmt
8934 tool and MOFiles builder.
8935 MSGFMTCOM
8937 Complete command line to run msgfmt(1) program. See msgfmt tool and
8938 MOFiles builder.
8939 MSGFMTCOMSTR
8941 String to display when msgfmt(1) is invoked (default: '', which
8942 means ``print $MSGFMTCOM''). See msgfmt tool and MOFiles builder.
8943 MSGFMTFLAGS
8945 Additional flags to msgfmt(1). See msgfmt tool and MOFiles builder.
8946 MSGINIT
8948 Path to msginit(1) program (found via Detect()). See msginit tool
8949 and POInit builder.
8950 MSGINITCOM
8952 Complete command line to run msginit(1) program. See msginit tool
8953 and POInit builder.
8954 MSGINITCOMSTR
8956 String to display when msginit(1) is invoked (default: '', which
8957 means ``print $MSGINITCOM''). See msginit tool and POInit builder.
8958 MSGINITFLAGS
8960 List of additional flags to msginit(1) (default: []). See msginit
8961 tool and POInit builder.
8962 _MSGINITLOCALE
8964 Internal ``macro''. Computes locale (language) name based on target
8965 filename (default: '${TARGET.filebase}').
8966 See msginit tool and POInit builder.
8968 MSGMERGE
8970 Absolute path to msgmerge(1) binary as found by Detect(). See
8971 msgmerge tool and POUpdate builder.
8972 MSGMERGECOM
8974 Complete command line to run msgmerge(1) command. See msgmerge tool
8975 and POUpdate builder.
8976 MSGMERGECOMSTR
8978 String to be displayed when msgmerge(1) is invoked (default: '',
8979 which means ``print $MSGMERGECOM''). See msgmerge tool and POUpdate
8980 builder.
8981 MSGMERGEFLAGS
8983 Additional flags to msgmerge(1) command. See msgmerge tool and
8984 POUpdate builder.
8985 MSSDK_DIR
8987 The directory containing the Microsoft SDK (either Platform SDK or
8988 Windows SDK) to be used for compilation.
8989 MSSDK_VERSION
8991 The version string of the Microsoft SDK (either Platform SDK or
8992 Windows SDK) to be used for compilation. Supported versions include
8993 6.1, 6.0A, 6.0, 2003R2 and 2003R1.
8994 MSVC_BATCH
8996 When set to any true value, specifies that SCons should batch
8997 compilation of object files when calling the Microsoft Visual C/C++
8998 compiler. All compilations of source files from the same source
8999 directory that generate target files in a same output directory and
9000 were configured in SCons using the same construction environment
9001 will be built in a single call to the compiler. Only source files
9002 that have changed since their object files were built will be
9003 passed to each compiler invocation (via the $CHANGED_SOURCES
9004 construction variable). Any compilations where the object (target)
9005 file base name (minus the .obj) does not match the source file base
9006 name will be compiled separately.
9007 MSVC_USE_SCRIPT
9009 Use a batch script to set up the Microsoft Visual C++ compiler.
9010 If set to the name of a Visual Studio .bat file (e.g. vcvars.bat),
9012 SCons will run that batch file instead of the auto-detected one,
9013 and extract the relevant variables from the result (typically
9014 %INCLUDE%, %LIB%, and %PATH%) for supplying to the build. This can
9015 be useful to force the use of a compiler version that SCons does
9016 not detect.
9017 Setting $MSVC_USE_SCRIPT to None bypasses the Visual Studio
9019 autodetection entirely; use this if you are running SCons in a
9020 Visual Studio cmd window and importing the shell's environment
9021 variables - that is, if you are sure everything is set correctly
9022 already and you don't want SCons to change anything.
9023 $MSVC_USE_SCRIPT overrides $MSVC_VERSION and $TARGET_ARCH.
9026 MSVC_UWP_APP
9028 Build libraries for a Universal Windows Platform (UWP) Application.
9029 If $MSVC_UWP_APP is set, the Visual C++ environment will be set up
9031 to point to the Windows Store compatible libraries and Visual C++
9032 runtimes. In doing so, any libraries that are built will be able to
9033 be used in a UWP App and published to the Windows Store. This flag
9034 will only have an effect with Visual Studio 2015 or later. This
9035 variable must be passed as an argument to the Environment()
9036 constructor; setting it later has no effect.
9037 Valid values are '1' or '0'
9039 MSVC_VERSION
9041 Sets the preferred version of Microsoft Visual C/C++ to use.
9042 If $MSVC_VERSION is not set, SCons will (by default) select the
9044 latest version of Visual C/C++ installed on your system. If the
9045 specified version isn't installed, tool initialization will fail.
9046 This variable must be passed as an argument to the Environment
9047 constructor; setting it later has no effect.
9048 Valid values for Windows are 14.3, 14.2, 14.1, 14.1Exp, 14.0,
9050 14.0Exp, 12.0, 12.0Exp, 11.0, 11.0Exp, 10.0, 10.0Exp, 9.0, 9.0Exp,
9051 8.0, 8.0Exp, 7.1, 7.0, and 6.0. Versions ending in Exp refer to
9052 "Express" or "Express for Desktop" editions.
9053 MSVS
9055 When the Microsoft Visual Studio tools are initialized, they set up
9056 this dictionary with the following keys:
9057 VERSION
9059 the version of MSVS being used (can be set via $MSVS_VERSION)
9060 VERSIONS
9062 the available versions of MSVS installed
9063 VCINSTALLDIR
9065 installed directory of Visual C++
9066 VSINSTALLDIR
9068 installed directory of Visual Studio
9069 FRAMEWORKDIR
9071 installed directory of the .NET framework
9072 FRAMEWORKVERSIONS
9074 list of installed versions of the .NET framework, sorted latest
9075 to oldest.
9076 FRAMEWORKVERSION
9078 latest installed version of the .NET framework
9079 FRAMEWORKSDKDIR
9081 installed location of the .NET SDK.
9082 PLATFORMSDKDIR
9084 installed location of the Platform SDK.
9085 PLATFORMSDK_MODULES
9087 dictionary of installed Platform SDK modules, where the
9088 dictionary keys are keywords for the various modules, and the
9089 values are 2-tuples where the first is the release date, and
9090 the second is the version number.
9091 If a value is not set, it was not available in the registry.
9093 MSVS_ARCH
9095 Sets the architecture for which the generated project(s) should
9096 build.
9097 The default value is x86. amd64 is also supported by SCons for
9099 most Visual Studio versions. Since Visual Studio 2015 arm is
9100 supported, and since Visual Studio 2017 arm64 is supported. Trying
9101 to set $MSVS_ARCH to an architecture that's not supported for a
9102 given Visual Studio version will generate an error.
9103 MSVS_PROJECT_GUID
9105 The string placed in a generated Microsoft Visual Studio project
9106 file as the value of the ProjectGUID attribute. There is no default
9107 value. If not defined, a new GUID is generated.
9108 MSVS_SCC_AUX_PATH
9110 The path name placed in a generated Microsoft Visual Studio project
9111 file as the value of the SccAuxPath attribute if the
9112 MSVS_SCC_PROVIDER construction variable is also set. There is no
9113 default value.
9114 MSVS_SCC_CONNECTION_ROOT
9116 The root path of projects in your SCC workspace, i.e the path under
9117 which all project and solution files will be generated. It is used
9118 as a reference path from which the relative paths of the generated
9119 Microsoft Visual Studio project and solution files are computed.
9120 The relative project file path is placed as the value of the
9121 SccLocalPath attribute of the project file and as the values of the
9122 SccProjectFilePathRelativizedFromConnection[i] (where [i] ranges
9123 from 0 to the number of projects in the solution) attributes of the
9124 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9125 Studio solution file. Similarly the relative solution file path is
9126 placed as the values of the SccLocalPath[i] (where [i] ranges from
9127 0 to the number of projects in the solution) attributes of the
9128 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9129 Studio solution file. This is used only if the MSVS_SCC_PROVIDER
9130 construction variable is also set. The default value is the current
9131 working directory.
9132 MSVS_SCC_PROJECT_NAME
9134 The project name placed in a generated Microsoft Visual Studio
9135 project file as the value of the SccProjectName attribute if the
9136 MSVS_SCC_PROVIDER construction variable is also set. In this case
9137 the string is also placed in the SccProjectName0 attribute of the
9138 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9139 Studio solution file. There is no default value.
9140 MSVS_SCC_PROVIDER
9142 The string placed in a generated Microsoft Visual Studio project
9143 file as the value of the SccProvider attribute. The string is also
9144 placed in the SccProvider0 attribute of the
9145 GlobalSection(SourceCodeControl) section of the Microsoft Visual
9146 Studio solution file. There is no default value.
9147 MSVS_VERSION
9149 Sets the preferred version of Microsoft Visual Studio to use.
9150 If $MSVS_VERSION is not set, SCons will (by default) select the
9152 latest version of Visual Studio installed on your system. So, if
9153 you have version 6 and version 7 (MSVS .NET) installed, it will
9154 prefer version 7. You can override this by specifying the
9155 MSVS_VERSION variable in the Environment initialization, setting it
9156 to the appropriate version ('6.0' or '7.0', for example). If the
9157 specified version isn't installed, tool initialization will fail.
9158 This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is
9160 set and $MSVC_VERSION is not, $MSVC_VERSION will be set
9161 automatically to $MSVS_VERSION. If both are set to different
9162 values, scons will raise an error.
9163 MSVSBUILDCOM
9165 The build command line placed in a generated Microsoft Visual
9166 Studio project file. The default is to have Visual Studio invoke
9167 SCons with any specified build targets.
9168 MSVSCLEANCOM
9170 The clean command line placed in a generated Microsoft Visual
9171 Studio project file. The default is to have Visual Studio invoke
9172 SCons with the -c option to remove any specified targets.
9173 MSVSENCODING
9175 The encoding string placed in a generated Microsoft Visual Studio
9176 project file. The default is encoding Windows-1252.
9177 MSVSPROJECTCOM
9179 The action used to generate Microsoft Visual Studio project files.
9180 MSVSPROJECTSUFFIX
9182 The suffix used for Microsoft Visual Studio project (DSP) files.
9183 The default value is .vcproj when using Visual Studio version 7.x
9184 (.NET) or later version, and .dsp when using earlier versions of
9185 Visual Studio.
9186 MSVSREBUILDCOM
9188 The rebuild command line placed in a generated Microsoft Visual
9189 Studio project file. The default is to have Visual Studio invoke
9190 SCons with any specified rebuild targets.
9191 MSVSSCONS
9193 The SCons used in generated Microsoft Visual Studio project files.
9194 The default is the version of SCons being used to generate the
9195 project file.
9196 MSVSSCONSCOM
9198 The default SCons command used in generated Microsoft Visual Studio
9199 project files.
9200 MSVSSCONSCRIPT
9202 The sconscript file (that is, SConstruct or SConscript file) that
9203 will be invoked by Visual Studio project files (through the
9204 $MSVSSCONSCOM variable). The default is the same sconscript file
9205 that contains the call to MSVSProject to build the project file.
9206 MSVSSCONSFLAGS
9208 The SCons flags used in generated Microsoft Visual Studio project
9209 files.
9210 MSVSSOLUTIONCOM
9212 The action used to generate Microsoft Visual Studio solution files.
9213 MSVSSOLUTIONSUFFIX
9215 The suffix used for Microsoft Visual Studio solution (DSW) files.
9216 The default value is .sln when using Visual Studio version 7.x
9217 (.NET), and .dsw when using earlier versions of Visual Studio.
9218 MT
9220 The program used on Windows systems to embed manifests into DLLs
9221 and EXEs. See also $WINDOWS_EMBED_MANIFEST.
9222 MTEXECOM
9224 The Windows command line used to embed manifests into executables.
9225 See also $MTSHLIBCOM.
9226 MTFLAGS
9228 Flags passed to the $MT manifest embedding program (Windows only).
9229 MTSHLIBCOM
9231 The Windows command line used to embed manifests into shared
9232 libraries (DLLs). See also $MTEXECOM.
9233 MWCW_VERSION
9235 The version number of the MetroWerks CodeWarrior C compiler to be
9236 used.
9237 MWCW_VERSIONS
9239 A list of installed versions of the MetroWerks CodeWarrior C
9240 compiler on this system.
9241 NAME
9243 Specfies the name of the project to package.
9244 See the Package builder.
9246 NINJA_ALIAS_NAME
9248 Name of the Alias() which is will cause SCons to create the
9249 ninja.build file, and then (optionally) run ninja.
9250 NINJA_COMPDB_EXPAND
9252 Boolean value (True|False) to instruct ninja to expand the command
9253 line arguments normally put into response files. This prevents
9254 lines in the compilation database like “gcc @rsp_file” and instead
9255 yields “gcc -c -o myfile.o myfile.c -Ia -DXYZ”
9256 Ninja's compdb tool added the “-x” flag in Ninja V1.9.0
9258 NINJA_DIR
9260 This propagates directly into the generated ninja.build file. From
9261 Ninja's docs: builddir A directory for some Ninja output files. ...
9262 (You can also store other build output in this directory.)
9263 NINJA_DISABLE_AUTO_RUN
9265 Boolean (True|False). Default: False When True, SCons will not run
9266 ninja automatically after creating the ninja.build file. If not
9267 set, this will be set to True if “--disable_execute_ninja” or
9268 SetOption('disable_execute_ninja', True)
9269 NINJA_ENV_VAR_CACHE
9271 A string that sets the environment for any environment variables
9272 that differ between the OS environment and the SCons command ENV.
9273 It will be compatible with the default shell of the operating
9274 system. If not explicitly specified, SCons will generate this
9275 dynamically from the Environment()'s 'ENV' “env['ENV']” where those
9276 values differ from the existing shell..
9277 NINJA_FILE_NAME
9279 The filename for the generated Ninja build file defaults to
9280 ninja.build
9281 NINJA_FORCE_SCONS_BUILD
9283 When NINJA_FORCE_SCONS_BUILD is True, this will cause the build
9284 nodes to callback to scons instead of using ninja to build them.
9285 This is intended to be passed to the environment on the builder
9286 invocation. It is useful if you have a build node which does
9287 something which is not easily translated into ninja.
9288 NINJA_GENERATED_SOURCE_SUFFIXES
9290 The list of source file suffixes which are generated by SCons build
9291 steps. All source files which match these suffixes will be added to
9292 the _generated_sources alias in the output ninja.build file. Then
9293 all other source files will be made to depend on this in the
9294 ninja.build file, forcing the generated sources to be built first.
9295 NINJA_MSVC_DEPS_PREFIX
9297 This propagates directly into the generated ninja.build file. From
9298 Ninja's docs “defines the string which should be stripped from
9299 msvc’s /showIncludes output”
9300 NINJA_POOL
9302 Set the “ninja_pool” for this or all targets in scope for this env
9303 var.
9304 NINJA_REGENERATE_DEPS
9306 A generator function used to create a ninja depsfile which includes
9307 all the files which would require SCons to be invoked if they
9308 change. Or a list of said files.
9309 _NINJA_REGENERATE_DEPS_FUNC
9311 Internal value used to specify the function to call with argument
9312 env to generate the list of files which if changed would require
9313 the ninja file to be regenerated.
9314 NINJA_SYNTAX
9316 Theres also NINJA_SYNTAX which is the path to a custom
9317 ninja_syntax.py file which is used in generation. The tool
9318 currently assumes you have ninja installed through pip, and grabs
9319 the syntax file from that installation if none specified.
9320 no_import_lib
9322 When set to non-zero, suppresses creation of a corresponding
9323 Windows static import lib by the SharedLibrary builder when used
9324 with MinGW, Microsoft Visual Studio or Metrowerks. This also
9325 suppresses creation of an export (.exp) file when using Microsoft
9326 Visual Studio.
9327 OBJPREFIX
9329 The prefix used for (static) object file names.
9330 OBJSUFFIX
9332 The suffix used for (static) object file names.
9333 PACKAGEROOT
9335 Specifies the directory where all files in resulting archive will
9336 be placed if applicable. The default value is “$NAME-$VERSION”.
9337 See the Package builder.
9339 PACKAGETYPE
9341 Selects the package type to build when using the Package builder.
9342 May be a string or list of strings. See the docuentation for the
9343 builder for the currently supported types.
9344 $PACKAGETYPE may be overridden with the --package-type command line
9347 option.
9348 See the Package builder.
9350 PACKAGEVERSION
9352 The version of the package (not the underlying project). This is
9353 currently only used by the rpm packager and should reflect changes
9354 in the packaging, not the underlying project code itself.
9355 See the Package builder.
9357 PCH
9359 The Microsoft Visual C++ precompiled header that will be used when
9360 compiling object files. This variable is ignored by tools other
9361 than Microsoft Visual C++. When this variable is defined SCons will
9362 add options to the compiler command line to cause it to use the
9363 precompiled header, and will also set up the dependencies for the
9364 PCH file. Example:
9365 env['PCH'] = File('StdAfx.pch')
9367 PCHCOM
9369 The command line used by the PCH builder to generated a precompiled
9370 header.
9371 PCHCOMSTR
9373 The string displayed when generating a precompiled header. If this
9374 is not set, then $PCHCOM (the command line) is displayed.
9375 PCHPDBFLAGS
9377 A construction variable that, when expanded, adds the /yD flag to
9378 the command line only if the $PDB construction variable is set.
9379 PCHSTOP
9381 This variable specifies how much of a source file is precompiled.
9382 This variable is ignored by tools other than Microsoft Visual C++,
9383 or when the PCH variable is not being used. When this variable is
9384 define it must be a string that is the name of the header that is
9385 included at the end of the precompiled portion of the source files,
9386 or the empty string if the "#pragma hrdstop" construct is being
9387 used:
9388 env['PCHSTOP'] = 'StdAfx.h'
9390 PDB
9392 The Microsoft Visual C++ PDB file that will store debugging
9393 information for object files, shared libraries, and programs. This
9394 variable is ignored by tools other than Microsoft Visual C++. When
9395 this variable is defined SCons will add options to the compiler and
9396 linker command line to cause them to generate external debugging
9397 information, and will also set up the dependencies for the PDB
9398 file. Example:
9399 env['PDB'] = 'hello.pdb'
9401 The Visual C++ compiler switch that SCons uses by default to
9403 generate PDB information is /Z7. This works correctly with parallel
9404 (-j) builds because it embeds the debug information in the
9405 intermediate object files, as opposed to sharing a single PDB file
9406 between multiple object files. This is also the only way to get
9407 debug information embedded into a static library. Using the /Zi
9408 instead may yield improved link-time performance, although parallel
9409 builds will no longer work. You can generate PDB files with the /Zi
9410 switch by overriding the default $CCPDBFLAGS variable; see the
9411 entry for that variable for specific examples.
9412 PDFLATEX
9414 The pdflatex utility.
9415 PDFLATEXCOM
9417 The command line used to call the pdflatex utility.
9418 PDFLATEXCOMSTR
9420 The string displayed when calling the pdflatex utility. If this is
9421 not set, then $PDFLATEXCOM (the command line) is displayed.
9422 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
9424 PDFLATEXFLAGS
9426 General options passed to the pdflatex utility.
9427 PDFPREFIX
9429 The prefix used for PDF file names.
9430 PDFSUFFIX
9432 The suffix used for PDF file names.
9433 PDFTEX
9435 The pdftex utility.
9436 PDFTEXCOM
9438 The command line used to call the pdftex utility.
9439 PDFTEXCOMSTR
9441 The string displayed when calling the pdftex utility. If this is
9442 not set, then $PDFTEXCOM (the command line) is displayed.
9443 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
9445 PDFTEXFLAGS
9447 General options passed to the pdftex utility.
9448 PKGCHK
9450 On Solaris systems, the package-checking program that will be used
9451 (along with $PKGINFO) to look for installed versions of the Sun PRO
9452 C++ compiler. The default is /usr/sbin/pgkchk.
9453 PKGINFO
9455 On Solaris systems, the package information program that will be
9456 used (along with $PKGCHK) to look for installed versions of the Sun
9457 PRO C++ compiler. The default is pkginfo.
9458 PLATFORM
9460 The name of the platform used to create this construction
9461 environment. SCons sets this when initializing the platform, which
9462 by default is auto-detected (see the platform argument to
9463 Environment).
9464 env = Environment(tools=[])
9466 if env['PLATFORM'] == 'cygwin':
9467 Tool('mingw')(env)
9468 else:
9469 Tool('msvc')(env)
9470 POAUTOINIT
9473 The $POAUTOINIT variable, if set to True (on non-zero numeric
9474 value), let the msginit tool to automatically initialize missing PO
9475 files with msginit(1). This applies to both, POInit and POUpdate
9476 builders (and others that use any of them).
9477 POCREATE_ALIAS
9479 Common alias for all PO files created with POInit builder (default:
9480 'po-create'). See msginit tool and POInit builder.
9481 POSUFFIX
9483 Suffix used for PO files (default: '.po') See msginit tool and
9484 POInit builder.
9485 POTDOMAIN
9487 The $POTDOMAIN defines default domain, used to generate POT
9488 filename as $POTDOMAIN.pot when no POT file name is provided by the
9489 user. This applies to POTUpdate, POInit and POUpdate builders (and
9490 builders, that use them, e.g. Translate). Normally (if $POTDOMAIN
9491 is not defined), the builders use messages.pot as default POT file
9492 name.
9493 POTSUFFIX
9495 Suffix used for PO Template files (default: '.pot'). See xgettext
9496 tool and POTUpdate builder.
9497 POTUPDATE_ALIAS
9499 Name of the common phony target for all PO Templates created with
9500 POUpdate (default: 'pot-update'). See xgettext tool and POTUpdate
9501 builder.
9502 POUPDATE_ALIAS
9504 Common alias for all PO files being defined with POUpdate builder
9505 (default: 'po-update'). See msgmerge tool and POUpdate builder.
9506 PRINT_CMD_LINE_FUNC
9508 A Python function used to print the command lines as they are
9509 executed (assuming command printing is not disabled by the -q or -s
9510 options or their equivalents). The function should take four
9511 arguments: s, the command being executed (a string), target, the
9512 target being built (file node, list, or string name(s)), source,
9513 the source(s) used (file node, list, or string name(s)), and env,
9514 the environment being used.
9515 The function must do the printing itself. The default
9517 implementation, used if this variable is not set or is None, is:
9518 def print_cmd_line(s, target, source, env):
9520 sys.stdout.write(s + "\n")
9521 Here's an example of a more interesting function:
9523 def print_cmd_line(s, target, source, env):
9525 sys.stdout.write("Building %s -> %s...\n" %
9526 (' and '.join([str(x) for x in source]),
9527 ' and '.join([str(x) for x in target])))
9528 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
9529 env.Program('foo', 'foo.c')
9530 This just prints "Building targetname from sourcename..." instead
9532 of the actual commands. Such a function could also log the actual
9533 commands to a log file, for example.
9534 PROGEMITTER
9536 Contains the emitter specification for the Program builder. The
9537 manpage section "Builder Objects" contains general information on
9538 specifying emitters.
9539 PROGPREFIX
9541 The prefix used for executable file names.
9542 PROGSUFFIX
9544 The suffix used for executable file names.
9545 PSCOM
9547 The command line used to convert TeX DVI files into a PostScript
9548 file.
9549 PSCOMSTR
9551 The string displayed when a TeX DVI file is converted into a
9552 PostScript file. If this is not set, then $PSCOM (the command line)
9553 is displayed.
9554 PSPREFIX
9556 The prefix used for PostScript file names.
9557 PSSUFFIX
9559 The prefix used for PostScript file names.
9560 QT_AUTOSCAN
9562 Turn off scanning for mocable files. Use the Moc Builder to
9563 explicitly specify files to run moc on.
9564 QT_BINPATH
9566 The path where the Qt binaries are installed. The default value is
9567 '$QTDIR/bin'.
9568 QT_CPPPATH
9570 The path where the Qt header files are installed. The default value
9571 is '$QTDIR/include'. Note: If you set this variable to None, the
9572 tool won't change the $CPPPATH construction variable.
9573 QT_DEBUG
9575 Prints lots of debugging information while scanning for moc files.
9576 QT_LIB
9578 Default value is 'qt'. You may want to set this to 'qt-mt'. Note:
9579 If you set this variable to None, the tool won't change the $LIBS
9580 variable.
9581 QT_LIBPATH
9583 The path where the Qt libraries are installed. The default value is
9584 '$QTDIR/lib'. Note: If you set this variable to None, the tool
9585 won't change the $LIBPATH construction variable.
9586 QT_MOC
9588 Default value is '$QT_BINPATH/moc'.
9589 QT_MOCCXXPREFIX
9591 Default value is ''. Prefix for moc output files when source is a
9592 C++ file.
9593 QT_MOCCXXSUFFIX
9595 Default value is '.moc'. Suffix for moc output files when source is
9596 a C++ file.
9597 QT_MOCFROMCXXCOM
9599 Command to generate a moc file from a C++ file.
9600 QT_MOCFROMCXXCOMSTR
9602 The string displayed when generating a moc file from a C++ file. If
9603 this is not set, then $QT_MOCFROMCXXCOM (the command line) is
9604 displayed.
9605 QT_MOCFROMCXXFLAGS
9607 Default value is '-i'. These flags are passed to moc when moccing a
9608 C++ file.
9609 QT_MOCFROMHCOM
9611 Command to generate a moc file from a header.
9612 QT_MOCFROMHCOMSTR
9614 The string displayed when generating a moc file from a C++ file. If
9615 this is not set, then $QT_MOCFROMHCOM (the command line) is
9616 displayed.
9617 QT_MOCFROMHFLAGS
9619 Default value is ''. These flags are passed to moc when moccing a
9620 header file.
9621 QT_MOCHPREFIX
9623 Default value is 'moc_'. Prefix for moc output files when source is
9624 a header.
9625 QT_MOCHSUFFIX
9627 Default value is '$CXXFILESUFFIX'. Suffix for moc output files when
9628 source is a header.
9629 QT_UIC
9631 Default value is '$QT_BINPATH/uic'.
9632 QT_UICCOM
9634 Command to generate header files from .ui files.
9635 QT_UICCOMSTR
9637 The string displayed when generating header files from .ui files.
9638 If this is not set, then $QT_UICCOM (the command line) is
9639 displayed.
9640 QT_UICDECLFLAGS
9642 Default value is ''. These flags are passed to uic when creating a
9643 header file from a .ui file.
9644 QT_UICDECLPREFIX
9646 Default value is ''. Prefix for uic generated header files.
9647 QT_UICDECLSUFFIX
9649 Default value is '.h'. Suffix for uic generated header files.
9650 QT_UICIMPLFLAGS
9652 Default value is ''. These flags are passed to uic when creating a
9653 C++ file from a .ui file.
9654 QT_UICIMPLPREFIX
9656 Default value is 'uic_'. Prefix for uic generated implementation
9657 files.
9658 QT_UICIMPLSUFFIX
9660 Default value is '$CXXFILESUFFIX'. Suffix for uic generated
9661 implementation files.
9662 QT_UISUFFIX
9664 Default value is '.ui'. Suffix of designer input files.
9665 QTDIR
9667 The path to the Qt installation to build against. If not already
9668 set, qt tool tries to obtain this from os.environ; if not found
9669 there, it tries to make a guess.
9670 RANLIB
9672 The archive indexer.
9673 RANLIBCOM
9675 The command line used to index a static library archive.
9676 RANLIBCOMSTR
9678 The string displayed when a static library archive is indexed. If
9679 this is not set, then $RANLIBCOM (the command line) is displayed.
9680 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
9682 RANLIBFLAGS
9684 General options passed to the archive indexer.
9685 RC
9687 The resource compiler used to build a Microsoft Visual C++ resource
9688 file.
9689 RCCOM
9691 The command line used to build a Microsoft Visual C++ resource
9692 file.
9693 RCCOMSTR
9695 The string displayed when invoking the resource compiler to build a
9696 Microsoft Visual C++ resource file. If this is not set, then $RCCOM
9697 (the command line) is displayed.
9698 RCFLAGS
9700 The flags passed to the resource compiler by the RES builder.
9701 RCINCFLAGS
9703 An automatically-generated construction variable containing the
9704 command-line options for specifying directories to be searched by
9705 the resource compiler. The value of $RCINCFLAGS is created by
9706 respectively prepending and appending $RCINCPREFIX and $RCINCSUFFIX
9707 to the beginning and end of each directory in $CPPPATH.
9708 RCINCPREFIX
9710 The prefix (flag) used to specify an include directory on the
9711 resource compiler command line. This will be prepended to the
9712 beginning of each directory in the $CPPPATH construction variable
9713 when the $RCINCFLAGS variable is expanded.
9714 RCINCSUFFIX
9716 The suffix used to specify an include directory on the resource
9717 compiler command line. This will be appended to the end of each
9718 directory in the $CPPPATH construction variable when the
9719 $RCINCFLAGS variable is expanded.
9720 RDirs
9722 A function that converts a string into a list of Dir instances by
9723 searching the repositories.
9724 REGSVR
9726 The program used on Windows systems to register a newly-built DLL
9727 library whenever the SharedLibrary builder is passed a keyword
9728 argument of register=True.
9729 REGSVRCOM
9731 The command line used on Windows systems to register a newly-built
9732 DLL library whenever the SharedLibrary builder is passed a keyword
9733 argument of register=True.
9734 REGSVRCOMSTR
9736 The string displayed when registering a newly-built DLL file. If
9737 this is not set, then $REGSVRCOM (the command line) is displayed.
9738 REGSVRFLAGS
9740 Flags passed to the DLL registration program on Windows systems
9741 when a newly-built DLL library is registered. By default, this
9742 includes the /s that prevents dialog boxes from popping up and
9743 requiring user attention.
9744 RMIC
9746 The Java RMI stub compiler.
9747 RMICCOM
9749 The command line used to compile stub and skeleton class files from
9750 Java classes that contain RMI implementations. Any options
9751 specified in the $RMICFLAGS construction variable are included on
9752 this command line.
9753 RMICCOMSTR
9755 The string displayed when compiling stub and skeleton class files
9756 from Java classes that contain RMI implementations. If this is not
9757 set, then $RMICCOM (the command line) is displayed.
9758 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
9760 RMICFLAGS
9762 General options passed to the Java RMI stub compiler.
9763 RPATH
9765 A list of paths to search for shared libraries when running
9766 programs. Currently only used in the GNU (gnulink), IRIX (sgilink)
9767 and Sun (sunlink) linkers. Ignored on platforms and toolchains that
9768 don't support it. Note that the paths added to RPATH are not
9769 transformed by scons in any way: if you want an absolute path, you
9770 must make it absolute yourself.
9771 _RPATH
9773 An automatically-generated construction variable containing the
9774 rpath flags to be used when linking a program with shared
9775 libraries. The value of $_RPATH is created by respectively
9776 prepending $RPATHPREFIX and appending $RPATHSUFFIX to the beginning
9777 and end of each directory in $RPATH.
9778 RPATHPREFIX
9780 The prefix used to specify a directory to be searched for shared
9781 libraries when running programs. This will be prepended to the
9782 beginning of each directory in the $RPATH construction variable
9783 when the $_RPATH variable is automatically generated.
9784 RPATHSUFFIX
9786 The suffix used to specify a directory to be searched for shared
9787 libraries when running programs. This will be appended to the end
9788 of each directory in the $RPATH construction variable when the
9789 $_RPATH variable is automatically generated.
9790 RPCGEN
9792 The RPC protocol compiler.
9793 RPCGENCLIENTFLAGS
9795 Options passed to the RPC protocol compiler when generating client
9796 side stubs. These are in addition to any flags specified in the
9797 $RPCGENFLAGS construction variable.
9798 RPCGENFLAGS
9800 General options passed to the RPC protocol compiler.
9801 RPCGENHEADERFLAGS
9803 Options passed to the RPC protocol compiler when generating a
9804 header file. These are in addition to any flags specified in the
9805 $RPCGENFLAGS construction variable.
9806 RPCGENSERVICEFLAGS
9808 Options passed to the RPC protocol compiler when generating server
9809 side stubs. These are in addition to any flags specified in the
9810 $RPCGENFLAGS construction variable.
9811 RPCGENXDRFLAGS
9813 Options passed to the RPC protocol compiler when generating XDR
9814 routines. These are in addition to any flags specified in the
9815 $RPCGENFLAGS construction variable.
9816 SCANNERS
9818 A list of the available implicit dependency scanners. New file
9819 scanners may be added by appending to this list, although the more
9820 flexible approach is to associate scanners with a specific Builder.
9821 See the manpage sections "Builder Objects" and "Scanner Objects"
9822 for more information.
9823 SCONS_HOME
9825 The (optional) path to the SCons library directory, initialized
9826 from the external environment. If set, this is used to construct a
9827 shorter and more efficient search path in the $MSVSSCONS command
9828 line executed from Microsoft Visual Studio project files.
9829 SHCC
9831 The C compiler used for generating shared-library objects. See also
9832 $CC for compiling to static objects.
9833 SHCCCOM
9835 The command line used to compile a C source file to a
9836 shared-library object file. Any options specified in the $SHCFLAGS,
9837 $SHCCFLAGS and $CPPFLAGS construction variables are included on
9838 this command line. See also $CCCOM for compiling to static objects.
9839 SHCCCOMSTR
9841 If set, the string displayed when a C source file is compiled to a
9842 shared object file. If not set, then $SHCCCOM (the command line) is
9843 displayed. See also $CCCOMSTR for compiling to static objects.
9844 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
9846 SHCCFLAGS
9848 Options that are passed to the C and C++ compilers to generate
9849 shared-library objects. See also $CCFLAGS for compiling to static
9850 objects.
9851 SHCFLAGS
9853 Options that are passed to the C compiler (only; not C++) to
9854 generate shared-library objects. See also $CFLAGS for compiling to
9855 static objects.
9856 SHCXX
9858 The C++ compiler used for generating shared-library objects. See
9859 also $CXX for compiling to static objects.
9860 SHCXXCOM
9862 The command line used to compile a C++ source file to a
9863 shared-library object file. Any options specified in the
9864 $SHCXXFLAGS and $CPPFLAGS construction variables are included on
9865 this command line. See also $CXXCOM for compiling to static
9866 objects.
9867 SHCXXCOMSTR
9869 If set, the string displayed when a C++ source file is compiled to
9870 a shared object file. If not set, then $SHCXXCOM (the command line)
9871 is displayed. See also $CXXCOMSTR for compiling to static objects.
9872 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
9874 SHCXXFLAGS
9876 Options that are passed to the C++ compiler to generate
9877 shared-library objects. See also $CXXFLAGS for compiling to static
9878 objects.
9879 SHDC
9881 The name of the compiler to use when compiling D source destined to
9882 be in a shared objects. See also $DC for compiling to static
9883 objects.
9884 SHDCOM
9886 The command line to use when compiling code to be part of shared
9887 objects. See also $DCOM for compiling to static objects.
9888 SHDCOMSTR
9890 If set, the string displayed when a D source file is compiled to a
9891 (shared) object file. If not set, then $SHDCOM (the command line)
9892 is displayed. See also $DCOMSTR for compiling to static objects.
9893 SHDLIBVERSIONFLAGS
9895 Extra flags added to $SHDLINKCOM when building versioned
9896 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
9897 SHDLINK
9899 The linker to use when creating shared objects for code bases
9900 include D sources. See also $DLINK for linking static objects.
9901 SHDLINKCOM
9903 The command line to use when generating shared objects. See also
9904 $DLINKCOM for linking static objects.
9905 SHDLINKFLAGS
9907 The list of flags to use when generating a shared object. See also
9908 $DLINKFLAGS for linking static objects.
9909 SHELL
9911 A string naming the shell program that will be passed to the $SPAWN
9912 function. See the $SPAWN construction variable for more
9913 information.
9914 SHF03
9916 The Fortran 03 compiler used for generating shared-library objects.
9917 You should normally set the $SHFORTRAN variable, which specifies
9918 the default Fortran compiler for all Fortran versions. You only
9919 need to set $SHF03 if you need to use a specific compiler or
9920 compiler version for Fortran 03 files.
9921 SHF03COM
9923 The command line used to compile a Fortran 03 source file to a
9924 shared-library object file. You only need to set $SHF03COM if you
9925 need to use a specific command line for Fortran 03 files. You
9926 should normally set the $SHFORTRANCOM variable, which specifies the
9927 default command line for all Fortran versions.
9928 SHF03COMSTR
9930 If set, the string displayed when a Fortran 03 source file is
9931 compiled to a shared-library object file. If not set, then
9932 $SHF03COM or $SHFORTRANCOM (the command line) is displayed.
9933 SHF03FLAGS
9935 Options that are passed to the Fortran 03 compiler to generated
9936 shared-library objects. You only need to set $SHF03FLAGS if you
9937 need to define specific user options for Fortran 03 files. You
9938 should normally set the $SHFORTRANFLAGS variable, which specifies
9939 the user-specified options passed to the default Fortran compiler
9940 for all Fortran versions.
9941 SHF03PPCOM
9943 The command line used to compile a Fortran 03 source file to a
9944 shared-library object file after first running the file through the
9945 C preprocessor. Any options specified in the $SHF03FLAGS and
9946 $CPPFLAGS construction variables are included on this command line.
9947 You only need to set $SHF03PPCOM if you need to use a specific
9948 C-preprocessor command line for Fortran 03 files. You should
9949 normally set the $SHFORTRANPPCOM variable, which specifies the
9950 default C-preprocessor command line for all Fortran versions.
9951 SHF03PPCOMSTR
9953 If set, the string displayed when a Fortran 03 source file is
9954 compiled to a shared-library object file after first running the
9955 file through the C preprocessor. If not set, then $SHF03PPCOM or
9956 $SHFORTRANPPCOM (the command line) is displayed.
9957 SHF08
9959 The Fortran 08 compiler used for generating shared-library objects.
9960 You should normally set the $SHFORTRAN variable, which specifies
9961 the default Fortran compiler for all Fortran versions. You only
9962 need to set $SHF08 if you need to use a specific compiler or
9963 compiler version for Fortran 08 files.
9964 SHF08COM
9966 The command line used to compile a Fortran 08 source file to a
9967 shared-library object file. You only need to set $SHF08COM if you
9968 need to use a specific command line for Fortran 08 files. You
9969 should normally set the $SHFORTRANCOM variable, which specifies the
9970 default command line for all Fortran versions.
9971 SHF08COMSTR
9973 If set, the string displayed when a Fortran 08 source file is
9974 compiled to a shared-library object file. If not set, then
9975 $SHF08COM or $SHFORTRANCOM (the command line) is displayed.
9976 SHF08FLAGS
9978 Options that are passed to the Fortran 08 compiler to generated
9979 shared-library objects. You only need to set $SHF08FLAGS if you
9980 need to define specific user options for Fortran 08 files. You
9981 should normally set the $SHFORTRANFLAGS variable, which specifies
9982 the user-specified options passed to the default Fortran compiler
9983 for all Fortran versions.
9984 SHF08PPCOM
9986 The command line used to compile a Fortran 08 source file to a
9987 shared-library object file after first running the file through the
9988 C preprocessor. Any options specified in the $SHF08FLAGS and
9989 $CPPFLAGS construction variables are included on this command line.
9990 You only need to set $SHF08PPCOM if you need to use a specific
9991 C-preprocessor command line for Fortran 08 files. You should
9992 normally set the $SHFORTRANPPCOM variable, which specifies the
9993 default C-preprocessor command line for all Fortran versions.
9994 SHF08PPCOMSTR
9996 If set, the string displayed when a Fortran 08 source file is
9997 compiled to a shared-library object file after first running the
9998 file through the C preprocessor. If not set, then $SHF08PPCOM or
9999 $SHFORTRANPPCOM (the command line) is displayed.
10000 SHF77
10002 The Fortran 77 compiler used for generating shared-library objects.
10003 You should normally set the $SHFORTRAN variable, which specifies
10004 the default Fortran compiler for all Fortran versions. You only
10005 need to set $SHF77 if you need to use a specific compiler or
10006 compiler version for Fortran 77 files.
10007 SHF77COM
10009 The command line used to compile a Fortran 77 source file to a
10010 shared-library object file. You only need to set $SHF77COM if you
10011 need to use a specific command line for Fortran 77 files. You
10012 should normally set the $SHFORTRANCOM variable, which specifies the
10013 default command line for all Fortran versions.
10014 SHF77COMSTR
10016 If set, the string displayed when a Fortran 77 source file is
10017 compiled to a shared-library object file. If not set, then
10018 $SHF77COM or $SHFORTRANCOM (the command line) is displayed.
10019 SHF77FLAGS
10021 Options that are passed to the Fortran 77 compiler to generated
10022 shared-library objects. You only need to set $SHF77FLAGS if you
10023 need to define specific user options for Fortran 77 files. You
10024 should normally set the $SHFORTRANFLAGS variable, which specifies
10025 the user-specified options passed to the default Fortran compiler
10026 for all Fortran versions.
10027 SHF77PPCOM
10029 The command line used to compile a Fortran 77 source file to a
10030 shared-library object file after first running the file through the
10031 C preprocessor. Any options specified in the $SHF77FLAGS and
10032 $CPPFLAGS construction variables are included on this command line.
10033 You only need to set $SHF77PPCOM if you need to use a specific
10034 C-preprocessor command line for Fortran 77 files. You should
10035 normally set the $SHFORTRANPPCOM variable, which specifies the
10036 default C-preprocessor command line for all Fortran versions.
10037 SHF77PPCOMSTR
10039 If set, the string displayed when a Fortran 77 source file is
10040 compiled to a shared-library object file after first running the
10041 file through the C preprocessor. If not set, then $SHF77PPCOM or
10042 $SHFORTRANPPCOM (the command line) is displayed.
10043 SHF90
10045 The Fortran 90 compiler used for generating shared-library objects.
10046 You should normally set the $SHFORTRAN variable, which specifies
10047 the default Fortran compiler for all Fortran versions. You only
10048 need to set $SHF90 if you need to use a specific compiler or
10049 compiler version for Fortran 90 files.
10050 SHF90COM
10052 The command line used to compile a Fortran 90 source file to a
10053 shared-library object file. You only need to set $SHF90COM if you
10054 need to use a specific command line for Fortran 90 files. You
10055 should normally set the $SHFORTRANCOM variable, which specifies the
10056 default command line for all Fortran versions.
10057 SHF90COMSTR
10059 If set, the string displayed when a Fortran 90 source file is
10060 compiled to a shared-library object file. If not set, then
10061 $SHF90COM or $SHFORTRANCOM (the command line) is displayed.
10062 SHF90FLAGS
10064 Options that are passed to the Fortran 90 compiler to generated
10065 shared-library objects. You only need to set $SHF90FLAGS if you
10066 need to define specific user options for Fortran 90 files. You
10067 should normally set the $SHFORTRANFLAGS variable, which specifies
10068 the user-specified options passed to the default Fortran compiler
10069 for all Fortran versions.
10070 SHF90PPCOM
10072 The command line used to compile a Fortran 90 source file to a
10073 shared-library object file after first running the file through the
10074 C preprocessor. Any options specified in the $SHF90FLAGS and
10075 $CPPFLAGS construction variables are included on this command line.
10076 You only need to set $SHF90PPCOM if you need to use a specific
10077 C-preprocessor command line for Fortran 90 files. You should
10078 normally set the $SHFORTRANPPCOM variable, which specifies the
10079 default C-preprocessor command line for all Fortran versions.
10080 SHF90PPCOMSTR
10082 If set, the string displayed when a Fortran 90 source file is
10083 compiled to a shared-library object file after first running the
10084 file through the C preprocessor. If not set, then $SHF90PPCOM or
10085 $SHFORTRANPPCOM (the command line) is displayed.
10086 SHF95
10088 The Fortran 95 compiler used for generating shared-library objects.
10089 You should normally set the $SHFORTRAN variable, which specifies
10090 the default Fortran compiler for all Fortran versions. You only
10091 need to set $SHF95 if you need to use a specific compiler or
10092 compiler version for Fortran 95 files.
10093 SHF95COM
10095 The command line used to compile a Fortran 95 source file to a
10096 shared-library object file. You only need to set $SHF95COM if you
10097 need to use a specific command line for Fortran 95 files. You
10098 should normally set the $SHFORTRANCOM variable, which specifies the
10099 default command line for all Fortran versions.
10100 SHF95COMSTR
10102 If set, the string displayed when a Fortran 95 source file is
10103 compiled to a shared-library object file. If not set, then
10104 $SHF95COM or $SHFORTRANCOM (the command line) is displayed.
10105 SHF95FLAGS
10107 Options that are passed to the Fortran 95 compiler to generated
10108 shared-library objects. You only need to set $SHF95FLAGS if you
10109 need to define specific user options for Fortran 95 files. You
10110 should normally set the $SHFORTRANFLAGS variable, which specifies
10111 the user-specified options passed to the default Fortran compiler
10112 for all Fortran versions.
10113 SHF95PPCOM
10115 The command line used to compile a Fortran 95 source file to a
10116 shared-library object file after first running the file through the
10117 C preprocessor. Any options specified in the $SHF95FLAGS and
10118 $CPPFLAGS construction variables are included on this command line.
10119 You only need to set $SHF95PPCOM if you need to use a specific
10120 C-preprocessor command line for Fortran 95 files. You should
10121 normally set the $SHFORTRANPPCOM variable, which specifies the
10122 default C-preprocessor command line for all Fortran versions.
10123 SHF95PPCOMSTR
10125 If set, the string displayed when a Fortran 95 source file is
10126 compiled to a shared-library object file after first running the
10127 file through the C preprocessor. If not set, then $SHF95PPCOM or
10128 $SHFORTRANPPCOM (the command line) is displayed.
10129 SHFORTRAN
10131 The default Fortran compiler used for generating shared-library
10132 objects.
10133 SHFORTRANCOM
10135 The command line used to compile a Fortran source file to a
10136 shared-library object file.
10137 SHFORTRANCOMSTR
10139 If set, the string displayed when a Fortran source file is compiled
10140 to a shared-library object file. If not set, then $SHFORTRANCOM
10141 (the command line) is displayed.
10142 SHFORTRANFLAGS
10144 Options that are passed to the Fortran compiler to generate
10145 shared-library objects.
10146 SHFORTRANPPCOM
10148 The command line used to compile a Fortran source file to a
10149 shared-library object file after first running the file through the
10150 C preprocessor. Any options specified in the $SHFORTRANFLAGS and
10151 $CPPFLAGS construction variables are included on this command line.
10152 SHFORTRANPPCOMSTR
10154 If set, the string displayed when a Fortran source file is compiled
10155 to a shared-library object file after first running the file
10156 through the C preprocessor. If not set, then $SHFORTRANPPCOM (the
10157 command line) is displayed.
10158 SHLIBEMITTER
10160 Contains the emitter specification for the SharedLibrary builder.
10161 The manpage section "Builder Objects" contains general information
10162 on specifying emitters.
10163 SHLIBNOVERSIONSYMLINKS
10165 Instructs the SharedLibrary builder to not create symlinks for
10166 versioned shared libraries.
10167 SHLIBPREFIX
10169 The prefix used for shared library file names.
10170 _SHLIBSONAME
10172 A macro that automatically generates shared library's SONAME based
10173 on $TARGET, $SHLIBVERSION and $SHLIBSUFFIX. Used by SharedLibrary
10174 builder when the linker tool supports SONAME (e.g. gnulink).
10175 SHLIBSUFFIX
10177 The suffix used for shared library file names.
10178 SHLIBVERSION
10180 When this construction variable is defined, a versioned shared
10181 library is created by the SharedLibrary builder. This activates the
10182 $_SHLIBVERSIONFLAGS and thus modifies the $SHLINKCOM as required,
10183 adds the version number to the library name, and creates the
10184 symlinks that are needed. $SHLIBVERSION versions should exist as
10185 alpha-numeric, decimal-delimited values as defined by the regular
10186 expression "\w+[\.\w+]*". Example $SHLIBVERSION values include '1',
10187 '1.2.3', and '1.2.gitaa412c8b'.
10188 _SHLIBVERSIONFLAGS
10190 This macro automatically introduces extra flags to $SHLINKCOM when
10191 building versioned SharedLibrary (that is when $SHLIBVERSION is
10192 set). _SHLIBVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS and some
10193 extra dynamically generated options (such as
10194 -Wl,-soname=$_SHLIBSONAME. It is unused by "plain" (unversioned)
10195 shared libraries.
10196 SHLIBVERSIONFLAGS
10198 Extra flags added to $SHLINKCOM when building versioned
10199 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
10200 SHLINK
10202 The linker for programs that use shared libraries. See also $LINK
10203 for linking static objects.
10204 On POSIX systems (those using the link tool), you should normally
10206 not change this value as it defaults to a "smart" linker tool which
10207 selects a compiler driver matching the type of source files in use.
10208 So for example, if you set $SHCXX to a specific compiler name, and
10209 are compiling C++ sources, the smartlink function will
10210 automatically select the same compiler for linking.
10211 SHLINKCOM
10213 The command line used to link programs using shared libraries. See
10214 also $LINKCOM for linking static objects.
10215 SHLINKCOMSTR
10217 The string displayed when programs using shared libraries are
10218 linked. If this is not set, then $SHLINKCOM (the command line) is
10219 displayed. See also $LINKCOMSTR for linking static objects.
10220 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
10222 SHLINKFLAGS
10224 General user options passed to the linker for programs using shared
10225 libraries. Note that this variable should not contain -l (or
10226 similar) options for linking with the libraries listed in $LIBS,
10227 nor -L (or similar) include search path options that scons
10228 generates automatically from $LIBPATH. See $_LIBFLAGS above, for
10229 the variable that expands to library-link options, and
10230 $_LIBDIRFLAGS above, for the variable that expands to library
10231 search path options. See also $LINKFLAGS for linking static
10232 objects.
10233 SHOBJPREFIX
10235 The prefix used for shared object file names.
10236 SHOBJSUFFIX
10238 The suffix used for shared object file names.
10239 SONAME
10241 Variable used to hard-code SONAME for versioned shared
10242 library/loadable module.
10243 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
10245 The variable is used, for example, by gnulink linker tool.
10247 SOURCE
10249 A reserved variable name that may not be set or used in a
10250 construction environment. (See the manpage section "Variable
10251 Substitution" for more information).
10252 SOURCE_URL
10254 The URL (web address) of the location from which the project was
10255 retrieved. This is used to fill in the Source: field in the
10256 controlling information for Ipkg and RPM packages.
10257 See the Package builder.
10259 SOURCES
10261 A reserved variable name that may not be set or used in a
10262 construction environment. (See the manpage section "Variable
10263 Substitution" for more information).
10264 SOVERSION
10266 This will construct the SONAME using on the base library name (test
10267 in the example below) and use specified SOVERSION to create SONAME.
10268 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SOVERSION='2')
10270 The variable is used, for example, by gnulink linker tool.
10272 In the example above SONAME would be libtest.so.2 which would be a
10274 symlink and point to libtest.so.0.1.2
10275 SPAWN
10277 A command interpreter function that will be called to execute
10278 command line strings. The function must expect the following
10279 arguments:
10280 def spawn(shell, escape, cmd, args, env):
10282 sh is a string naming the shell program to use. escape is a
10285 function that can be called to escape shell special characters in
10286 the command line. cmd is the path to the command to be executed.
10287 args is the arguments to the command. env is a dictionary of the
10288 environment variables in which the command should be executed.
10289 STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME
10291 When this variable is true, static objects and shared objects are
10292 assumed to be the same; that is, SCons does not check for linking
10293 static objects into a shared library.
10294 SUBST_DICT
10296 The dictionary used by the Substfile or Textfile builders for
10297 substitution values. It can be anything acceptable to the dict()
10298 constructor, so in addition to a dictionary, lists of tuples are
10299 also acceptable.
10300 SUBSTFILEPREFIX
10302 The prefix used for Substfile file names, an empty string by
10303 default.
10304 SUBSTFILESUFFIX
10306 The suffix used for Substfile file names, an empty string by
10307 default.
10308 SUMMARY
10310 A short summary of what the project is about. This is used to fill
10311 in the Summary: field in the controlling information for Ipkg and
10312 RPM packages, and as the Description: field in MSI packages.
10313 See the Package builder.
10315 SWIG
10317 The scripting language wrapper and interface generator.
10318 SWIGCFILESUFFIX
10320 The suffix that will be used for intermediate C source files
10321 generated by the scripting language wrapper and interface
10322 generator. The default value is _wrap$CFILESUFFIX. By default, this
10323 value is used whenever the -c++ option is not specified as part of
10324 the $SWIGFLAGS construction variable.
10325 SWIGCOM
10327 The command line used to call the scripting language wrapper and
10328 interface generator.
10329 SWIGCOMSTR
10331 The string displayed when calling the scripting language wrapper
10332 and interface generator. If this is not set, then $SWIGCOM (the
10333 command line) is displayed.
10334 SWIGCXXFILESUFFIX
10336 The suffix that will be used for intermediate C++ source files
10337 generated by the scripting language wrapper and interface
10338 generator. The default value is _wrap$CFILESUFFIX. By default, this
10339 value is used whenever the -c++ option is specified as part of the
10340 $SWIGFLAGS construction variable.
10341 SWIGDIRECTORSUFFIX
10343 The suffix that will be used for intermediate C++ header files
10344 generated by the scripting language wrapper and interface
10345 generator. These are only generated for C++ code when the SWIG
10346 'directors' feature is turned on. The default value is _wrap.h.
10347 SWIGFLAGS
10349 General options passed to the scripting language wrapper and
10350 interface generator. This is where you should set -python, -perl5,
10351 -tcl, or whatever other options you want to specify to SWIG. If you
10352 set the -c++ option in this variable, scons will, by default,
10353 generate a C++ intermediate source file with the extension that is
10354 specified as the $CXXFILESUFFIX variable.
10355 _SWIGINCFLAGS
10357 An automatically-generated construction variable containing the
10358 SWIG command-line options for specifying directories to be searched
10359 for included files. The value of $_SWIGINCFLAGS is created by
10360 respectively prepending and appending $SWIGINCPREFIX and
10361 $SWIGINCSUFFIX to the beginning and end of each directory in
10362 $SWIGPATH.
10363 SWIGINCPREFIX
10365 The prefix used to specify an include directory on the SWIG command
10366 line. This will be prepended to the beginning of each directory in
10367 the $SWIGPATH construction variable when the $_SWIGINCFLAGS
10368 variable is automatically generated.
10369 SWIGINCSUFFIX
10371 The suffix used to specify an include directory on the SWIG command
10372 line. This will be appended to the end of each directory in the
10373 $SWIGPATH construction variable when the $_SWIGINCFLAGS variable is
10374 automatically generated.
10375 SWIGOUTDIR
10377 Specifies the output directory in which the scripting language
10378 wrapper and interface generator should place generated
10379 language-specific files. This will be used by SCons to identify the
10380 files that will be generated by the swig call, and translated into
10381 the swig -outdir option on the command line.
10382 SWIGPATH
10384 The list of directories that the scripting language wrapper and
10385 interface generate will search for included files. The SWIG
10386 implicit dependency scanner will search these directories for
10387 include files. The default value is an empty list.
10388 Don't explicitly put include directory arguments in SWIGFLAGS; the
10390 result will be non-portable and the directories will not be
10391 searched by the dependency scanner. Note: directory names in
10392 SWIGPATH will be looked-up relative to the SConscript directory
10393 when they are used in a command. To force scons to look-up a
10394 directory relative to the root of the source tree use #:
10395 env = Environment(SWIGPATH='#/include')
10397 The directory look-up can also be forced using the Dir() function:
10399 include = Dir('include')
10401 env = Environment(SWIGPATH=include)
10402 The directory list will be added to command lines through the
10404 automatically-generated $_SWIGINCFLAGS construction variable, which
10405 is constructed by respectively prepending and appending the values
10406 of the $SWIGINCPREFIX and $SWIGINCSUFFIX construction variables to
10407 the beginning and end of each directory in $SWIGPATH. Any command
10408 lines you define that need the SWIGPATH directory list should
10409 include $_SWIGINCFLAGS:
10410 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
10412 SWIGVERSION
10414 The version number of the SWIG tool.
10415 TAR
10417 The tar archiver.
10418 TARCOM
10420 The command line used to call the tar archiver.
10421 TARCOMSTR
10423 The string displayed when archiving files using the tar archiver.
10424 If this is not set, then $TARCOM (the command line) is displayed.
10425 env = Environment(TARCOMSTR = "Archiving $TARGET")
10427 TARFLAGS
10429 General options passed to the tar archiver.
10430 TARGET
10432 A reserved variable name that may not be set or used in a
10433 construction environment. (See the manpage section "Variable
10434 Substitution" for more information).
10435 TARGET_ARCH
10437 The name of the hardware architecture that objects created using
10438 this construction environment should target. Can be set when
10439 creating a construction environment by passing as a keyword
10440 argument in the Environment call.
10441 On the win32 platform, if the Microsoft Visual C++ compiler is
10443 available, msvc tool setup is done using $HOST_ARCH and
10444 $TARGET_ARCH. If a value is not specified, will be set to the same
10445 value as $HOST_ARCH. Changing the value after the environment is
10446 initialized will not cause the tool to be reinitialized. Compiled
10447 objects will be in the target architecture if the compilation
10448 system supports generating for that target. The latest compiler
10449 which can fulfill the requirement will be selected, unless a
10450 different version is directed by the value of the $MSVC_VERSION
10451 construction variable.
10452 On the win32/msvc combination, valid target arch values are x86,
10454 arm, i386 for 32-bit targets and amd64, arm64, x86_64 and ia64
10455 (Itanium) for 64-bit targets. For example, if you want to compile
10456 64-bit binaries, you would set TARGET_ARCH='x86_64' when creating
10457 the construction environment. Note that not all target
10458 architectures are supported for all Visual Studio / MSVC versions.
10459 Check the relevant Microsoft documentation.
10460 $TARGET_ARCH is not currently used by other compilation tools, but
10463 the option is reserved to do so in future
10464 TARGET_OS
10466 The name of the operating system that objects created using this
10467 construction environment should target. Can be set when creating a
10468 construction environment by passing as a keyword argument in the
10469 Environment call;.
10470 $TARGET_OS is not currently used by SCons but the option is
10473 reserved to do so in future
10474 TARGETS
10476 A reserved variable name that may not be set or used in a
10477 construction environment. (See the manpage section "Variable
10478 Substitution" for more information).
10479 TARSUFFIX
10481 The suffix used for tar file names.
10482 TEMPFILE
10484 A callable object used to handle overly long command line strings,
10485 since operations which call out to a shell will fail if the line is
10486 longer than the shell can accept. This tends to particularly impact
10487 linking. The tempfile object stores the command line in a temporary
10488 file in the appropriate format, and returns an alternate command
10489 line so the invoked tool will make use of the contents of the
10490 temporary file. If you need to replace the default tempfile object,
10491 the callable should take into account the settings of
10492 $MAXLINELENGTH, $TEMPFILEPREFIX, $TEMPFILESUFFIX, $TEMPFILEARGJOIN,
10493 $TEMPFILEDIR and $TEMPFILEARGESCFUNC.
10494 TEMPFILEARGESCFUNC
10496 The default argument escape function is SCons.Subst.quote_spaces.
10497 If you need to apply extra operations on a command argument (to fix
10498 Windows slashes, normalize paths, etc.) before writing to the
10499 temporary file, you can set the $TEMPFILEARGESCFUNC variable to a
10500 custom function. Such a function takes a single string argument and
10501 returns a new string with any modifications applied. Example:
10502 import sys
10504 import re
10505 from SCons.Subst import quote_spaces
10506 WINPATHSEP_RE = re.compile(r"\\([^\"'\\]|$)")
10508 def tempfile_arg_esc_func(arg):
10510 arg = quote_spaces(arg)
10511 if sys.platform != "win32":
10512 return arg
10513 # GCC requires double Windows slashes, let's use UNIX separator
10514 return WINPATHSEP_RE.sub(r"/\1", arg)
10515 env["TEMPFILEARGESCFUNC"] = tempfile_arg_esc_func
10517 TEMPFILEARGJOIN
10519 The string to use to join the arguments passed to $TEMPFILE when
10520 the command line exceeds the limit set by $MAXLINELENGTH. The
10521 default value is a space. However for MSVC, MSLINK the default is a
10522 line separator as defined by os.linesep. Note this value is used
10523 literally and not expanded by the subst logic.
10524 TEMPFILEDIR
10526 The directory to create the long-lines temporary file in.
10527 TEMPFILEPREFIX
10529 The prefix for the name of the temporary file used to store command
10530 lines exceeding $MAXLINELENGTH. The default prefix is '@', which
10531 works for the Microsoft and GNU toolchains on Windows. Set this
10532 appropriately for other toolchains, for example '-@' for the diab
10533 compiler or '-via' for ARM toolchain.
10534 TEMPFILESUFFIX
10536 The suffix for the name of the temporary file used to store command
10537 lines exceeding $MAXLINELENGTH. The suffix should include the dot
10538 ('.') if one is wanted as it will not be added automatically. The
10539 default is .lnk.
10540 TEX
10542 The TeX formatter and typesetter.
10543 TEXCOM
10545 The command line used to call the TeX formatter and typesetter.
10546 TEXCOMSTR
10548 The string displayed when calling the TeX formatter and typesetter.
10549 If this is not set, then $TEXCOM (the command line) is displayed.
10550 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
10552 TEXFLAGS
10554 General options passed to the TeX formatter and typesetter.
10555 TEXINPUTS
10557 List of directories that the LaTeX program will search for include
10558 directories. The LaTeX implicit dependency scanner will search
10559 these directories for \include and \import files.
10560 TEXTFILEPREFIX
10562 The prefix used for Textfile file names, an empty string by
10563 default.
10564 TEXTFILESUFFIX
10566 The suffix used for Textfile file names; .txt by default.
10567 TOOLS
10569 A list of the names of the Tool specifications that are part of
10570 this construction environment.
10571 UNCHANGED_SOURCES
10573 A reserved variable name that may not be set or used in a
10574 construction environment. (See the manpage section "Variable
10575 Substitution" for more information).
10576 UNCHANGED_TARGETS
10578 A reserved variable name that may not be set or used in a
10579 construction environment. (See the manpage section "Variable
10580 Substitution" for more information).
10581 VENDOR
10583 The person or organization who supply the packaged software. This
10584 is used to fill in the Vendor: field in the controlling information
10585 for RPM packages, and the Manufacturer: field in the controlling
10586 information for MSI packages.
10587 See the Package builder.
10589 VERSION
10591 The version of the project, specified as a string.
10592 See the Package builder.
10594 VSWHERE
10596 Specify the location of vswhere.exe.
10597 The vswhere.exe executable is distributed with Microsoft Visual
10599 Studio and Build Tools since the 2017 edition, but is also
10600 available standalone. It provides full information about
10601 installations of 2017 and later editions. With the -legacy
10602 argument, vswhere.exe can detect installations of the 2010 through
10603 2015 editions with limited data returned. If VSWHERE is set, SCons
10604 will use that location.
10605 Otherwise SCons will look in the following locations and set
10607 VSWHERE to the path of the first vswhere.exe located.
10608 • %ProgramFiles(x86)%\Microsoft Visual Studio\Installer
10610 • %ProgramFiles%\Microsoft Visual Studio\Installer
10612 • %ChocolateyInstall%\bin
10614 Note that VSWHERE must be set at the same time or prior to any of
10616 msvc, msvs , and/or mslink Tool being initialized. Either set it as
10617 follows
10618 env = Environment(VSWHERE='c:/my/path/to/vswhere')
10620 or if your construction environment is created specifying an empty
10622 tools list (or a list of tools which omits all of default, msvs,
10623 msvc, and mslink), and also before env.Tool is called to
10624 ininitialize any of those tools:
10625 env = Environment(tools=[])
10627 env['VSWHERE'] = r'c:/my/vswhere/install/location/vswhere.exe'
10628 env.Tool('msvc')
10629 env.Tool('mslink')
10630 env.Tool('msvs')
10631 WINDOWS_EMBED_MANIFEST
10635 Set to True to embed the compiler-generated manifest (normally
10636 ${TARGET}.manifest) into all Windows executables and DLLs built
10637 with this environment, as a resource during their link step. This
10638 is done using $MT and $MTEXECOM and $MTSHLIBCOM. See also
10639 $WINDOWS_INSERT_MANIFEST.
10640 WINDOWS_INSERT_DEF
10642 If set to true, a library build of a Windows shared library (.dll
10643 file) will include a reference to the corresponding
10644 module-definition file at the same time, if a module-definition
10645 file is not already listed as a build target. The name of the
10646 module-definition file will be constructed from the base name of
10647 the library and the construction variables $WINDOWSDEFSUFFIX and
10648 $WINDOWSDEFPREFIX. The default is to not add a module-definition
10649 file. The module-definition file is not created by this directive,
10650 and must be supplied by the developer.
10651 WINDOWS_INSERT_MANIFEST
10653 If set to true, scons will add the manifest file generated by
10654 Microsoft Visual C++ 8.0 and later to the target list so SCons will
10655 be aware they were generated. In the case of an executable, the
10656 manifest file name is constructed using $WINDOWSPROGMANIFESTSUFFIX
10657 and $WINDOWSPROGMANIFESTPREFIX. In the case of a shared library,
10658 the manifest file name is constructed using
10659 $WINDOWSSHLIBMANIFESTSUFFIX and $WINDOWSSHLIBMANIFESTPREFIX. See
10660 also $WINDOWS_EMBED_MANIFEST.
10661 WINDOWSDEFPREFIX
10663 The prefix used for a Windows linker module-definition file name.
10664 Defaults to empty.
10665 WINDOWSDEFSUFFIX
10667 The suffix used for a Windows linker module-definition file name.
10668 Defaults to .def.
10669 WINDOWSEXPPREFIX
10671 The prefix used for Windows linker exports file names. Defaults to
10672 empty.
10673 WINDOWSEXPSUFFIX
10675 The suffix used for Windows linker exports file names. Defaults to
10676 .exp.
10677 WINDOWSPROGMANIFESTPREFIX
10679 The prefix used for executable program manifest files generated by
10680 Microsoft Visual C/C++. Defaults to empty.
10681 WINDOWSPROGMANIFESTSUFFIX
10683 The suffix used for executable program manifest files generated by
10684 Microsoft Visual C/C++. Defaults to .manifest.
10685 WINDOWSSHLIBMANIFESTPREFIX
10687 The prefix used for shared library manifest files generated by
10688 Microsoft Visual C/C++. Defaults to empty.
10689 WINDOWSSHLIBMANIFESTSUFFIX
10691 The suffix used for shared library manifest files generated by
10692 Microsoft Visual C/C++. Defaults to .manifest.
10693 X_IPK_DEPENDS
10695 This is used to fill in the Depends: field in the controlling
10696 information for Ipkg packages.
10697 See the Package builder.
10699 X_IPK_DESCRIPTION
10701 This is used to fill in the Description: field in the controlling
10702 information for Ipkg packages. The default value is
10703 “$SUMMARY\n$DESCRIPTION”
10704 X_IPK_MAINTAINER
10706 This is used to fill in the Maintainer: field in the controlling
10707 information for Ipkg packages.
10708 X_IPK_PRIORITY
10710 This is used to fill in the Priority: field in the controlling
10711 information for Ipkg packages.
10712 X_IPK_SECTION
10714 This is used to fill in the Section: field in the controlling
10715 information for Ipkg packages.
10716 X_MSI_LANGUAGE
10718 This is used to fill in the Language: attribute in the controlling
10719 information for MSI packages.
10720 See the Package builder.
10722 X_MSI_LICENSE_TEXT
10724 The text of the software license in RTF format. Carriage return
10725 characters will be replaced with the RTF equivalent \\par.
10726 See the Package builder.
10728 X_MSI_UPGRADE_CODE
10730 TODO
10731 X_RPM_AUTOREQPROV
10733 This is used to fill in the AutoReqProv: field in the RPM .spec
10734 file.
10735 See the Package builder.
10737 X_RPM_BUILD
10739 internal, but overridable
10740 X_RPM_BUILDREQUIRES
10742 This is used to fill in the BuildRequires: field in the RPM .spec
10743 file. Note this should only be used on a host managed by rpm as the
10744 dependencies will not be resolvable at build time otherwise.
10745 X_RPM_BUILDROOT
10747 internal, but overridable
10748 X_RPM_CLEAN
10750 internal, but overridable
10751 X_RPM_CONFLICTS
10753 This is used to fill in the Conflicts: field in the RPM .spec file.
10754 X_RPM_DEFATTR
10756 This value is used as the default attributes for the files in the
10757 RPM package. The default value is “(-,root,root)”.
10758 X_RPM_DISTRIBUTION
10760 This is used to fill in the Distribution: field in the RPM .spec
10761 file.
10762 X_RPM_EPOCH
10764 This is used to fill in the Epoch: field in the RPM .spec file.
10765 X_RPM_EXCLUDEARCH
10767 This is used to fill in the ExcludeArch: field in the RPM .spec
10768 file.
10769 X_RPM_EXLUSIVEARCH
10771 This is used to fill in the ExclusiveArch: field in the RPM .spec
10772 file.
10773 X_RPM_EXTRADEFS
10775 A list used to supply extra defintions or flags to be added to the
10776 RPM .spec file. Each item is added as-is with a carriage return
10777 appended. This is useful if some specific RPM feature not otherwise
10778 anticipated by SCons needs to be turned on or off. Note if this
10779 variable is omitted, SCons will by default supply the value
10780 '%global debug_package %{nil}' to disable debug package generation.
10781 To enable debug package generation, include this variable set
10782 either to None, or to a custom list that does not include the
10783 default line. Added in version 3.1.
10784 env.Package(
10786 NAME="foo",
10787 ...
10788 X_RPM_EXTRADEFS=[
10789 "%define _unpackaged_files_terminate_build 0"
10790 "%define _missing_doc_files_terminate_build 0"
10791 ],
10792 ...
10793 )
10794 X_RPM_GROUP
10796 This is used to fill in the Group: field in the RPM .spec file.
10797 X_RPM_GROUP_lang
10799 This is used to fill in the Group(lang): field in the RPM .spec
10800 file. Note that lang is not literal and should be replaced by the
10801 appropriate language code.
10802 X_RPM_ICON
10804 This is used to fill in the Icon: field in the RPM .spec file.
10805 X_RPM_INSTALL
10807 internal, but overridable
10808 X_RPM_PACKAGER
10810 This is used to fill in the Packager: field in the RPM .spec file.
10811 X_RPM_POSTINSTALL
10813 This is used to fill in the %post: section in the RPM .spec file.
10814 X_RPM_POSTUNINSTALL
10816 This is used to fill in the %postun: section in the RPM .spec file.
10817 X_RPM_PREFIX
10819 This is used to fill in the Prefix: field in the RPM .spec file.
10820 X_RPM_PREINSTALL
10822 This is used to fill in the %pre: section in the RPM .spec file.
10823 X_RPM_PREP
10825 internal, but overridable
10826 X_RPM_PREUNINSTALL
10828 This is used to fill in the %preun: section in the RPM .spec file.
10829 X_RPM_PROVIDES
10831 This is used to fill in the Provides: field in the RPM .spec file.
10832 X_RPM_REQUIRES
10834 This is used to fill in the Requires: field in the RPM .spec file.
10835 X_RPM_SERIAL
10837 This is used to fill in the Serial: field in the RPM .spec file.
10838 X_RPM_URL
10840 This is used to fill in the Url: field in the RPM .spec file.
10841 XGETTEXT
10843 Path to xgettext(1) program (found via Detect()). See xgettext tool
10844 and POTUpdate builder.
10845 XGETTEXTCOM
10847 Complete xgettext command line. See xgettext tool and POTUpdate
10848 builder.
10849 XGETTEXTCOMSTR
10851 A string that is shown when xgettext(1) command is invoked
10852 (default: '', which means "print $XGETTEXTCOM"). See xgettext tool
10853 and POTUpdate builder.
10854 _XGETTEXTDOMAIN
10856 Internal "macro". Generates xgettext domain name form source and
10857 target (default: '${TARGET.filebase}').
10858 XGETTEXTFLAGS
10860 Additional flags to xgettext(1). See xgettext tool and POTUpdate
10861 builder.
10862 XGETTEXTFROM
10864 Name of file containing list of xgettext(1)'s source files.
10865 Autotools' users know this as POTFILES.in so they will in most
10866 cases set XGETTEXTFROM="POTFILES.in" here. The $XGETTEXTFROM files
10867 have same syntax and semantics as the well known GNU POTFILES.in.
10868 See xgettext tool and POTUpdate builder.
10869 _XGETTEXTFROMFLAGS
10871 Internal "macro". Genrates list of -D<dir> flags from the
10872 $XGETTEXTPATH list.
10873 XGETTEXTFROMPREFIX
10875 This flag is used to add single $XGETTEXTFROM file to xgettext(1)'s
10876 commandline (default: '-f').
10877 XGETTEXTFROMSUFFIX
10879 (default: '')
10880 XGETTEXTPATH
10882 List of directories, there xgettext(1) will look for source files
10883 (default: []).
10884 Note
10886 This variable works only together with $XGETTEXTFROM
10887 See also xgettext tool and POTUpdate builder.
10888 _XGETTEXTPATHFLAGS
10890 Internal "macro". Generates list of -f<file> flags from
10891 $XGETTEXTFROM.
10892 XGETTEXTPATHPREFIX
10894 This flag is used to add single search path to xgettext(1)'s
10895 commandline (default: '-D').
10896 XGETTEXTPATHSUFFIX
10898 (default: '')
10899 YACC
10901 The parser generator.
10902 YACCCOM
10904 The command line used to call the parser generator to generate a
10905 source file.
10906 YACCCOMSTR
10908 The string displayed when generating a source file using the parser
10909 generator. If this is not set, then $YACCCOM (the command line) is
10910 displayed.
10911 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
10913 YACCFLAGS
10915 General options passed to the parser generator. If $YACCFLAGS
10916 contains a -d option, SCons assumes that the call will also create
10917 a .h file (if the yacc source file ends in a .y suffix) or a .hpp
10918 file (if the yacc source file ends in a .yy suffix)
10919 YACCHFILESUFFIX
10921 The suffix of the C header file generated by the parser generator
10922 when the -d option is used. Note that setting this variable does
10923 not cause the parser generator to generate a header file with the
10924 specified suffix, it exists to allow you to specify what suffix the
10925 parser generator will use of its own accord. The default value is
10926 .h.
10927 YACCHXXFILESUFFIX
10929 The suffix of the C++ header file generated by the parser generator
10930 when the -d option is used. Note that setting this variable does
10931 not cause the parser generator to generate a header file with the
10932 specified suffix, it exists to allow you to specify what suffix the
10933 parser generator will use of its own accord. The default value is
10934 .hpp, except on Mac OS X, where the default is ${TARGET.suffix}.h.
10935 because the default bison parser generator just appends .h to the
10936 name of the generated C++ file.
10937 YACCVCGFILESUFFIX
10939 The suffix of the file containing the VCG grammar automaton
10940 definition when the --graph= option is used. Note that setting this
10941 variable does not cause the parser generator to generate a VCG file
10942 with the specified suffix, it exists to allow you to specify what
10943 suffix the parser generator will use of its own accord. The default
10944 value is .vcg.
10945 ZIP
10947 The zip compression and file packaging utility.
10948 ZIP_OVERRIDE_TIMESTAMP
10950 An optional timestamp which overrides the last modification time of
10951 the file when stored inside the Zip archive. This is a tuple of six
10952 values: Year (>= 1980) Month (one-based) Day of month (one-based)
10953 Hours (zero-based) Minutes (zero-based) Seconds (zero-based)
10954 ZIPCOM
10956 The command line used to call the zip utility, or the internal
10957 Python function used to create a zip archive.
10958 ZIPCOMPRESSION
10960 The compression flag from the Python zipfile module used by the
10961 internal Python function to control whether the zip archive is
10962 compressed or not. The default value is zipfile.ZIP_DEFLATED, which
10963 creates a compressed zip archive. This value has no effect if the
10964 zipfile module is unavailable.
10965 ZIPCOMSTR
10967 The string displayed when archiving files using the zip utility. If
10968 this is not set, then $ZIPCOM (the command line or internal Python
10969 function) is displayed.
10970 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
10972 ZIPFLAGS
10974 General options passed to the zip utility.
10975 ZIPROOT
10977 An optional zip root directory (default empty). The filenames
10978 stored in the zip file will be relative to this directory, if
10979 given. Otherwise the filenames are relative to the current
10980 directory of the command. For instance:
10981 env = Environment()
10983 env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
10984 will produce a zip file foo.zip containing a file with the name
10986 subdir2/file1 rather than subdir1/subdir2/file1.
10987 ZIPSUFFIX
10989 The suffix used for zip file names.
10990 Configure Contexts
10992 SCons supports a configure context, an integrated mechanism similar to
10993 the various AC_CHECK macros in GNU Autoconf for testing the existence
10994 of external items needed for the build, such as C header files,
10995 libraries, etc. The mechanism is portable across platforms.
10996 scons does not maintain an explicit cache of the tested values (this is
10998 different than Autoconf), but uses its normal dependency tracking to
10999 keep the checked values up to date. However, users may override this
11000 behaviour with the --config command line option.
11001 Configure(env, [custom_tests, conf_dir, log_file, config_h, clean,
11003 help]), env.Configure([custom_tests, conf_dir, log_file, config_h,
11004 clean, help])
11005 Create a configure context, which tracks information discovered
11006 while running tests. The context includes a local construction
11007 environment (available as context.env) which is used when running
11008 the tests and which can be updated with the check results. Only one
11009 context may be active at a time (since 4.0, scons will raise an
11010 exception on an attempt to create a new context when there is an
11011 active context), but a new context can be created after the active
11012 one is completed. For the global function form, the required env
11013 describes the initial values for the context's local construction
11014 environment; for the construction environment method form the
11015 instance provides the values.
11016 custom_tests specifies a dictionary containing custom tests (see
11018 the section on custom tests below). The default value is None,
11019 meaning no custom tests are added to the configure context.
11020 conf_dir specifies a directory where the test cases are built. This
11023 directory is not used for building normal targets. The default
11024 value is “#/.sconf_temp”.
11025 log_file specifies a file which collects the output from commands
11028 that are executed to check for the existence of header files,
11029 libraries, etc. The default is “#/config.log”. If you are using the
11030 VariantDir function, you may want to specify a subdirectory under
11031 your variant directory.
11032 config_h specifies a C header file where the results of tests will
11035 be written. The results will consist of lines like #define
11036 HAVE_STDIO_H, #define HAVE_LIBM, etc. Customarily, the name chosen
11037 is “config.h”. The default is to not write a config_h file. You can
11038 specify the same config_h file in multiple calls to Configure, in
11039 which case SCons will concatenate all results in the specified
11040 file. Note that SCons uses its normal dependency checking to decide
11041 if it's necessary to rebuild the specified config_h file. This
11042 means that the file is not necessarily re-built each time scons is
11043 run, but is only rebuilt if its contents will have changed and some
11044 target that depends on the config_h file is being built.
11045 The clean and help arguments can be used to suppress execution of
11047 the configuration tests when the -c/--clean or -H/-h/--help options
11048 are used, respectively. The default behavior is always to execute
11049 configure context tests, since the results of the tests may affect
11050 the list of targets to be cleaned or the help text. If the
11051 configure tests do not affect these, then you may add the
11052 clean=False or help=False arguments (or both) to avoid unnecessary
11053 test execution.
11054 SConf.Finish(context), context.Finish()
11056 This method must be called after configuration is done. Though
11057 required, this is not enforced except if Configure is called again
11058 while there is still an active context, in which case an exception
11059 is raised. Finish returns the environment as modified during the
11060 course of running the configuration checks. After this method is
11061 called, no further checks can be performed with this configuration
11062 context. However, you can create a new configure context to perform
11063 additional checks.
11064 Example of a typical Configure usage:
11066 env = Environment()
11068 conf = Configure(env)
11069 if not conf.CheckCHeader("math.h"):
11070 print("We really need math.h!")
11071 Exit(1)
11072 if conf.CheckLibWithHeader("qt", "qapp.h", "c++", "QApplication qapp(0,0);"):
11073 # do stuff for qt - usage, e.g.
11074 conf.env.Append(CPPDEFINES="WITH_QT")
11075 env = conf.Finish()
11076 A configure context has the following predefined methods which can be
11078 used to perform checks. Where language is a required or optional
11079 parameter, the choice can currently be C or C++. The spellings accepted
11080 for C are “C” or “c”; for C++ the value can be “CXX”, “cxx”, “C++” or
11081 “c++”.
11082 SConf.CheckHeader(context, header, [include_quotes, language]),
11084 context.CheckHeader(header, [include_quotes, language])
11085 Checks if header is usable in the specified language. header may
11086 be a list, in which case the last item in the list is the header
11087 file to be checked, and the previous list items are header files
11088 whose #include lines should precede the header line being checked
11089 for. The optional argument include_quotes must be a two character
11090 string, where the first character denotes the opening quote and the
11091 second character denotes the closing quote. By default, both
11092 characters are " (double quote). The optional argument language
11093 should be either C or C++ and selects the compiler to be used for
11094 the check. Returns a boolean indicating success or failure.
11095 SConf.CheckCHeader(context, header, [include_quotes]),
11097 context.CheckCHeader(header, [include_quotes])
11098 This is a wrapper around SConf.CheckHeader which checks if header
11099 is usable in the C language. header may be a list, in which case
11100 the last item in the list is the header file to be checked, and the
11101 previous list items are header files whose #include lines should
11102 precede the header line being checked for. The optional argument
11103 include_quotes must be a two character string, where the first
11104 character denotes the opening quote and the second character
11105 denotes the closing quote. By default, both characters are "
11106 (double quote). Returns a boolean indicating success or failure.
11107 SConf.CheckCXXHeader(context, header, [include_quotes]),
11109 context.CheckCXXHeader(header, [include_quotes])
11110 This is a wrapper around SConf.CheckHeader which checks if header
11111 is usable in the C++ language. header may be a list, in which case
11112 the last item in the list is the header file to be checked, and the
11113 previous list items are header files whose #include lines should
11114 precede the header line being checked for. The optional argument
11115 include_quotes must be a two character string, where the first
11116 character denotes the opening quote and the second character
11117 denotes the closing quote. By default, both characters are "
11118 (double quote). Returns a boolean indicating success or failure.
11119 SConf.CheckFunc(context, function_name, [header, language]),
11121 context.CheckFunc(function_name, [header, language])
11122 Checks if the specified C or C++ library function is available
11123 based on the context's local environment settings (that is, using
11124 the values of CFLAGS, CPPFLAGS, LIBS or other relevant construction
11125 variables).
11126 function_name is the name of the function to check for. The
11129 optional header argument is a string that will be placed at the top
11130 of the test file that will be compiled to check if the function
11131 exists; the default is:
11132 #ifdef __cplusplus
11134 extern "C"
11135 #endif
11136 char function_name();
11137 Returns an empty string on success, a string containing an error
11139 message on failure.
11140 SConf.CheckLib(context, [library, symbol, header, language,
11142 autoadd=True]), context.CheckLib([library, symbol, header, language,
11143 autoadd=True])
11144 Checks if library provides symbol. If autoadd is true (the default)
11145 and the library provides the specified symbol, appends the library
11146 to the LIBS construction variable library may also be None (the
11147 default), in which case symbol is checked with the current LIBS
11148 variable, or a list of library names, in which case each library in
11149 the list will be checked for symbol. If symbol is not set or is
11150 None, then SConf.CheckLib just checks if you can link against the
11151 specified library. Note though it is legal syntax, it would not be
11152 very useful to call this method with library and symbol both
11153 omitted or None. Returns a boolean indicating success or failure.
11154 SConf.CheckLibWithHeader(context, library, header, language, [call,
11156 autoadd=True]), context.CheckLibWithHeader(library, header, language,
11157 [call, autoadd=True])
11158 Provides a more sophisticated way to check against libraries then
11159 the SConf.CheckLib call. library specifies the library or a list
11160 of libraries to check. header specifies a header to check for.
11161 header may be a list, in which case the last item in the list is
11162 the header file to be checked, and the previous list items are
11163 header files whose #include lines should precede the header line
11164 being checked for. call can be any valid expression (with a
11165 trailing ';'). If call is not set, the default simply checks that
11166 you can link against the specified library. autoadd (default true)
11167 specifies whether to add the library to the environment if the
11168 check succeeds. Returns a boolean indicating success or failure.
11169 SConf.CheckType(context, type_name, [includes, language]),
11171 context.CheckType(type_name, [includes, language])
11172 Checks for the existence of a type defined by typedef. type_name
11173 specifies the typedef name to check for. includes is a string
11174 containing one or more #include lines that will be inserted into
11175 the program that will be run to test for the existence of the type.
11176 Example:
11177 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
11179 Returns an empty string on success, a string containing an error
11181 message on failure.
11182 SConf.CheckCC(context), context.CheckCC()
11184 Checks whether the C compiler (as defined by the CC construction
11185 variable) works by trying to compile a small source file. Returns a
11186 boolean indicating success or failure.
11187 By default, SCons only detects if there is a program with the
11189 correct name, not if it is a functioning compiler.
11190 This uses the exact same command as the one used by the object
11192 builder for C source files, so it can be used to detect if a
11193 particular compiler flag works or not.
11194 SConf.CheckCXX(context), context.CheckCXX()
11196 Checks whether the C++ compiler (as defined by the CXX construction
11197 variable) works by trying to compile a small source file. By
11198 default, SCons only detects if there is a program with the correct
11199 name, not if it is a functioning compiler. Returns a boolean
11200 indicating success or failure.
11201 This uses the exact same command as the one used by the object
11203 builder for C++ source files, so it can be used to detect if a
11204 particular compiler flag works or not.
11205 SConf.CheckSHCC(context), context.CheckSHCC()
11207 Checks whether the shared-object C compiler (as defined by the SHCC
11208 construction variable) works by trying to compile a small source
11209 file. By default, SCons only detects if there is a program with the
11210 correct name, not if it is a functioning compiler. Returns a
11211 boolean indicating success or failure.
11212 This uses the exact same command as the one used by the object
11214 builder for C source file, so it can be used to detect if a
11215 particular compiler flag works or not. This does not check whether
11216 the object code can be used to build a shared library, only that
11217 the compilation (not link) succeeds.
11218 SConf.CheckSHCXX(context), context.CheckSHCXX()
11220 Checks whether the shared-object C++ compiler (as defined by the
11221 SHCXX construction variable) works by trying to compile a small
11222 source file. By default, SCons only detects if there is a program
11223 with the correct name, not if it is a functioning compiler. Returns
11224 a boolean indicating success or failure.
11225 This uses the exact same command as the one used by the object
11227 builder for C++ source files, so it can be used to detect if a
11228 particular compiler flag works or not. This does not check whether
11229 the object code can be used to build a shared library, only that
11230 the compilation (not link) succeeds.
11231 SConf.CheckTypeSize(context, type_name, [header, language, expect]),
11233 context.CheckTypeSize(type_name, [header, language, expect])
11234 Checks for the size of a type defined by typedef. type_name
11235 specifies the typedef name to check for. The optional header
11236 argument is a string that will be placed at the top of the test
11237 file that will be compiled to check if the type exists; the default
11238 is empty. If the optional expect, is supplied, it should be an
11239 integer size; CheckTypeSize will fail unless type_name is actually
11240 that size. Returns the size in bytes, or zero if the type was not
11241 found (or if the size did not match expect).
11242 For example,
11244 CheckTypeSize('short', expect=2)
11246 will return the size 2 only if short is actually two bytes.
11248 SConf.CheckDeclaration(context, symbol, [includes, language]),
11250 context.CheckDeclaration(symbol, [includes, language])
11251 Checks if the specified symbol is declared. includes is a string
11252 containing one or more #include lines that will be inserted into
11253 the program that will be run to test for the existence of the
11254 symbol. Returns a boolean indicating success or failure.
11255 SConf.Define(context, symbol, [value, comment]), context.Define(symbol,
11257 [value, comment])
11258 This function does not check for anything, but defines a
11259 preprocessor symbol that will be added to the configuration header
11260 file. It is the equivalent of AC_DEFINE, and defines the symbol
11261 name with the optional value and the optional comment comment.
11262 Define Examples:
11264 env = Environment()
11266 conf = Configure(env)
11267 # Puts the following line in the config header file:
11269 # #define A_SYMBOL
11270 conf.Define("A_SYMBOL")
11271 # Puts the following line in the config header file:
11273 # #define A_SYMBOL 1
11274 conf.Define("A_SYMBOL", 1)
11275 Be careful about quoting string values, though:
11277 env = Environment()
11279 conf = Configure(env)
11280 # Puts the following line in the config header file:
11282 # #define A_SYMBOL YA
11283 conf.Define("A_SYMBOL", "YA")
11284 # Puts the following line in the config header file:
11286 # #define A_SYMBOL "YA"
11287 conf.Define("A_SYMBOL", '"YA"')
11288 For comment:
11290 env = Environment()
11292 conf = Configure(env)
11293 # Puts the following lines in the config header file:
11295 # /* Set to 1 if you have a symbol */
11296 # #define A_SYMBOL 1
11297 conf.Define("A_SYMBOL", 1, "Set to 1 if you have a symbol")
11298 You can define your own custom checks in addition to the predefined
11300 checks. You pass a dictionary of these to the Configure function as the
11301 custom_tests argument. This dictionary maps the names of the checks to
11302 the user defined Python callables (either Python functions or class
11303 instances implementing a __call__ method). Each custom check will be
11304 called with a first argument of a CheckContext, instance followed by
11305 the arguments, which must be supplied by the user of the check. A
11306 CheckContext instance defines the following methods:
11307 context.Message(text)
11309 Displays a message, as an indicator of progess. text will be
11310 displayed, e.g. Checking for library X.... Usually called before
11311 the check is started.
11312 context.Result(res)
11314 Displays a “result” message, as an indicator of progress. res can
11315 be either an integer or a string. If an integer, displays yes (if
11316 res evaluates True) or no (if res evaluates False). If a string, it
11317 is displayed as-is. Usually called after the check has completed.
11318 context.TryCompile(text, extension='')
11320 Checks if a file with the specified extension (e.g. '.c')
11321 containing text can be compiled using the environment's Object
11322 builder. Returns a boolean indicating success or failure.
11323 context.TryLink(text, extension='')
11325 Checks, if a file with the specified extension (e.g. '.c')
11326 containing text can be compiled using the environment's Program
11327 builder. Returns a boolean indicating success or failure.
11328 context.TryRun(text, extension='')
11330 Checks if a file with the specified extension (e.g. '.c')
11331 containing text can be compiled using the environment's Program
11332 builder. On success, the program is run. If the program executes
11333 successfully (that is, its return status is 0), a tuple (1,
11334 outputStr) is returned, where outputStr is the standard output of
11335 the program. If the program fails execution (its return status is
11336 non-zero), then (0, '') is returned.
11337 context.TryAction(action, [text, extension=''])
11339 Checks if the specified action with an optional source file
11340 (contents text, extension extension) can be executed. action may
11341 be anything which can be converted to a scons Action. On success,
11342 (1, outputStr) is returned, where outputStr is the content of the
11343 target file. On failure (0, '') is returned.
11344 context.TryBuild(builder[, text, extension=''])
11346 Low level implementation for testing specific builds; the methods
11347 above are based on this method. Given the Builder instance builder
11348 and the optional text of a source file with optional extension,
11349 returns a boolean indicating success or failure. In addition,
11350 context.lastTarget is set to the build target node if the build was
11351 successful.
11352 Example of implementing and using custom tests:
11354 def CheckQt(context, qtdir):
11356 context.Message( 'Checking for qt ...' )
11357 lastLIBS = context.env['LIBS']
11358 lastLIBPATH = context.env['LIBPATH']
11359 lastCPPPATH= context.env['CPPPATH']
11360 context.env.Append(LIBS='qt', LIBPATH=qtdir + '/lib', CPPPATH=qtdir + '/include')
11361 ret = context.TryLink("""
11362 #include <qapp.h>
11363 int main(int argc, char **argv) {
11364 QApplication qapp(argc, argv);
11365 return 0;
11366 }
11367 """)
11368 if not ret:
11369 context.env.Replace(LIBS=lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
11370 context.Result( ret )
11371 return ret
11372 env = Environment()
11374 conf = Configure(env, custom_tests={'CheckQt': CheckQt})
11375 if not conf.CheckQt('/usr/lib/qt'):
11376 print('We really need qt!')
11377 Exit(1)
11378 env = conf.Finish()
11379 Command-Line Construction Variables
11381 Often when building software, some variables need to be specified at
11382 build time. For example, libraries needed for the build may be in
11383 non-standard locations, or site-specific compiler options may need to
11384 be passed to the compiler. SCons provides a Variables object to
11385 support overriding construction variables with values obtained from
11386 various sources, often from the command line:
11387 scons VARIABLE=foo
11389 The variable values can also be specified in a configuration file or an
11391 SConscript file.
11392 To obtain the object for manipulating values, call the Variables
11394 function:
11395 Variables([files, [args]])
11397 If files is a file or list of files, they are executed as Python
11398 scripts, and the values of (global) Python variables set in those
11399 files are added as construction variables in the Default
11400 Environment. If no files are specified, or the files argument is
11401 None, then no files will be read (supplying None is necessary if
11402 there are no files but you want to specify args as a positional
11403 argument).
11404 The following example file contents could be used to set an
11406 alternative C compiler:
11407 CC = 'my_cc'
11409 If args is specified, it is a dictionary of values that will
11411 override anything read from files. The primary use is to pass the
11412 ARGUMENTS dictionary that holds variables specified on the command
11413 line, allowing you to indicate that if a setting appears on both
11414 the command line and in the file(s), the command line setting takes
11415 precedence. However, any dictionary can be passed. Examples:
11416 vars = Variables('custom.py')
11418 vars = Variables('overrides.py', ARGUMENTS)
11419 vars = Variables(None, {FOO:'expansion', BAR:7})
11420 Calling Variables with no arguments is equivalent to:
11422 vars = Variables(files=None, args=ARGUMENTS)
11424 Note that since the variables are eventually added as construction
11426 variables, you should choose variable names which do not
11427 unintentionally change pre-defined construction variables that your
11428 project will make use of (see the section called “Construction
11429 Variables”).
11430 Variables objects have the following methods:
11432 vars.Add(key, [help, default, validator, converter])
11434 Add a customizable construction variable to the Variables object.
11435 key is either the name of the variable, or a tuple (or list), in
11436 which case the first item in the tuple is taken as the variable
11437 name, and any remaining values are considered aliases for the
11438 variable. help is the help text for the variable (default empty
11439 string). default is the default value of the variable (default
11440 None). If default is None and a value is not specified, the
11441 construction variable will not be added to the construction
11442 environment.
11443 As a special case, if key is a tuple (or list) and is the only
11445 argument, the tuple is unpacked into the five parameters listed
11446 above left to right, with any missing members filled with the
11447 respecitive default values. This form allows Add to consume a tuple
11448 emitted by the convenience functions BoolVariable, EnumVariable,
11449 ListVariable, PackageVariable and PathVariable.
11450 If the optional validator is supplied, it is called to validate the
11452 value of the variable. A function supplied as a validator must
11453 accept three arguments: key, value and env, and should raise an
11454 exception with a helpful error message if value is invalid. No
11455 return value is expected from the validator.
11456 If the optional converter is supplied, it is called to convert the
11458 value before putting it in the environment, and should take either
11459 a value or a value and environment as parameters. The converter
11460 function must return a value, which will be converted into a string
11461 and be passed to the validator (if any) and then added to the
11462 construction environment.
11463 Examples:
11465 vars.Add('CC', help='The C compiler')
11467 def valid_color(key, val, env):
11469 if not val in ['red', 'blue', 'yellow']:
11470 raise Exception("Invalid color value '%s'" % val)
11471 vars.Add('COLOR', validator=valid_color)
11473 vars.AddVariables(args)
11475 A convenience method that adds one or more customizable
11476 construction variables to a Variables object in one call;
11477 equivalent to calling Add multiple times. The args are tuples (or
11478 lists) that contain the arguments for an individual call to the Add
11479 method. Since tuples are not Python mappings, the arguments cannot
11480 use the keyword form, but rather are positional arguments as
11481 documented for Add: a required name, the other four optional, but
11482 must be in the specified order if used.
11483 opt.AddVariables(
11485 ("debug", "", 0),
11486 ("CC", "The C compiler"),
11487 ("VALIDATE", "An option for testing validation", "notset", validator, None),
11488 )
11489 vars.Update(env, [args])
11491 Update a construction environment env with the customized
11492 construction variables. Any specified variables that are not
11493 configured for the Variables object will be saved and may be
11494 retrieved using the UnknownVariables method.
11495 Normally this method is not called directly, but rather invoked
11497 indirectly by passing the Variables object to the Environment
11498 function:
11499 env = Environment(variables=vars)
11501 vars.UnknownVariables()
11503 Returns a dictionary containing any variables that were specified
11504 either in the files or the dictionary with which the Variables
11505 object was initialized, but for which the Variables object was not
11506 configured.
11507 env = Environment(variables=vars)
11509 for key, value in vars.UnknownVariables():
11510 print("unknown variable: %s=%s" % (key, value))
11511 vars.Save(filename, env)
11513 Save the currently set variables into a script file named by
11514 filename. Only variables that are set to non-default values are
11515 saved. You can load these saved settings on a subsequent run by
11516 passing filename to the Variables function, providing a way to
11517 cache particular settings for reuse.
11518 env = Environment()
11520 vars = Variables(['variables.cache', 'custom.py'])
11521 vars.Add(...)
11522 vars.Update(env)
11523 vars.Save('variables.cache', env)
11524 vars.GenerateHelpText(env, [sort])
11526 Generate help text documenting the customizable construction
11527 variables, suitable for passing in to the Help function. env is
11528 the construction environment that will be used to get the actual
11529 values of the customizable variables. If the (optional) value of
11530 sort is callable, it is used as a comparison function to determine
11531 how to sort the added variables. This function must accept two
11532 arguments, compare them, and return a negative integer if the first
11533 is less-than the second, zero for equality, or a positive integer
11534 for greater-than. Optionally a Boolean value of True for sort will
11535 cause a standard alphabetical sort to be performed.
11536 Help(vars.GenerateHelpText(env))
11538 def cmp(a, b):
11540 return (a > b) - (a < b)
11541 Help(vars.GenerateHelpText(env, sort=cmp))
11543 vars.FormatVariableHelpText(env, opt, help, default, actual)
11545 Returns a formatted string containing the printable help text for
11546 one option. It is normally not called directly, but is called by
11547 the GenerateHelpText method to create the returned help text. It
11548 may be overridden with your own function that takes the arguments
11549 specified above and returns a string of help text formatted to your
11550 liking. Note that GenerateHelpText will not put any blank lines or
11551 extra characters in between the entries, so you must add those
11552 characters to the returned string if you want the entries
11553 separated.
11554 def my_format(env, opt, help, default, actual):
11556 fmt = "\n%s: default=%s actual=%s (%s)\n"
11557 return fmt % (opt, default, actual, help)
11558 vars.FormatVariableHelpText = my_format
11560 To make it more convenient to work with customizable Variables, scons
11562 provides a number of functions that make it easy to set up various
11563 types of Variables. Each of these return a tuple ready to be passed to
11564 the Add or AddVariables method:
11565 BoolVariable(key, help, default)
11567 Returns a tuple of arguments to set up a Boolean option. The option
11568 will use the specified name key, have a default value of default,
11569 and help will form the descriptive part of the help text. The
11570 option will interpret the values y, yes, t, true, 1, on and all as
11571 true, and the values n, no, f, false, 0, off and none as false.
11572 EnumVariable(key, help, default, allowed_values, [map, ignorecase])
11574 Returns a tuple of arguments to set up an option whose value may be
11575 one of a specified list of legal enumerated values. The option will
11576 use the specified name key, have a default value of default, and
11577 help will form the descriptive part of the help text. The option
11578 will only support those values in the allowed_values list. The
11579 optional map argument is a dictionary that can be used to convert
11580 input values into specific legal values in the allowed_values list.
11581 If the value of ignore_case is 0 (the default), then the values are
11582 case-sensitive. If the value of ignore_case is 1, then values will
11583 be matched case-insensitively. If the value of ignore_case is 2,
11584 then values will be matched case-insensitively, and all input
11585 values will be converted to lower case.
11586 ListVariable(key, help, default, names, [map])
11588 Returns a tuple of arguments to set up an option whose value may be
11589 one or more of a specified list of legal enumerated values. The
11590 option will use the specified name key, have a default value of
11591 default, and help will form the descriptive part of the help text.
11592 The option will only accept the values “all”, “none”, or the values
11593 in the names list. More than one value may be specified, separated
11594 by commas. The default may be a string of comma-separated default
11595 values, or a list of the default values. The optional map argument
11596 is a dictionary that can be used to convert input values into
11597 specific legal values in the names list. (Note that the additional
11598 values accepted through the use of a map are not reflected in the
11599 generated help message).
11600 PackageVariable(key, help, default)
11602 Returns a tuple of arguments to set up an option whose value is a
11603 path name of a package that may be enabled, disabled or given an
11604 explicit path name. The option will use the specified name key,
11605 have a default value of default, and help will form the descriptive
11606 part of the help text. The option will support the values yes,
11607 true, on, enable or search, in which case the specified default
11608 will be used, or the option may be set to an arbitrary string
11609 (typically the path name to a package that is being enabled). The
11610 option will also support the values no, false, off or disable to
11611 disable use of the specified option.
11612 PathVariable(key, help, default, [validator])
11614 Returns a tuple of arguments to set up an option whose value is
11615 expected to be a path name. The option will use the specified name
11616 key, have a default value of default, and help will form the
11617 descriptive part of the help text. An additional validator may be
11618 specified that will be called to verify that the specified path is
11619 acceptable. SCons supplies the following ready-made validators:
11620 PathVariable.PathExists
11622 Verify that the specified path exists (this the default
11623 behavior if no validator is supplied).
11624 PathVariable.PathIsFile
11626 Verify that the specified path exists and is a regular file.
11627 PathVariable.PathIsDir
11629 Verify that the specified path exists and is a directory.
11630 PathVariable.PathIsDirCreate
11632 Verify that the specified path exists and is a directory; if it
11633 does not exist, create the directory.
11634 PathVariable.PathAccept
11636 Accept the specific path name argument without validation,
11637 suitable for when you want your users to be able to specify a
11638 directory path that will be created as part of the build
11639 process, for example.
11640 You may supply your own validator function, which must accept three
11642 arguments (key, the name of the variable to be set; val, the
11643 specified value being checked; and env, the construction
11644 environment) and should raise an exception if the specified value
11645 is not acceptable.
11646 These functions make it convenient to create a number of variables with
11648 consistent behavior in a single call to the AddVariables method:
11649 vars.AddVariables(
11651 BoolVariable(
11652 "warnings",
11653 help="compilation with -Wall and similar",
11654 default=1,
11655 ),
11656 EnumVariable(
11657 "debug",
11658 help="debug output and symbols",
11659 default="no",
11660 allowed_values=("yes", "no", "full"),
11661 map={},
11662 ignorecase=0, # case sensitive
11663 ),
11664 ListVariable(
11665 "shared",
11666 help="libraries to build as shared libraries",
11667 default="all",
11668 names=list_of_libs,
11669 ),
11670 PackageVariable(
11671 "x11",
11672 help="use X11 installed here (yes = search some places)",
11673 default="yes",
11674 ),
11675 PathVariable(
11676 "qtdir",
11677 help="where the root of Qt is installed",
11678 default=qtdir),
11679 PathVariable(
11680 "foopath",
11681 help="where the foo library is installed",
11682 default=foopath,
11683 validator=PathVariable.PathIsDir,
11684 ),
11685 )
11686 File and Directory Nodes
11688 The File and Dir functions/methods return File and Directory Nodes,
11689 respectively. Such nodes are Python objects with several user-visible
11690 attributes and methods that are often useful to access in SConscript
11691 files:
11692 n.path
11694 The build path of the given file or directory. This path is
11695 relative to the top-level directory (where the SConstruct file is
11696 found). The build path is the same as the source path if
11697 variant_dir is not being used.
11698 n.abspath
11700 The absolute build path of the given file or directory.
11701 n.relpath
11703 The build path of the given file or directory relative to the root
11704 SConstruct file's directory.
11705 n.srcnode()
11707 The srcnode method returns another File or Directory Node
11708 representing the source path of the given File or Directory Node.
11709 For example:
11711 # Get the current build dir's path, relative to top.
11713 Dir('.').path
11714 # Current dir's absolute path
11715 Dir('.').abspath
11716 # Current dir's path relative to the root SConstruct file's directory
11717 Dir('.').relpath
11718 # Next line is always '.', because it is the top dir's path relative to itself.
11719 Dir('#.').path
11720 File('foo.c').srcnode().path # source path of the given source file.
11721 # Builders also return File objects:
11723 foo = env.Program('foo.c')
11724 print("foo will be built in", foo.path)
11725 File and Directory Node objects have methods to create File and
11727 Directory Nodes relative to the original Node.
11728 If the object is a Directory Node, these methods will place the the new
11730 Node within the directory the Node represents:
11731 d.Dir(name)
11733 Returns a directory Node for a subdirectory of d named name.
11734 d.File(name)
11736 Returns a file Node for a file within d named name.
11737 d.Entry(name)
11739 Returns an unresolved Node within d named name.
11740 If the object is a File Node, these methods will place the the new Node
11742 in the same directory as the one the Node represents:
11743 f.Dir(name)
11745 Returns a directory named name within the parent directory of f.
11746 f.File(name)
11748 Returns a file named name within the parent directory of f.
11749 f.Entry(name)
11751 Returns an unresolved Node named name within the parent directory
11752 of f.
11753 For example:
11755 # Get a Node for a file within a directory
11757 incl = Dir('include')
11758 f = incl.File('header.h')
11759 # Get a Node for a subdirectory within a directory
11761 dist = Dir('project-3.2.1')
11762 src = dist.Dir('src')
11763 # Get a Node for a file in the same directory
11765 cfile = File('sample.c')
11766 hfile = cfile.File('sample.h')
11767 # Combined example
11769 docs = Dir('docs')
11770 html = docs.Dir('html')
11771 index = html.File('index.html')
11772 css = index.File('app.css')
11773
11775 Builder Objects
11776 scons can be extended to build different types of targets by adding new
11777 Builder objects to a construction environment. In general, you should
11778 only need to add a new Builder object when you want to build a new type
11779 of file or other external target. For output file types scons already
11780 knows about, you can usually modify the behavior of premade Builders
11781 such as Program, Object or Library by changing the construction
11782 variables they use ($CC, $LINK, etc.). In this manner you can, for
11783 example, change the compiler to use, which is simpler and less
11784 error-prone than writing a new builder. The documentation for each
11785 Builder lists which construction variables it uses.
11786 Builder objects are created using the Builder factory function. Once
11788 created, a builder is added to an environment by entering it in the
11789 $BUILDERS dictionary in that environment (some of the examples in this
11790 section illustrate that).
11791 The Builder function accepts the following keyword arguments:
11793 action
11795 The command used to build the target from the source. action may
11796 be a string representing a template command line to execute, a list
11797 of strings representing the command to execute with its arguments
11798 (suitable for enclosing white space in an argument), a dictionary
11799 mapping source file name suffixes to any combination of command
11800 line strings (if the builder should accept multiple source file
11801 extensions), a Python function, an Action object (see the section
11802 called “Action Objects”) or a list of any of the above.
11803 An action function must accept three arguments: source, target and
11805 env. source is a list of source nodes; target is a list of target
11806 nodes; env is the construction environment to use for context.
11807 The action and generator arguments must not both be used for the
11809 same Builder.
11810 prefix
11812 The prefix to prepend to the target file name. prefix may be a
11813 string, a function (or other callable) that takes two arguments (a
11814 construction environment and a list of sources) and returns a
11815 prefix string, or a dictionary specifying a mapping from a specific
11816 source suffix (of the first source specified) to a corresponding
11817 target prefix string. For the dictionary form, both the source
11818 suffix (key) and target prefix (value) specifications may use
11819 environment variable substitution, and the target prefix may also
11820 be a callable object. The default target prefix may be indicated by
11821 a dictionary entry with a key of None.
11822 b = Builder("build_it < $SOURCE > $TARGET",
11824 prefix="file-")
11825 def gen_prefix(env, sources):
11827 return "file-" + env['PLATFORM'] + '-'
11828 b = Builder("build_it < $SOURCE > $TARGET",
11830 prefix=gen_prefix)
11831 b = Builder("build_it < $SOURCE > $TARGET",
11833 suffix={None: "file-", "$SRC_SFX_A": gen_prefix})
11834 suffix
11836 The suffix to append to the target file name. Specified in the same
11837 manner as for prefix above. If the suffix is a string, then scons
11838 prepends a '.' to the suffix if it's not already there. The string
11839 returned by the callable object or obtained from the dictionary is
11840 untouched and you need to manually prepend a '.' if one is
11841 required.
11842 b = Builder("build_it < $SOURCE > $TARGET"
11844 suffix="-file")
11845 def gen_suffix(env, sources):
11847 return "." + env['PLATFORM'] + "-file"
11848 b = Builder("build_it < $SOURCE > $TARGET",
11850 suffix=gen_suffix)
11851 b = Builder("build_it < $SOURCE > $TARGET",
11853 suffix={None: ".sfx1", "$SRC_SFX_A": gen_suffix})
11854 ensure_suffix
11856 If set to a true value, ensures that targets will end in suffix.
11857 Thus, the suffix will also be added to any target strings that have
11858 a suffix that is not already suffix. The default behavior (also
11859 indicated by a false value) is to leave unchanged any target string
11860 that looks like it already has a suffix.
11861 b1 = Builder("build_it < $SOURCE > $TARGET"
11863 suffix = ".out")
11864 b2 = Builder("build_it < $SOURCE > $TARGET"
11865 suffix = ".out",
11866 ensure_suffix=True)
11867 env = Environment()
11868 env['BUILDERS']['B1'] = b1
11869 env['BUILDERS']['B2'] = b2
11870 # Builds "foo.txt" because ensure_suffix is not set.
11872 env.B1('foo.txt', 'foo.in')
11873 # Builds "bar.txt.out" because ensure_suffix is set.
11875 env.B2('bar.txt', 'bar.in')
11876 src_suffix
11878 The expected source file name suffix. src_suffix may be a string
11879 or a list of strings.
11880 target_scanner
11882 A Scanner object that will be invoked to find implicit dependencies
11883 for this target file. This keyword argument should be used for
11884 Scanner objects that find implicit dependencies based only on the
11885 target file and the construction environment, not for implicit
11886 dependencies based on source files. See the section called “Scanner
11887 Objects” for information about creating Scanner objects.
11888 source_scanner
11890 A Scanner object that will be invoked to find implicit dependencies
11891 in any source files used to build this target file. This is where
11892 you would specify a scanner to find things like #include lines in
11893 source files. The pre-built DirScanner Scanner object may be used
11894 to indicate that this Builder should scan directory trees for
11895 on-disk changes to files that scons does not know about from other
11896 Builder or function calls. See the section called “Scanner Objects”
11897 for information about creating your own Scanner objects.
11898 target_factory
11900 A factory function that the Builder will use to turn any targets
11901 specified as strings into SCons Nodes. By default, SCons assumes
11902 that all targets are files. Other useful target_factory values
11903 include Dir, for when a Builder creates a directory target, and
11904 Entry, for when a Builder can create either a file or directory
11905 target.
11906 Example:
11908 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
11910 env = Environment()
11911 env.Append(BUILDERS={'MakeDirectory': MakeDirectoryBuilder})
11912 env.MakeDirectory('new_directory', [])
11913 Note that the call to this MakeDirectory Builder needs to specify
11915 an empty source list to make the string represent the builder's
11916 target; without that, it would assume the argument is the source,
11917 and would try to deduce the target name from it, which in the
11918 absence of an automatically-added prefix or suffix would lead to a
11919 matching target and source name and a circular dependency.
11920 source_factory
11922 A factory function that the Builder will use to turn any sources
11923 specified as strings into SCons Nodes. By default, SCons assumes
11924 that all source are files. Other useful source_factory values
11925 include Dir, for when a Builder uses a directory as a source, and
11926 Entry, for when a Builder can use files or directories (or both) as
11927 sources.
11928 Example:
11930 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
11932 env = Environment()
11933 env.Append(BUILDERS={'Collect': CollectBuilder})
11934 env.Collect('archive', ['directory_name', 'file_name'])
11935 emitter
11937 A function or list of functions to manipulate the target and source
11938 lists before dependencies are established and the target(s) are
11939 actually built. emitter can also be a string containing a
11940 construction variable to expand to an emitter function or list of
11941 functions, or a dictionary mapping source file suffixes to emitter
11942 functions. (Only the suffix of the first source file is used to
11943 select the actual emitter function from an emitter dictionary.)
11944 A function passed as emitter must accept three arguments: source,
11946 target and env. source is a list of source nodes, target is a list
11947 of target nodes, env is the construction environment to use for
11948 context.
11949 An emitter must return a tuple containing two lists, the list of
11951 targets to be built by this builder, and the list of sources for
11952 this builder.
11953 Example:
11955 def e(target, source, env):
11957 return (target + ['foo.foo'], source + ['foo.src'])
11958 # Simple association of an emitter function with a Builder.
11960 b = Builder("my_build < $TARGET > $SOURCE",
11961 emitter = e)
11962 def e2(target, source, env):
11964 return (target + ['bar.foo'], source + ['bar.src'])
11965 # Simple association of a list of emitter functions with a Builder.
11967 b = Builder("my_build < $TARGET > $SOURCE",
11968 emitter = [e, e2])
11969 # Calling an emitter function through a construction variable.
11971 env = Environment(MY_EMITTER=e)
11972 b = Builder("my_build < $TARGET > $SOURCE",
11973 emitter='$MY_EMITTER')
11974 # Calling a list of emitter functions through a construction variable.
11976 env = Environment(EMITTER_LIST=[e, e2])
11977 b = Builder("my_build < $TARGET > $SOURCE",
11978 emitter='$EMITTER_LIST')
11979 # Associating multiple emitters with different file
11981 # suffixes using a dictionary.
11982 def e_suf1(target, source, env):
11983 return (target + ['another_target_file'], source)
11984 def e_suf2(target, source, env):
11985 return (target, source + ['another_source_file'])
11986 b = Builder("my_build < $TARGET > $SOURCE",
11987 emitter={'.suf1' : e_suf1,
11988 '.suf2' : e_suf2})
11989 multi
11991 Specifies whether this builder is allowed to be called multiple
11992 times for the same target file(s). The default is False, which
11993 means the builder can not be called multiple times for the same
11994 target file(s). Calling a builder multiple times for the same
11995 target simply adds additional source files to the target; it is not
11996 allowed to change the environment associated with the target,
11997 specify additional environment overrides, or associate a different
11998 builder with the target.
11999 env
12001 A construction environment that can be used to fetch source code
12002 using this Builder. (Note that this environment is not used for
12003 normal builds of normal target files, which use the environment
12004 that was used to call the Builder for the target file.)
12005 generator
12007 A function that returns a list of actions that will be executed to
12008 build the target(s) from the source(s). The returned action(s) may
12009 be an Action object, or anything that can be converted into an
12010 Action object (see the next section).
12011 A function passed as generator must accept four arguments: source,
12013 target, env and for_signature. source is a list of source nodes,
12014 target is a list of target nodes, env is the construction
12015 environment to use for context, for_signature is a Boolean value
12016 that specifies whether the generator is being called for generating
12017 a build signature (as opposed to actually executing the command).
12018 Example:
12020 def g(source, target, env, for_signature):
12022 return [["gcc", "-c", "-o"] + target + source]
12023 b = Builder(generator=g)
12025 The generator and action arguments must not both be used for the
12027 same Builder.
12028 src_builder
12030 Specifies a builder to use when a source file name suffix does not
12031 match any of the suffixes of the builder. Using this argument
12032 produces a multi-stage builder.
12033 single_source
12035 Specifies that this builder expects exactly one source file per
12036 call. Giving more than one source file without target files results
12037 in implicitly calling the builder multiple times (once for each
12038 source given). Giving multiple source files together with target
12039 files results in a UserError exception.
12040 source_ext_match
12042 When the specified action argument is a dictionary, the default
12043 behavior when a builder is passed multiple source files is to make
12044 sure that the extensions of all the source files match. If it is
12045 legal for this builder to be called with a list of source files
12046 with different extensions, this check can be suppressed by setting
12047 source_ext_match to False or some other non-true value. In this
12048 case, scons will use the suffix of the first specified source file
12049 to select the appropriate action from the action dictionary.
12050 In the following example, the setting of source_ext_match prevents
12052 scons from exiting with an error due to the mismatched suffixes of
12053 foo.in and foo.extra.
12054 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
12056 source_ext_match=False)
12057 env = Environment(BUILDERS={'MyBuild':b})
12059 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
12060 env
12062 A construction environment that can be used to fetch source code
12063 using this Builder. (Note that this environment is not used for
12064 normal builds of normal target files, which use the environment
12065 that was used to call the Builder for the target file.)
12066 b = Builder(action="build < $SOURCE > $TARGET")
12068 env = Environment(BUILDERS={'MyBuild' : b})
12069 env.MyBuild('foo.out', 'foo.in', my_arg='xyzzy')
12070 chdir
12072 A directory from which scons will execute the action(s) specified
12073 for this Builder. If the chdir argument is a string or a directory
12074 Node, scons will change to the specified directory. If the chdir is
12075 not a string or Node and is non-zero, then scons will change to the
12076 target file's directory.
12077 Note that scons will not automatically modify its expansion of
12079 construction variables like $TARGET and $SOURCE when using the
12080 chdir keyword argument--that is, the expanded file names will still
12081 be relative to the top-level directory containing the SConstruct
12082 file, and consequently incorrect relative to the chdir directory.
12083 Builders created using chdir keyword argument, will need to use
12084 construction variable expansions like ${TARGET.file} and
12085 ${SOURCE.file} to use just the filename portion of the targets and
12086 source.
12087 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
12089 chdir=1)
12090 env = Environment(BUILDERS={'MyBuild' : b})
12091 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
12092 Warning
12094 Python only keeps one current directory location even if there
12095 are multiple threads. This means that use of the chdir argument
12096 will not work with the SCons -j option, because individual
12097 worker threads spawned by SCons interfere with each other when
12098 they start changing directory.
12099 Any additional keyword arguments supplied when a Builder object is
12101 created (that is, when the Builder function is called) will be set in
12102 the executing construction environment when the Builder object is
12103 called. The canonical example here would be to set a construction
12104 variable to the repository of a source code system.
12105 Any additional keyword arguments supplied when a Builder object is
12107 called will only be associated with the target created by that
12108 particular Builder call (and any other files built as a result of the
12109 call).
12110 These extra keyword arguments are passed to the following functions:
12112 command generator functions, function Actions, and emitter functions.
12113 Action Objects
12115 The Builder factory function will turn its action keyword argument into
12116 an appropriate internal Action object, as will the Command function.
12117 You can also explicitly create Action objects for passing to Builder,
12118 or other functions that take actions as arguments, by calling the
12119 Action factory function. This may more efficient when multiple Builder
12120 objects need to do the same thing rather than letting each of those
12121 Builder objects create a separate Action object. It also allows more
12122 flexible configuration of an Action object. For example, to control the
12123 message printed when the action is taken you need to create the action
12124 object using Action.
12125 The Action factory function returns an appropriate object for the
12127 action represented by the type of the action argument (the first
12128 positional parmeter):
12129 • If action is already an Action object, the object is simply
12131 returned.
12132 • If action is a string, a command-line Action is returned. If such a
12134 string begins with @, the command line is not printed. If the
12135 string begins with hyphen (-), the exit status from the specified
12136 command is ignored, allowing execution to continue even if the
12137 command reports failure:
12138 Action('$CC -c -o $TARGET $SOURCES')
12140 # Doesn't print the line being executed.
12142 Action('@build $TARGET $SOURCES')
12143 # Ignores return value
12145 Action('-build $TARGET $SOURCES')
12146 • If action is a list, then a list of Action objects is returned. An
12148 Action object is created as necessary for each element in the list.
12149 If an element within the list is itself a list, the embedded list
12150 is taken as the command and arguments to be executed via the
12151 command line. This allows white space to be enclosed in an argument
12152 rather than taken as a separator by defining a command in a list
12153 within a list:
12154 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
12156 • If action is a callable object, a Function Action is returned. The
12158 callable must accept three keyword arguments: target, source and
12159 env. target is a Node object representing the target file, source
12160 is a Node object representing the source file and env is the
12161 construction environment used for building the target file.
12162 The target and source arguments may be lists of Node objects if
12164 there is more than one target file or source file. The actual
12165 target and source file name(s) may be retrieved from their Node
12166 objects via the built-in Python str function:
12167 target_file_name = str(target)
12169 source_file_names = [str(x) for x in source]
12170 The function should return 0 or None to indicate a successful build
12172 of the target file(s). The function may raise an exception or
12173 return a non-zero exit status to indicate an unsuccessful build.
12174 def build_it(target=None, source=None, env=None):
12176 # build the target from the source
12177 return 0
12178 a = Action(build_it)
12180 • If action is not one of the above types, no action object is
12182 generated and Action returns None.
12183 The environment method form env.Action will expand construction
12185 variables in any argument strings, including action, at the time it is
12186 called, using the construction variables in the construction
12187 environment through which it was called. The global function form
12188 Action delays variable expansion until the Action object is actually
12189 used.
12190 The optional second argument to Action is used to control the output
12192 which is printed when the Action is actually performed. If this
12193 parameter is omitted, or if the value is an empty string, a default
12194 output depending on the type of the action is used. For example, a
12195 command-line action will print the executed command. The following
12196 argument types are accepted:
12197 • If output is a string, substitution is performed on the string
12199 before it is printed. The string typically contains variables,
12200 notably $TARGET(S) and $SOURCE(S), or consists of just a single
12201 variable, which is optionally defined somewhere else. SCons itself
12202 heavily uses the latter variant.
12203 • If output is a function, the function will be called to obtain a
12205 string describing the action being executed. The function must
12206 accept three keyword arguments: target, source and env, with the
12207 same interpretation as for a callable action argument above.
12208 • If outputis None, output is suppressed entirely.
12210 Instead of using a positional argument, the cmdstr keyword argument may
12212 be used to specify the output string, or the strfunction keyword
12213 argument may be used to specify a function to return the output string.
12214 cmdstr=None suppresses output entirely.
12215 Examples:
12217 def build_it(target, source, env):
12219 # build the target from the source
12220 return 0
12221 def string_it(target, source, env):
12223 return "building '%s' from '%s'" % (target[0], source[0])
12224 # Use a positional argument.
12226 f = Action(build_it, string_it)
12227 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
12228 # Alternatively, use a keyword argument.
12230 f = Action(build_it, strfunction=string_it)
12231 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
12232 # You can provide a configurable variable.
12234 l = Action(build_it, '$STRINGIT')
12235 Any additional positional arguments, if present, may either be
12237 construction variables or lists of construction variables whose values
12238 will be included in the signature of the Action when deciding whether a
12239 target should be rebuilt because the action changed. Such variables may
12240 also be specified using the varlist keyword parameter; both positional
12241 and keyword forms may be present, and will be combined. This is
12242 necessary whenever you want a target to be rebuilt when a specific
12243 construction variable changes. This is not often needed for a string
12244 action, as the expanded variables will normally be part of the command
12245 line, but may be needed if a Python function action uses the value of a
12246 construction variable when generating the command line.
12247 def build_it(target, source, env):
12249 # build the target from the 'XXX' construction variable
12250 with open(target[0], 'w') as f:
12251 f.write(env['XXX'])
12252 return 0
12253 # Use positional arguments.
12255 a = Action(build_it, '$STRINGIT', ['XXX'])
12256 # Alternatively, use a keyword argument.
12258 a = Action(build_it, varlist=['XXX'])
12259 The Action factory function can be passed the following optional
12261 keyword arguments to modify the Action object's behavior:
12262 chdir
12264 If chdir is true (the default is False), SCons will change
12265 directories before executing the action. If the value of chdir is a
12266 string or a directory Node, SCons will change to the specified
12267 directory. Otherwise, if chdir evaluates true, SCons will change to
12268 the target file's directory.
12269 Note that SCons will not automatically modify its expansion of
12271 construction variables like $TARGET and $SOURCE when using the
12272 chdir parameter - that is, the expanded file names will still be
12273 relative to the top-level directory containing the SConstruct file,
12274 and consequently incorrect relative to the chdir directory.
12275 Builders created using chdir keyword argument, will need to use
12276 construction variable expansions like ${TARGET.file} and
12277 ${SOURCE.file} to use just the filename portion of the targets and
12278 source. Example:
12279 a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=True)
12281 exitstatfunc
12283 If provided, must be a callable which accepts a single parameter,
12284 the exit status (or return value) from the specified action, and
12285 which returns an arbitrary or modified value. This can be used, for
12286 example, to specify that an Action object's return value should be
12287 ignored under special conditions and SCons should, therefore,
12288 consider that the action always succeeds. Example:
12289 def always_succeed(s):
12291 # Always return 0, which indicates success.
12292 return 0
12293 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
12295 exitstatfunc=always_succeed)
12296 batch_key
12298 If provided, indicates that the Action can create multiple target
12299 files by processing multiple independent source files
12300 simultaneously. (The canonical example is "batch compilation" of
12301 multiple object files by passing multiple source files to a single
12302 invocation of a compiler such as Microsoft's Visual C / C++
12303 compiler.) If the batch_key argument evaluates True and is not a
12304 callable object, the configured Action object will cause scons to
12305 collect all targets built with the Action object and configured
12306 with the same construction environment into single invocations of
12307 the Action object's command line or function. Command lines will
12308 typically want to use the $CHANGED_SOURCES construction variable
12309 (and possibly $CHANGED_TARGETS as well) to only pass to the command
12310 line those sources that have actually changed since their targets
12311 were built. Example:
12312 a = Action('build $CHANGED_SOURCES', batch_key=True)
12314 The batch_key argument may also be a callable function that returns
12316 a key that will be used to identify different "batches" of target
12317 files to be collected for batch building. A batch_key function must
12318 accept four parameters: action, env, target and source. The first
12319 parameter, action, is the active action object. The second
12320 parameter, env, is the construction environment configured for the
12321 target. The target and source parameters are the lists of targets
12322 and sources for the configured action.
12323 The returned key should typically be a tuple of values derived from
12325 the arguments, using any appropriate logic to decide how multiple
12326 invocations should be batched. For example, a batch_key function
12327 may decide to return the value of a specific construction variable
12328 from env which will cause scons to batch-build targets with
12329 matching values of that construction variable, or perhaps return
12330 the Python id() of the entire construction environment, in which
12331 case scons will batch-build all targets configured with the same
12332 construction environment. Returning None indicates that the
12333 particular target should not be part of any batched build, but
12334 instead will be built by a separate invocation of action's command
12335 or function. Example:
12336 def batch_key(action, env, target, source):
12338 tdir = target[0].dir
12339 if tdir.name == 'special':
12340 # Don't batch-build any target
12341 # in the special/ subdirectory.
12342 return None
12343 return (id(action), id(env), tdir)
12344 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
12345 Miscellaneous Action Functions
12347 SCons supplies Action functions that arrange for various common file
12348 and directory manipulations to be performed. These are similar in
12349 concept to "tasks" in the Ant build tool, although the implementation
12350 is slightly different. These functions do not actually perform the
12351 specified action at the time the function is called, but rather are
12352 factory functions which return an Action object that can be executed at
12353 the appropriate time.
12354 There are two natural ways that these Action Functions are intended to
12356 be used.
12357 First, if you need to perform the action at the time the SConscript
12359 file is being read, you can use the Execute global function:
12360 Execute(Touch('file'))
12362 Second, you can use these functions to supply Actions in a list for use
12364 by the env.Command method. This can allow you to perform more
12365 complicated sequences of file manipulation without relying on
12366 platform-specific external commands:
12367 env = Environment(TMPBUILD='/tmp/builddir')
12369 env.Command(
12370 target='foo.out',
12371 source='foo.in',
12372 action=[
12373 Mkdir('$TMPBUILD'),
12374 Copy('$TMPBUILD', '${SOURCE.dir}'),
12375 "cd $TMPBUILD && make",
12376 Delete('$TMPBUILD'),
12377 ],
12378 )
12379 Chmod(dest, mode)
12381 Returns an Action object that changes the permissions on the
12382 specified dest file or directory to the specified mode which can be
12383 octal or string, similar to the bash command. Examples:
12384 Execute(Chmod('file', 0o755))
12386 env.Command('foo.out', 'foo.in',
12388 [Copy('$TARGET', '$SOURCE'),
12389 Chmod('$TARGET', 0o755)])
12390 Execute(Chmod('file', "ugo+w"))
12392 env.Command('foo.out', 'foo.in',
12394 [Copy('$TARGET', '$SOURCE'),
12395 Chmod('$TARGET', "ugo+w")])
12396 The behavior of Chmod is limited on Windows, see the notes in the
12398 Python documentation for os.chmod, which is the underlying
12399 function.
12400 Copy(dest, src)
12402 Returns an Action object that will copy the src source file or
12403 directory to the dest destination file or directory. Examples:
12404 Execute(Copy('foo.output', 'foo.input'))
12406 env.Command('bar.out', 'bar.in', Copy('$TARGET', '$SOURCE'))
12408 Delete(entry, [must_exist])
12410 Returns an Action that deletes the specified entry, which may be a
12411 file or a directory tree. If a directory is specified, the entire
12412 directory tree will be removed. If the must_exist flag is set to a
12413 true value, then a Python error will be raised if the specified
12414 entry does not exist; the default is false, that is, the Action
12415 will silently do nothing if the entry does not exist. Examples:
12416 Execute(Delete('/tmp/buildroot'))
12418 env.Command(
12420 'foo.out',
12421 'foo.in',
12422 action=[
12423 Delete('${TARGET.dir}'),
12424 MyBuildAction,
12425 ],
12426 )
12427 Execute(Delete('file_that_must_exist', must_exist=True))
12429 Mkdir(name)
12431 Returns an Action that creates the directory name and all needed
12432 intermediate directories. name may also be a list of directories
12433 to create. Examples:
12434 Execute(Mkdir('/tmp/outputdir'))
12436 env.Command(
12438 'foo.out',
12439 'foo.in',
12440 action=[
12441 Mkdir('/tmp/builddir'),
12442 Copy('/tmp/builddir/foo.in', '$SOURCE'),
12443 "cd /tmp/builddir && make",
12444 Copy('$TARGET', '/tmp/builddir/foo.out'),
12445 ],
12446 )
12447 Move(dest, src)
12449 Returns an Action that moves the specified src file or directory to
12450 the specified dest file or directory. Examples:
12451 Execute(Move('file.destination', 'file.source'))
12453 env.Command(
12455 'output_file',
12456 'input_file',
12457 action=[MyBuildAction, Move('$TARGET', 'file_created_by_MyBuildAction')],
12458 )
12459 Touch(file)
12461 Returns an Action that updates the modification time on the
12462 specified file. Examples:
12463 Execute(Touch('file_to_be_touched'))
12465 env.Command('marker', 'input_file', action=[MyBuildAction, Touch('$TARGET')])
12467 Variable Substitution
12469 Before executing a command, scons performs variable substitution on the
12470 string that makes up the action part of the builder. Variables to be
12471 interpolated are indicated in the string with a leading $, to
12472 distinguish them from plain text which is not to be substituted. The
12473 name may be surrounded by curly braces (${}) to separate the name from
12474 surrounding characters if necessary. Curly braces are required when you
12475 use Python list subscripting/slicing notation on a variable to select
12476 one or more items from a list, or access a variable's special
12477 attributes, or use Python expression substitution.
12478 Besides regular construction variables, scons provides the following
12480 special variables for use in expanding commands:
12481 $CHANGED_SOURCES
12483 The file names of all sources of the build command that have
12484 changed since the target was last built.
12485 $CHANGED_TARGETS
12487 The file names of all targets that would be built from sources that
12488 have changed since the target was last built.
12489 $SOURCE
12491 The file name of the source of the build command, or the file name
12492 of the first source if multiple sources are being built.
12493 $SOURCES
12495 The file names of the sources of the build command.
12496 $TARGET
12498 The file name of the target being built, or the file name of the
12499 first target if multiple targets are being built.
12500 $TARGETS
12502 The file names of all targets being built.
12503 $UNCHANGED_SOURCES
12505 The file names of all sources of the build command that have not
12506 changed since the target was last built.
12507 $UNCHANGED_TARGETS
12509 The file names of all targets that would be built from sources that
12510 have not changed since the target was last built.
12511 These names are reserved and may not be assigned to or used as
12513 construction variables.
12514 For example, the following builder call:
12516 env = Environment(CC='cc')
12518 env.Command(
12519 target=['foo'],
12520 source=['foo.c', 'bar.c'],
12521 action='@echo $CC -c -o $TARGET $SOURCES'
12522 )
12523 would produce the following output:
12525 cc -c -o foo foo.c bar.c
12527 In the previous example, a string ${SOURCES[1]} would expand to: bar.c.
12529 A variable name may have the following modifiers appended within the
12531 enclosing curly braces to access properties of the interpolated string.
12532 These are known as special attributes.
12533 base -
12534 The base path of the file name,
12535 including the directory path
12536 but excluding any suffix.
12537 dir - The name of the directory in which the file exists.
12539 file - The file name, minus any directory portion.
12540 filebase - Like file but minus its suffix.
12541 suffix - Just the file suffix.
12542 abspath - The absolute path name of the file.
12543 relpath - The path name of the file relative to the root SConstruct
12544 file's directory.
12545 posix -
12546 The path with directories separated by forward slashes
12547 (/).
12548 Sometimes necessary on Windows systems
12549 when a path references a file on other (POSIX) systems.
12550 windows -
12552 The path with directories separated by backslashes
12553 (\\).
12554 Sometimes necessary on POSIX-style systems
12555 when a path references a file on other (Windows) systems.
12556 win32 is a (deprecated) synonym for
12557 windows.
12558 srcpath -
12560 The directory and file name to the source file linked to this
12561 file through
12562 VariantDir().
12563 If this file isn't linked,
12564 it just returns the directory and filename unchanged.
12565 srcdir -
12567 The directory containing the source file linked to this file
12568 through
12569 VariantDir().
12570 If this file isn't linked,
12571 it just returns the directory part of the filename.
12572 rsrcpath -
12574 The directory and file name to the source file linked to this
12575 file through
12576 VariantDir().
12577 If the file does not exist locally but exists in a Repository,
12578 the path in the Repository is returned.
12579 If this file isn't linked, it just returns the
12580 directory and filename unchanged.
12581 rsrcdir -
12583 The Repository directory containing the source file linked to
12584 this file through
12585 VariantDir().
12586 If this file isn't linked,
12587 it just returns the directory part of the filename.
12588 For example, the specified target will expand as follows for the
12591 corresponding modifiers:
12592 $TARGET => sub/dir/file.x
12594 ${TARGET.base} => sub/dir/file
12595 ${TARGET.dir} => sub/dir
12596 ${TARGET.file} => file.x
12597 ${TARGET.filebase} => file
12598 ${TARGET.suffix} => .x
12599 ${TARGET.abspath} => /top/dir/sub/dir/file.x
12600 ${TARGET.relpath} => sub/dir/file.x
12601 $TARGET => ../dir2/file.x
12603 ${TARGET.abspath} => /top/dir2/file.x
12604 ${TARGET.relpath} => ../dir2/file.x
12605 SConscript('src/SConscript', variant_dir='sub/dir')
12607 $SOURCE => sub/dir/file.x
12608 ${SOURCE.srcpath} => src/file.x
12609 ${SOURCE.srcdir} => src
12610 Repository('/usr/repository')
12612 $SOURCE => sub/dir/file.x
12613 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
12614 ${SOURCE.rsrcdir} => /usr/repository/src
12615 Some modifiers can be combined, like ${TARGET.srcpath.base),
12617 ${TARGET.file.suffix}, etc.
12618 The curly brace notation may also be used to enclose a Python
12620 expression to be evaluated. See the section called “Python Code
12621 Substitution” below for a description.
12622 A variable name may also be a Python function associated with a
12624 construction variable in the environment. The function should accept
12625 four arguments:
12626 target - a list of target nodes
12627 source - a list of source nodes
12628 env - the construction environment
12629 for_signature -
12630 a Boolean value that specifies
12631 whether the function is being called
12632 for generating a build signature.
12633 SCons will insert whatever the called function returns into the
12636 expanded string:
12637 def foo(target, source, env, for_signature):
12639 return "bar"
12640 # Will expand $BAR to "bar baz"
12642 env=Environment(FOO=foo, BAR="$FOO baz")
12643 As a reminder, this evaluation happens when $BAR is actually used in a
12645 builder action. The value of env['BAR'] will be exactly as it was set:
12646 "$FOO baz".
12647 You can use this feature to pass arguments to a Python function by
12649 creating a callable class that stores one or more arguments in an
12650 object, and then uses them when the __call__() method is called. Note
12651 that in this case, the entire variable expansion must be enclosed by
12652 curly braces so that the arguments will be associated with the
12653 instantiation of the class:
12654 class foo:
12656 def __init__(self, arg):
12657 self.arg = arg
12658 def __call__(self, target, source, env, for_signature):
12660 return self.arg + " bar"
12661 # Will expand $BAR to "my argument bar baz"
12663 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
12664 The special pseudo-variables $( and $) may be used to surround parts of
12666 a command line that may change without causing a rebuild--that is,
12667 which are not included in the signature of target files built with this
12668 command. All text between $( and $) will be removed from the command
12669 line before it is added to file signatures, and the $( and $) will be
12670 removed before the command is executed. For example, the command line:
12671 echo Last build occurred $( $TODAY $). > $TARGET
12673 would execute the command:
12675 echo Last build occurred $TODAY. > $TARGET
12677 but the command signature added to any target files would be:
12679 echo Last build occurred . > $TARGET
12681 Python Code Substitution
12683 If a substitutable expression using the notation ${something} does not
12684 appear to match one of the other substitution patterns, it is evaluated
12685 as a Python expression. This uses Python's eval function, with the
12686 globals parameter set to the current environment's set of construction
12687 variables, and the result substituted in. So in the following case:
12688 env.Command(
12690 'foo.out', 'foo.in', "echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET"
12691 )
12692 the command executed will be either
12694 echo FOO > foo.out
12696 or
12698 echo BAR > foo.out
12700 according to the current value of env['COND'] when the command is
12702 executed. The evaluation takes place when the target is being built,
12703 not when the SConscript is being read. So if env['COND'] is changed
12704 later in the SConscript, the final value will be used.
12705 Here's a more complete example. Note that all of COND, FOO, and BAR are
12707 construction variables, and their values are substituted into the final
12708 command. FOO is a list, so its elements are interpolated separated by
12709 spaces.
12710 env=Environment()
12712 env['COND'] = 1
12713 env['FOO'] = ['foo1', 'foo2']
12714 env['BAR'] = 'barbar'
12715 env.Command(
12716 'foo.out', 'foo.in', "echo ${COND==1 and FOO or BAR} > $TARGET"
12717 )
12718 will execute:
12720 echo foo1 foo2 > foo.out
12722 In point of fact, Python expression evaluation is how the special
12724 attributes are substituted: they are simply attributes of the Python
12725 objects that represent $TARGET, $SOURCES, etc., which SCons passes to
12726 eval which returns the value.
12727 SCons uses the following rules when converting construction variables
12729 into command lines:
12730 string
12732 When the value is a string it is interpreted as a space delimited
12733 list of command line arguments.
12734 list
12736 When the value is a list it is interpreted as a list of command
12737 line arguments. Each element of the list is converted to a string.
12738 other
12740 Anything that is not a list or string is converted to a string and
12741 interpreted as a single command line argument.
12742 newline
12744 Newline characters (\n) delimit lines. The newline parsing is done
12745 after all other parsing, so it is not possible for arguments (e.g.
12746 file names) to contain embedded newline characters.
12747 Note
12749 Use of the Python eval function is considered to have security
12750 implications, since, depending on input sources, arbitrary
12751 unchecked strings of code can be executed by the Python
12752 interpreter. Although SCons makes use of it in a somewhat
12753 restricted context, you should be aware of this issue when using
12754 the ${python-expression-for-subst} form.
12755 Scanner Objects
12757 Scanner objects are used to scan specific file types for implicit
12758 dependencies. SCons has a number of pre-built Scanner objects, so it
12759 is usually only necessary to set up Scanners for new file types. You do
12760 this by calling the Scanner function. The Scanner function accepts the
12761 following arguments, only function is required, the rest are optional:
12762 function
12764 A Python function that will process a given Node (usually a file)
12765 and return a list of Nodes representing the implicit dependencies
12766 (file names) found in the contents. The function must accept three
12767 required arguments, node, env and path, and an optional fourth,
12768 arg. node is the internal SCons node representing the file to
12769 scan, env is the construction environment to use during the scan,
12770 and path is a tuple of directories that can be searched for files,
12771 as generated by the optional path_function (see below). If argument
12772 was supplied when the Scanner object was created, it is given as
12773 arg when the function is called; since argument is optional, the
12774 default is no arg.
12775 The function can use use str(node) to fetch the name of the file,
12777 and node.get_contents() to fetch the contents of the file as bytes
12778 or node.get_text_contents() to fetch the file's contents as text.
12779 Note that the file is not guaranteed to exist at the time the
12780 scanner is called (it could be a generated file, not generated
12781 yet), so the scanner function must be tolerant of that.
12782 name
12784 The name to use for the Scanner. This is mainly used to identify
12785 the Scanner internally. The default value is "NONE".
12786 argument
12788 If specified, will be passed to the scanner function function and
12789 the path function path_function when called, as the additional
12790 argument each of those functions takes.
12791 skeys
12793 Scanner key(s) indicating the file types this scanner is associated
12794 with. Used internally to select an appropriate scanner. In the
12795 usual case of scanning for file names, this argument will be a list
12796 of suffixes for the different file types that this Scanner knows
12797 how to scan. If skeys is a string, it will be expanded into a list
12798 by the current environment.
12799 path_function
12801 A Python function that takes four or five arguments: a construction
12802 environment, a Node for the directory containing the SConscript
12803 file in which the first target was defined, a list of target nodes,
12804 a list of source nodes, and the value of argument if it was
12805 supplied when the scanner was created. Must return a tuple of
12806 directories that can be searched for files to be returned by this
12807 Scanner object. (Note that the FindPathDirs function can be used to
12808 return a ready-made path_function for a given construction variable
12809 name, instead of having to write your own function from scratch.)
12810 node_class
12812 The class of Node that should be returned by this Scanner object.
12813 Any strings or other objects returned by the scanner function that
12814 are not of this class will be run through the function supplied by
12815 the node_factory argument. A value of None can be supplied to
12816 indicate no conversion; the default is to return File nodes.
12817 node_factory
12819 A Python function that will take a string or other object and turn
12820 it into the appropriate class of Node to be returned by this
12821 Scanner object, as indicated by node_class.
12822 scan_check
12824 A Python function that takes two arguments, a Node (file) and a
12825 construction environment, and returns whether the Node should, in
12826 fact, be scanned for dependencies. This check can be used to
12827 eliminate unnecessary calls to the scanner function when, for
12828 example, the underlying file represented by a Node does not yet
12829 exist.
12830 recursive
12832 Specifies whether this scanner should be re-invoked on the
12833 dependency files returned by the scanner. If omitted, the Node
12834 subsystem will only invoke the scanner on the file being scanned
12835 and not recurse. Recursion is needed when the files returned by the
12836 scanner may themselves contain further file dependencies, as in the
12837 case of preprocessor #include lines. A value that evaluates true
12838 enables recursion; recursive may be a callable function, in which
12839 case it will be called with a list of Nodes found and should return
12840 a list of Nodes that should be scanned recursively; this can be
12841 used to select a specific subset of Nodes for additional scanning.
12842 Note that scons has a global SourceFileScanner object that is used by
12844 the Object, SharedObject and StaticObject builders to decide which
12845 scanner should be used for different file extensions. You can use the
12846 SourceFileScanner.add_scanner() method to add your own Scanner object
12847 to the SCons infrastructure that builds target programs or libraries
12848 from a list of source files of different types:
12849 def xyz_scan(node, env, path):
12851 contents = node.get_text_contents()
12852 # Scan the contents and return the included files.
12853 XYZScanner = Scanner(xyz_scan)
12855 SourceFileScanner.add_scanner('.xyz', XYZScanner)
12857 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
12859
12861 scons and its configuration files are very portable, due largely to its
12862 implementation in Python. There are, however, a few portability issues
12863 waiting to trap the unwary.
12864 .C file suffix
12866 scons handles the upper-case .C file suffix differently, depending on
12867 the capabilities of the underlying system. On a case-sensitive system
12868 such as Linux or UNIX, scons treats a file with a .C suffix as a C++
12869 source file. On a case-insensitive system such as Windows, scons treats
12870 a file with a .C suffix as a C source file.
12871 Fortran file suffixes
12873 scons handles upper-case Fortran file suffixes differently depending on
12874 the capabilities of the underlying system. On a case-sensitive system
12875 such as Linux or UNIX, scons treats a file with a .F as a Fortran
12876 source file that is to be first run through the standard C
12877 preprocessor, while the lower-case version is not. This matches the
12878 convention of gfortran, which may also be followed by other Fortran
12879 compilers. This also applies to other naming variants, .FOR, .FTN,
12880 .F90, .F95, .F03 and .F08; files suffixed with .FPP and .fpp are both
12881 run through the preprocessor, as indicated by the pp part of the name.
12882 On a case-insensitive system such as Windows, scons treats a file with
12883 a .F suffix as a Fortran source file that should not be run through the
12884 C preprocessor.
12885 Run through the C preprocessor here means that a different set of
12887 construction variables will be applied in constructed commands, for
12888 example $FORTRANPPCOM and $FORTRANPPCOMSTR instead of $FORTRANCOM and
12889 $FORTRANCOMSTR. See the Fortran-related construction variables for more
12890 details.
12891 Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
12893 Cygwin supplies a set of tools and utilities that let users work on a
12894 Windows system using a more POSIX-like environment. The Cygwin tools,
12895 including Cygwin Python, do this, in part, by sharing an ability to
12896 interpret UNIX-like path names. For example, the Cygwin tools will
12897 internally translate a Cygwin path name like /cygdrive/c/mydir to an
12898 equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
12899 Versions of Python that are built for native Windows execution, such as
12901 the python.org and ActiveState versions, do not have the Cygwin path
12902 name semantics. This means that using a native Windows version of
12903 Python to build compiled programs using Cygwin tools (such as gcc,
12904 bison and flex) may yield unpredictable results. "Mixing and matching"
12905 in this way can be made to work, but it requires careful attention to
12906 the use of path names in your SConscript files.
12907 In practice, users can sidestep the issue by adopting the following
12909 rules: When using Cygwin's gcc for compiling, use the Cygwin-supplied
12910 Python interpreter to run scons; when using Microsoft Visual C/C++ (or
12911 some other Windows compiler) use the python.org or Microsoft Store or
12912 ActiveState version of Python to run scons.
12913 Windows: scons.bat file
12915 On Windows, if scons is executed via a wrapper scons.bat batch file,
12916 there are (at least) two ramifications. Note this is no longer the
12917 default - scons installed via Python's pip installer will have an
12918 scons.exe which does not have these limitations:
12919 First, Windows command-line users that want to use variable assignment
12921 on the command line may have to put double quotes around the
12922 assignments, otherwise the Windows command shell will consume those as
12923 arguments to itself, not to scons:
12924 scons "FOO=BAR" "BAZ=BLEH"
12926 Second, the Cygwin shell does not reognize typing scons at the command
12928 line prompt as referring to this weapper. You can work around this
12929 either by executing scons.bat (including the extension) from the Cygwin
12930 command line, or by creating a wrapper shell script named scons which
12931 invokes scons.bat.
12932 MinGW
12934 The MinGW bin directory must be in your PATH environment variable or
12935 the ['ENV']['PATH'] construction variable for scons to detect and use
12936 the MinGW tools. When running under the native Windows Python
12937 interpreter, scons will prefer the MinGW tools over the Cygwin tools,
12938 if they are both installed, regardless of the order of the bin
12939 directories in the PATH variable. If you have both MSVC and MinGW
12940 installed and you want to use MinGW instead of MSVC, then you must
12941 explicitly tell scons to use MinGW by passing tools=['mingw'] to the
12942 Environment function, because scons will prefer the MSVC tools over the
12943 MinGW tools.
12944
12946 In general, scons is not controlled by environment variables set in the
12947 shell used to invoke it, leaving it up to the SConscript file author to
12948 import those if desired. However the following variables are imported
12949 by scons itself if set:
12950 SCONS_LIB_DIR
12952 Specifies the directory that contains the scons Python module
12953 directory. Normally scons can deduce this, but in some
12954 circumstances, such as working with a source release, it may be
12955 necessary to specify (for example,
12956 /home/aroach/scons-src-0.01/src/engine).
12957 SCONSFLAGS
12959 A string containing options that will be used by scons in addition
12960 to those passed on the command line. Can be used to reduce frequent
12961 retyping of common options. The contents of SCONSFLAGS are
12962 considered before any passed command line options, so the command
12963 line can be used to override SCONSFLAGS options if necessary.
12964 SCONS_CACHE_MSVC_CONFIG
12966 (Windows only). If set, save the shell environment variables
12967 generated when setting up the Microsoft Visual C++ compiler (and/or
12968 Build Tools) to a cache file, to give these settings, which are
12969 relatively expensive to generate, persistence across scons
12970 invocations. Use of this option is primarily intended to aid
12971 performance in tightly controlled Continuous Integration setups.
12972 If set to a True-like value ("1", "true" or "True") will cache to a
12974 file named .scons_msvc_cache in the user's home directory. If set
12975 to a pathname, will use that pathname for the cache.
12976 Note: use this cache with caution as it might be somewhat fragile:
12978 while each major toolset version (e.g. Visual Studio 2017 vs 2019)
12979 and architecture pair will get separate cache entries, if toolset
12980 updates cause a change to settings within a given release series,
12981 scons will not detect the change and will reuse old settings.
12982 Remove the cache file in case of problems with this. scons will
12983 ignore failures reading or writing the file and will silently
12984 revert to non-cached behavior in such cases.
12985 Available since scons 3.1 (experimental).
12987 QTDIR
12989 If using the qt tool, this is the path to the Qt installation to
12990 build against. SCons respects this setting because it is a
12991 long-standing convention in the Qt world, where multiple Qt
12992 installations are possible.
12993
12995 The SCons User Guide at
12996 https://scons.org/doc/production/HTML/scons-user.html
12997 The SCons Design Document (old)
12999 The SCons Cookbook at
13001 https://scons-cookbook.readthedocs.io
13002 for examples of how to solve various problems with SCons.
13003 SCons source code
13006 on GitHub[7]
13007 The SCons API Reference
13010 https://scons.org/doc/production/HTML/scons-api/index.html
13011 (for internal details)
13012
13015 Originally: Steven Knight knight@baldmt.com and Anthony Roach
13016 aroach@electriceyeball.com.
13017 Since 2010: The SCons Development Team scons-dev@scons.org.
13019
13021 The SCons Development Team
13022
13024 Copyright © 2001 - 2022 The SCons Foundation
13025
13027 1. https://github.com/SCons/scons-contrib
13028 https://github.com/SCons/scons-contrib
13029 2. LLVM specification
13031 https://clang.llvm.org/docs/JSONCompilationDatabase.html
13032 3. JEP 313
13034 https:openjdk.java.net/jeps/313
13035 4. ninja package
13037 https://pypi.org/project/ninja/
13038 5. If no_progress is set via SetOption in an SConscript file (but not
13040 if set in a site_init.py file) there will still be an initial
13041 status message about reading SConscript files since SCons has to
13042 start reading them before it can see the SetOption.
13043 6. http://www.opensource.org/licenses/alphabetical
13045 http://www.opensource.org/licenses/alphabetical
13046 7. on GitHub
13048 https://github.com/SCons/scons
13049SCons 4.3.0<pVuebrdsaitoen>R4e.l3e.a0sed Sat, 22 Jan 2022 00:00:00 +0000</pubdate> SCONS(1)