1SCONS(1) SCons 3.0.1 SCONS(1)
2
6 scons - a software construction tool
7
9 scons [options...] [name=val...] [targets...]
10
12 The scons utility builds software (or other files) by determining which
13 component pieces must be rebuilt and executing the necessary commands
14 to rebuild them.
15 By default, scons searches for a file named SConstruct, Sconstruct, or
17 sconstruct (in that order) in the current directory and reads its
18 configuration from the first file found. An alternate file name may be
19 specified via the -f option.
20 The SConstruct file can specify subsidiary configuration files using
22 the SConscript() function. By convention, these subsidiary files are
23 named SConscript, although any name may be used. (Because of this
24 naming convention, the term "SConscript files" is sometimes used to
25 refer generically to all scons configuration files, regardless of
26 actual file name.)
27 The configuration files specify the target files to be built, and
29 (optionally) the rules to build those targets. Reasonable default rules
30 exist for building common software components (executable programs,
31 object files, libraries), so that for most software projects, only the
32 target and input files need be specified.
33 Before reading the SConstruct file, scons looks for a directory named
35 site_scons in various system directories (see below) and the directory
36 containing the SConstruct file; for each of those dirs which exists,
37 site_scons is prepended to sys.path, the file site_scons/site_init.py,
38 is evaluated if it exists, and the directory site_scons/site_tools is
39 prepended to the default toolpath if it exists. See the --no-site-dir
40 and --site-dir options for more details.
41 scons reads and executes the SConscript files as Python scripts, so you
43 may use normal Python scripting capabilities (such as flow control,
44 data manipulation, and imported Python libraries) to handle complicated
45 build situations. scons, however, reads and executes all of the
46 SConscript files before it begins building any targets. To make this
47 obvious, scons prints the following messages about what it is doing:
48 $ scons foo.out
50 scons: Reading SConscript files ...
51 scons: done reading SConscript files.
52 scons: Building targets ...
53 cp foo.in foo.out
54 scons: done building targets.
55 $
56 The status messages (everything except the line that reads "cp foo.in
58 foo.out") may be suppressed using the -Q option.
59 scons does not automatically propagate the external environment used to
61 execute scons to the commands used to build target files. This is so
62 that builds will be guaranteed repeatable regardless of the environment
63 variables set at the time scons is invoked. This also means that if the
64 compiler or other commands that you want to use to build your target
65 files are not in standard system locations, scons will not find them
66 unless you explicitly set the PATH to include those locations. Whenever
67 you create an scons construction environment, you can propagate the
68 value of PATH from your external environment as follows:
69 import os
71 env = Environment(ENV = {'PATH' : os.environ['PATH']})
72 Similarly, if the commands use external environment variables like
74 $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables
75 can also be explicitly propagated:
76 import os
78 env = Environment(ENV = {'PATH' : os.environ['PATH'],
79 'HOME' : os.environ['HOME']})
80 Or you may explicitly propagate the invoking user's complete external
82 environment:
83 import os
85 env = Environment(ENV = os.environ)
86 This comes at the expense of making your build dependent on the user's
88 environment being set correctly, but it may be more convenient for many
89 configurations.
90 scons can scan known input files automatically for dependency
92 information (for example, #include statements in C or C++ files) and
93 will rebuild dependent files appropriately whenever any "included"
94 input file changes. scons supports the ability to define new scanners
95 for unknown input file types.
96 scons knows how to fetch files automatically from SCCS or RCS
98 subdirectories using SCCS, RCS or BitKeeper.
99 scons is normally executed in a top-level directory containing a
101 SConstruct file, optionally specifying as command-line arguments the
102 target file or files to be built.
103 By default, the command
105 scons
107 will build all target files in or below the current directory. Explicit
109 default targets (to be built when no targets are specified on the
110 command line) may be defined the SConscript file(s) using the Default()
111 function, described below.
112 Even when Default() targets are specified in the SConscript file(s),
114 all target files in or below the current directory may be built by
115 explicitly specifying the current directory (.) as a command-line
116 target:
117 scons .
119 Building all target files, including any files outside of the current
121 directory, may be specified by supplying a command-line target of the
122 root directory (on POSIX systems):
123 scons /
125 or the path name(s) of the volume(s) in which all the targets should be
127 built (on Windows systems):
128 scons C:\ D:\
130 To build only specific targets, supply them as command-line arguments:
132 scons foo bar
134 in which case only the specified targets will be built (along with any
136 derived files on which they depend).
137 Specifying "cleanup" targets in SConscript files is not usually
139 necessary. The -c flag removes all files necessary to build the
140 specified target:
141 scons -c .
143 to remove all target files, or:
145 scons -c build export
147 to remove target files under build and export. Additional files or
149 directories to remove can be specified using the Clean() function.
150 Conversely, targets that would normally be removed by the -c invocation
151 can be prevented from being removed by using the NoClean() function.
152 A subset of a hierarchical tree may be built by remaining at the
154 top-level directory (where the SConstruct file lives) and specifying
155 the subdirectory as the target to be built:
156 scons src/subdir
158 or by changing directory and invoking scons with the -u option, which
160 traverses up the directory hierarchy until it finds the SConstruct
161 file, and then builds targets relatively to the current subdirectory:
162 cd src/subdir
164 scons -u .
165 scons supports building multiple targets in parallel via a -j option
167 that takes, as its argument, the number of simultaneous tasks that may
168 be spawned:
169 scons -j 4
171 builds four targets in parallel, for example.
173 scons can maintain a cache of target (derived) files that can be shared
175 between multiple builds. When caching is enabled in a SConscript file,
176 any target files built by scons will be copied to the cache. If an
177 up-to-date target file is found in the cache, it will be retrieved from
178 the cache instead of being rebuilt locally. Caching behavior may be
179 disabled and controlled in other ways by the --cache-force,
180 --cache-disable, --cache-readonly, and --cache-show command-line
181 options. The --random option is useful to prevent multiple builds from
182 trying to update the cache simultaneously.
183 Values of variables to be passed to the SConscript file(s) may be
185 specified on the command line:
186 scons debug=1 .
188 These variables are available in SConscript files through the ARGUMENTS
190 dictionary, and can be used in the SConscript file(s) to modify the
191 build in any way:
192 if ARGUMENTS.get('debug', 0):
194 env = Environment(CCFLAGS = '-g')
195 else:
196 env = Environment()
197 The command-line variable arguments are also available in the ARGLIST
199 list, indexed by their order on the command line. This allows you to
200 process them in order rather than by name, if necessary. ARGLIST[0]
201 returns a tuple containing (argname, argvalue). A Python exception is
202 thrown if you try to access a list member that does not exist.
203 scons requires Python version 2.7 or later. There should be no other
205 dependencies or requirements to run scons.
206 By default, scons knows how to search for available programming tools
208 on various systems. On Windows systems, scons searches in order for the
209 Microsoft Visual C++ tools, the MinGW tool chain, the Intel compiler
210 tools, and the PharLap ETS compiler. On OS/2 systems, scons searches in
211 order for the OS/2 compiler, the GCC tool chain, and the Microsoft
212 Visual C++ tools, On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun
213 Solaris systems, scons searches for the native compiler tools (MIPSpro,
214 Visual Age, aCC, and Forte tools respectively) and the GCC tool chain.
215 On all other platforms, including POSIX (Linux and UNIX) platforms,
216 scons searches in order for the GCC tool chain, the Microsoft Visual
217 C++ tools, and the Intel compiler tools. You may, of course, override
218 these default values by appropriate configuration of Environment
219 construction variables.
220
222 In general, scons supports the same command-line options as GNU make,
223 and many of those supported by cons.
224 -b
226 Ignored for compatibility with non-GNU versions of make.
227 -c, --clean, --remove
229 Clean up by removing all target files for which a construction
230 command is specified. Also remove any files or directories
231 associated to the construction command using the Clean() function.
232 Will not remove any targets specified by the NoClean() function.
233 --cache-debug=file
235 Print debug information about the CacheDir() derived-file caching
236 to the specified file. If file is - (a hyphen), the debug
237 information are printed to the standard output. The printed
238 messages describe what signature file names are being looked for
239 in, retrieved from, or written to the CacheDir() directory tree.
240 --cache-disable, --no-cache
242 Disable the derived-file caching specified by CacheDir(). scons
243 will neither retrieve files from the cache nor copy files to the
244 cache.
245 --cache-force, --cache-populate
247 When using CacheDir(), populate a cache by copying any
248 already-existing, up-to-date derived files to the cache, in
249 addition to files built by this invocation. This is useful to
250 populate a new cache with all the current derived files, or to add
251 to the cache any derived files recently built with caching disabled
252 via the --cache-disable option.
253 --cache-readonly
255 Use the cache (if enabled) for reading, but do not not update the
256 cache with changed files.
257 --cache-show
259 When using CacheDir() and retrieving a derived file from the cache,
260 show the command that would have been executed to build the file,
261 instead of the usual report, "Retrieved `file' from cache." This
262 will produce consistent output for build logs, regardless of
263 whether a target file was rebuilt or retrieved from the cache.
264 --config=mode
266 This specifies how the Configure call should use or generate the
267 results of configuration tests. The option should be specified from
268 among the following choices:
269 --config=auto
271 scons will use its normal dependency mechanisms to decide if a test
272 must be rebuilt or not. This saves time by not running the same
273 configuration tests every time you invoke scons, but will overlook
274 changes in system header files or external commands (such as
275 compilers) if you don't specify those dependecies explicitly. This
276 is the default behavior.
277 --config=force
279 If this option is specified, all configuration tests will be re-run
280 regardless of whether the cached results are out of date. This can
281 be used to explicitly force the configuration tests to be updated
282 in response to an otherwise unconfigured change in a system header
283 file or compiler.
284 --config=cache
286 If this option is specified, no configuration tests will be rerun
287 and all results will be taken from cache. Note that scons will
288 still consider it an error if --config=cache is specified and a
289 necessary test does not yet have any results in the cache.
290 -C directory, --directory=directory
292 Change to the specified directory before searching for the
293 SConstruct, Sconstruct, or sconstruct file, or doing anything else.
294 Multiple -C options are interpreted relative to the previous one,
295 and the right-most -C option wins. (This option is nearly
296 equivalent to -f directory/SConstruct, except that it will search
297 for SConstruct, Sconstruct, or sconstruct in the specified
298 directory.)
299 -D
301 Works exactly the same way as the -u option except for the way
302 default targets are handled. When this option is used and no
303 targets are specified on the command line, all default targets are
304 built, whether or not they are below the current directory.
305 --debug=type
307 Debug the build process. type[,type...] specifies what type of
308 debugging. Multiple types may be specified, separated by commas.
309 The following types are valid:
310 --debug=count
312 Print how many objects are created of the various classes used
313 internally by SCons before and after reading the SConscript files
314 and before and after building targets. This is not supported when
315 SCons is executed with the Python -O (optimized) option or when the
316 SCons modules have been compiled with optimization (that is, when
317 executing from *.pyo files).
318 --debug=duplicate
320 Print a line for each unlink/relink (or copy) of a variant file
321 from its source file. Includes debugging info for unlinking stale
322 variant files, as well as unlinking old targets before building
323 them.
324 --debug=dtree
326 A synonym for the newer --tree=derived option. This will be
327 deprecated in some future release and ultimately removed.
328 --debug=explain
330 Print an explanation of precisely why scons is deciding to
331 (re-)build any targets. (Note: this does not print anything for
332 targets that are not rebuilt.)
333 --debug=findlibs
335 Instruct the scanner that searches for libraries to print a message
336 about each potential library name it is searching for, and about
337 the actual libraries it finds.
338 --debug=includes
340 Print the include tree after each top-level target is built. This
341 is generally used to find out what files are included by the
342 sources of a given derived file:
343 $ scons --debug=includes foo.o
345 --debug=memoizer
347 Prints a summary of hits and misses using the Memoizer, an internal
348 subsystem that counts how often SCons uses cached values in memory
349 instead of recomputing them each time they're needed.
350 --debug=memory
352 Prints how much memory SCons uses before and after reading the
353 SConscript files and before and after building targets.
354 --debug=nomemoizer
356 A deprecated option preserved for backwards compatibility.
357 --debug=objects
359 Prints a list of the various objects of the various classes used
360 internally by SCons.
361 --debug=pdb
363 Re-run SCons under the control of the pdb Python debugger.
364 --debug=prepare
366 Print a line each time any target (internal or external) is
367 prepared for building. scons prints this for each target it
368 considers, even if that target is up to date (see also
369 --debug=explain). This can help debug problems with targets that
370 aren't being built; it shows whether scons is at least considering
371 them or not.
372 --debug=presub
374 Print the raw command line used to build each target before the
375 construction environment variables are substituted. Also shows
376 which targets are being built by this command. Output looks
377 something like this:
378 $ scons --debug=presub
380 Building myprog.o with action(s):
381 $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES
382 ...
383 --debug=stacktrace
385 Prints an internal Python stack trace when encountering an
386 otherwise unexplained error.
387 --debug=stree
389 A synonym for the newer --tree=all,status option. This will be
390 deprecated in some future release and ultimately removed.
391 --debug=time
393 Prints various time profiling information:
394 · The time spent executing each individual build command.RE
396 · The total build time (time SCons ran from beginning to
398 end).RE
399 · The total time spent reading and executing SConscript
401 files.RE
402 · The total time spent SCons itself spend running
404 (that is, not counting reading and executing
405 SConscript files).RE
406 · The total time spent executing all build
408 commands.RE
409 · The elapsed wall-clock time spent executing
411 those build commands.RE
412 · The time spent processing each file
414 passed to the SConscript() function.RE
415 (When scons is executed without the -j
417 option, the elapsed wall-clock time
418 will typically be slightly longer than
419 the total time spent executing all the
420 build commands, due to the SCons
421 processing that takes place in between
422 executing each command. When scons is
423 executed with the -j option, and your
424 build configuration allows good
425 parallelization, the elapsed wall-clock
426 time should be significantly smaller
427 than the total time spent executing all
428 the build commands, since multiple
429 build commands and intervening SCons
430 processing should take place in
431 parallel.)
432 --debug=tree
434 A synonym for the newer --tree=all
435 option. This will be deprecated in some
436 future release and ultimately removed.
437 --diskcheck=types
439 Enable specific checks for whether or
440 not there is a file on disk where the
441 SCons configuration expects a directory
442 (or vice versa), and whether or not RCS
443 or SCCS sources exist when searching
444 for source and include files. The types
445 argument can be set to: all, to enable
446 all checks explicitly (the default
447 behavior); none, to disable all such
448 checks; match, to check that files and
449 directories on disk match SCons'
450 expected configuration; rcs, to check
451 for the existence of an RCS source for
452 any missing source or include files;
453 sccs, to check for the existence of an
454 SCCS source for any missing source or
455 include files. Multiple checks can be
456 specified separated by commas; for
457 example, --diskcheck=sccs,rcs would
458 still check for SCCS and RCS sources,
459 but disable the check for on-disk
460 matches of files and directories.
461 Disabling some or all of these checks
462 can provide a performance boost for
463 large configurations, or when the
464 configuration will check for files
465 and/or directories across networked or
466 shared file systems, at the slight
467 increased risk of an incorrect build or
468 of not handling errors gracefully (if
469 include files really should be found in
470 SCCS or RCS, for example, or if a file
471 really does exist where the SCons
472 configuration expects a directory).
473 --duplicate=ORDER
475 There are three ways to duplicate files
476 in a build tree: hard links, soft
477 (symbolic) links and copies. The
478 default behaviour of SCons is to prefer
479 hard links to soft links to copies. You
480 can specify different behaviours with
481 this option. ORDER must be one of
482 hard-soft-copy (the default),
483 soft-hard-copy, hard-copy, soft-copy or
484 copy. SCons will attempt to duplicate
485 files using the mechanisms in the
486 specified order.
487 -f file, --file=file, --makefile=file,
489 --sconstruct=file
490 Use file as the initial SConscript
491 file. Multiple -f options may be
492 specified, in which case scons will
493 read all of the specified files.
494 -h, --help
496 Print a local help message for this
497 build, if one is defined in the
498 SConscript file(s), plus a line that
499 describes the -H option for
500 command-line option help. If no local
501 help message is defined, prints the
502 standard help message about
503 command-line options. Exits after
504 displaying the appropriate message.
505 -H, --help-options
507 Print the standard help message about
508 command-line options and exit.
509 -i, --ignore-errors
511 Ignore all errors from commands
512 executed to rebuild files.
513 -I directory, --include-dir=directory
515 Specifies a directory to search for
516 imported Python modules. If several -I
517 options are used, the directories are
518 searched in the order specified.
519 --implicit-cache
521 Cache implicit dependencies. This
522 causes scons to use the implicit
523 (scanned) dependencies from the last
524 time it was run instead of scanning the
525 files for implicit dependencies. This
526 can significantly speed up SCons, but
527 with the following limitations:
528 scons will not detect changes to implicit
530 dependency search paths (e.g. CPPPATH,
531 LIBPATH) that would ordinarily cause
532 different versions of same-named files to
533 be used.
534 scons will miss changes in the implicit
536 dependencies in cases where a new implicit
537 dependency is added earlier in the implicit
538 dependency search path (e.g. CPPPATH,
539 LIBPATH) than a current implicit dependency
540 with the same name.
541 --implicit-deps-changed
543 Forces SCons to ignore the cached
544 implicit dependencies. This causes the
545 implicit dependencies to be rescanned
546 and recached. This implies
547 --implicit-cache.
548 --implicit-deps-unchanged
550 Force SCons to ignore changes in the
551 implicit dependencies. This causes
552 cached implicit dependencies to always
553 be used. This implies --implicit-cache.
554 --interactive
556 Starts SCons in interactive mode. The
557 SConscript files are read once and a
558 scons>>> prompt is printed. Targets may
559 now be rebuilt by typing commands at
560 interactive prompt without having to
561 re-read the SConscript files and
562 re-initialize the dependency graph from
563 scratch.
564 SCons interactive mode supports the
566 following commands:
567 build[OPTIONS] [TARGETS] ...
569 Builds the specified TARGETS (and
570 their dependencies) with the
571 specified SCons command-line
572 OPTIONS. b and scons are synonyms.
573 The following SCons command-line
575 options affect the build command:
576 --cache-debug=FILE
578 --cache-disable, --no-cache
579 --cache-force, --cache-populate
580 --cache-readonly
581 --cache-show
582 --debug=TYPE
583 -i, --ignore-errors
584 -j N, --jobs=N
585 -k, --keep-going
586 -n, --no-exec, --just-print, --dry-run, --recon
587 -Q
588 -s, --silent, --quiet
589 --taskmastertrace=FILE
590 --tree=OPTIONS
591 Any other SCons command-line options
593 that are specified do not cause errors
594 but have no effect on the build command
595 (mainly because they affect how the
596 SConscript files are read, which only
597 happens once at the beginning of
598 interactive mode).
599 clean[OPTIONS] [TARGETS] ...
601 Cleans the specified TARGETS (and
602 their dependencies) with the
603 specified options. c is a synonym.
604 This command is itself a synonym
605 for build --clean
606 exit
608 Exits SCons interactive mode. You
609 can also exit by terminating input
610 (CTRL+D on UNIX or Linux systems,
611 CTRL+Z on Windows systems).
612 help[COMMAND]
614 Provides a help message about the
615 commands available in SCons
616 interactive mode. If COMMAND is
617 specified, h and ? are synonyms.
618 shell[COMMANDLINE]
620 Executes the specified COMMANDLINE
621 in a subshell. If no COMMANDLINE is
622 specified, executes the interactive
623 command interpreter specified in
624 the SHELL environment variable (on
625 UNIX and Linux systems) or the
626 COMSPEC environment variable (on
627 Windows systems). sh and ! are
628 synonyms.
629 version
631 Prints SCons version information.
632 An empty line repeats the last typed
634 command. Command-line editing can be used
635 if the readline module is available.
636 $ scons --interactive
638 scons: Reading SConscript files ...
639 scons: done reading SConscript files.
640 scons>>> build -n prog
641 scons>>> exit
642 -j N, --jobs=N
644 Specifies the number of jobs (commands)
645 to run simultaneously. If there is more
646 than one -j option, the last one is
647 effective.
648 -k, --keep-going
650 Continue as much as possible after an
651 error. The target that failed and those
652 that depend on it will not be remade,
653 but other targets specified on the
654 command line will still be processed.
655 -m
657 Ignored for compatibility with non-GNU
658 versions of make.
659 --max-drift=SECONDS
661 Set the maximum expected drift in the
662 modification time of files to SECONDS.
663 This value determines how long a file
664 must be unmodified before its cached
665 content signature will be used instead
666 of calculating a new content signature
667 (MD5 checksum) of the file's contents.
668 The default value is 2 days, which
669 means a file must have a modification
670 time of at least two days ago in order
671 to have its cached content signature
672 used. A negative value means to never
673 cache the content signature and to
674 ignore the cached value if there
675 already is one. A value of 0 means to
676 always use the cached signature, no
677 matter how old the file is.
678 --md5-chunksize=KILOBYTES
680 Set the block size used to compute MD5
681 signatures to KILOBYTES. This value
682 determines the size of the chunks which
683 are read in at once when computing MD5
684 signatures. Files below that size are
685 fully stored in memory before
686 performing the signature computation
687 while bigger files are read in
688 block-by-block. A huge block-size leads
689 to high memory consumption while a very
690 small block-size slows down the build
691 considerably.
692 The default value is to use a chunk
694 size of 64 kilobytes, which should be
695 appropriate for most uses.
696 -n, --just-print, --dry-run, --recon
698 No execute. Print the commands that
699 would be executed to build any
700 out-of-date target files, but do not
701 execute the commands.
702 --no-site-dir
704 Prevents the automatic addition of the
705 standard site_scons dirs to sys.path.
706 Also prevents loading the
707 site_scons/site_init.py modules if they
708 exist, and prevents adding their
709 site_scons/site_tools dirs to the
710 toolpath.
711 --profile=file
713 Run SCons under the Python profiler and
714 save the results in the specified file.
715 The results may be analyzed using the
716 Python pstats module.
717 -q, --question
719 Do not run any commands, or print
720 anything. Just return an exit status
721 that is zero if the specified targets
722 are already up to date, non-zero
723 otherwise.
724 -Q
726 Quiets SCons status messages about
727 reading SConscript files, building
728 targets and entering directories.
729 Commands that are executed to rebuild
730 target files are still printed.
731 --random
733 Build dependencies in a random order.
734 This is useful when building multiple
735 trees simultaneously with caching
736 enabled, to prevent multiple builds
737 from simultaneously trying to build or
738 retrieve the same target files.
739 -s, --silent, --quiet
741 Silent. Do not print commands that are
742 executed to rebuild target files. Also
743 suppresses SCons status messages.
744 -S, --no-keep-going, --stop
746 Ignored for compatibility with GNU
747 make.
748 --site-dir=dir
750 Uses the named dir as the site dir
751 rather than the default site_scons
752 dirs. This dir will get prepended to
753 sys.path, the module dir/site_init.py
754 will get loaded if it exists, and
755 dir/site_tools will get added to the
756 default toolpath.
757 The default set of site_scons dirs used
759 when --site-dir is not specified
760 depends on the system platform, as
761 follows. Note that the directories are
762 examined in the order given, from most
763 generic to most specific, so the
764 last-executed site_init.py file is the
765 most specific one (which gives it the
766 chance to override everything else),
767 and the dirs are prepended to the
768 paths, again so the last dir examined
769 comes first in the resulting path.
770 Windows:
772 %ALLUSERSPROFILE/Application Data/scons/site_scons
774 %USERPROFILE%/Local Settings/Application Data/scons/site_scons
775 %APPDATA%/scons/site_scons
776 %HOME%/.scons/site_scons
777 ./site_scons
778 Mac OS X:
780 /Library/Application Support/SCons/site_scons
782 /opt/local/share/scons/site_scons (for MacPorts)
783 /sw/share/scons/site_scons (for Fink)
784 $HOME/Library/Application Support/SCons/site_scons
785 $HOME/.scons/site_scons
786 ./site_scons
787 Solaris:
789 /opt/sfw/scons/site_scons
791 /usr/share/scons/site_scons
792 $HOME/.scons/site_scons
793 ./site_scons
794 Linux, HPUX, and other Posix-like systems:
796 /usr/share/scons/site_scons
798 $HOME/.scons/site_scons
799 ./site_scons
800 --stack-size=KILOBYTES
802 Set the size stack used to run threads
803 to KILOBYTES. This value determines the
804 stack size of the threads used to run
805 jobs. These are the threads that
806 execute the actions of the builders for
807 the nodes that are out-of-date. Note
808 that this option has no effect unless
809 the num_jobs option, which corresponds
810 to -j and --jobs, is larger than one.
811 Using a stack size that is too small
812 may cause stack overflow errors. This
813 usually shows up as segmentation faults
814 that cause scons to abort before
815 building anything. Using a stack size
816 that is too large will cause scons to
817 use more memory than required and may
818 slow down the entire build process.
819 The default value is to use a stack
821 size of 256 kilobytes, which should be
822 appropriate for most uses. You should
823 not need to increase this value unless
824 you encounter stack overflow errors.
825 -t, --touch
827 Ignored for compatibility with GNU
828 make. (Touching a file to make it
829 appear up-to-date is unnecessary when
830 using scons.)
831 --taskmastertrace=file
833 Prints trace information to the
834 specified file about how the internal
835 Taskmaster object evaluates and
836 controls the order in which Nodes are
837 built. A file name of - may be used to
838 specify the standard output.
839 -tree=options
841 Prints a tree of the dependencies after
842 each top-level target is built. This
843 prints out some or all of the tree, in
844 various formats, depending on the
845 options specified:
846 --tree=all
848 Print the entire dependency tree after
849 each top-level target is built. This
850 prints out the complete dependency
851 tree, including implicit dependencies
852 and ignored dependencies.
853 --tree=derived
855 Restricts the tree output to only
856 derived (target) files, not source
857 files.
858 --tree=status
860 Prints status information for each
861 displayed node.
862 --tree=prune
864 Prunes the tree to avoid repeating
865 dependency information for nodes that
866 have already been displayed. Any node
867 that has already been displayed will
868 have its name printed in [square
869 brackets], as an indication that the
870 dependencies for that node can be found
871 by searching for the relevant output
872 higher up in the tree.
873 Multiple options may be specified,
875 separated by commas:
876 # Prints only derived files, with status information:
878 scons --tree=derived,status
879 # Prints all dependencies of target, with status information
881 # and pruning dependencies of already-visited Nodes:
882 scons --tree=all,prune,status target
883 -u, --up, --search-up
885 Walks up the directory structure until
886 an SConstruct , Sconstruct or
887 sconstruct file is found, and uses that
888 as the top of the directory tree. If no
889 targets are specified on the command
890 line, only targets at or below the
891 current directory will be built.
892 -U
894 Works exactly the same way as the -u
895 option except for the way default
896 targets are handled. When this option
897 is used and no targets are specified on
898 the command line, all default targets
899 that are defined in the SConscript(s)
900 in the current directory are built,
901 regardless of what directory the
902 resultant targets end up in.
903 -v, --version
905 Print the scons version, copyright
906 information, list of authors, and any
907 other relevant information. Then exit.
908 -w, --print-directory
910 Print a message containing the working
911 directory before and after other
912 processing.
913 --no-print-directory
915 Turn off -w, even if it was turned on
916 implicitly.
917 --warn=type, --warn=no-type
919 Enable or disable warnings. type
920 specifies the type of warnings to be
921 enabled or disabled:
922 --warn=all, --warn=no-all
924 Enables or disables all warnings.
925 --warn=cache-version,
927 --warn=no-cache-version
928 Enables or disables warnings about the
929 cache directory not using the latest
930 configuration information CacheDir().
931 These warnings are enabled by default.
932 --warn=cache-write-error,
934 --warn=no-cache-write-error
935 Enables or disables warnings about
936 errors trying to write a copy of a
937 built file to a specified CacheDir().
938 These warnings are disabled by default.
939 --warn=corrupt-sconsign,
941 --warn=no-corrupt-sconsign
942 Enables or disables warnings about
943 unfamiliar signature data in .sconsign
944 files. These warnings are enabled by
945 default.
946 --warn=dependency, --warn=no-dependency
948 Enables or disables warnings about
949 dependencies. These warnings are
950 disabled by default.
951 --warn=deprecated, --warn=no-deprecated
953 Enables or disables all warnings about
954 use of currently deprecated features.
955 These warnings are enabled by default.
956 Note that the --warn=no-deprecated
957 option does not disable warnings about
958 absolutely all deprecated features.
959 Warnings for some deprecated features
960 that have already been through several
961 releases with deprecation warnings may
962 be mandatory for a release or two
963 before they are officially no longer
964 supported by SCons. Warnings for some
965 specific deprecated features may be
966 enabled or disabled individually; see
967 below.
968 --warn=deprecated-copy,
970 --warn=no-deprecated-copy
971 Enables or disables warnings about
972 use of the deprecated env.Copy()
973 method.
974 --warn=deprecated-source-signatures,
976 --warn=no-deprecated-source-signatures
977 Enables or disables warnings about
978 use of the deprecated
979 SourceSignatures() function or
980 env.SourceSignatures() method.
981 --warn=deprecated-target-signatures,
983 --warn=no-deprecated-target-signatures
984 Enables or disables warnings about
985 use of the deprecated
986 TargetSignatures() function or
987 env.TargetSignatures() method.
988 --warn=duplicate-environment,
990 --warn=no-duplicate-environment
991 Enables or disables warnings about
992 attempts to specify a build of a target
993 with two different construction
994 environments that use the same action.
995 These warnings are enabled by default.
996 --warn=fortran-cxx-mix,
998 --warn=no-fortran-cxx-mix
999 Enables or disables the specific
1000 warning about linking Fortran and C++
1001 object files in a single executable,
1002 which can yield unpredictable behavior
1003 with some compilers.
1004 --warn=future-deprecated,
1006 --warn=no-future-deprecated
1007 Enables or disables warnings about
1008 features that will be deprecated in the
1009 future. These warnings are disabled by
1010 default. Enabling this warning is
1011 especially recommended for projects
1012 that redistribute SCons configurations
1013 for other users to build, so that the
1014 project can be warned as soon as
1015 possible about to-be-deprecated
1016 features that may require changes to
1017 the configuration.
1018 --warn=link, --warn=no-link
1020 Enables or disables warnings about link
1021 steps.
1022 --warn=misleading-keywords,
1024 --warn=no-misleading-keywords
1025 Enables or disables warnings about use
1026 of the misspelled keywords targets and
1027 sources when calling Builders. (Note
1028 the last s characters, the correct
1029 spellings are target and source.)
1030 These warnings are enabled by default.
1031 --warn=missing-sconscript,
1033 --warn=no-missing-sconscript
1034 Enables or disables warnings about
1035 missing SConscript files. These
1036 warnings are enabled by default.
1037 --warn=no-md5-module,
1039 --warn=no-no-md5-module
1040 Enables or disables warnings about the
1041 version of Python not having an MD5
1042 checksum module available. These
1043 warnings are enabled by default.
1044 --warn=no-metaclass-support,
1046 --warn=no-no-metaclass-support
1047 Enables or disables warnings about the
1048 version of Python not supporting
1049 metaclasses when the --debug=memoizer
1050 option is used. These warnings are
1051 enabled by default.
1052 --warn=no-object-count,
1054 --warn=no-no-object-count
1055 Enables or disables warnings about the
1056 --debug=object feature not working when
1057 scons is run with the python -O option
1058 or from optimized Python (.pyo)
1059 modules.
1060 --warn=no-parallel-support,
1062 --warn=no-no-parallel-support
1063 Enables or disables warnings about the
1064 version of Python not being able to
1065 support parallel builds when the -j
1066 option is used. These warnings are
1067 enabled by default.
1068 --warn=python-version,
1070 --warn=no-python-version
1071 Enables or disables the warning about
1072 running SCons with a deprecated version
1073 of Python. These warnings are enabled
1074 by default.
1075 --warn=reserved-variable,
1077 --warn=no-reserved-variable
1078 Enables or disables warnings about
1079 attempts to set the reserved
1080 construction variable names
1081 CHANGED_SOURCES, CHANGED_TARGETS,
1082 TARGET, TARGETS, SOURCE, SOURCES,
1083 UNCHANGED_SOURCES or UNCHANGED_TARGETS.
1084 These warnings are disabled by default.
1085 --warn=stack-size, --warn=no-stack-size
1087 Enables or disables warnings about
1088 requests to set the stack size that
1089 could not be honored. These warnings
1090 are enabled by default.
1091 --warn=target_not_build,
1093 --warn=no-target_not_built
1094 Enables or disables warnings about a
1095 build rule not building the expected
1096 targets. These warnings are not
1097 currently enabled by default.
1098 -Y repository, --repository=repository,
1100 --srcdir=repository
1101 Search the specified repository for any
1102 input and target files not found in the
1103 local directory hierarchy. Multiple -Y
1104 options may be specified, in which case
1105 the repositories are searched in the
1106 order specified.
1107
1109 Construction Environments
1110 A construction environment is the basic means by which the SConscript
1111 files communicate build information to scons. A new construction
1112 environment is created using the Environment function:
1113 env = Environment()
1115 Variables, called construction variables, may be set in a construction
1117 environment either by specifying them as keywords when the object is
1118 created or by assigning them a value after the object is created:
1119 env = Environment(FOO = 'foo')
1121 env['BAR'] = 'bar'
1122 As a convenience, construction variables may also be set or modified by
1124 the parse_flags keyword argument, which applies the ParseFlags method
1125 (described below) to the argument value after all other processing is
1126 completed. This is useful either if the exact content of the flags is
1127 unknown (for example, read from a control file) or if the flags are
1128 distributed to a number of construction variables.
1129 env = Environment(parse_flags = '-Iinclude -DEBUG -lm')
1131 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
1133 to LIBS.
1134 By default, a new construction environment is initialized with a set of
1136 builder methods and construction variables that are appropriate for the
1137 current platform. An optional platform keyword argument may be used to
1138 specify that an environment should be initialized for a different
1139 platform:
1140 env = Environment(platform = 'cygwin')
1142 env = Environment(platform = 'os2')
1143 env = Environment(platform = 'posix')
1144 env = Environment(platform = 'win32')
1145 Specifying a platform initializes the appropriate construction
1147 variables in the environment to use and generate file names with
1148 prefixes and suffixes appropriate for the platform.
1149 Note that the win32 platform adds the SystemDrive and SystemRoot
1151 variables from the user's external environment to the construction
1152 environment's ENV dictionary. This is so that any executed commands
1153 that use sockets to connect with other systems (such as fetching source
1154 files from external CVS repository specifications like
1155 :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) will work on
1156 Windows systems.
1157 The platform argument may be function or callable object, in which case
1159 the Environment() method will call the specified argument to update the
1160 new construction environment:
1161 def my_platform(env):
1163 env['VAR'] = 'xyzzy'
1164 env = Environment(platform = my_platform)
1166 Additionally, a specific set of tools with which to initialize the
1168 environment may be specified as an optional keyword argument:
1169 env = Environment(tools = ['msvc', 'lex'])
1171 Non-built-in tools may be specified using the toolpath argument:
1173 env = Environment(tools = ['default', 'foo'], toolpath = ['tools'])
1175 This looks for a tool specification in tools/foo.py (as well as using
1177 the ordinary default tools for the platform). foo.py should have two
1178 functions: generate(env, **kw) and exists(env). The generate() function
1179 modifies the passed-in environment to set up variables so that the tool
1180 can be executed; it may use any keyword arguments that the user
1181 supplies (see below) to vary its initialization. The exists() function
1182 should return a true value if the tool is available. Tools in the
1183 toolpath are used before any of the built-in ones. For example, adding
1184 gcc.py to the toolpath would override the built-in gcc tool. Also note
1185 that the toolpath is stored in the environment for use by later calls
1186 to Clone() and Tool() methods:
1187 base = Environment(toolpath=['custom_path'])
1189 derived = base.Clone(tools=['custom_tool'])
1190 derived.CustomBuilder()
1191 The elements of the tools list may also be functions or callable
1193 objects, in which case the Environment() method will call the specified
1194 elements to update the new construction environment:
1195 def my_tool(env):
1197 env['XYZZY'] = 'xyzzy'
1198 env = Environment(tools = [my_tool])
1200 The individual elements of the tools list may also themselves be
1202 two-element lists of the form (toolname, kw_dict). SCons searches for
1203 the toolname specification file as described above, and passes kw_dict,
1204 which must be a dictionary, as keyword arguments to the tool's generate
1205 function. The generate function can use the arguments to modify the
1206 tool's behavior by setting up the environment in different ways or
1207 otherwise changing its initialization.
1208 # in tools/my_tool.py:
1210 def generate(env, **kw):
1211 # Sets MY_TOOL to the value of keyword argument 'arg1' or 1.
1212 env['MY_TOOL'] = kw.get('arg1', '1')
1213 def exists(env):
1214 return 1
1215 # in SConstruct:
1217 env = Environment(tools = ['default', ('my_tool', {'arg1': 'abc'})],
1218 toolpath=['tools'])
1219 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
1221 the environment it receives to customize the tool for different
1222 platforms.
1223 If no tool list is specified, then SCons will auto-detect the installed
1225 tools using the PATH variable in the ENV construction variable and the
1226 platform name when the Environment is constructed. Changing the PATH
1227 variable after the Environment is constructed will not cause the tools
1228 to be redetected.
1229 One feature now present within Scons is the ability to have nested
1231 tools. Tools which can be located within a subdirectory in the
1232 toolpath. With a nested tool name the dot represents a directory
1233 seperator
1234 # namespaced builder
1236 env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
1237 env.SomeTool(targets, sources)
1238 # Search Paths
1240 # SCons\Tool\SubDir1\SubDir2\SomeTool.py
1241 # SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
1242 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
1243 # .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
1244 SCons supports the following tool specifications out of the box:
1246 386asm
1248 Sets construction variables for the 386ASM assembler for the Phar
1249 Lap ETS embedded operating system.
1250 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1252 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1254 aixc++
1256 Sets construction variables for the IMB xlc / Visual Age C++
1257 compiler.
1258 Sets: $CXX, $CXXVERSION, $SHCXX, $SHOBJSUFFIX.
1260 aixcc
1262 Sets construction variables for the IBM xlc / Visual Age C
1263 compiler.
1264 Sets: $CC, $CCVERSION, $SHCC.
1266 aixf77
1268 Sets construction variables for the IBM Visual Age f77 Fortran
1269 compiler.
1270 Sets: $F77, $SHF77.
1272 aixlink
1274 Sets construction variables for the IBM Visual Age linker.
1275 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1277 applelink
1279 Sets construction variables for the Apple linker (similar to the
1280 GNU linker).
1281 Sets: $FRAMEWORKPATHPREFIX, $LDMODULECOM, $LDMODULEFLAGS,
1283 $LDMODULEPREFIX, $LDMODULESUFFIX, $LINKCOM, $SHLINKCOM,
1284 $SHLINKFLAGS, $_FRAMEWORKPATH, $_FRAMEWORKS.
1285 Uses: $FRAMEWORKSFLAGS.
1287 ar
1289 Sets construction variables for the ar library archiver.
1290 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $RANLIB,
1292 $RANLIBCOM, $RANLIBFLAGS.
1293 as
1295 Sets construction variables for the as assembler.
1296 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1298 Uses: $CC, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1300 bcc32
1302 Sets construction variables for the bcc32 compiler.
1303 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1305 $CPPDEFSUFFIX, $INCPREFIX, $INCSUFFIX, $SHCC, $SHCCCOM, $SHCCFLAGS,
1306 $SHCFLAGS, $SHOBJSUFFIX.
1307 Uses: $_CPPDEFFLAGS, $_CPPINCFLAGS.
1309 cc
1311 Sets construction variables for generic POSIX C copmilers.
1312 Sets: $CC, $CCCOM, $CCFLAGS, $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX,
1314 $CPPDEFSUFFIX, $FRAMEWORKPATH, $FRAMEWORKS, $INCPREFIX, $INCSUFFIX,
1315 $SHCC, $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHOBJSUFFIX.
1316 Uses: $PLATFORM.
1318 clang
1320 Set construction variables for the Clang C compiler.
1321 Sets: $CC, $CCVERSION, $SHCCFLAGS.
1323 clangxx
1325 Set construction variables for the Clang C++ compiler.
1326 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX,
1328 $STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME.
1329 cvf
1331 Sets construction variables for the Compaq Visual Fortran compiler.
1332 Sets: $FORTRAN, $FORTRANCOM, $FORTRANMODDIR, $FORTRANMODDIRPREFIX,
1334 $FORTRANMODDIRSUFFIX, $FORTRANPPCOM, $OBJSUFFIX, $SHFORTRANCOM,
1335 $SHFORTRANPPCOM.
1336 Uses: $CPPFLAGS, $FORTRANFLAGS, $SHFORTRANFLAGS, $_CPPDEFFLAGS,
1338 $_FORTRANINCFLAGS, $_FORTRANMODFLAG.
1339 cXX
1341 Sets construction variables for generic POSIX C++ compilers.
1342 Sets: $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM, $CXXFILESUFFIX,
1344 $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJSUFFIX, $SHCXX, $SHCXXCOM,
1345 $SHCXXFLAGS, $SHOBJSUFFIX.
1346 Uses: $CXXCOMSTR.
1348 cyglink
1350 Set construction variables for cygwin linker/loader.
1351 Sets: $IMPLIBPREFIX, $IMPLIBSUFFIX, $LDMODULEVERSIONFLAGS,
1353 $LINKFLAGS, $RPATHPREFIX, $RPATHSUFFIX, $SHLIBPREFIX, $SHLIBSUFFIX,
1354 $SHLIBVERSIONFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1355 $_LDMODULEVERSIONFLAGS, $_SHLIBVERSIONFLAGS.
1356 default
1358 Sets variables by calling a default list of Tool modules for the
1359 platform on which SCons is running.
1360 dmd
1362 Sets construction variables for D language compiler DMD.
1363 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1365 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1366 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1367 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1368 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1369 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DShLibSonameGenerator,
1370 $DVERPREFIX, $DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM,
1371 $SHDLIBVERSION, $SHDLIBVERSIONFLAGS, $SHDLINK, $SHDLINKCOM,
1372 $SHDLINKFLAGS.
1373 docbook
1375 This tool tries to make working with Docbook in SCons a little
1376 easier. It provides several toolchains for creating different
1377 output formats, like HTML or PDF. Contained in the package is a
1378 distribution of the Docbook XSL stylesheets as of version 1.76.1.
1379 As long as you don't specify your own stylesheets for
1380 customization, these official versions are picked as
1381 default...which should reduce the inevitable setup hassles for you.
1382 Implicit dependencies to images and XIncludes are detected
1384 automatically if you meet the HTML requirements. The additional
1385 stylesheet utils/xmldepend.xsl by Paul DuBois is used for this
1386 purpose.
1387 Note, that there is no support for XML catalog resolving offered!
1389 This tool calls the XSLT processors and PDF renderers with the
1390 stylesheets you specified, that's it. The rest lies in your hands
1391 and you still have to know what you're doing when resolving names
1392 via a catalog.
1393 For activating the tool "docbook", you have to add its name to the
1395 Environment constructor, like this
1396 env = Environment(tools=['docbook'])
1398 On its startup, the Docbook tool tries to find a required xsltproc
1400 processor, and a PDF renderer, e.g. fop. So make sure that these
1401 are added to your system's environment PATH and can be called
1402 directly, without specifying their full path.
1403 For the most basic processing of Docbook to HTML, you need to have
1405 installed
1406 · the Python lxml binding to libxml2, or
1408 · the direct Python bindings for libxml2/libxslt, or
1410 · a standalone XSLT processor, currently detected are xsltproc,
1412 saxon, saxon-xslt and xalan.
1413 Rendering to PDF requires you to have one of the applications fop
1415 or xep installed.
1416 Creating a HTML or PDF document is very simple and straightforward.
1418 Say
1419 env = Environment(tools=['docbook'])
1421 env.DocbookHtml('manual.html', 'manual.xml')
1422 env.DocbookPdf('manual.pdf', 'manual.xml')
1423 to get both outputs from your XML source manual.xml. As a shortcut,
1425 you can give the stem of the filenames alone, like this:
1426 env = Environment(tools=['docbook'])
1428 env.DocbookHtml('manual')
1429 env.DocbookPdf('manual')
1430 and get the same result. Target and source lists are also
1432 supported:
1433 env = Environment(tools=['docbook'])
1435 env.DocbookHtml(['manual.html','reference.html'], ['manual.xml','reference.xml'])
1436 or even
1438 env = Environment(tools=['docbook'])
1440 env.DocbookHtml(['manual','reference'])
1441 Important
1444 Whenever you leave out the list of sources, you may not specify
1445 a file extension! The Tool uses the given names as file stems,
1446 and adds the suffixes for target and source files accordingly.
1447 The rules given above are valid for the Builders DocbookHtml,
1448 DocbookPdf, DocbookEpub, DocbookSlidesPdf and DocbookXInclude. For
1449 the DocbookMan transformation you can specify a target name, but
1450 the actual output names are automatically set from the refname
1451 entries in your XML source.
1452 The Builders DocbookHtmlChunked, DocbookHtmlhelp and
1454 DocbookSlidesHtml are special, in that:
1455 1. they create a large set of files, where the exact names and
1457 their number depend on the content of the source file, and
1458 2. the main target is always named index.html, i.e. the output
1460 name for the XSL transformation is not picked up by the
1461 stylesheets.
1462 As a result, there is simply no use in specifying a target HTML
1464 name. So the basic syntax for these builders is always:
1465 env = Environment(tools=['docbook'])
1467 env.DocbookHtmlhelp('manual')
1468 If you want to use a specific XSL file, you can set the additional
1470 xsl parameter to your Builder call as follows:
1471 env.DocbookHtml('other.html', 'manual.xml', xsl='html.xsl')
1473 Since this may get tedious if you always use the same local naming
1475 for your customized XSL files, e.g. html.xsl for HTML and pdf.xsl
1476 for PDF output, a set of variables for setting the default XSL name
1477 is provided. These are:
1478 DOCBOOK_DEFAULT_XSL_HTML
1480 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
1481 DOCBOOK_DEFAULT_XSL_HTMLHELP
1482 DOCBOOK_DEFAULT_XSL_PDF
1483 DOCBOOK_DEFAULT_XSL_EPUB
1484 DOCBOOK_DEFAULT_XSL_MAN
1485 DOCBOOK_DEFAULT_XSL_SLIDESPDF
1486 DOCBOOK_DEFAULT_XSL_SLIDESHTML
1487 and you can set them when constructing your environment:
1489 env = Environment(tools=['docbook'],
1491 DOCBOOK_DEFAULT_XSL_HTML='html.xsl',
1492 DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl')
1493 env.DocbookHtml('manual') # now uses html.xsl
1494 Sets: $DOCBOOK_DEFAULT_XSL_EPUB, $DOCBOOK_DEFAULT_XSL_HTML,
1496 $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED, $DOCBOOK_DEFAULT_XSL_HTMLHELP,
1497 $DOCBOOK_DEFAULT_XSL_MAN, $DOCBOOK_DEFAULT_XSL_PDF,
1498 $DOCBOOK_DEFAULT_XSL_SLIDESHTML, $DOCBOOK_DEFAULT_XSL_SLIDESPDF,
1499 $DOCBOOK_FOP, $DOCBOOK_FOPCOM, $DOCBOOK_FOPFLAGS, $DOCBOOK_XMLLINT,
1500 $DOCBOOK_XMLLINTCOM, $DOCBOOK_XMLLINTFLAGS, $DOCBOOK_XSLTPROC,
1501 $DOCBOOK_XSLTPROCCOM, $DOCBOOK_XSLTPROCFLAGS,
1502 $DOCBOOK_XSLTPROCPARAMS.
1503 Uses: $DOCBOOK_FOPCOMSTR, $DOCBOOK_XMLLINTCOMSTR,
1505 $DOCBOOK_XSLTPROCCOMSTR.
1506 dvi
1508 Attaches the DVI builder to the construction environment.
1509 dvipdf
1511 Sets construction variables for the dvipdf utility.
1512 Sets: $DVIPDF, $DVIPDFCOM, $DVIPDFFLAGS.
1514 Uses: $DVIPDFCOMSTR.
1516 dvips
1518 Sets construction variables for the dvips utility.
1519 Sets: $DVIPS, $DVIPSFLAGS, $PSCOM, $PSPREFIX, $PSSUFFIX.
1521 Uses: $PSCOMSTR.
1523 f03
1525 Set construction variables for generic POSIX Fortran 03 compilers.
1526 Sets: $F03, $F03COM, $F03FLAGS, $F03PPCOM, $SHF03, $SHF03COM,
1528 $SHF03FLAGS, $SHF03PPCOM, $_F03INCFLAGS.
1529 Uses: $F03COMSTR, $F03PPCOMSTR, $SHF03COMSTR, $SHF03PPCOMSTR.
1531 f08
1533 Set construction variables for generic POSIX Fortran 08 compilers.
1534 Sets: $F08, $F08COM, $F08FLAGS, $F08PPCOM, $SHF08, $SHF08COM,
1536 $SHF08FLAGS, $SHF08PPCOM, $_F08INCFLAGS.
1537 Uses: $F08COMSTR, $F08PPCOMSTR, $SHF08COMSTR, $SHF08PPCOMSTR.
1539 f77
1541 Set construction variables for generic POSIX Fortran 77 compilers.
1542 Sets: $F77, $F77COM, $F77FILESUFFIXES, $F77FLAGS, $F77PPCOM,
1544 $F77PPFILESUFFIXES, $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHF77,
1545 $SHF77COM, $SHF77FLAGS, $SHF77PPCOM, $SHFORTRAN, $SHFORTRANCOM,
1546 $SHFORTRANFLAGS, $SHFORTRANPPCOM, $_F77INCFLAGS.
1547 Uses: $F77COMSTR, $F77PPCOMSTR, $FORTRANCOMSTR, $FORTRANPPCOMSTR,
1549 $SHF77COMSTR, $SHF77PPCOMSTR, $SHFORTRANCOMSTR, $SHFORTRANPPCOMSTR.
1550 f90
1552 Set construction variables for generic POSIX Fortran 90 compilers.
1553 Sets: $F90, $F90COM, $F90FLAGS, $F90PPCOM, $SHF90, $SHF90COM,
1555 $SHF90FLAGS, $SHF90PPCOM, $_F90INCFLAGS.
1556 Uses: $F90COMSTR, $F90PPCOMSTR, $SHF90COMSTR, $SHF90PPCOMSTR.
1558 f95
1560 Set construction variables for generic POSIX Fortran 95 compilers.
1561 Sets: $F95, $F95COM, $F95FLAGS, $F95PPCOM, $SHF95, $SHF95COM,
1563 $SHF95FLAGS, $SHF95PPCOM, $_F95INCFLAGS.
1564 Uses: $F95COMSTR, $F95PPCOMSTR, $SHF95COMSTR, $SHF95PPCOMSTR.
1566 fortran
1568 Set construction variables for generic POSIX Fortran compilers.
1569 Sets: $FORTRAN, $FORTRANCOM, $FORTRANFLAGS, $SHFORTRAN,
1571 $SHFORTRANCOM, $SHFORTRANFLAGS, $SHFORTRANPPCOM.
1572 Uses: $FORTRANCOMSTR, $FORTRANPPCOMSTR, $SHFORTRANCOMSTR,
1574 $SHFORTRANPPCOMSTR.
1575 g++
1577 Set construction variables for the gXX C++ compiler.
1578 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS, $SHOBJSUFFIX.
1580 g77
1582 Set construction variables for the g77 Fortran compiler. Calls the
1583 f77 Tool module to set variables.
1584 gas
1586 Sets construction variables for the gas assembler. Calls the as
1587 module.
1588 Sets: $AS.
1590 gcc
1592 Set construction variables for the gcc C compiler.
1593 Sets: $CC, $CCVERSION, $SHCCFLAGS.
1595 gdc
1597 Sets construction variables for the D language compiler GDC.
1598 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1600 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1601 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1602 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1603 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1604 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DShLibSonameGenerator,
1605 $DVERPREFIX, $DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM,
1606 $SHDLIBVERSION, $SHDLIBVERSIONFLAGS, $SHDLINK, $SHDLINKCOM,
1607 $SHDLINKFLAGS.
1608 gettext
1610 This is actually a toolset, which supports internationalization and
1611 localization of software being constructed with SCons. The toolset
1612 loads following tools:
1613 · xgettext - to extract internationalized messages from source
1617 code to POT file(s),
1618 · msginit - may be optionally used to initialize PO files,
1620 · msgmerge - to update PO files, that already contain translated
1622 messages,
1623 · msgfmt - to compile textual PO file to binary installable MO
1625 file.
1626 When you enable gettext, it internally loads all abovementioned
1628 tools, so you're encouraged to see their individual documentation.
1629 Each of the above tools provides its own builder(s) which may be
1631 used to perform particular activities related to software
1632 internationalization. You may be however interested in top-level
1633 builder Translate described few paragraphs later.
1634 To use gettext tools add 'gettext' tool to your environment:
1636 env = Environment( tools = ['default', 'gettext'] )
1638 gfortran
1640 Sets construction variables for the GNU F95/F2003 GNU compiler.
1641 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1643 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1644 gnulink
1646 Set construction variables for GNU linker/loader.
1647 Sets: $LDMODULEVERSIONFLAGS, $RPATHPREFIX, $RPATHSUFFIX,
1649 $SHLIBVERSIONFLAGS, $SHLINKFLAGS, $_LDMODULESONAME, $_SHLIBSONAME.
1650 gs
1652 This Tool sets the required construction variables for working with
1653 the Ghostscript command. It also registers an appropriate Action
1654 with the PDF Builder (PDF), such that the conversion from PS/EPS to
1655 PDF happens automatically for the TeX/LaTeX toolchain. Finally, it
1656 adds an explicit Ghostscript Builder (Gs) to the environment.
1657 Sets: $GS, $GSCOM, $GSFLAGS.
1659 Uses: $GSCOMSTR.
1661 hpc++
1663 Set construction variables for the compilers aCC on HP/UX systems.
1664 hpcc
1666 Set construction variables for the aCC on HP/UX systems. Calls the
1667 cXX tool for additional variables.
1668 Sets: $CXX, $CXXVERSION, $SHCXXFLAGS.
1670 hplink
1672 Sets construction variables for the linker on HP/UX systems.
1673 Sets: $LINKFLAGS, $SHLIBSUFFIX, $SHLINKFLAGS.
1675 icc
1677 Sets construction variables for the icc compiler on OS/2 systems.
1678 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1680 $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX.
1681 Uses: $CCFLAGS, $CFLAGS, $CPPFLAGS, $_CPPDEFFLAGS, $_CPPINCFLAGS.
1683 icl
1685 Sets construction variables for the Intel C/C++ compiler. Calls the
1686 intelc Tool module to set its variables.
1687 ifl
1689 Sets construction variables for the Intel Fortran compiler.
1690 Sets: $FORTRAN, $FORTRANCOM, $FORTRANPPCOM, $SHFORTRANCOM,
1692 $SHFORTRANPPCOM.
1693 Uses: $CPPFLAGS, $FORTRANFLAGS, $_CPPDEFFLAGS, $_FORTRANINCFLAGS.
1695 ifort
1697 Sets construction variables for newer versions of the Intel Fortran
1698 compiler for Linux.
1699 Sets: $F77, $F90, $F95, $FORTRAN, $SHF77, $SHF77FLAGS, $SHF90,
1701 $SHF90FLAGS, $SHF95, $SHF95FLAGS, $SHFORTRAN, $SHFORTRANFLAGS.
1702 ilink
1704 Sets construction variables for the ilink linker on OS/2 systems.
1705 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1707 $LINK, $LINKCOM, $LINKFLAGS.
1708 ilink32
1710 Sets construction variables for the Borland ilink32 linker.
1711 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1713 $LINK, $LINKCOM, $LINKFLAGS.
1714 install
1716 Sets construction variables for file and directory installation.
1717 Sets: $INSTALL, $INSTALLSTR.
1719 intelc
1721 Sets construction variables for the Intel C/C++ compiler (Linux and
1722 Windows, version 7 and later). Calls the gcc or msvc (on Linux and
1723 Windows, respectively) to set underlying variables.
1724 Sets: $AR, $CC, $CXX, $INTEL_C_COMPILER_VERSION, $LINK.
1726 jar
1728 Sets construction variables for the jar utility.
1729 Sets: $JAR, $JARCOM, $JARFLAGS, $JARSUFFIX.
1731 Uses: $JARCOMSTR.
1733 javac
1735 Sets construction variables for the javac compiler.
1736 Sets: $JAVABOOTCLASSPATH, $JAVAC, $JAVACCOM, $JAVACFLAGS,
1738 $JAVACLASSPATH, $JAVACLASSSUFFIX, $JAVASOURCEPATH, $JAVASUFFIX.
1739 Uses: $JAVACCOMSTR.
1741 javah
1743 Sets construction variables for the javah tool.
1744 Sets: $JAVACLASSSUFFIX, $JAVAH, $JAVAHCOM, $JAVAHFLAGS.
1746 Uses: $JAVACLASSPATH, $JAVAHCOMSTR.
1748 latex
1750 Sets construction variables for the latex utility.
1751 Sets: $LATEX, $LATEXCOM, $LATEXFLAGS.
1753 Uses: $LATEXCOMSTR.
1755 ldc
1757 Sets construction variables for the D language compiler LDC2.
1758 Sets: $DC, $DCOM, $DDEBUG, $DDEBUGPREFIX, $DDEBUGSUFFIX,
1760 $DFILESUFFIX, $DFLAGPREFIX, $DFLAGS, $DFLAGSUFFIX, $DINCPREFIX,
1761 $DINCSUFFIX, $DLIB, $DLIBCOM, $DLIBDIRPREFIX, $DLIBDIRSUFFIX,
1762 $DLIBFLAGPREFIX, $DLIBFLAGSUFFIX, $DLIBLINKPREFIX, $DLIBLINKSUFFIX,
1763 $DLINK, $DLINKCOM, $DLINKFLAGPREFIX, $DLINKFLAGS, $DLINKFLAGSUFFIX,
1764 $DPATH, $DRPATHPREFIX, $DRPATHSUFFIX, $DShLibSonameGenerator,
1765 $DVERPREFIX, $DVERSIONS, $DVERSUFFIX, $SHDC, $SHDCOM,
1766 $SHDLIBVERSION, $SHDLIBVERSIONFLAGS, $SHDLINK, $SHDLINKCOM,
1767 $SHDLINKFLAGS.
1768 lex
1770 Sets construction variables for the lex lexical analyser.
1771 Sets: $LEX, $LEXCOM, $LEXFLAGS.
1773 Uses: $LEXCOMSTR.
1775 link
1777 Sets construction variables for generic POSIX linkers.
1778 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS,
1780 $LDMODULENOVERSIONSYMLINKS, $LDMODULEPREFIX, $LDMODULESUFFIX,
1781 $LDMODULEVERSION, $LDMODULEVERSIONFLAGS, $LIBDIRPREFIX,
1782 $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX, $LINK, $LINKCOM,
1783 $LINKFLAGS, $SHLIBSUFFIX, $SHLINK, $SHLINKCOM, $SHLINKFLAGS,
1784 $__LDMODULEVERSIONFLAGS, $__SHLIBVERSIONFLAGS.
1785 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $SHLINKCOMSTR.
1787 linkloc
1789 Sets construction variables for the LinkLoc linker for the Phar Lap
1790 ETS embedded operating system.
1791 Sets: $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX, $LIBLINKSUFFIX,
1793 $LINK, $LINKCOM, $LINKFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
1794 Uses: $LINKCOMSTR, $SHLINKCOMSTR.
1796 m4
1798 Sets construction variables for the m4 macro processor.
1799 Sets: $M4, $M4COM, $M4FLAGS.
1801 Uses: $M4COMSTR.
1803 masm
1805 Sets construction variables for the Microsoft assembler.
1806 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1808 Uses: $ASCOMSTR, $ASPPCOMSTR, $CPPFLAGS, $_CPPDEFFLAGS,
1810 $_CPPINCFLAGS.
1811 midl
1813 Sets construction variables for the Microsoft IDL compiler.
1814 Sets: $MIDL, $MIDLCOM, $MIDLFLAGS.
1816 Uses: $MIDLCOMSTR.
1818 mingw
1820 Sets construction variables for MinGW (Minimal Gnu on Windows).
1821 Sets: $AS, $CC, $CXX, $LDMODULECOM, $LIBPREFIX, $LIBSUFFIX,
1823 $OBJSUFFIX, $RC, $RCCOM, $RCFLAGS, $RCINCFLAGS, $RCINCPREFIX,
1824 $RCINCSUFFIX, $SHCCFLAGS, $SHCXXFLAGS, $SHLINKCOM, $SHLINKFLAGS,
1825 $SHOBJSUFFIX, $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX.
1826 Uses: $RCCOMSTR, $SHLINKCOMSTR.
1828 msgfmt
1830 This scons tool is a part of scons gettext toolset. It provides
1831 scons interface to msgfmt(1) command, which generates binary
1832 message catalog (MO) from a textual translation description (PO).
1833 Sets: $MOSUFFIX, $MSGFMT, $MSGFMTCOM, $MSGFMTCOMSTR, $MSGFMTFLAGS,
1835 $POSUFFIX.
1836 Uses: $LINGUAS_FILE.
1838 msginit
1840 This scons tool is a part of scons gettext toolset. It provides
1841 scons interface to msginit(1) program, which creates new PO file,
1842 initializing the meta information with values from user's
1843 environment (or options).
1844 Sets: $MSGINIT, $MSGINITCOM, $MSGINITCOMSTR, $MSGINITFLAGS,
1846 $POAUTOINIT, $POCREATE_ALIAS, $POSUFFIX, $POTSUFFIX,
1847 $_MSGINITLOCALE.
1848 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1850 msgmerge
1852 This scons tool is a part of scons gettext toolset. It provides
1853 scons interface to msgmerge(1) command, which merges two Uniform
1854 style .po files together.
1855 Sets: $MSGMERGE, $MSGMERGECOM, $MSGMERGECOMSTR, $MSGMERGEFLAGS,
1857 $POSUFFIX, $POTSUFFIX, $POUPDATE_ALIAS.
1858 Uses: $LINGUAS_FILE, $POAUTOINIT, $POTDOMAIN.
1860 mslib
1862 Sets construction variables for the Microsoft mslib library
1863 archiver.
1864 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
1866 Uses: $ARCOMSTR.
1868 mslink
1870 Sets construction variables for the Microsoft linker.
1871 Sets: $LDMODULE, $LDMODULECOM, $LDMODULEFLAGS, $LDMODULEPREFIX,
1873 $LDMODULESUFFIX, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
1874 $LIBLINKSUFFIX, $LINK, $LINKCOM, $LINKFLAGS, $REGSVR, $REGSVRCOM,
1875 $REGSVRFLAGS, $SHLINK, $SHLINKCOM, $SHLINKFLAGS, $WIN32DEFPREFIX,
1876 $WIN32DEFSUFFIX, $WIN32EXPPREFIX, $WIN32EXPSUFFIX,
1877 $WINDOWSDEFPREFIX, $WINDOWSDEFSUFFIX, $WINDOWSEXPPREFIX,
1878 $WINDOWSEXPSUFFIX, $WINDOWSPROGMANIFESTPREFIX,
1879 $WINDOWSPROGMANIFESTSUFFIX, $WINDOWSSHLIBMANIFESTPREFIX,
1880 $WINDOWSSHLIBMANIFESTSUFFIX, $WINDOWS_INSERT_DEF.
1881 Uses: $LDMODULECOMSTR, $LINKCOMSTR, $REGSVRCOMSTR, $SHLINKCOMSTR.
1883 mssdk
1885 Sets variables for Microsoft Platform SDK and/or Windows SDK. Note
1886 that unlike most other Tool modules, mssdk does not set
1887 construction variables, but sets the environment variables in the
1888 environment SCons uses to execute the Microsoft toolchain:
1889 %INCLUDE%, %LIB%, %LIBPATH% and %PATH%.
1890 Uses: $MSSDK_DIR, $MSSDK_VERSION, $MSVS_VERSION.
1892 msvc
1894 Sets construction variables for the Microsoft Visual C/C++
1895 compiler.
1896 Sets: $BUILDERS, $CC, $CCCOM, $CCFLAGS, $CCPCHFLAGS, $CCPDBFLAGS,
1898 $CFILESUFFIX, $CFLAGS, $CPPDEFPREFIX, $CPPDEFSUFFIX, $CXX, $CXXCOM,
1899 $CXXFILESUFFIX, $CXXFLAGS, $INCPREFIX, $INCSUFFIX, $OBJPREFIX,
1900 $OBJSUFFIX, $PCHCOM, $PCHPDBFLAGS, $RC, $RCCOM, $RCFLAGS, $SHCC,
1901 $SHCCCOM, $SHCCFLAGS, $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS,
1902 $SHOBJPREFIX, $SHOBJSUFFIX.
1903 Uses: $CCCOMSTR, $CXXCOMSTR, $PCH, $PCHSTOP, $PDB, $SHCCCOMSTR,
1905 $SHCXXCOMSTR.
1906 msvs
1908 Sets construction variables for Microsoft Visual Studio.
1909 Sets: $MSVSBUILDCOM, $MSVSCLEANCOM, $MSVSENCODING, $MSVSPROJECTCOM,
1911 $MSVSREBUILDCOM, $MSVSSCONS, $MSVSSCONSCOM, $MSVSSCONSCRIPT,
1912 $MSVSSCONSFLAGS, $MSVSSOLUTIONCOM.
1913 mwcc
1915 Sets construction variables for the Metrowerks CodeWarrior
1916 compiler.
1917 Sets: $CC, $CCCOM, $CFILESUFFIX, $CPPDEFPREFIX, $CPPDEFSUFFIX,
1919 $CXX, $CXXCOM, $CXXFILESUFFIX, $INCPREFIX, $INCSUFFIX,
1920 $MWCW_VERSION, $MWCW_VERSIONS, $SHCC, $SHCCCOM, $SHCCFLAGS,
1921 $SHCFLAGS, $SHCXX, $SHCXXCOM, $SHCXXFLAGS.
1922 Uses: $CCCOMSTR, $CXXCOMSTR, $SHCCCOMSTR, $SHCXXCOMSTR.
1924 mwld
1926 Sets construction variables for the Metrowerks CodeWarrior linker.
1927 Sets: $AR, $ARCOM, $LIBDIRPREFIX, $LIBDIRSUFFIX, $LIBLINKPREFIX,
1929 $LIBLINKSUFFIX, $LINK, $LINKCOM, $SHLINK, $SHLINKCOM, $SHLINKFLAGS.
1930 nasm
1932 Sets construction variables for the nasm Netwide Assembler.
1933 Sets: $AS, $ASCOM, $ASFLAGS, $ASPPCOM, $ASPPFLAGS.
1935 Uses: $ASCOMSTR, $ASPPCOMSTR.
1937 packaging
1939 A framework for building binary and source packages.
1940 Packaging
1942 Sets construction variables for the Package Builder.
1943 pdf
1945 Sets construction variables for the Portable Document Format
1946 builder.
1947 Sets: $PDFPREFIX, $PDFSUFFIX.
1949 pdflatex
1951 Sets construction variables for the pdflatex utility.
1952 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS.
1954 Uses: $PDFLATEXCOMSTR.
1956 pdftex
1958 Sets construction variables for the pdftex utility.
1959 Sets: $LATEXRETRIES, $PDFLATEX, $PDFLATEXCOM, $PDFLATEXFLAGS,
1961 $PDFTEX, $PDFTEXCOM, $PDFTEXFLAGS.
1962 Uses: $PDFLATEXCOMSTR, $PDFTEXCOMSTR.
1964 qt
1966 Sets construction variables for building Qt applications.
1967 Sets: $QTDIR, $QT_AUTOSCAN, $QT_BINPATH, $QT_CPPPATH, $QT_LIB,
1969 $QT_LIBPATH, $QT_MOC, $QT_MOCCXXPREFIX, $QT_MOCCXXSUFFIX,
1970 $QT_MOCFROMCXXCOM, $QT_MOCFROMCXXFLAGS, $QT_MOCFROMHCOM,
1971 $QT_MOCFROMHFLAGS, $QT_MOCHPREFIX, $QT_MOCHSUFFIX, $QT_UIC,
1972 $QT_UICCOM, $QT_UICDECLFLAGS, $QT_UICDECLPREFIX, $QT_UICDECLSUFFIX,
1973 $QT_UICIMPLFLAGS, $QT_UICIMPLPREFIX, $QT_UICIMPLSUFFIX,
1974 $QT_UISUFFIX.
1975 rmic
1977 Sets construction variables for the rmic utility.
1978 Sets: $JAVACLASSSUFFIX, $RMIC, $RMICCOM, $RMICFLAGS.
1980 Uses: $RMICCOMSTR.
1982 rpcgen
1984 Sets construction variables for building with RPCGEN.
1985 Sets: $RPCGEN, $RPCGENCLIENTFLAGS, $RPCGENFLAGS,
1987 $RPCGENHEADERFLAGS, $RPCGENSERVICEFLAGS, $RPCGENXDRFLAGS.
1988 sgiar
1990 Sets construction variables for the SGI library archiver.
1991 Sets: $AR, $ARCOMSTR, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX, $SHLINK,
1993 $SHLINKFLAGS.
1994 Uses: $ARCOMSTR, $SHLINKCOMSTR.
1996 sgic++
1998 Sets construction variables for the SGI C++ compiler.
1999 Sets: $CXX, $CXXFLAGS, $SHCXX, $SHOBJSUFFIX.
2001 sgicc
2003 Sets construction variables for the SGI C compiler.
2004 Sets: $CXX, $SHOBJSUFFIX.
2006 sgilink
2008 Sets construction variables for the SGI linker.
2009 Sets: $LINK, $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2011 sunar
2013 Sets construction variables for the Sun library archiver.
2014 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2016 Uses: $ARCOMSTR.
2018 sunc++
2020 Sets construction variables for the Sun C++ compiler.
2021 Sets: $CXX, $CXXVERSION, $SHCXX, $SHCXXFLAGS, $SHOBJPREFIX,
2023 $SHOBJSUFFIX.
2024 suncc
2026 Sets construction variables for the Sun C compiler.
2027 Sets: $CXX, $SHCCFLAGS, $SHOBJPREFIX, $SHOBJSUFFIX.
2029 sunf77
2031 Set construction variables for the Sun f77 Fortran compiler.
2032 Sets: $F77, $FORTRAN, $SHF77, $SHF77FLAGS, $SHFORTRAN,
2034 $SHFORTRANFLAGS.
2035 sunf90
2037 Set construction variables for the Sun f90 Fortran compiler.
2038 Sets: $F90, $FORTRAN, $SHF90, $SHF90FLAGS, $SHFORTRAN,
2040 $SHFORTRANFLAGS.
2041 sunf95
2043 Set construction variables for the Sun f95 Fortran compiler.
2044 Sets: $F95, $FORTRAN, $SHF95, $SHF95FLAGS, $SHFORTRAN,
2046 $SHFORTRANFLAGS.
2047 sunlink
2049 Sets construction variables for the Sun linker.
2050 Sets: $RPATHPREFIX, $RPATHSUFFIX, $SHLINKFLAGS.
2052 swig
2054 Sets construction variables for the SWIG interface generator.
2055 Sets: $SWIG, $SWIGCFILESUFFIX, $SWIGCOM, $SWIGCXXFILESUFFIX,
2057 $SWIGDIRECTORSUFFIX, $SWIGFLAGS, $SWIGINCPREFIX, $SWIGINCSUFFIX,
2058 $SWIGPATH, $SWIGVERSION, $_SWIGINCFLAGS.
2059 Uses: $SWIGCOMSTR.
2061 tar
2063 Sets construction variables for the tar archiver.
2064 Sets: $TAR, $TARCOM, $TARFLAGS, $TARSUFFIX.
2066 Uses: $TARCOMSTR.
2068 tex
2070 Sets construction variables for the TeX formatter and typesetter.
2071 Sets: $BIBTEX, $BIBTEXCOM, $BIBTEXFLAGS, $LATEX, $LATEXCOM,
2073 $LATEXFLAGS, $MAKEINDEX, $MAKEINDEXCOM, $MAKEINDEXFLAGS, $TEX,
2074 $TEXCOM, $TEXFLAGS.
2075 Uses: $BIBTEXCOMSTR, $LATEXCOMSTR, $MAKEINDEXCOMSTR, $TEXCOMSTR.
2077 textfile
2079 Set construction variables for the Textfile and Substfile builders.
2080 Sets: $LINESEPARATOR, $SUBSTFILEPREFIX, $SUBSTFILESUFFIX,
2082 $TEXTFILEPREFIX, $TEXTFILESUFFIX.
2083 Uses: $SUBST_DICT.
2085 tlib
2087 Sets construction variables for the Borlan tib library archiver.
2088 Sets: $AR, $ARCOM, $ARFLAGS, $LIBPREFIX, $LIBSUFFIX.
2090 Uses: $ARCOMSTR.
2092 xgettext
2094 This scons tool is a part of scons gettext toolset. It provides
2095 scons interface to xgettext(1) program, which extracts
2096 internationalized messages from source code. The tool provides
2097 POTUpdate builder to make PO Template files.
2098 Sets: $POTSUFFIX, $POTUPDATE_ALIAS, $XGETTEXTCOM, $XGETTEXTCOMSTR,
2100 $XGETTEXTFLAGS, $XGETTEXTFROM, $XGETTEXTFROMPREFIX,
2101 $XGETTEXTFROMSUFFIX, $XGETTEXTPATH, $XGETTEXTPATHPREFIX,
2102 $XGETTEXTPATHSUFFIX, $_XGETTEXTDOMAIN, $_XGETTEXTFROMFLAGS,
2103 $_XGETTEXTPATHFLAGS.
2104 Uses: $POTDOMAIN.
2106 yacc
2108 Sets construction variables for the yacc parse generator.
2109 Sets: $YACC, $YACCCOM, $YACCFLAGS, $YACCHFILESUFFIX,
2111 $YACCHXXFILESUFFIX, $YACCVCGFILESUFFIX.
2112 Uses: $YACCCOMSTR.
2114 zip
2116 Sets construction variables for the zip archiver.
2117 Sets: $ZIP, $ZIPCOM, $ZIPCOMPRESSION, $ZIPFLAGS, $ZIPSUFFIX.
2119 Uses: $ZIPCOMSTR.
2121 Additionally, there is a "tool" named default which configures the
2123 environment with a default set of tools for the current platform.
2124 On posix and cygwin platforms the GNU tools (e.g. gcc) are preferred by
2126 SCons, on Windows the Microsoft tools (e.g. msvc) followed by MinGW are
2127 preferred by SCons, and in OS/2 the IBM tools (e.g. icc) are preferred
2128 by SCons.
2129 Builder Methods
2131 Build rules are specified by calling a construction environment's
2132 builder methods. The arguments to the builder methods are target (a
2133 list of targets to be built, usually file names) and source (a list of
2134 sources to be built, usually file names).
2135 Because long lists of file names can lead to a lot of quoting, scons
2137 supplies a Split() global function and a same-named environment method
2138 that split a single string into a list, separated on strings of
2139 white-space characters. (These are similar to the split() member
2140 function of Python strings but work even if the input isn't a string.)
2141 Like all Python arguments, the target and source arguments to a builder
2143 method can be specified either with or without the "target" and
2144 "source" keywords. When the keywords are omitted, the target is first,
2145 followed by the source. The following are equivalent examples of
2146 calling the Program builder method:
2147 env.Program('bar', ['bar.c', 'foo.c'])
2149 env.Program('bar', Split('bar.c foo.c'))
2150 env.Program('bar', env.Split('bar.c foo.c'))
2151 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
2152 env.Program(target = 'bar', Split('bar.c foo.c'))
2153 env.Program(target = 'bar', env.Split('bar.c foo.c'))
2154 env.Program('bar', source = 'bar.c foo.c'.split())
2155 Target and source file names that are not absolute path names (that is,
2157 do not begin with / on POSIX systems or \fR on Windows systems, with or
2158 without an optional drive letter) are interpreted relative to the
2159 directory containing the SConscript file being read. An initial # (hash
2160 mark) on a path name means that the rest of the file name is
2161 interpreted relative to the directory containing the top-level
2162 SConstruct file, even if the # is followed by a directory separator
2163 character (slash or backslash).
2164 Examples:
2166 # The comments describing the targets that will be built
2168 # assume these calls are in a SConscript file in the
2169 # a subdirectory named "subdir".
2170 # Builds the program "subdir/foo" from "subdir/foo.c":
2172 env.Program('foo', 'foo.c')
2173 # Builds the program "/tmp/bar" from "subdir/bar.c":
2175 env.Program('/tmp/bar', 'bar.c')
2176 # An initial '#' or '#/' are equivalent; the following
2178 # calls build the programs "foo" and "bar" (in the
2179 # top-level SConstruct directory) from "subdir/foo.c" and
2180 # "subdir/bar.c", respectively:
2181 env.Program('#foo', 'foo.c')
2182 env.Program('#/bar', 'bar.c')
2183 # Builds the program "other/foo" (relative to the top-level
2185 # SConstruct directory) from "subdir/foo.c":
2186 env.Program('#other/foo', 'foo.c')
2187 When the target shares the same base name as the source and only the
2189 suffix varies, and if the builder method has a suffix defined for the
2190 target file type, then the target argument may be omitted completely,
2191 and scons will deduce the target file name from the source file name.
2192 The following examples all build the executable program bar (on POSIX
2193 systems) or bar.exe (on Windows systems) from the bar.c source file:
2194 env.Program(target = 'bar', source = 'bar.c')
2196 env.Program('bar', source = 'bar.c')
2197 env.Program(source = 'bar.c')
2198 env.Program('bar.c')
2199 As a convenience, a srcdir keyword argument may be specified when
2201 calling a Builder. When specified, all source file strings that are not
2202 absolute paths will be interpreted relative to the specified srcdir.
2203 The following example will build the build/prog (or build/prog.exe on
2204 Windows) program from the files src/f1.c and src/f2.c:
2205 env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src')
2207 It is possible to override or add construction variables when calling a
2209 builder method by passing additional keyword arguments. These
2210 overridden or added variables will only be in effect when building the
2211 target, so they will not affect other parts of the build. For example,
2212 if you want to add additional libraries for just one program:
2213 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
2215 or generate a shared library with a non-standard suffix:
2217 env.SharedLibrary('word', 'word.cpp',
2219 SHLIBSUFFIX='.ocx',
2220 LIBSUFFIXES=['.ocx'])
2221 (Note that both the $SHLIBSUFFIX and $LIBSUFFIXES variables must be set
2223 if you want SCons to search automatically for dependencies on the
2224 non-standard library names; see the descriptions of these variables,
2225 below, for more information.)
2226 It is also possible to use the parse_flags keyword argument in an
2228 override:
2229 env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm')
2231 This example adds 'include' to CPPPATH, 'EBUG' to CPPDEFINES, and 'm'
2233 to LIBS.
2234 Although the builder methods defined by scons are, in fact, methods of
2236 a construction environment object, they may also be called without an
2237 explicit environment:
2238 Program('hello', 'hello.c')
2240 SharedLibrary('word', 'word.cpp')
2241 In this case, the methods are called internally using a default
2243 construction environment that consists of the tools and values that
2244 scons has determined are appropriate for the local system.
2245 Builder methods that can be called without an explicit environment may
2247 be called from custom Python modules that you import into an SConscript
2248 file by adding the following to the Python module:
2249 from SCons.Script import *
2251 All builder methods return a list-like object containing Nodes that
2253 represent the target or targets that will be built. A Node is an
2254 internal SCons object which represents build targets or sources.
2255 The returned Node-list object can be passed to other builder methods as
2257 source(s) or passed to any SCons function or method where a filename
2258 would normally be accepted. For example, if it were necessary to add a
2259 specific -D flag when compiling one specific object file:
2260 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2262 env.Program(source = ['foo.c', bar_obj_list, 'main.c'])
2263 Using a Node in this way makes for a more portable build by avoiding
2265 having to specify a platform-specific object suffix when calling the
2266 Program() builder method.
2267 Note that Builder calls will automatically "flatten" the source and
2269 target file lists, so it's all right to have the bar_obj list return by
2270 the StaticObject() call in the middle of the source file list. If you
2271 need to manipulate a list of lists returned by Builders directly using
2272 Python, you can either build the list by hand:
2273 foo = Object('foo.c')
2275 bar = Object('bar.c')
2276 objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o']
2277 for object in objects:
2278 print(str(object))
2279 Or you can use the Flatten() function supplied by scons to create a
2281 list containing just the Nodes, which may be more convenient:
2282 foo = Object('foo.c')
2284 bar = Object('bar.c')
2285 objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o'])
2286 for object in objects:
2287 print(str(object))
2288 Note also that because Builder calls return a list-like object, not an
2290 actual Python list, you should not use the Python += operator to append
2291 Builder results to a Python list. Because the list and the object are
2292 different types, Python will not update the original list in place, but
2293 will instead create a new Node-list object containing the concatenation
2294 of the list elements and the Builder results. This will cause problems
2295 for any other Python variables in your SCons configuration that still
2296 hold on to a reference to the original list. Instead, use the Python
2297 .extend() method to make sure the list is updated in-place. Example:
2298 object_files = []
2300 # Do NOT use += as follows:
2302 #
2303 # object_files += Object('bar.c')
2304 #
2305 # It will not update the object_files list in place.
2306 #
2307 # Instead, use the .extend() method:
2308 object_files.extend(Object('bar.c'))
2309 The path name for a Node's file may be used by passing the Node to the
2312 Python-builtin str() function:
2313 bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR')
2315 print("The path to bar_obj is:", str(bar_obj_list[0]))
2316 Note again that because the Builder call returns a list, we have to
2318 access the first element in the list (bar_obj_list[0]) to get at the
2319 Node that actually represents the object file.
2320 Builder calls support a chdir keyword argument that specifies that the
2322 Builder's action(s) should be executed after changing directory. If the
2323 chdir argument is a string or a directory Node, scons will change to
2324 the specified directory. If the chdir is not a string or Node and is
2325 non-zero, then scons will change to the target file's directory.
2326 # scons will change to the "sub" subdirectory
2328 # before executing the "cp" command.
2329 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2330 "cp dir/foo.in dir/foo.out",
2331 chdir='sub')
2332 # Because chdir is not a string, scons will change to the
2334 # target's directory ("sub/dir") before executing the
2335 # "cp" command.
2336 env.Command('sub/dir/foo.out', 'sub/dir/foo.in',
2337 "cp foo.in foo.out",
2338 chdir=1)
2339 Note that scons will not automatically modify its expansion of
2341 construction variables like $TARGET and $SOURCE when using the chdir
2342 keyword argument--that is, the expanded file names will still be
2343 relative to the top-level SConstruct directory, and consequently
2344 incorrect relative to the chdir directory. If you use the chdir keyword
2345 argument, you will typically need to supply a different command line
2346 using expansions like ${TARGET.file} and ${SOURCE.file} to use just the
2347 filename portion of the targets and source.
2348 scons provides the following builder methods:
2350 CFile(), env.CFile()
2352 Builds a C source file given a lex (.l) or yacc (.y) input file.
2353 The suffix specified by the $CFILESUFFIX construction variable (.c
2354 by default) is automatically added to the target if it is not
2355 already present. Example:
2356 # builds foo.c
2358 env.CFile(target = 'foo.c', source = 'foo.l')
2359 # builds bar.c
2360 env.CFile(target = 'bar', source = 'bar.y')
2361 Command(), env.Command()
2363 The Command "Builder" is actually implemented as a function that
2364 looks like a Builder, but actually takes an additional argument of
2365 the action from which the Builder should be made. See the Command
2366 function description for the calling syntax and details.
2367 CXXFile(), env.CXXFile()
2369 Builds a C++ source file given a lex (.ll) or yacc (.yy) input
2370 file. The suffix specified by the $CXXFILESUFFIX construction
2371 variable (.cc by default) is automatically added to the target if
2372 it is not already present. Example:
2373 # builds foo.cc
2375 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
2376 # builds bar.cc
2377 env.CXXFile(target = 'bar', source = 'bar.yy')
2378 DocbookEpub(), env.DocbookEpub()
2380 A pseudo-Builder, providing a Docbook toolchain for EPUB output.
2381 env = Environment(tools=['docbook'])
2383 env.DocbookEpub('manual.epub', 'manual.xml')
2384 or simply
2386 env = Environment(tools=['docbook'])
2388 env.DocbookEpub('manual')
2389 DocbookHtml(), env.DocbookHtml()
2391 A pseudo-Builder, providing a Docbook toolchain for HTML output.
2392 env = Environment(tools=['docbook'])
2394 env.DocbookHtml('manual.html', 'manual.xml')
2395 or simply
2397 env = Environment(tools=['docbook'])
2399 env.DocbookHtml('manual')
2400 DocbookHtmlChunked(), env.DocbookHtmlChunked()
2402 A pseudo-Builder, providing a Docbook toolchain for chunked HTML
2403 output. It supports the base.dir parameter. The chunkfast.xsl file
2404 (requires "EXSLT") is used as the default stylesheet. Basic syntax:
2405 env = Environment(tools=['docbook'])
2407 env.DocbookHtmlChunked('manual')
2408 where manual.xml is the input file.
2410 If you use the root.filename parameter in your own stylesheets you
2412 have to specify the new target name. This ensures that the
2413 dependencies get correct, especially for the cleanup via “scons
2414 -c”:
2415 env = Environment(tools=['docbook'])
2417 env.DocbookHtmlChunked('mymanual.html', 'manual', xsl='htmlchunk.xsl')
2418 Some basic support for the base.dir is provided. You can add the
2420 base_dir keyword to your Builder call, and the given prefix gets
2421 prepended to all the created filenames:
2422 env = Environment(tools=['docbook'])
2424 env.DocbookHtmlChunked('manual', xsl='htmlchunk.xsl', base_dir='output/')
2425 Make sure that you don't forget the trailing slash for the base
2427 folder, else your files get renamed only!
2428 DocbookHtmlhelp(), env.DocbookHtmlhelp()
2430 A pseudo-Builder, providing a Docbook toolchain for HTMLHELP
2431 output. Its basic syntax is:
2432 env = Environment(tools=['docbook'])
2434 env.DocbookHtmlhelp('manual')
2435 where manual.xml is the input file.
2437 If you use the root.filename parameter in your own stylesheets you
2439 have to specify the new target name. This ensures that the
2440 dependencies get correct, especially for the cleanup via “scons
2441 -c”:
2442 env = Environment(tools=['docbook'])
2444 env.DocbookHtmlhelp('mymanual.html', 'manual', xsl='htmlhelp.xsl')
2445 Some basic support for the base.dir parameter is provided. You can
2447 add the base_dir keyword to your Builder call, and the given prefix
2448 gets prepended to all the created filenames:
2449 env = Environment(tools=['docbook'])
2451 env.DocbookHtmlhelp('manual', xsl='htmlhelp.xsl', base_dir='output/')
2452 Make sure that you don't forget the trailing slash for the base
2454 folder, else your files get renamed only!
2455 DocbookMan(), env.DocbookMan()
2457 A pseudo-Builder, providing a Docbook toolchain for Man page
2458 output. Its basic syntax is:
2459 env = Environment(tools=['docbook'])
2461 env.DocbookMan('manual')
2462 where manual.xml is the input file. Note, that you can specify a
2464 target name, but the actual output names are automatically set from
2465 the refname entries in your XML source.
2466 DocbookPdf(), env.DocbookPdf()
2468 A pseudo-Builder, providing a Docbook toolchain for PDF output.
2469 env = Environment(tools=['docbook'])
2471 env.DocbookPdf('manual.pdf', 'manual.xml')
2472 or simply
2474 env = Environment(tools=['docbook'])
2476 env.DocbookPdf('manual')
2477 DocbookSlidesHtml(), env.DocbookSlidesHtml()
2479 A pseudo-Builder, providing a Docbook toolchain for HTML slides
2480 output.
2481 env = Environment(tools=['docbook'])
2483 env.DocbookSlidesHtml('manual')
2484 If you use the titlefoil.html parameter in your own stylesheets you
2486 have to give the new target name. This ensures that the
2487 dependencies get correct, especially for the cleanup via “scons
2488 -c”:
2489 env = Environment(tools=['docbook'])
2491 env.DocbookSlidesHtml('mymanual.html','manual', xsl='slideshtml.xsl')
2492 Some basic support for the base.dir parameter is provided. You can
2494 add the base_dir keyword to your Builder call, and the given prefix
2495 gets prepended to all the created filenames:
2496 env = Environment(tools=['docbook'])
2498 env.DocbookSlidesHtml('manual', xsl='slideshtml.xsl', base_dir='output/')
2499 Make sure that you don't forget the trailing slash for the base
2501 folder, else your files get renamed only!
2502 DocbookSlidesPdf(), env.DocbookSlidesPdf()
2504 A pseudo-Builder, providing a Docbook toolchain for PDF slides
2505 output.
2506 env = Environment(tools=['docbook'])
2508 env.DocbookSlidesPdf('manual.pdf', 'manual.xml')
2509 or simply
2511 env = Environment(tools=['docbook'])
2513 env.DocbookSlidesPdf('manual')
2514 DocbookXInclude(), env.DocbookXInclude()
2516 A pseudo-Builder, for resolving XIncludes in a separate processing
2517 step.
2518 env = Environment(tools=['docbook'])
2520 env.DocbookXInclude('manual_xincluded.xml', 'manual.xml')
2521 DocbookXslt(), env.DocbookXslt()
2523 A pseudo-Builder, applying a given XSL transformation to the input
2524 file.
2525 env = Environment(tools=['docbook'])
2527 env.DocbookXslt('manual_transformed.xml', 'manual.xml', xsl='transform.xslt')
2528 Note, that this builder requires the xsl parameter to be set.
2530 DVI(), env.DVI()
2532 Builds a .dvi file from a .tex, .ltx or .latex input file. If the
2533 source file suffix is .tex, scons will examine the contents of the
2534 file; if the string \documentclass or \documentstyle is found, the
2535 file is assumed to be a LaTeX file and the target is built by
2536 invoking the $LATEXCOM command line; otherwise, the $TEXCOM command
2537 line is used. If the file is a LaTeX file, the DVI builder method
2538 will also examine the contents of the .aux file and invoke the
2539 $BIBTEX command line if the string bibdata is found, start
2540 $MAKEINDEX to generate an index if a .ind file is found and will
2541 examine the contents .log file and re-run the $LATEXCOM command if
2542 the log file says it is necessary.
2543 The suffix .dvi (hard-coded within TeX itself) is automatically
2545 added to the target if it is not already present. Examples:
2546 # builds from aaa.tex
2548 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
2549 # builds bbb.dvi
2550 env.DVI(target = 'bbb', source = 'bbb.ltx')
2551 # builds from ccc.latex
2552 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
2553 Gs(), env.Gs()
2555 A Builder for explicitly calling the gs executable. Depending on
2556 the underlying OS, the different names gs, gsos2 and gswin32c are
2557 tried.
2558 env = Environment(tools=['gs'])
2560 env.Gs('cover.jpg','scons-scons.pdf',
2561 GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -q')
2562 )
2563 Install(), env.Install()
2565 Installs one or more source files or directories in the specified
2566 target, which must be a directory. The names of the specified
2567 source files or directories remain the same within the destination
2568 directory. The sources may be given as a string or as a node
2569 returned by a builder.
2570 env.Install('/usr/local/bin', source = ['foo', 'bar'])
2572 InstallAs(), env.InstallAs()
2574 Installs one or more source files or directories to specific names,
2575 allowing changing a file or directory name as part of the
2576 installation. It is an error if the target and source arguments
2577 list different numbers of files or directories.
2578 env.InstallAs(target = '/usr/local/bin/foo',
2580 source = 'foo_debug')
2581 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
2582 source = ['libFOO.a', 'libBAR.a'])
2583 InstallVersionedLib(), env.InstallVersionedLib()
2585 Installs a versioned shared library. The symlinks appropriate to
2586 the architecture will be generated based on symlinks of the source
2587 library.
2588 env.InstallVersionedLib(target = '/usr/local/bin/foo',
2590 source = 'libxyz.1.5.2.so')
2591 Jar(), env.Jar()
2593 Builds a Java archive (.jar) file from the specified list of
2594 sources. Any directories in the source list will be searched for
2595 .class files). Any .java files in the source list will be compiled
2596 to .class files by calling the Java Builder.
2597 If the $JARCHDIR value is set, the jar command will change to the
2599 specified directory using the -C option. If $JARCHDIR is not set
2600 explicitly, SCons will use the top of any subdirectory tree in
2601 which Java .class were built by the Java Builder.
2602 If the contents any of the source files begin with the string
2604 Manifest-Version, the file is assumed to be a manifest and is
2605 passed to the jar command with the m option set.
2606 env.Jar(target = 'foo.jar', source = 'classes')
2608 env.Jar(target = 'bar.jar',
2610 source = ['bar1.java', 'bar2.java'])
2611 Java(), env.Java()
2613 Builds one or more Java class files. The sources may be any
2614 combination of explicit .java files, or directory trees which will
2615 be scanned for .java files.
2616 SCons will parse each source .java file to find the classes
2618 (including inner classes) defined within that file, and from that
2619 figure out the target .class files that will be created. The class
2620 files will be placed underneath the specified target directory.
2621 SCons will also search each Java file for the Java package name,
2623 which it assumes can be found on a line beginning with the string
2624 package in the first column; the resulting .class files will be
2625 placed in a directory reflecting the specified package name. For
2626 example, the file Foo.java defining a single public Foo class and
2627 containing a package name of sub.dir will generate a corresponding
2628 sub/dir/Foo.class class file.
2629 Examples:
2631 env.Java(target = 'classes', source = 'src')
2633 env.Java(target = 'classes', source = ['src1', 'src2'])
2634 env.Java(target = 'classes', source = ['File1.java', 'File2.java'])
2635 Java source files can use the native encoding for the underlying
2637 OS. Since SCons compiles in simple ASCII mode by default, the
2638 compiler will generate warnings about unmappable characters, which
2639 may lead to errors as the file is processed further. In this case,
2640 the user must specify the LANG environment variable to tell the
2641 compiler what encoding is used. For portibility, it's best if the
2642 encoding is hard-coded so that the compile will work if it is done
2643 on a system with a different encoding.
2644 env = Environment()
2646 env['ENV']['LANG'] = 'en_GB.UTF-8'
2647 JavaH(), env.JavaH()
2649 Builds C header and source files for implementing Java native
2650 methods. The target can be either a directory in which the header
2651 files will be written, or a header file name which will contain all
2652 of the definitions. The source can be the names of .class files,
2653 the names of .java files to be compiled into .class files by
2654 calling the Java builder method, or the objects returned from the
2655 Java builder method.
2656 If the construction variable $JAVACLASSDIR is set, either in the
2658 environment or in the call to the JavaH builder method itself, then
2659 the value of the variable will be stripped from the beginning of
2660 any .class file names.
2661 Examples:
2663 # builds java_native.h
2665 classes = env.Java(target = 'classdir', source = 'src')
2666 env.JavaH(target = 'java_native.h', source = classes)
2667 # builds include/package_foo.h and include/package_bar.h
2669 env.JavaH(target = 'include',
2670 source = ['package/foo.class', 'package/bar.class'])
2671 # builds export/foo.h and export/bar.h
2673 env.JavaH(target = 'export',
2674 source = ['classes/foo.class', 'classes/bar.class'],
2675 JAVACLASSDIR = 'classes')
2676 Library(), env.Library()
2678 A synonym for the StaticLibrary builder method.
2679 LoadableModule(), env.LoadableModule()
2681 On most systems, this is the same as SharedLibrary. On Mac OS X
2682 (Darwin) platforms, this creates a loadable module bundle.
2683 M4(), env.M4()
2685 Builds an output file from an M4 input file. This uses a default
2686 $M4FLAGS value of -E, which considers all warnings to be fatal and
2687 stops on the first warning when using the GNU version of m4.
2688 Example:
2689 env.M4(target = 'foo.c', source = 'foo.c.m4')
2691 Moc(), env.Moc()
2693 Builds an output file from a moc input file. Moc input files are
2694 either header files or cxx files. This builder is only available
2695 after using the tool 'qt'. See the $QTDIR variable for more
2696 information. Example:
2697 env.Moc('foo.h') # generates moc_foo.cc
2699 env.Moc('foo.cpp') # generates foo.moc
2700 MOFiles(), env.MOFiles()
2702 This builder belongs to msgfmt tool. The builder compiles PO files
2703 to MO files.
2704 Example 1. Create pl.mo and en.mo by compiling pl.po and en.po:
2707 # ...
2709 env.MOFiles(['pl', 'en'])
2710 Example 2. Compile files for languages defined in LINGUAS file:
2713 # ...
2715 env.MOFiles(LINGUAS_FILE = 1)
2716 Example 3. Create pl.mo and en.mo by compiling pl.po and en.po plus
2719 files for languages defined in LINGUAS file:
2720 # ...
2722 env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1)
2723 Example 4. Compile files for languages defined in LINGUAS file
2726 (another version):
2727 # ...
2729 env['LINGUAS_FILE'] = 1
2730 env.MOFiles()
2731 MSVSProject(), env.MSVSProject()
2733 Builds a Microsoft Visual Studio project file, and by default
2734 builds a solution file as well.
2735 This builds a Visual Studio project file, based on the version of
2737 Visual Studio that is configured (either the latest installed
2738 version, or the version specified by $MSVS_VERSION in the
2739 Environment constructor). For Visual Studio 6, it will generate a
2740 .dsp file. For Visual Studio 7 (.NET) and later versions, it will
2741 generate a .vcproj file.
2742 By default, this also generates a solution file for the specified
2744 project, a .dsw file for Visual Studio 6 or a .sln file for Visual
2745 Studio 7 (.NET). This behavior may be disabled by specifying
2746 auto_build_solution=0 when you call MSVSProject, in which case you
2747 presumably want to build the solution file(s) by calling the
2748 MSVSSolution Builder (see below).
2749 The MSVSProject builder takes several lists of filenames to be
2751 placed into the project file. These are currently limited to srcs,
2752 incs, localincs, resources, and misc. These are pretty
2753 self-explanatory, but it should be noted that these lists are added
2754 to the $SOURCES construction variable as strings, NOT as SCons File
2755 Nodes. This is because they represent file names to be added to the
2756 project file, not the source files used to build the project file.
2757 The above filename lists are all optional, although at least one
2759 must be specified for the resulting project file to be non-empty.
2760 In addition to the above lists of values, the following values may
2762 be specified:
2763 target
2765 The name of the target .dsp or .vcproj file. The correct suffix
2766 for the version of Visual Studio must be used, but the
2767 $MSVSPROJECTSUFFIX construction variable will be defined to the
2768 correct value (see example below).
2769 variant
2771 The name of this particular variant. For Visual Studio 7
2772 projects, this can also be a list of variant names. These are
2773 typically things like "Debug" or "Release", but really can be
2774 anything you want. For Visual Studio 7 projects, they may also
2775 specify a target platform separated from the variant name by a
2776 | (vertical pipe) character: Debug|Xbox. The default target
2777 platform is Win32. Multiple calls to MSVSProject with different
2778 variants are allowed; all variants will be added to the project
2779 file with their appropriate build targets and sources.
2780 cmdargs
2782 Additional command line arguments for the different variants.
2783 The number of cmdargs entries must match the number of variant
2784 entries, or be empty (not specified). If you give only one, it
2785 will automatically be propagated to all variants.
2786 buildtarget
2788 An optional string, node, or list of strings or nodes (one per
2789 build variant), to tell the Visual Studio debugger what output
2790 target to use in what build variant. The number of buildtarget
2791 entries must match the number of variant entries.
2792 runfile
2794 The name of the file that Visual Studio 7 and later will run
2795 and debug. This appears as the value of the Output field in the
2796 resulting Visual Studio project file. If this is not specified,
2797 the default is the same as the specified buildtarget value.
2798 Note that because SCons always executes its build commands from the
2800 directory in which the SConstruct file is located, if you generate
2801 a project file in a different directory than the SConstruct
2802 directory, users will not be able to double-click on the file name
2803 in compilation error messages displayed in the Visual Studio
2804 console output window. This can be remedied by adding the Visual
2805 C/C++ /FC compiler option to the $CCFLAGS variable so that the
2806 compiler will print the full path name of any files that cause
2807 compilation errors.
2808 Example usage:
2810 barsrcs = ['bar.cpp']
2812 barincs = ['bar.h']
2813 barlocalincs = ['StdAfx.h']
2814 barresources = ['bar.rc','resource.h']
2815 barmisc = ['bar_readme.txt']
2816 dll = env.SharedLibrary(target = 'bar.dll',
2818 source = barsrcs)
2819 buildtarget = [s for s in dll if str(s).endswith('dll')]
2820 env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
2821 srcs = barsrcs,
2822 incs = barincs,
2823 localincs = barlocalincs,
2824 resources = barresources,
2825 misc = barmisc,
2826 buildtarget = buildtarget,
2827 variant = 'Release')
2828 Starting with version 2.4 of SCons it's also possible to specify
2830 the optional argument DebugSettings, which creates files for
2831 debugging under Visual Studio:
2832 DebugSettings
2834 A dictionary of debug settings that get written to the
2835 .vcproj.user or the .vcxproj.user file, depending on the
2836 version installed. As it is done for cmdargs (see above), you
2837 can specify a DebugSettings dictionary per variant. If you give
2838 only one, it will be propagated to all variants.
2839 Currently, only Visual Studio v9.0 and Visual Studio version v11
2841 are implemented, for other versions no file is generated. To
2842 generate the user file, you just need to add a DebugSettings
2843 dictionary to the environment with the right parameters for your
2844 MSVS version. If the dictionary is empty, or does not contain any
2845 good value, no file will be generated.
2846 Following is a more contrived example, involving the setup of a
2848 project for variants and DebugSettings:
2849 # Assuming you store your defaults in a file
2851 vars = Variables('variables.py')
2852 msvcver = vars.args.get('vc', '9')
2853 # Check command args to force one Microsoft Visual Studio version
2855 if msvcver == '9' or msvcver == '11':
2856 env = Environment(MSVC_VERSION=msvcver+'.0', MSVC_BATCH=False)
2857 else:
2858 env = Environment()
2859 AddOption('--userfile', action='store_true', dest='userfile', default=False,
2861 help="Create Visual Studio Project user file")
2862 #
2864 # 1. Configure your Debug Setting dictionary with options you want in the list
2865 # of allowed options, for instance if you want to create a user file to launch
2866 # a specific application for testing your dll with Microsoft Visual Studio 2008 (v9):
2867 #
2868 V9DebugSettings = {
2869 'Command':'c:\\myapp\\using\\thisdll.exe',
2870 'WorkingDirectory': 'c:\\myapp\\using\\',
2871 'CommandArguments': '-p password',
2872 # 'Attach':'false',
2873 # 'DebuggerType':'3',
2874 # 'Remote':'1',
2875 # 'RemoteMachine': None,
2876 # 'RemoteCommand': None,
2877 # 'HttpUrl': None,
2878 # 'PDBPath': None,
2879 # 'SQLDebugging': None,
2880 # 'Environment': '',
2881 # 'EnvironmentMerge':'true',
2882 # 'DebuggerFlavor': None,
2883 # 'MPIRunCommand': None,
2884 # 'MPIRunArguments': None,
2885 # 'MPIRunWorkingDirectory': None,
2886 # 'ApplicationCommand': None,
2887 # 'ApplicationArguments': None,
2888 # 'ShimCommand': None,
2889 # 'MPIAcceptMode': None,
2890 # 'MPIAcceptFilter': None,
2891 }
2892 #
2894 # 2. Because there are a lot of different options depending on the Microsoft
2895 # Visual Studio version, if you use more than one version you have to
2896 # define a dictionary per version, for instance if you want to create a user
2897 # file to launch a specific application for testing your dll with Microsoft
2898 # Visual Studio 2012 (v11):
2899 #
2900 V10DebugSettings = {
2901 'LocalDebuggerCommand': 'c:\\myapp\\using\\thisdll.exe',
2902 'LocalDebuggerWorkingDirectory': 'c:\\myapp\\using\\',
2903 'LocalDebuggerCommandArguments': '-p password',
2904 # 'LocalDebuggerEnvironment': None,
2905 # 'DebuggerFlavor': 'WindowsLocalDebugger',
2906 # 'LocalDebuggerAttach': None,
2907 # 'LocalDebuggerDebuggerType': None,
2908 # 'LocalDebuggerMergeEnvironment': None,
2909 # 'LocalDebuggerSQLDebugging': None,
2910 # 'RemoteDebuggerCommand': None,
2911 # 'RemoteDebuggerCommandArguments': None,
2912 # 'RemoteDebuggerWorkingDirectory': None,
2913 # 'RemoteDebuggerServerName': None,
2914 # 'RemoteDebuggerConnection': None,
2915 # 'RemoteDebuggerDebuggerType': None,
2916 # 'RemoteDebuggerAttach': None,
2917 # 'RemoteDebuggerSQLDebugging': None,
2918 # 'DeploymentDirectory': None,
2919 # 'AdditionalFiles': None,
2920 # 'RemoteDebuggerDeployDebugCppRuntime': None,
2921 # 'WebBrowserDebuggerHttpUrl': None,
2922 # 'WebBrowserDebuggerDebuggerType': None,
2923 # 'WebServiceDebuggerHttpUrl': None,
2924 # 'WebServiceDebuggerDebuggerType': None,
2925 # 'WebServiceDebuggerSQLDebugging': None,
2926 }
2927 #
2929 # 3. Select the dictionary you want depending on the version of visual Studio
2930 # Files you want to generate.
2931 #
2932 if not env.GetOption('userfile'):
2933 dbgSettings = None
2934 elif env.get('MSVC_VERSION', None) == '9.0':
2935 dbgSettings = V9DebugSettings
2936 elif env.get('MSVC_VERSION', None) == '11.0':
2937 dbgSettings = V10DebugSettings
2938 else:
2939 dbgSettings = None
2940 #
2942 # 4. Add the dictionary to the DebugSettings keyword.
2943 #
2944 barsrcs = ['bar.cpp', 'dllmain.cpp', 'stdafx.cpp']
2945 barincs = ['targetver.h']
2946 barlocalincs = ['StdAfx.h']
2947 barresources = ['bar.rc','resource.h']
2948 barmisc = ['ReadMe.txt']
2949 dll = env.SharedLibrary(target = 'bar.dll',
2951 source = barsrcs)
2952 env.MSVSProject(target = 'Bar' + env['MSVSPROJECTSUFFIX'],
2954 srcs = barsrcs,
2955 incs = barincs,
2956 localincs = barlocalincs,
2957 resources = barresources,
2958 misc = barmisc,
2959 buildtarget = [dll[0]] * 2,
2960 variant = ('Debug|Win32', 'Release|Win32'),
2961 cmdargs = 'vc=%s' % msvcver,
2962 DebugSettings = (dbgSettings, {}))
2963 MSVSSolution(), env.MSVSSolution()
2965 Builds a Microsoft Visual Studio solution file.
2966 This builds a Visual Studio solution file, based on the version of
2968 Visual Studio that is configured (either the latest installed
2969 version, or the version specified by $MSVS_VERSION in the
2970 construction environment). For Visual Studio 6, it will generate a
2971 .dsw file. For Visual Studio 7 (.NET), it will generate a .sln
2972 file.
2973 The following values must be specified:
2975 target
2977 The name of the target .dsw or .sln file. The correct suffix
2978 for the version of Visual Studio must be used, but the value
2979 $MSVSSOLUTIONSUFFIX will be defined to the correct value (see
2980 example below).
2981 variant
2983 The name of this particular variant, or a list of variant names
2984 (the latter is only supported for MSVS 7 solutions). These are
2985 typically things like "Debug" or "Release", but really can be
2986 anything you want. For MSVS 7 they may also specify target
2987 platform, like this "Debug|Xbox". Default platform is Win32.
2988 projects
2990 A list of project file names, or Project nodes returned by
2991 calls to the MSVSProject Builder, to be placed into the
2992 solution file. It should be noted that these file names are NOT
2993 added to the $SOURCES environment variable in form of files,
2994 but rather as strings. This is because they represent file
2995 names to be added to the solution file, not the source files
2996 used to build the solution file.
2997 Example Usage:
2999 env.MSVSSolution(target = 'Bar' + env['MSVSSOLUTIONSUFFIX'], projects = ['bar'
3001 + env['MSVSPROJECTSUFFIX']], variant = 'Release')
3002 Object(), env.Object()
3004 A synonym for the StaticObject builder method.
3005 Package(), env.Package()
3007 Builds a Binary Package of the given source files.
3008 env.Package(source = FindInstalledFiles())
3010 Builds software distribution packages. Packages consist of files to
3012 install and packaging information. The former may be specified with
3013 the source parameter and may be left out, in which case the
3014 FindInstalledFiles function will collect all files that have an
3015 Install or InstallAs Builder attached. If the target is not
3016 specified it will be deduced from additional information given to
3017 this Builder.
3018 The packaging information is specified with the help of
3020 construction variables documented below. This information is called
3021 a tag to stress that some of them can also be attached to files
3022 with the Tag function. The mandatory ones will complain if they
3023 were not specified. They vary depending on chosen target packager.
3024 The target packager may be selected with the "PACKAGETYPE" command
3026 line option or with the $PACKAGETYPE construction variable.
3027 Currently the following packagers available:
3028 * msi - Microsoft Installer * rpm - Redhat Package Manger * ipkg -
3030 Itsy Package Management System * tarbz2 - compressed tar * targz -
3031 compressed tar * zip - zip file * src_tarbz2 - compressed tar
3032 source * src_targz - compressed tar source * src_zip - zip file
3033 source
3034 An updated list is always available under the "package_type" option
3036 when running "scons --help" on a project that has packaging
3037 activated.
3038 env = Environment(tools=['default', 'packaging'])
3040 env.Install('/bin/', 'my_program')
3041 env.Package( NAME = 'foo',
3042 VERSION = '1.2.3',
3043 PACKAGEVERSION = 0,
3044 PACKAGETYPE = 'rpm',
3045 LICENSE = 'gpl',
3046 SUMMARY = 'balalalalal',
3047 DESCRIPTION = 'this should be really really long',
3048 X_RPM_GROUP = 'Application/fu',
3049 SOURCE_URL = 'http://foo.org/foo-1.2.3.tar.gz'
3050 )
3051 PCH(), env.PCH()
3053 Builds a Microsoft Visual C++ precompiled header. Calling this
3054 builder method returns a list of two targets: the PCH as the first
3055 element, and the object file as the second element. Normally the
3056 object file is ignored. This builder method is only provided when
3057 Microsoft Visual C++ is being used as the compiler. The PCH builder
3058 method is generally used in conjunction with the PCH construction
3059 variable to force object files to use the precompiled header:
3060 env['PCH'] = env.PCH('StdAfx.cpp')[0]
3062 PDF(), env.PDF()
3064 Builds a .pdf file from a .dvi input file (or, by extension, a
3065 .tex, .ltx, or .latex input file). The suffix specified by the
3066 $PDFSUFFIX construction variable (.pdf by default) is added
3067 automatically to the target if it is not already present. Example:
3068 # builds from aaa.tex
3070 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
3071 # builds bbb.pdf from bbb.dvi
3072 env.PDF(target = 'bbb', source = 'bbb.dvi')
3073 POInit(), env.POInit()
3075 This builder belongs to msginit tool. The builder initializes
3076 missing PO file(s) if $POAUTOINIT is set. If $POAUTOINIT is not set
3077 (default), POInit prints instruction for user (that is supposed to
3078 be a translator), telling how the PO file should be initialized. In
3079 normal projects you should not use POInit and use POUpdate instead.
3080 POUpdate chooses intelligently between msgmerge(1) and msginit(1).
3081 POInit always uses msginit(1) and should be regarded as builder for
3082 special purposes or for temporary use (e.g. for quick, one time
3083 initialization of a bunch of PO files) or for tests.
3084 Target nodes defined through POInit are not built by default
3086 (they're Ignored from '.' node) but are added to special Alias
3087 ('po-create' by default). The alias name may be changed through the
3088 $POCREATE_ALIAS construction variable. All PO files defined through
3089 POInit may be easily initialized by scons po-create.
3090 Example 1. Initialize en.po and pl.po from messages.pot:
3093 # ...
3095 env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po]
3096 Example 2. Initialize en.po and pl.po from foo.pot:
3099 # ...
3101 env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po]
3102 Example 3. Initialize en.po and pl.po from foo.pot but using
3105 $POTDOMAIN construction variable:
3106 # ...
3108 env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po]
3109 Example 4. Initialize PO files for languages defined in LINGUAS
3112 file. The files will be initialized from template messages.pot:
3113 # ...
3115 env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3116 Example 5. Initialize en.po and pl.pl PO files plus files for
3119 languages defined in LINGUAS file. The files will be initialized
3120 from template messages.pot:
3121 # ...
3123 env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
3124 Example 6. You may preconfigure your environment first, and then
3127 initialize PO files:
3128 # ...
3130 env['POAUTOINIT'] = 1
3131 env['LINGUAS_FILE'] = 1
3132 env['POTDOMAIN'] = 'foo'
3133 env.POInit()
3134 which has same efect as:
3136 # ...
3138 env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
3139 PostScript(), env.PostScript()
3141 Builds a .ps file from a .dvi input file (or, by extension, a .tex,
3142 .ltx, or .latex input file). The suffix specified by the $PSSUFFIX
3143 construction variable (.ps by default) is added automatically to
3144 the target if it is not already present. Example:
3145 # builds from aaa.tex
3147 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
3148 # builds bbb.ps from bbb.dvi
3149 env.PostScript(target = 'bbb', source = 'bbb.dvi')
3150 POTUpdate(), env.POTUpdate()
3152 The builder belongs to xgettext tool. The builder updates target
3153 POT file if exists or creates one if it doesn't. The node is not
3154 built by default (i.e. it is Ignored from '.'), but only on demand
3155 (i.e. when given POT file is required or when special alias is
3156 invoked). This builder adds its targe node (messages.pot, say) to a
3157 special alias (pot-update by default, see $POTUPDATE_ALIAS) so you
3158 can update/create them easily with scons pot-update. The file is
3159 not written until there is no real change in internationalized
3160 messages (or in comments that enter POT file).
3161 Note
3164 You may see xgettext(1) being invoked by the xgettext tool even
3165 if there is no real change in internationalized messages (so
3166 the POT file is not being updated). This happens every time a
3167 source file has changed. In such case we invoke xgettext(1) and
3168 compare its output with the content of POT file to decide
3169 whether the file should be updated or not.
3170 Example 1. Let's create po/ directory and place following
3173 SConstruct script there:
3174 # SConstruct in 'po/' subdir
3176 env = Environment( tools = ['default', 'xgettext'] )
3177 env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp'])
3178 env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp'])
3179 Then invoke scons few times:
3181 user@host:$ scons # Does not create foo.pot nor bar.pot
3183 user@host:$ scons foo.pot # Updates or creates foo.pot
3184 user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot
3185 user@host:$ scons -c # Does not clean foo.pot nor bar.pot.
3186 the results shall be as the comments above say.
3188 Example 2. The POTUpdate builder may be used with no target
3191 specified, in which case default target messages.pot will be used.
3192 The default target may also be overridden by setting $POTDOMAIN
3193 construction variable or providing it as an override to POTUpdate
3194 builder:
3195 # SConstruct script
3198 env = Environment( tools = ['default', 'xgettext'] )
3199 env['POTDOMAIN'] = "foo"
3200 env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ...
3201 env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot
3202 Example 3. The sources may be specified within separate file, for
3205 example POTFILES.in:
3206 # POTFILES.in in 'po/' subdirectory
3209 ../a.cpp
3210 ../b.cpp
3211 # end of file
3212 The name of the file (POTFILES.in) containing the list of sources
3214 is provided via $XGETTEXTFROM:
3215 # SConstruct file in 'po/' subdirectory
3218 env = Environment( tools = ['default', 'xgettext'] )
3219 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in')
3220 Example 4. You may use $XGETTEXTPATH to define source search path.
3223 Assume, for example, that you have files a.cpp, b.cpp,
3224 po/SConstruct, po/POTFILES.in. Then your POT-related files could
3225 look as below:
3226 # POTFILES.in in 'po/' subdirectory
3228 a.cpp
3229 b.cpp
3230 # end of file
3231 # SConstruct file in 'po/' subdirectory
3233 env = Environment( tools = ['default', 'xgettext'] )
3234 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../')
3235 Example 5. Multiple search directories may be defined within a
3238 list, i.e. XGETTEXTPATH = ['dir1', 'dir2', ...]. The order in the
3239 list determines the search order of source files. The path to the
3240 first file found is used.
3241 Let's create 0/1/po/SConstruct script:
3243 # SConstruct file in '0/1/po/' subdirectory
3245 env = Environment( tools = ['default', 'xgettext'] )
3246 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../'])
3247 and 0/1/po/POTFILES.in:
3249 # POTFILES.in in '0/1/po/' subdirectory
3251 a.cpp
3252 # end of file
3253 Write two *.cpp files, the first one is 0/a.cpp:
3255 /* 0/a.cpp */
3257 gettext("Hello from ../../a.cpp")
3258 and the second is 0/1/a.cpp:
3260 /* 0/1/a.cpp */
3262 gettext("Hello from ../a.cpp")
3263 then run scons. You'll obtain 0/1/po/messages.pot with the message
3265 "Hello from ../a.cpp". When you reverse order in $XGETTEXTFOM, i.e.
3266 when you write SConscript as
3267 # SConstruct file in '0/1/po/' subdirectory
3269 env = Environment( tools = ['default', 'xgettext'] )
3270 env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../'])
3271 then the messages.pot will contain msgid "Hello from ../../a.cpp"
3273 line and not msgid "Hello from ../a.cpp".
3274 POUpdate(), env.POUpdate()
3276 The builder belongs to msgmerge tool. The builder updates PO files
3277 with msgmerge(1), or initializes missing PO files as described in
3278 documentation of msginit tool and POInit builder (see also
3279 $POAUTOINIT). Note, that POUpdate does not add its targets to
3280 po-create alias as POInit does.
3281 Target nodes defined through POUpdate are not built by default
3283 (they're Ignored from '.' node). Instead, they are added
3284 automatically to special Alias ('po-update' by default). The alias
3285 name may be changed through the $POUPDATE_ALIAS construction
3286 variable. You can easily update PO files in your project by scons
3287 po-update.
3288 Example 1. Update en.po and pl.po from messages.pot template (see
3291 also $POTDOMAIN), assuming that the later one exists or there is
3292 rule to build it (see POTUpdate):
3293 # ...
3295 env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po]
3296 Example 2. Update en.po and pl.po from foo.pot template:
3299 # ...
3301 env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl]
3302 Example 3. Update en.po and pl.po from foo.pot (another version):
3305 # ...
3307 env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl]
3308 Example 4. Update files for languages defined in LINGUAS file. The
3311 files are updated from messages.pot template:
3312 # ...
3314 env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file
3315 Example 5. Same as above, but update from foo.pot template:
3318 # ...
3320 env.POUpdate(LINGUAS_FILE = 1, source = ['foo'])
3321 Example 6. Update en.po and pl.po plus files for languages defined
3324 in LINGUAS file. The files are updated from messages.pot template:
3325 # produce 'en.po', 'pl.po' + files defined in 'LINGUAS':
3327 env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1)
3328 Example 7. Use $POAUTOINIT to automatically initialize PO file if
3331 it doesn't exist:
3332 # ...
3334 env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1)
3335 Example 8. Update PO files for languages defined in LINGUAS file.
3338 The files are updated from foo.pot template. All necessary settings
3339 are pre-configured via environment.
3340 # ...
3342 env['POAUTOINIT'] = 1
3343 env['LINGUAS_FILE'] = 1
3344 env['POTDOMAIN'] = 'foo'
3345 env.POUpdate()
3346 Program(), env.Program()
3348 Builds an executable given one or more object files or C, C++, D,
3349 or Fortran source files. If any C, C++, D or Fortran source files
3350 are specified, then they will be automatically compiled to object
3351 files using the Object builder method; see that builder method's
3352 description for a list of legal source file suffixes and how they
3353 are interpreted. The target executable file prefix (specified by
3354 the $PROGPREFIX construction variable; nothing by default) and
3355 suffix (specified by the $PROGSUFFIX construction variable; by
3356 default, .exe on Windows systems, nothing on POSIX systems) are
3357 automatically added to the target if not already present. Example:
3358 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
3360 ProgramAllAtOnce(), env.ProgramAllAtOnce()
3362 Builds an executable from D sources without first creating
3363 individual objects for each file.
3364 D sources can be compiled file-by-file as C and C++ source are, and
3366 D is integrated into the scons Object and Program builders for this
3367 model of build. D codes can though do whole source meta-programming
3368 (some of the testing frameworks do this). For this it is imperative
3369 that all sources are compiled and linked in a single call of the D
3370 compiler. This builder serves that purpose.
3371 env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
3373 This command will compile the modules mod_a, mod_b, and mod_c in a
3376 single compilation process without first creating object files for
3377 the modules. Some of the D compilers will create executable.o
3378 others will not.
3379 Builds an executable from D sources without first creating
3381 individual objects for each file.
3382 D sources can be compiled file-by-file as C and C++ source are, and
3384 D is integrated into the scons Object and Program builders for this
3385 model of build. D codes can though do whole source meta-programming
3386 (some of the testing frameworks do this). For this it is imperative
3387 that all sources are compiled and linked in a single call of the D
3388 compiler. This builder serves that purpose.
3389 env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
3391 This command will compile the modules mod_a, mod_b, and mod_c in a
3394 single compilation process without first creating object files for
3395 the modules. Some of the D compilers will create executable.o
3396 others will not.
3397 Builds an executable from D sources without first creating
3399 individual objects for each file.
3400 D sources can be compiled file-by-file as C and C++ source are, and
3402 D is integrated into the scons Object and Program builders for this
3403 model of build. D codes can though do whole source meta-programming
3404 (some of the testing frameworks do this). For this it is imperative
3405 that all sources are compiled and linked in a single call of the D
3406 compiler. This builder serves that purpose.
3407 env.ProgramAllAtOnce('executable', ['mod_a.d, mod_b.d', 'mod_c.d'])
3409 This command will compile the modules mod_a, mod_b, and mod_c in a
3412 single compilation process without first creating object files for
3413 the modules. Some of the D compilers will create executable.o
3414 others will not.
3415 RES(), env.RES()
3417 Builds a Microsoft Visual C++ resource file. This builder method is
3418 only provided when Microsoft Visual C++ or MinGW is being used as
3419 the compiler. The .res (or .o for MinGW) suffix is added to the
3420 target name if no other suffix is given. The source file is scanned
3421 for implicit dependencies as though it were a C file. Example:
3422 env.RES('resource.rc')
3424 RMIC(), env.RMIC()
3426 Builds stub and skeleton class files for remote objects from Java
3427 .class files. The target is a directory relative to which the stub
3428 and skeleton class files will be written. The source can be the
3429 names of .class files, or the objects return from the Java builder
3430 method.
3431 If the construction variable $JAVACLASSDIR is set, either in the
3433 environment or in the call to the RMIC builder method itself, then
3434 the value of the variable will be stripped from the beginning of
3435 any .class file names.
3436 classes = env.Java(target = 'classdir', source = 'src')
3438 env.RMIC(target = 'outdir1', source = classes)
3439 env.RMIC(target = 'outdir2',
3441 source = ['package/foo.class', 'package/bar.class'])
3442 env.RMIC(target = 'outdir3',
3444 source = ['classes/foo.class', 'classes/bar.class'],
3445 JAVACLASSDIR = 'classes')
3446 RPCGenClient(), env.RPCGenClient()
3448 Generates an RPC client stub (_clnt.c) file from a specified RPC
3449 (.x) source file. Because rpcgen only builds output files in the
3450 local directory, the command will be executed in the source file's
3451 directory by default.
3452 # Builds src/rpcif_clnt.c
3454 env.RPCGenClient('src/rpcif.x')
3455 RPCGenHeader(), env.RPCGenHeader()
3457 Generates an RPC header (.h) file from a specified RPC (.x) source
3458 file. Because rpcgen only builds output files in the local
3459 directory, the command will be executed in the source file's
3460 directory by default.
3461 # Builds src/rpcif.h
3463 env.RPCGenHeader('src/rpcif.x')
3464 RPCGenService(), env.RPCGenService()
3466 Generates an RPC server-skeleton (_svc.c) file from a specified RPC
3467 (.x) source file. Because rpcgen only builds output files in the
3468 local directory, the command will be executed in the source file's
3469 directory by default.
3470 # Builds src/rpcif_svc.c
3472 env.RPCGenClient('src/rpcif.x')
3473 RPCGenXDR(), env.RPCGenXDR()
3475 Generates an RPC XDR routine (_xdr.c) file from a specified RPC
3476 (.x) source file. Because rpcgen only builds output files in the
3477 local directory, the command will be executed in the source file's
3478 directory by default.
3479 # Builds src/rpcif_xdr.c
3481 env.RPCGenClient('src/rpcif.x')
3482 SharedLibrary(), env.SharedLibrary()
3484 Builds a shared library (.so on a POSIX system, .dll on Windows)
3485 given one or more object files or C, C++, D or Fortran source
3486 files. If any source files are given, then they will be
3487 automatically compiled to object files. The static library prefix
3488 and suffix (if any) are automatically added to the target. The
3489 target library file prefix (specified by the $SHLIBPREFIX
3490 construction variable; by default, lib on POSIX systems, nothing on
3491 Windows systems) and suffix (specified by the $SHLIBSUFFIX
3492 construction variable; by default, .dll on Windows systems, .so on
3493 POSIX systems) are automatically added to the target if not already
3494 present. Example:
3495 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
3497 On Windows systems, the SharedLibrary builder method will always
3499 build an import (.lib) library in addition to the shared (.dll)
3500 library, adding a .lib library with the same basename if there is
3501 not already a .lib file explicitly listed in the targets.
3502 On Cygwin systems, the SharedLibrary builder method will always
3504 build an import (.dll.a) library in addition to the shared (.dll)
3505 library, adding a .dll.a library with the same basename if there is
3506 not already a .dll.a file explicitly listed in the targets.
3507 Any object files listed in the source must have been built for a
3509 shared library (that is, using the SharedObject builder method).
3510 scons will raise an error if there is any mismatch.
3511 On some platforms, there is a distinction between a shared library
3513 (loaded automatically by the system to resolve external references)
3514 and a loadable module (explicitly loaded by user action). For
3515 maximum portability, use the LoadableModule builder for the latter.
3516 When the $SHLIBVERSION construction variable is defined a versioned
3518 shared library is created. This modifies the $SHLINKFLAGS as
3519 required, adds the version number to the library name, and creates
3520 the symlinks that are needed.
3521 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'], SHLIBVERSION='1.5.2')
3523 On a POSIX system, versions with a single token create exactly one
3525 symlink: libbar.so.6 would have symlinks libbar.so only. On a POSIX
3526 system, versions with two or more tokens create exactly two
3527 symlinks: libbar.so.2.3.1 would have symlinks libbar.so and
3528 libbar.so.2; on a Darwin (OSX) system the library would be
3529 libbar.2.3.1.dylib and the link would be libbar.dylib.
3530 On Windows systems, specifying register=1 will cause the .dll to be
3532 registered after it is built using REGSVR32. The command that is
3533 run ("regsvr32" by default) is determined by $REGSVR construction
3534 variable, and the flags passed are determined by $REGSVRFLAGS. By
3535 default, $REGSVRFLAGS includes the /s option, to prevent dialogs
3536 from popping up and requiring user attention when it is run. If you
3537 change $REGSVRFLAGS, be sure to include the /s option. For example,
3538 env.SharedLibrary(target = 'bar',
3540 source = ['bar.cxx', 'foo.obj'],
3541 register=1)
3542 will register bar.dll as a COM object when it is done linking it.
3544 SharedObject(), env.SharedObject()
3546 Builds an object file for inclusion in a shared library. Source
3547 files must have one of the same set of extensions specified above
3548 for the StaticObject builder method. On some platforms building a
3549 shared object requires additional compiler option (e.g. -fPIC for
3550 gcc) in addition to those needed to build a normal (static) object,
3551 but on some platforms there is no difference between a shared
3552 object and a normal (static) one. When there is a difference, SCons
3553 will only allow shared objects to be linked into a shared library,
3554 and will use a different suffix for shared objects. On platforms
3555 where there is no difference, SCons will allow both normal (static)
3556 and shared objects to be linked into a shared library, and will use
3557 the same suffix for shared and normal (static) objects. The target
3558 object file prefix (specified by the $SHOBJPREFIX construction
3559 variable; by default, the same as $OBJPREFIX) and suffix (specified
3560 by the $SHOBJSUFFIX construction variable) are automatically added
3561 to the target if not already present. Examples:
3562 env.SharedObject(target = 'ddd', source = 'ddd.c')
3564 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
3565 env.SharedObject(target = 'fff.obj', source = 'fff.for')
3566 Note that the source files will be scanned according to the suffix
3568 mappings in the SourceFileScanner object. See the section "Scanner
3569 Objects," below, for more information.
3570 StaticLibrary(), env.StaticLibrary()
3572 Builds a static library given one or more object files or C, C++, D
3573 or Fortran source files. If any source files are given, then they
3574 will be automatically compiled to object files. The static library
3575 prefix and suffix (if any) are automatically added to the target.
3576 The target library file prefix (specified by the $LIBPREFIX
3577 construction variable; by default, lib on POSIX systems, nothing on
3578 Windows systems) and suffix (specified by the $LIBSUFFIX
3579 construction variable; by default, .lib on Windows systems, .a on
3580 POSIX systems) are automatically added to the target if not already
3581 present. Example:
3582 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
3584 Any object files listed in the source must have been built for a
3586 static library (that is, using the StaticObject builder method).
3587 scons will raise an error if there is any mismatch.
3588 StaticObject(), env.StaticObject()
3590 Builds a static object file from one or more C, C++, D, or Fortran
3591 source files. Source files must have one of the following
3592 extensions:
3593 .asm assembly language file
3595 .ASM assembly language file
3596 .c C file
3597 .C Windows: C file
3598 POSIX: C++ file
3599 .cc C++ file
3600 .cpp C++ file
3601 .cxx C++ file
3602 .cxx C++ file
3603 .c++ C++ file
3604 .C++ C++ file
3605 .d D file
3606 .f Fortran file
3607 .F Windows: Fortran file
3608 POSIX: Fortran file + C pre-processor
3609 .for Fortran file
3610 .FOR Fortran file
3611 .fpp Fortran file + C pre-processor
3612 .FPP Fortran file + C pre-processor
3613 .m Object C file
3614 .mm Object C++ file
3615 .s assembly language file
3616 .S Windows: assembly language file
3617 ARM: CodeSourcery Sourcery Lite
3618 .sx assembly language file + C pre-processor
3619 POSIX: assembly language file + C pre-processor
3620 .spp assembly language file + C pre-processor
3621 .SPP assembly language file + C pre-processor
3622 The target object file prefix (specified by the $OBJPREFIX
3624 construction variable; nothing by default) and suffix (specified by
3625 the $OBJSUFFIX construction variable; .obj on Windows systems, .o
3626 on POSIX systems) are automatically added to the target if not
3627 already present. Examples:
3628 env.StaticObject(target = 'aaa', source = 'aaa.c')
3630 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
3631 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
3632 Note that the source files will be scanned according to the suffix
3634 mappings in SourceFileScanner object. See the section "Scanner
3635 Objects," below, for more information.
3636 Substfile(), env.Substfile()
3638 The Substfile builder creates a single text file from another file
3639 or set of files by concatenating them with $LINESEPARATOR and
3640 replacing text using the $SUBST_DICT construction variable. Nested
3641 lists of source files are flattened. See also Textfile.
3642 If a single source file is present with an .in suffix, the suffix
3644 is stripped and the remainder is used as the default target name.
3645 The prefix and suffix specified by the $SUBSTFILEPREFIX and
3647 $SUBSTFILESUFFIX construction variables (the null string by default
3648 in both cases) are automatically added to the target if they are
3649 not already present.
3650 If a construction variable named $SUBST_DICT is present, it may be
3652 either a Python dictionary or a sequence of (key,value) tuples. If
3653 it is a dictionary it is converted into a list of tuples in an
3654 arbitrary order, so if one key is a prefix of another key or if one
3655 substitution could be further expanded by another subsitition, it
3656 is unpredictable whether the expansion will occur.
3657 Any occurrences of a key in the source are replaced by the
3659 corresponding value, which may be a Python callable function or a
3660 string. If the value is a callable, it is called with no arguments
3661 to get a string. Strings are subst-expanded and the result replaces
3662 the key.
3663 env = Environment(tools = ['default', 'textfile'])
3665 env['prefix'] = '/usr/bin'
3667 script_dict = {'@prefix@': '/bin', '@exec_prefix@': '$prefix'}
3668 env.Substfile('script.in', SUBST_DICT = script_dict)
3669 conf_dict = {'%VERSION%': '1.2.3', '%BASE%': 'MyProg'}
3671 env.Substfile('config.h.in', conf_dict, SUBST_DICT = conf_dict)
3672 # UNPREDICTABLE - one key is a prefix of another
3674 bad_foo = {'$foo': '$foo', '$foobar': '$foobar'}
3675 env.Substfile('foo.in', SUBST_DICT = bad_foo)
3676 # PREDICTABLE - keys are applied longest first
3678 good_foo = [('$foobar', '$foobar'), ('$foo', '$foo')]
3679 env.Substfile('foo.in', SUBST_DICT = good_foo)
3680 # UNPREDICTABLE - one substitution could be futher expanded
3682 bad_bar = {'@bar@': '@soap@', '@soap@': 'lye'}
3683 env.Substfile('bar.in', SUBST_DICT = bad_bar)
3684 # PREDICTABLE - substitutions are expanded in order
3686 good_bar = (('@bar@', '@soap@'), ('@soap@', 'lye'))
3687 env.Substfile('bar.in', SUBST_DICT = good_bar)
3688 # the SUBST_DICT may be in common (and not an override)
3690 substutions = {}
3691 subst = Environment(tools = ['textfile'], SUBST_DICT = substitutions)
3692 substitutions['@foo@'] = 'foo'
3693 subst['SUBST_DICT']['@bar@'] = 'bar'
3694 subst.Substfile('pgm1.c', [Value('#include "@foo@.h"'),
3695 Value('#include "@bar@.h"'),
3696 "common.in",
3697 "pgm1.in"
3698 ])
3699 subst.Substfile('pgm2.c', [Value('#include "@foo@.h"'),
3700 Value('#include "@bar@.h"'),
3701 "common.in",
3702 "pgm2.in"
3703 ])
3704 Tar(), env.Tar()
3707 Builds a tar archive of the specified files and/or directories.
3708 Unlike most builder methods, the Tar builder method may be called
3709 multiple times for a given target; each additional call adds to the
3710 list of entries that will be built into the archive. Any source
3711 directories will be scanned for changes to any on-disk files,
3712 regardless of whether or not scons knows about them from other
3713 Builder or function calls.
3714 env.Tar('src.tar', 'src')
3716 # Create the stuff.tar file.
3718 env.Tar('stuff', ['subdir1', 'subdir2'])
3719 # Also add "another" to the stuff.tar file.
3720 env.Tar('stuff', 'another')
3721 # Set TARFLAGS to create a gzip-filtered archive.
3723 env = Environment(TARFLAGS = '-c -z')
3724 env.Tar('foo.tar.gz', 'foo')
3725 # Also set the suffix to .tgz.
3727 env = Environment(TARFLAGS = '-c -z',
3728 TARSUFFIX = '.tgz')
3729 env.Tar('foo')
3730 Textfile(), env.Textfile()
3732 The Textfile builder generates a single text file. The source
3733 strings constitute the lines; nested lists of sources are
3734 flattened. $LINESEPARATOR is used to separate the strings.
3735 If present, the $SUBST_DICT construction variable is used to modify
3737 the strings before they are written; see the Substfile description
3738 for details.
3739 The prefix and suffix specified by the $TEXTFILEPREFIX and
3741 $TEXTFILESUFFIX construction variables (the null string and .txt by
3742 default, respectively) are automatically added to the target if
3743 they are not already present. Examples:
3744 # builds/writes foo.txt
3746 env.Textfile(target = 'foo.txt', source = ['Goethe', 42, 'Schiller'])
3747 # builds/writes bar.txt
3749 env.Textfile(target = 'bar',
3750 source = ['lalala', 'tanteratei'],
3751 LINESEPARATOR='|*')
3752 # nested lists are flattened automatically
3754 env.Textfile(target = 'blob',
3755 source = ['lalala', ['Goethe', 42 'Schiller'], 'tanteratei'])
3756 # files may be used as input by wraping them in File()
3758 env.Textfile(target = 'concat', # concatenate files with a marker between
3759 source = [File('concat1'), File('concat2')],
3760 LINESEPARATOR = '====================\n')
3761 Results are:
3763 foo.txt
3764 ....8<----
3765 Goethe
3766 42
3767 Schiller
3768 ....8<---- (no linefeed at the end)
3769 bar.txt:
3771 ....8<----
3772 lalala|*tanteratei
3773 ....8<---- (no linefeed at the end)
3774 blob.txt
3776 ....8<----
3777 lalala
3778 Goethe
3779 42
3780 Schiller
3781 tanteratei
3782 ....8<---- (no linefeed at the end)
3783 Translate(), env.Translate()
3785 This pseudo-builder belongs to gettext toolset. The builder
3786 extracts internationalized messages from source files, updates POT
3787 template (if necessary) and then updates PO translations (if
3788 necessary). If $POAUTOINIT is set, missing PO files will be
3789 automatically created (i.e. without translator person
3790 intervention). The variables $LINGUAS_FILE and $POTDOMAIN are taken
3791 into acount too. All other construction variables used by
3792 POTUpdate, and POUpdate work here too.
3793 Example 1. The simplest way is to specify input files and output
3796 languages inline in a SCons script when invoking Translate
3797 # SConscript in 'po/' directory
3799 env = Environment( tools = ["default", "gettext"] )
3800 env['POAUTOINIT'] = 1
3801 env.Translate(['en','pl'], ['../a.cpp','../b.cpp'])
3802 Example 2. If you wish, you may also stick to conventional style
3805 known from autotools, i.e. using POTFILES.in and LINGUAS files
3806 # LINGUAS
3808 en pl
3809 #end
3810 # POTFILES.in
3812 a.cpp
3813 b.cpp
3814 # end
3815 # SConscript
3817 env = Environment( tools = ["default", "gettext"] )
3818 env['POAUTOINIT'] = 1
3819 env['XGETTEXTPATH'] = ['../']
3820 env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in')
3821 The last approach is perhaps the recommended one. It allows easily
3823 split internationalization/localization onto separate SCons
3824 scripts, where a script in source tree is responsible for
3825 translations (from sources to PO files) and script(s) under variant
3826 directories are responsible for compilation of PO to MO files to
3827 and for installation of MO files. The "gluing factor" synchronizing
3828 these two scripts is then the content of LINGUAS file. Note, that
3829 the updated POT and PO files are usually going to be committed back
3830 to the repository, so they must be updated within the source
3831 directory (and not in variant directories). Additionaly, the file
3832 listing of po/ directory contains LINGUAS file, so the source tree
3833 looks familiar to translators, and they may work with the project
3834 in their usual way.
3835 Example 3. Let's prepare a development tree as below
3838 project/
3840 + SConstruct
3841 + build/
3842 + src/
3843 + po/
3844 + SConscript
3845 + SConscript.i18n
3846 + POTFILES.in
3847 + LINGUAS
3848 with build being variant directory. Write the top-level SConstruct
3850 script as follows
3851 # SConstruct
3853 env = Environment( tools = ["default", "gettext"] )
3854 VariantDir('build', 'src', duplicate = 0)
3855 env['POAUTOINIT'] = 1
3856 SConscript('src/po/SConscript.i18n', exports = 'env')
3857 SConscript('build/po/SConscript', exports = 'env')
3858 the src/po/SConscript.i18n as
3860 # src/po/SConscript.i18n
3862 Import('env')
3863 env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../'])
3864 and the src/po/SConscript
3866 # src/po/SConscript
3868 Import('env')
3869 env.MOFiles(LINGUAS_FILE = 1)
3870 Such setup produces POT and PO files under source tree in src/po/
3872 and binary MO files under variant tree in build/po/. This way the
3873 POT and PO files are separated from other output files, which must
3874 not be committed back to source repositories (e.g. MO files).
3875 Note
3878 In above example, the PO files are not updated, nor created
3879 automatically when you issue scons '.' command. The files must
3880 be updated (created) by hand via scons po-update and then MO
3881 files can be compiled by running scons '.'.
3882 TypeLibrary(), env.TypeLibrary()
3884 Builds a Windows type library (.tlb) file from an input IDL file
3885 (.idl). In addition, it will build the associated interface stub
3886 and proxy source files, naming them according to the base name of
3887 the .idl file. For example,
3888 env.TypeLibrary(source="foo.idl")
3890 Will create foo.tlb, foo.h, foo_i.c, foo_p.c and foo_data.c files.
3892 Uic(), env.Uic()
3894 Builds a header file, an implementation file and a moc file from an
3895 ui file. and returns the corresponding nodes in the above order.
3896 This builder is only available after using the tool 'qt'. Note: you
3897 can specify .ui files directly as source files to the Program,
3898 Library and SharedLibrary builders without using this builder.
3899 Using this builder lets you override the standard naming
3900 conventions (be careful: prefixes are always prepended to names of
3901 built files; if you don't want prefixes, you may set them to ``).
3902 See the $QTDIR variable for more information. Example:
3903 env.Uic('foo.ui') # -> ['foo.h', 'uic_foo.cc', 'moc_foo.cc']
3905 env.Uic(target = Split('include/foo.h gen/uicfoo.cc gen/mocfoo.cc'),
3906 source = 'foo.ui') # -> ['include/foo.h', 'gen/uicfoo.cc', 'gen/mocfoo.cc']
3907 Zip(), env.Zip()
3909 Builds a zip archive of the specified files and/or directories.
3910 Unlike most builder methods, the Zip builder method may be called
3911 multiple times for a given target; each additional call adds to the
3912 list of entries that will be built into the archive. Any source
3913 directories will be scanned for changes to any on-disk files,
3914 regardless of whether or not scons knows about them from other
3915 Builder or function calls.
3916 env.Zip('src.zip', 'src')
3918 # Create the stuff.zip file.
3920 env.Zip('stuff', ['subdir1', 'subdir2'])
3921 # Also add "another" to the stuff.tar file.
3922 env.Zip('stuff', 'another')
3923 All targets of builder methods automatically depend on their sources.
3925 An explicit dependency can be specified using the Depends method of a
3926 construction environment (see below).
3927 In addition, scons automatically scans source files for various
3929 programming languages, so the dependencies do not need to be specified
3930 explicitly. By default, SCons can C source files, C++ source files,
3931 Fortran source files with .F (POSIX systems only), .fpp, or .FPP file
3932 extensions, and assembly language files with .S (POSIX systems only),
3933 .spp, or .SPP files extensions for C preprocessor dependencies. SCons
3934 also has default support for scanning D source files, You can also
3935 write your own Scanners to add support for additional source file
3936 types. These can be added to the default Scanner object used by the
3937 Object(), StaticObject(), and SharedObject() Builders by adding them to
3938 the SourceFileScanner object. See the section "Scanner Objects" below,
3939 for more information about defining your own Scanner objects and using
3940 the SourceFileScanner object.
3941 Methods and Functions to Do Things
3943 In addition to Builder methods, scons provides a number of other
3944 construction environment methods and global functions to manipulate the
3945 build configuration.
3946 Usually, a construction environment method and global function with the
3948 same name both exist so that you don't have to remember whether to a
3949 specific bit of functionality must be called with or without a
3950 construction environment. In the following list, if you call something
3951 as a global function it looks like:
3952 Function(arguments)
3954 and if you call something through a construction environment it looks
3956 like:
3957 env.Function(arguments)
3959 If you can call the functionality in both ways, then both forms are
3961 listed.
3962 Global functions may be called from custom Python modules that you
3964 import into an SConscript file by adding the following to the Python
3965 module:
3966 from SCons.Script import *
3968 Except where otherwise noted, the same-named construction environment
3970 method and global function provide the exact same functionality. The
3971 only difference is that, where appropriate, calling the functionality
3972 through a construction environment will substitute construction
3973 variables into any supplied strings. For example:
3974 env = Environment(FOO = 'foo')
3976 Default('$FOO')
3977 env.Default('$FOO')
3978 In the above example, the first call to the global Default() function
3980 will actually add a target named $FOO to the list of default targets,
3981 while the second call to the env.Default() construction environment
3982 method will expand the value and add a target named foo to the list of
3983 default targets. For more on construction variable expansion, see the
3984 next section on construction variables.
3985 Construction environment methods and global functions supported by
3987 scons include:
3988 Action(action, [cmd/str/fun, [var, ...]] [option=value, ...]),
3990 env.Action(action, [cmd/str/fun, [var, ...]] [option=value, ...])
3991 Creates an Action object for the specified action. See the section
3992 "Action Objects," below, for a complete explanation of the
3993 arguments and behavior.
3994 Note that the env.Action() form of the invocation will expand
3996 construction variables in any argument strings, including the
3997 action argument, at the time it is called using the construction
3998 variables in the env construction environment through which
3999 env.Action() was called. The Action() form delays all variable
4000 expansion until the Action object is actually used.
4001 AddMethod(object, function, [name]), env.AddMethod(function, [name])
4003 When called with the AddMethod() form, adds the specified function
4004 to the specified object as the specified method name. When called
4005 with the env.AddMethod() form, adds the specified function to the
4006 construction environment env as the specified method name. In both
4007 cases, if name is omitted or None, the name of the specified
4008 function itself is used for the method name.
4009 Examples:
4011 # Note that the first argument to the function to
4013 # be attached as a method must be the object through
4014 # which the method will be called; the Python
4015 # convention is to call it 'self'.
4016 def my_method(self, arg):
4017 print("my_method() got", arg)
4018 # Use the global AddMethod() function to add a method
4020 # to the Environment class. This
4021 AddMethod(Environment, my_method)
4022 env = Environment()
4023 env.my_method('arg')
4024 # Add the function as a method, using the function
4026 # name for the method call.
4027 env = Environment()
4028 env.AddMethod(my_method, 'other_method_name')
4029 env.other_method_name('another arg')
4030 AddOption(arguments)
4032 This function adds a new command-line option to be recognized. The
4033 specified arguments are the same as supported by the standard
4034 Python optparse.add_option() method (with a few additional
4035 capabilities noted below); see the documentation for optparse for a
4036 thorough discussion of its option-processing capabities.
4037 In addition to the arguments and values supported by the
4039 optparse.add_option() method, the SCons AddOption function allows
4040 you to set the nargs keyword value to '?' (a string with just the
4041 question mark) to indicate that the specified long option(s)
4042 take(s) an optional argument. When nargs = '?' is passed to the
4043 AddOption function, the const keyword argument may be used to
4044 supply the "default" value that should be used when the option is
4045 specified on the command line without an explicit argument.
4046 If no default= keyword argument is supplied when calling AddOption,
4048 the option will have a default value of None.
4049 Once a new command-line option has been added with AddOption, the
4051 option value may be accessed using GetOption or env.GetOption().
4052 The value may also be set, using SetOption or env.SetOption(), if
4053 conditions in a SConscript require overriding any default value.
4054 Note, however, that a value specified on the command line will
4055 always override a value set by any SConscript file.
4056 Any specified help= strings for the new option(s) will be displayed
4058 by the -H or -h options (the latter only if no other help text is
4059 specified in the SConscript files). The help text for the local
4060 options specified by AddOption will appear below the SCons options
4061 themselves, under a separate Local Options heading. The options
4062 will appear in the help text in the order in which the AddOption
4063 calls occur.
4064 Example:
4066 AddOption('--prefix',
4068 dest='prefix',
4069 nargs=1, type='string',
4070 action='store',
4071 metavar='DIR',
4072 help='installation prefix')
4073 env = Environment(PREFIX = GetOption('prefix'))
4074 AddPostAction(target, action), env.AddPostAction(target, action)
4076 Arranges for the specified action to be performed after the
4077 specified target has been built. The specified action(s) may be an
4078 Action object, or anything that can be converted into an Action
4079 object (see below).
4080 When multiple targets are supplied, the action may be called
4082 multiple times, once after each action that generates one or more
4083 targets in the list.
4084 AddPreAction(target, action), env.AddPreAction(target, action)
4086 Arranges for the specified action to be performed before the
4087 specified target is built. The specified action(s) may be an Action
4088 object, or anything that can be converted into an Action object
4089 (see below).
4090 When multiple targets are specified, the action(s) may be called
4092 multiple times, once before each action that generates one or more
4093 targets in the list.
4094 Note that if any of the targets are built in multiple steps, the
4096 action will be invoked just before the "final" action that
4097 specifically generates the specified target(s). For example, when
4098 building an executable program from a specified source .c file via
4099 an intermediate object file:
4100 foo = Program('foo.c')
4102 AddPreAction(foo, 'pre_action')
4103 The specified pre_action would be executed before scons calls the
4105 link command that actually generates the executable program binary
4106 foo, not before compiling the foo.c file into an object file.
4107 Alias(alias, [targets, [action]]), env.Alias(alias, [targets,
4109 [action]])
4110 Creates one or more phony targets that expand to one or more other
4111 targets. An optional action (command) or list of actions can be
4112 specified that will be executed whenever the any of the alias
4113 targets are out-of-date. Returns the Node object representing the
4114 alias, which exists outside of any file system. This Node object,
4115 or the alias name, may be used as a dependency of any other target,
4116 including another alias. Alias can be called multiple times for
4117 the same alias to add additional targets to the alias, or
4118 additional actions to the list for this alias.
4119 Examples:
4121 Alias('install')
4123 Alias('install', '/usr/bin')
4124 Alias(['install', 'install-lib'], '/usr/local/lib')
4125 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
4127 env.Alias('install', ['/usr/local/man'])
4128 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
4130 AllowSubstExceptions([exception, ...])
4132 Specifies the exceptions that will be allowed when expanding
4133 construction variables. By default, any construction variable
4134 expansions that generate a NameError or IndexError exception will
4135 expand to a '' (a null string) and not cause scons to fail. All
4136 exceptions not in the specified list will generate an error message
4137 and terminate processing.
4138 If AllowSubstExceptions is called multiple times, each call
4140 completely overwrites the previous list of allowed exceptions.
4141 Example:
4143 # Requires that all construction variable names exist.
4145 # (You may wish to do this if you want to enforce strictly
4146 # that all construction variables must be defined before use.)
4147 AllowSubstExceptions()
4148 # Also allow a string containing a zero-division expansion
4150 # like '${1 / 0}' to evalute to ''.
4151 AllowSubstExceptions(IndexError, NameError, ZeroDivisionError)
4152 AlwaysBuild(target, ...), env.AlwaysBuild(target, ...)
4154 Marks each given target so that it is always assumed to be out of
4155 date, and will always be rebuilt if needed. Note, however, that
4156 AlwaysBuild does not add its target(s) to the default target list,
4157 so the targets will only be built if they are specified on the
4158 command line, or are a dependent of a target specified on the
4159 command line--but they will always be built if so specified.
4160 Multiple targets can be passed in to a single call to AlwaysBuild.
4161 env.Append(key=val, [...])
4163 Appends the specified keyword arguments to the end of construction
4164 variables in the environment. If the Environment does not have the
4165 specified construction variable, it is simply added to the
4166 environment. If the values of the construction variable and the
4167 keyword argument are the same type, then the two values will be
4168 simply added together. Otherwise, the construction variable and the
4169 value of the keyword argument are both coerced to lists, and the
4170 lists are added together. (See also the Prepend method, below.)
4171 Example:
4173 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
4175 env.AppendENVPath(name, newpath, [envname, sep, delete_existing])
4177 This appends new path elements to the given path in the specified
4178 external environment (ENV by default). This will only add any
4179 particular path once (leaving the last one it encounters and
4180 ignoring the rest, to preserve path order), and to help assure
4181 this, will normalize all paths (using os.path.normpath and
4182 os.path.normcase). This can also handle the case where the given
4183 old path variable is a list instead of a string, in which case a
4184 list will be returned instead of a string.
4185 If delete_existing is 0, then adding a path that already exists
4187 will not move it to the end; it will stay where it is in the list.
4188 Example:
4190 print 'before:',env['ENV']['INCLUDE']
4192 include_path = '/foo/bar:/foo'
4193 env.AppendENVPath('INCLUDE', include_path)
4194 print 'after:',env['ENV']['INCLUDE']
4195 yields:
4197 before: /foo:/biz
4198 after: /biz:/foo/bar:/foo
4199 env.AppendUnique(key=val, [...], delete_existing=0)
4201 Appends the specified keyword arguments to the end of construction
4202 variables in the environment. If the Environment does not have the
4203 specified construction variable, it is simply added to the
4204 environment. If the construction variable being appended to is a
4205 list, then any value(s) that already exist in the construction
4206 variable will not be added again to the list. However, if
4207 delete_existing is 1, existing matching values are removed first,
4208 so existing values in the arg list move to the end of the list.
4209 Example:
4211 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
4213 BuildDir(build_dir, src_dir, [duplicate]), env.BuildDir(build_dir,
4215 src_dir, [duplicate])
4216 Deprecated synonyms for VariantDir and env.VariantDir(). The
4217 build_dir argument becomes the variant_dir argument of VariantDir
4218 or env.VariantDir().
4219 Builder(action, [arguments]), env.Builder(action, [arguments])
4221 Creates a Builder object for the specified action. See the section
4222 "Builder Objects," below, for a complete explanation of the
4223 arguments and behavior.
4224 Note that the env.Builder() form of the invocation will expand
4226 construction variables in any arguments strings, including the
4227 action argument, at the time it is called using the construction
4228 variables in the env construction environment through which
4229 env.Builder() was called. The Builder form delays all variable
4230 expansion until after the Builder object is actually called.
4231 CacheDir(cache_dir), env.CacheDir(cache_dir)
4233 Specifies that scons will maintain a cache of derived files in
4234 cache_dir. The derived files in the cache will be shared among all
4235 the builds using the same CacheDir call. Specifying a cache_dir of
4236 None disables derived file caching.
4237 Calling env.CacheDir() will only affect targets built through the
4239 specified construction environment. Calling CacheDir sets a global
4240 default that will be used by all targets built through construction
4241 environments that do not have an env.CacheDir() specified.
4242 When a CacheDir() is being used and scons finds a derived file that
4244 needs to be rebuilt, it will first look in the cache to see if a
4245 derived file has already been built from identical input files and
4246 an identical build action (as incorporated into the MD5 build
4247 signature). If so, scons will retrieve the file from the cache. If
4248 the derived file is not present in the cache, scons will rebuild it
4249 and then place a copy of the built file in the cache (identified by
4250 its MD5 build signature), so that it may be retrieved by other
4251 builds that need to build the same derived file from identical
4252 inputs.
4253 Use of a specified CacheDir may be disabled for any invocation by
4255 using the --cache-disable option.
4256 If the --cache-force option is used, scons will place a copy of all
4258 derived files in the cache, even if they already existed and were
4259 not built by this invocation. This is useful to populate a cache
4260 the first time CacheDir is added to a build, or after using the
4261 --cache-disable option.
4262 When using CacheDir, scons will report, "Retrieved `file' from
4264 cache," unless the --cache-show option is being used. When the
4265 --cache-show option is used, scons will print the action that would
4266 have been used to build the file, without any indication that the
4267 file was actually retrieved from the cache. This is useful to
4268 generate build logs that are equivalent regardless of whether a
4269 given derived file has been built in-place or retrieved from the
4270 cache.
4271 The NoCache method can be used to disable caching of specific
4273 files. This can be useful if inputs and/or outputs of some tool are
4274 impossible to predict or prohibitively large.
4275 Clean(targets, files_or_dirs), env.Clean(targets, files_or_dirs)
4277 This specifies a list of files or directories which should be
4278 removed whenever the targets are specified with the -c command line
4279 option. The specified targets may be a list or an individual
4280 target. Multiple calls to Clean are legal, and create new targets
4281 or add files and directories to the clean list for the specified
4282 targets.
4283 Multiple files or directories should be specified either as
4285 separate arguments to the Clean method, or as a list. Clean will
4286 also accept the return value of any of the construction environment
4287 Builder methods. Examples:
4288 The related NoClean function overrides calling Clean for the same
4290 target, and any targets passed to both functions will not be
4291 removed by the -c option.
4292 Examples:
4294 Clean('foo', ['bar', 'baz'])
4296 Clean('dist', env.Program('hello', 'hello.c'))
4297 Clean(['foo', 'bar'], 'something_else_to_clean')
4298 In this example, installing the project creates a subdirectory for
4300 the documentation. This statement causes the subdirectory to be
4301 removed if the project is deinstalled.
4302 Clean(docdir, os.path.join(docdir, projectname))
4304 env.Clone([key=val, ...])
4306 Returns a separate copy of a construction environment. If there are
4307 any keyword arguments specified, they are added to the returned
4308 copy, overwriting any existing values for the keywords.
4309 Example:
4311 env2 = env.Clone()
4313 env3 = env.Clone(CCFLAGS = '-g')
4314 Additionally, a list of tools and a toolpath may be specified, as
4316 in the Environment constructor:
4317 def MyTool(env): env['FOO'] = 'bar'
4319 env4 = env.Clone(tools = ['msvc', MyTool])
4320 The parse_flags keyword argument is also recognized:
4322 # create an environment for compiling programs that use wxWidgets
4324 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
4325 Command(target, source, action, [key=val, ...]), env.Command(target,
4327 source, action, [key=val, ...])
4328 Executes a specific action (or list of actions) to build a target
4329 file or files. This is more convenient than defining a separate
4330 Builder object for a single special-case build.
4331 As a special case, the source_scanner keyword argument can be used
4333 to specify a Scanner object that will be used to scan the sources.
4334 (The global DirScanner object can be used if any of the sources
4335 will be directories that must be scanned on-disk for changes to
4336 files that aren't already specified in other Builder of function
4337 calls.)
4338 Any other keyword arguments specified override any same-named
4340 existing construction variables.
4341 An action can be an external command, specified as a string, or a
4343 callable Python object; see "Action Objects," below, for more
4344 complete information. Also note that a string specifying an
4345 external command may be preceded by an @ (at-sign) to suppress
4346 printing the command in question, or by a - (hyphen) to ignore the
4347 exit status of the external command.
4348 Examples:
4350 env.Command('foo.out', 'foo.in',
4352 "$FOO_BUILD < $SOURCES > $TARGET")
4353 env.Command('bar.out', 'bar.in',
4355 ["rm -f $TARGET",
4356 "$BAR_BUILD < $SOURCES > $TARGET"],
4357 ENV = {'PATH' : '/usr/local/bin/'})
4358 def rename(env, target, source):
4360 import os
4361 os.rename('.tmp', str(target[0]))
4362 env.Command('baz.out', 'baz.in',
4364 ["$BAZ_BUILD < $SOURCES > .tmp",
4365 rename ])
4366 Note that the Command function will usually assume, by default,
4368 that the specified targets and/or sources are Files, if no other
4369 part of the configuration identifies what type of entry it is. If
4370 necessary, you can explicitly specify that targets or source nodes
4371 should be treated as directoriese by using the Dir or env.Dir()
4372 functions.
4373 Examples:
4375 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
4377 env['DISTDIR'] = 'destination/directory'
4379 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
4380 (Also note that SCons will usually automatically create any
4382 directory necessary to hold a target file, so you normally don't
4383 need to create directories by hand.)
4384 Configure(env, [custom_tests, conf_dir, log_file, config_h]),
4386 env.Configure([custom_tests, conf_dir, log_file, config_h])
4387 Creates a Configure object for integrated functionality similar to
4388 GNU autoconf. See the section "Configure Contexts," below, for a
4389 complete explanation of the arguments and behavior.
4390 env.Copy([key=val, ...])
4392 A now-deprecated synonym for env.Clone().
4393 Decider(function), env.Decider(function)
4395 Specifies that all up-to-date decisions for targets built through
4396 this construction environment will be handled by the specified
4397 function. The function can be one of the following strings that
4398 specify the type of decision function to be performed:
4399 timestamp-newer
4401 Specifies that a target shall be considered out of date and
4402 rebuilt if the dependency's timestamp is newer than the target
4403 file's timestamp. This is the behavior of the classic Make
4404 utility, and make can be used a synonym for timestamp-newer.
4405 timestamp-match
4407 Specifies that a target shall be considered out of date and
4408 rebuilt if the dependency's timestamp is different than the
4409 timestamp recorded the last time the target was built. This
4410 provides behavior very similar to the classic Make utility (in
4411 particular, files are not opened up so that their contents can
4412 be checksummed) except that the target will also be rebuilt if
4413 a dependency file has been restored to a version with an
4414 earlier timestamp, such as can happen when restoring files from
4415 backup archives.
4416 MD5
4418 Specifies that a target shall be considered out of date and
4419 rebuilt if the dependency's content has changed since the last
4420 time the target was built, as determined be performing an MD5
4421 checksum on the dependency's contents and comparing it to the
4422 checksum recorded the last time the target was built. content
4423 can be used as a synonym for MD5.
4424 MD5-timestamp
4426 Specifies that a target shall be considered out of date and
4427 rebuilt if the dependency's content has changed since the last
4428 time the target was built, except that dependencies with a
4429 timestamp that matches the last time the target was rebuilt
4430 will be assumed to be up-to-date and not rebuilt. This provides
4431 behavior very similar to the MD5 behavior of always
4432 checksumming file contents, with an optimization of not
4433 checking the contents of files whose timestamps haven't
4434 changed. The drawback is that SCons will not detect if a file's
4435 content has changed but its timestamp is the same, as might
4436 happen in an automated script that runs a build, updates a
4437 file, and runs the build again, all within a single second.
4438 Examples:
4440 # Use exact timestamp matches by default.
4442 Decider('timestamp-match')
4443 # Use MD5 content signatures for any targets built
4445 # with the attached construction environment.
4446 env.Decider('content')
4447 In addition to the above already-available functions, the function
4449 argument may be an actual Python function that takes the following
4450 three arguments:
4451 dependency
4453 The Node (file) which should cause the target to be rebuilt if
4454 it has "changed" since the last tme target was built.
4455 target
4457 The Node (file) being built. In the normal case, this is what
4458 should get rebuilt if the dependency has "changed."
4459 prev_ni
4461 Stored information about the state of the dependency the last
4462 time the target was built. This can be consulted to match
4463 various file characteristics such as the timestamp, size, or
4464 content signature.
4465 The function should return a True (non-zero) value if the
4467 dependency has "changed" since the last time the target was built
4468 (indicating that the target should be rebuilt), and False (zero)
4469 otherwise (indicating that the target should not be rebuilt). Note
4470 that the decision can be made using whatever criteria are
4471 appopriate. Ignoring some or all of the function arguments is
4472 perfectly normal.
4473 Example:
4475 def my_decider(dependency, target, prev_ni):
4477 return not os.path.exists(str(target))
4478 env.Decider(my_decider)
4480 Default(targets), env.Default(targets)
4482 This specifies a list of default targets, which will be built by
4483 scons if no explicit targets are given on the command line.
4484 Multiple calls to Default are legal, and add to the list of default
4485 targets.
4486 Multiple targets should be specified as separate arguments to the
4488 Default method, or as a list. Default will also accept the Node
4489 returned by any of a construction environment's builder methods.
4490 Examples:
4492 Default('foo', 'bar', 'baz')
4494 env.Default(['a', 'b', 'c'])
4495 hello = env.Program('hello', 'hello.c')
4496 env.Default(hello)
4497 An argument to Default of None will clear all default targets.
4499 Later calls to Default will add to the (now empty) default-target
4500 list like normal.
4501 The current list of targets added using the Default function or
4503 method is available in the DEFAULT_TARGETS list; see below.
4504 DefaultEnvironment([args])
4506 Creates and returns a default construction environment object. This
4507 construction environment is used internally by SCons in order to
4508 execute many of the global functions in this list, and to fetch
4509 source files transparently from source code management systems.
4510 Depends(target, dependency), env.Depends(target, dependency)
4512 Specifies an explicit dependency; the target will be rebuilt
4513 whenever the dependency has changed. Both the specified target and
4514 dependency can be a string (usually the path name of a file or
4515 directory) or Node objects, or a list of strings or Node objects
4516 (such as returned by a Builder call). This should only be necessary
4517 for cases where the dependency is not caught by a Scanner for the
4518 file.
4519 Example:
4521 env.Depends('foo', 'other-input-file-for-foo')
4523 mylib = env.Library('mylib.c')
4525 installed_lib = env.Install('lib', mylib)
4526 bar = env.Program('bar.c')
4527 # Arrange for the library to be copied into the installation
4529 # directory before trying to build the "bar" program.
4530 # (Note that this is for example only. A "real" library
4531 # dependency would normally be configured through the $LIBS
4532 # and $LIBPATH variables, not using an env.Depends() call.)
4533 env.Depends(bar, installed_lib)
4535 env.Dictionary([vars])
4537 Returns a dictionary object containing copies of all of the
4538 construction variables in the environment. If there are any
4539 variable names specified, only the specified construction variables
4540 are returned in the dictionary.
4541 Example:
4543 dict = env.Dictionary()
4545 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
4546 Dir(name, [directory]), env.Dir(name, [directory])
4548 This returns a Directory Node, an object that represents the
4549 specified directory name. name can be a relative or absolute path.
4550 directory is an optional directory that will be used as the parent
4551 directory. If no directory is specified, the current script's
4552 directory is used as the parent.
4553 If name is a list, SCons returns a list of Dir nodes. Construction
4555 variables are expanded in name.
4556 Directory Nodes can be used anywhere you would supply a string as a
4558 directory name to a Builder method or function. Directory Nodes
4559 have attributes and methods that are useful in many situations; see
4560 "File and Directory Nodes," below.
4561 env.Dump([key])
4563 Returns a pretty printable representation of the environment. key,
4564 if not None, should be a string containing the name of the variable
4565 of interest.
4566 This SConstruct:
4568 env=Environment()
4570 print env.Dump('CCCOM')
4571 will print:
4573 '$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
4575 While this SConstruct:
4577 env=Environment()
4579 print env.Dump()
4580 will print:
4582 { 'AR': 'ar',
4584 'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
4585 'ARFLAGS': ['r'],
4586 'AS': 'as',
4587 'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
4588 'ASFLAGS': [],
4589 ...
4590 EnsurePythonVersion(major, minor), env.EnsurePythonVersion(major,
4592 minor)
4593 Ensure that the Python version is at least major.minor. This
4594 function will print out an error message and exit SCons with a
4595 non-zero exit code if the actual Python version is not late enough.
4596 Example:
4598 EnsurePythonVersion(2,2)
4600 EnsureSConsVersion(major, minor, [revision]),
4602 env.EnsureSConsVersion(major, minor, [revision])
4603 Ensure that the SCons version is at least major.minor, or
4604 major.minor.revision. if revision is specified. This function will
4605 print out an error message and exit SCons with a non-zero exit code
4606 if the actual SCons version is not late enough.
4607 Examples:
4609 EnsureSConsVersion(0,14)
4611 EnsureSConsVersion(0,96,90)
4613 Environment([key=value, ...]), env.Environment([key=value, ...])
4615 Return a new construction environment initialized with the
4616 specified key=value pairs.
4617 Execute(action, [strfunction, varlist]), env.Execute(action,
4619 [strfunction, varlist])
4620 Executes an Action object. The specified action may be an Action
4621 object (see the section "Action Objects," below, for a complete
4622 explanation of the arguments and behavior), or it may be a
4623 command-line string, list of commands, or executable Python
4624 function, each of which will be converted into an Action object and
4625 then executed. The exit value of the command or return value of the
4626 Python function will be returned.
4627 Note that scons will print an error message if the executed action
4629 fails--that is, exits with or returns a non-zero value. scons will
4630 not, however, automatically terminate the build if the specified
4631 action fails. If you want the build to stop in response to a failed
4632 Execute call, you must explicitly check for a non-zero return
4633 value:
4634 Execute(Copy('file.out', 'file.in'))
4636 if Execute("mkdir sub/dir/ectory"):
4638 # The mkdir failed, don't try to build.
4639 Exit(1)
4640 Exit([value]), env.Exit([value])
4642 This tells scons to exit immediately with the specified value. A
4643 default exit value of 0 (zero) is used if no value is specified.
4644 Export(vars), env.Export(vars)
4646 This tells scons to export a list of variables from the current
4647 SConscript file to all other SConscript files. The exported
4648 variables are kept in a global collection, so subsequent calls to
4649 Export will over-write previous exports that have the same name.
4650 Multiple variable names can be passed to Export as separate
4651 arguments or as a list. Keyword arguments can be used to provide
4652 names and their values. A dictionary can be used to map variables
4653 to a different name when exported. Both local variables and global
4654 variables can be exported.
4655 Examples:
4657 env = Environment()
4659 # Make env available for all SConscript files to Import().
4660 Export("env")
4661 package = 'my_name'
4663 # Make env and package available for all SConscript files:.
4664 Export("env", "package")
4665 # Make env and package available for all SConscript files:
4667 Export(["env", "package"])
4668 # Make env available using the name debug:
4670 Export(debug = env)
4671 # Make env available using the name debug:
4673 Export({"debug":env})
4674 Note that the SConscript function supports an exports argument that
4676 makes it easier to to export a variable or set of variables to a
4677 single SConscript file. See the description of the SConscript
4678 function, below.
4679 File(name, [directory]), env.File(name, [directory])
4681 This returns a File Node, an object that represents the specified
4682 file name. name can be a relative or absolute path. directory is
4683 an optional directory that will be used as the parent directory.
4684 If name is a list, SCons returns a list of File nodes. Construction
4686 variables are expanded in name.
4687 File Nodes can be used anywhere you would supply a string as a file
4689 name to a Builder method or function. File Nodes have attributes
4690 and methods that are useful in many situations; see "File and
4691 Directory Nodes," below.
4692 FindFile(file, dirs), env.FindFile(file, dirs)
4694 Search for file in the path specified by dirs. dirs may be a list
4695 of directory names or a single directory name. In addition to
4696 searching for files that exist in the filesystem, this function
4697 also searches for derived files that have not yet been built.
4698 Example:
4700 foo = env.FindFile('foo', ['dir1', 'dir2'])
4702 FindInstalledFiles(), env.FindInstalledFiles()
4704 Returns the list of targets set up by the Install or InstallAs
4705 builders.
4706 This function serves as a convenient method to select the contents
4708 of a binary package.
4709 Example:
4711 Install( '/bin', [ 'executable_a', 'executable_b' ] )
4713 # will return the file node list
4715 # [ '/bin/executable_a', '/bin/executable_b' ]
4716 FindInstalledFiles()
4717 Install( '/lib', [ 'some_library' ] )
4719 # will return the file node list
4721 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
4722 FindInstalledFiles()
4723 FindPathDirs(variable)
4725 Returns a function (actually a callable Python object) intended to
4726 be used as the path_function of a Scanner object. The returned
4727 object will look up the specified variable in a construction
4728 environment and treat the construction variable's value as a list
4729 of directory paths that should be searched (like $CPPPATH,
4730 $LIBPATH, etc.).
4731 Note that use of FindPathDirs is generally preferable to writing
4733 your own path_function for the following reasons: 1) The returned
4734 list will contain all appropriate directories found in source trees
4735 (when VariantDir is used) or in code repositories (when Repository
4736 or the -Y option are used). 2) scons will identify expansions of
4737 variable that evaluate to the same list of directories as, in fact,
4738 the same list, and avoid re-scanning the directories for files,
4739 when possible.
4740 Example:
4742 def my_scan(node, env, path, arg):
4744 # Code to scan file contents goes here...
4745 return include_files
4746 scanner = Scanner(name = 'myscanner',
4748 function = my_scan,
4749 path_function = FindPathDirs('MYPATH'))
4750 FindSourceFiles(node='"."'), env.FindSourceFiles(node='"."')
4752 Returns the list of nodes which serve as the source of the built
4753 files. It does so by inspecting the dependency tree starting at the
4754 optional argument node which defaults to the '"."'-node. It will
4755 then return all leaves of node. These are all children which have
4756 no further children.
4757 This function is a convenient method to select the contents of a
4759 Source Package.
4760 Example:
4762 Program( 'src/main_a.c' )
4764 Program( 'src/main_b.c' )
4765 Program( 'main_c.c' )
4766 # returns ['main_c.c', 'src/main_a.c', 'SConstruct', 'src/main_b.c']
4768 FindSourceFiles()
4769 # returns ['src/main_b.c', 'src/main_a.c' ]
4771 FindSourceFiles( 'src' )
4772 As you can see build support files (SConstruct in the above
4774 example) will also be returned by this function.
4775 Flatten(sequence), env.Flatten(sequence)
4777 Takes a sequence (that is, a Python list or tuple) that may contain
4778 nested sequences and returns a flattened list containing all of the
4779 individual elements in any sequence. This can be helpful for
4780 collecting the lists returned by calls to Builders; other Builders
4781 will automatically flatten lists specified as input, but direct
4782 Python manipulation of these lists does not.
4783 Examples:
4785 foo = Object('foo.c')
4787 bar = Object('bar.c')
4788 # Because `foo' and `bar' are lists returned by the Object() Builder,
4790 # `objects' will be a list containing nested lists:
4791 objects = ['f1.o', foo, 'f2.o', bar, 'f3.o']
4792 # Passing such a list to another Builder is all right because
4794 # the Builder will flatten the list automatically:
4795 Program(source = objects)
4796 # If you need to manipulate the list directly using Python, you need to
4798 # call Flatten() yourself, or otherwise handle nested lists:
4799 for object in Flatten(objects):
4800 print str(object)
4801 GetBuildFailures()
4803 Returns a list of exceptions for the actions that failed while
4804 attempting to build targets. Each element in the returned list is a
4805 BuildError object with the following attributes that record various
4806 aspects of the build failure:
4807 .node The node that was being built when the build failure
4810 occurred.
4811 .status The numeric exit status returned by the command or Python
4814 function that failed when trying to build the specified Node.
4815 .errstr The SCons error string describing the build failure. (This
4818 is often a generic message like "Error 2" to indicate that an
4819 executed command exited with a status of 2.)
4820 .filename The name of the file or directory that actually caused
4823 the failure. This may be different from the .node attribute. For
4824 example, if an attempt to build a target named sub/dir/target fails
4825 because the sub/dir directory could not be created, then the .node
4826 attribute will be sub/dir/target but the .filename attribute will
4827 be sub/dir.
4828 .executor The SCons Executor object for the target Node being
4831 built. This can be used to retrieve the construction environment
4832 used for the failed action.
4833 .action The actual SCons Action object that failed. This will be
4836 one specific action out of the possible list of actions that would
4837 have been executed to build the target.
4838 .command The actual expanded command that was executed and failed,
4841 after expansion of $TARGET, $SOURCE, and other construction
4842 variables.
4843 Note that the GetBuildFailures function will always return an empty
4845 list until any build failure has occurred, which means that
4846 GetBuildFailures will always return an empty list while the
4847 SConscript files are being read. Its primary intended use is for
4848 functions that will be executed before SCons exits by passing them
4849 to the standard Python atexit.register() function. Example:
4850 import atexit
4852 def print_build_failures():
4854 from SCons.Script import GetBuildFailures
4855 for bf in GetBuildFailures():
4856 print("%s failed: %s" % (bf.node, bf.errstr))
4857 atexit.register(print_build_failures)
4859 GetBuildPath(file, [...]), env.GetBuildPath(file, [...])
4861 Returns the scons path name (or names) for the specified file (or
4862 files). The specified file or files may be scons Nodes or strings
4863 representing path names.
4864 GetLaunchDir(), env.GetLaunchDir()
4866 Returns the absolute path name of the directory from which scons
4867 was initially invoked. This can be useful when using the -u, -U or
4868 -D options, which internally change to the directory in which the
4869 SConstruct file is found.
4870 GetOption(name), env.GetOption(name)
4872 This function provides a way to query the value of SCons options
4873 set on scons command line (or set using the SetOption function).
4874 The options supported are:
4875 cache_debug
4877 which corresponds to --cache-debug;
4878 cache_disable
4880 which corresponds to --cache-disable;
4881 cache_force
4883 which corresponds to --cache-force;
4884 cache_show
4886 which corresponds to --cache-show;
4887 clean
4889 which corresponds to -c, --clean and --remove;
4890 config
4892 which corresponds to --config;
4893 directory
4895 which corresponds to -C and --directory;
4896 diskcheck
4898 which corresponds to --diskcheck
4899 duplicate
4901 which corresponds to --duplicate;
4902 file
4904 which corresponds to -f, --file, --makefile and --sconstruct;
4905 help
4907 which corresponds to -h and --help;
4908 ignore_errors
4910 which corresponds to --ignore-errors;
4911 implicit_cache
4913 which corresponds to --implicit-cache;
4914 implicit_deps_changed
4916 which corresponds to --implicit-deps-changed;
4917 implicit_deps_unchanged
4919 which corresponds to --implicit-deps-unchanged;
4920 interactive
4922 which corresponds to --interact and --interactive;
4923 keep_going
4925 which corresponds to -k and --keep-going;
4926 max_drift
4928 which corresponds to --max-drift;
4929 no_exec
4931 which corresponds to -n, --no-exec, --just-print, --dry-run and
4932 --recon;
4933 no_site_dir
4935 which corresponds to --no-site-dir;
4936 num_jobs
4938 which corresponds to -j and --jobs;
4939 profile_file
4941 which corresponds to --profile;
4942 question
4944 which corresponds to -q and --question;
4945 random
4947 which corresponds to --random;
4948 repository
4950 which corresponds to -Y, --repository and --srcdir;
4951 silent
4953 which corresponds to -s, --silent and --quiet;
4954 site_dir
4956 which corresponds to --site-dir;
4957 stack_size
4959 which corresponds to --stack-size;
4960 taskmastertrace_file
4962 which corresponds to --taskmastertrace; and
4963 warn
4965 which corresponds to --warn and --warning.
4966 See the documentation for the corresponding command line object for
4968 information about each specific option.
4969 Glob(pattern, [ondisk, source, strings, exclude]), env.Glob(pattern,
4971 [ondisk, source, strings, exclude])
4972 Returns Nodes (or strings) that match the specified pattern,
4973 relative to the directory of the current SConscript file. The
4974 env.Glob() form performs string substition on pattern and returns
4975 whatever matches the resulting expanded pattern.
4976 The specified pattern uses Unix shell style metacharacters for
4978 matching:
4979 * matches everything
4981 ? matches any single character
4982 [seq] matches any character in seq
4983 [!seq] matches any char not in seq
4984 If the first character of a filename is a dot, it must be matched
4986 explicitly. Character matches do not span directory separators.
4987 The Glob knows about repositories (see the Repository function) and
4989 source directories (see the VariantDir function) and returns a Node
4990 (or string, if so configured) in the local (SConscript) directory
4991 if matching Node is found anywhere in a corresponding repository or
4992 source directory.
4993 The ondisk argument may be set to False (or any other non-true
4995 value) to disable the search for matches on disk, thereby only
4996 returning matches among already-configured File or Dir Nodes. The
4997 default behavior is to return corresponding Nodes for any on-disk
4998 matches found.
4999 The source argument may be set to True (or any equivalent value) to
5001 specify that, when the local directory is a VariantDir, the
5002 returned Nodes should be from the corresponding source directory,
5003 not the local directory.
5004 The strings argument may be set to True (or any equivalent value)
5006 to have the Glob function return strings, not Nodes, that represent
5007 the matched files or directories. The returned strings will be
5008 relative to the local (SConscript) directory. (Note that This may
5009 make it easier to perform arbitrary manipulation of file names, but
5010 if the returned strings are passed to a different SConscript file,
5011 any Node translation will be relative to the other SConscript
5012 directory, not the original SConscript directory.)
5013 The exclude argument may be set to a pattern or a list of patterns
5015 (following the same Unix shell semantics) which must be filtered
5016 out of returned elements. Elements matching a least one pattern of
5017 this list will be excluded.
5018 Examples:
5020 Program('foo', Glob('*.c'))
5022 Zip('/tmp/everything', Glob('.??*') + Glob('*'))
5023 sources = Glob('*.cpp', exclude=['os_*_specific_*.cpp']) + Glob('os_%s_specific_*.cpp'%currentOS)
5024 Help(text, append=False), env.Help(text, append=False)
5026 This specifies help text to be printed if the -h argument is given
5027 to scons. If Help is called multiple times, the text is appended
5028 together in the order that Help is called. With append set to
5029 False, any Help text generated with AddOption is clobbered. If
5030 append is True, the AddOption help is prepended to the help string,
5031 thus preserving the -h message.
5032 Ignore(target, dependency), env.Ignore(target, dependency)
5034 The specified dependency file(s) will be ignored when deciding if
5035 the target file(s) need to be rebuilt.
5036 You can also use Ignore to remove a target from the default build.
5038 In order to do this you must specify the directory the target will
5039 be built in as the target, and the file you want to skip building
5040 as the dependency.
5041 Note that this will only remove the dependencies listed from the
5043 files built by default. It will still be built if that dependency
5044 is needed by another object being built. See the third and forth
5045 examples below.
5046 Examples:
5048 env.Ignore('foo', 'foo.c')
5050 env.Ignore('bar', ['bar1.h', 'bar2.h'])
5051 env.Ignore('.','foobar.obj')
5052 env.Ignore('bar','bar/foobar.obj')
5053 Import(vars), env.Import(vars)
5055 This tells scons to import a list of variables into the current
5056 SConscript file. This will import variables that were exported with
5057 Export or in the exports argument to SConscript. Variables exported
5058 by SConscript have precedence. Multiple variable names can be
5059 passed to Import as separate arguments or as a list. The variable
5060 "*" can be used to import all variables.
5061 Examples:
5063 Import("env")
5065 Import("env", "variable")
5066 Import(["env", "variable"])
5067 Import("*")
5068 Literal(string), env.Literal(string)
5070 The specified string will be preserved as-is and not have
5071 construction variables expanded.
5072 Local(targets), env.Local(targets)
5074 The specified targets will have copies made in the local tree, even
5075 if an already up-to-date copy exists in a repository. Returns a
5076 list of the target Node or Nodes.
5077 env.MergeFlags(arg, [unique])
5079 Merges the specified arg values to the construction environment's
5080 construction variables. If the arg argument is not a dictionary, it
5081 is converted to one by calling env.ParseFlags on the argument
5082 before the values are merged. Note that arg must be a single value,
5083 so multiple strings must be passed in as a list, not as separate
5084 arguments to env.MergeFlags.
5085 By default, duplicate values are eliminated; you can, however,
5087 specify unique=0 to allow duplicate values to be added. When
5088 eliminating duplicate values, any construction variables that end
5089 with the string PATH keep the left-most unique value. All other
5090 construction variables keep the right-most unique value.
5091 Examples:
5093 # Add an optimization flag to $CCFLAGS.
5095 env.MergeFlags('-O3')
5096 # Combine the flags returned from running pkg-config with an optimization
5098 # flag and merge the result into the construction variables.
5099 env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
5100 # Combine an optimization flag with the flags returned from running pkg-config
5102 # twice and merge the result into the construction variables.
5103 env.MergeFlags(['-O3',
5104 '!pkg-config gtk+-2.0 --cflags --libs',
5105 '!pkg-config libpng12 --cflags --libs'])
5106 NoCache(target, ...), env.NoCache(target, ...)
5108 Specifies a list of files which should not be cached whenever the
5109 CacheDir method has been activated. The specified targets may be a
5110 list or an individual target.
5111 Multiple files should be specified either as separate arguments to
5113 the NoCache method, or as a list. NoCache will also accept the
5114 return value of any of the construction environment Builder
5115 methods.
5116 Calling NoCache on directories and other non-File Node types has no
5118 effect because only File Nodes are cached.
5119 Examples:
5121 NoCache('foo.elf')
5123 NoCache(env.Program('hello', 'hello.c'))
5124 NoClean(target, ...), env.NoClean(target, ...)
5126 Specifies a list of files or directories which should not be
5127 removed whenever the targets (or their dependencies) are specified
5128 with the -c command line option. The specified targets may be a
5129 list or an individual target. Multiple calls to NoClean are legal,
5130 and prevent each specified target from being removed by calls to
5131 the -c option.
5132 Multiple files or directories should be specified either as
5134 separate arguments to the NoClean method, or as a list. NoClean
5135 will also accept the return value of any of the construction
5136 environment Builder methods.
5137 Calling NoClean for a target overrides calling Clean for the same
5139 target, and any targets passed to both functions will not be
5140 removed by the -c option.
5141 Examples:
5143 NoClean('foo.elf')
5145 NoClean(env.Program('hello', 'hello.c'))
5146 env.ParseConfig(command, [function, unique])
5148 Calls the specified function to modify the environment as specified
5149 by the output of command. The default function is env.MergeFlags,
5150 which expects the output of a typical *-config command (for
5151 example, gtk-config) and adds the options to the appropriate
5152 construction variables. By default, duplicate values are not added
5153 to any construction variables; you can specify unique=0 to allow
5154 duplicate values to be added.
5155 Interpreted options and the construction variables they affect are
5157 as specified for the env.ParseFlags method (which this method
5158 calls). See that method's description, below, for a table of
5159 options and construction variables.
5160 ParseDepends(filename, [must_exist, only_one]),
5162 env.ParseDepends(filename, [must_exist, only_one])
5163 Parses the contents of the specified filename as a list of
5164 dependencies in the style of Make or mkdep, and explicitly
5165 establishes all of the listed dependencies.
5166 By default, it is not an error if the specified filename does not
5168 exist. The optional must_exist argument may be set to a non-zero
5169 value to have scons throw an exception and generate an error if the
5170 file does not exist, or is otherwise inaccessible.
5171 The optional only_one argument may be set to a non-zero value to
5173 have scons thrown an exception and generate an error if the file
5174 contains dependency information for more than one target. This can
5175 provide a small sanity check for files intended to be generated by,
5176 for example, the gcc -M flag, which should typically only write
5177 dependency information for one output file into a corresponding .d
5178 file.
5179 The filename and all of the files listed therein will be
5181 interpreted relative to the directory of the SConscript file which
5182 calls the ParseDepends function.
5183 env.ParseFlags(flags, ...)
5185 Parses one or more strings containing typical command-line flags
5186 for GCC tool chains and returns a dictionary with the flag values
5187 separated into the appropriate SCons construction variables. This
5188 is intended as a companion to the env.MergeFlags method, but allows
5189 for the values in the returned dictionary to be modified, if
5190 necessary, before merging them into the construction environment.
5191 (Note that env.MergeFlags will call this method if its argument is
5192 not a dictionary, so it is usually not necessary to call
5193 env.ParseFlags directly unless you want to manipulate the values.)
5194 If the first character in any string is an exclamation mark (!),
5196 the rest of the string is executed as a command, and the output
5197 from the command is parsed as GCC tool chain command-line flags and
5198 added to the resulting dictionary.
5199 Flag values are translated accordig to the prefix found, and added
5201 to the following construction variables:
5202 -arch CCFLAGS, LINKFLAGS
5204 -D CPPDEFINES
5205 -framework FRAMEWORKS
5206 -frameworkdir= FRAMEWORKPATH
5207 -include CCFLAGS
5208 -isysroot CCFLAGS, LINKFLAGS
5209 -I CPPPATH
5210 -l LIBS
5211 -L LIBPATH
5212 -mno-cygwin CCFLAGS, LINKFLAGS
5213 -mwindows LINKFLAGS
5214 -pthread CCFLAGS, LINKFLAGS
5215 -std= CFLAGS
5216 -Wa, ASFLAGS, CCFLAGS
5217 -Wl,-rpath= RPATH
5218 -Wl,-R, RPATH
5219 -Wl,-R RPATH
5220 -Wl, LINKFLAGS
5221 -Wp, CPPFLAGS
5222 - CCFLAGS
5223 + CCFLAGS, LINKFLAGS
5224 Any other strings not associated with options are assumed to be the
5226 names of libraries and added to the $LIBS construction variable.
5227 Examples (all of which produce the same result):
5229 dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
5231 dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
5232 dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
5233 dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
5234 Platform(string)
5236 The Platform form returns a callable object that can be used to
5237 initialize a construction environment using the platform keyword of
5238 the Environment function.
5239 Example:
5241 env = Environment(platform = Platform('win32'))
5243 The env.Platform form applies the callable object for the specified
5245 platform string to the environment through which the method was
5246 called.
5247 env.Platform('posix')
5249 Note that the win32 platform adds the SystemDrive and SystemRoot
5251 variables from the user's external environment to the construction
5252 environment's $ENV dictionary. This is so that any executed
5253 commands that use sockets to connect with other systems (such as
5254 fetching source files from external CVS repository specifications
5255 like :pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons) will
5256 work on Windows systems.
5257 Precious(target, ...), env.Precious(target, ...)
5259 Marks each given target as precious so it is not deleted before it
5260 is rebuilt. Normally scons deletes a target before building it.
5261 Multiple targets can be passed in to a single call to Precious.
5262 env.Prepend(key=val, [...])
5264 Appends the specified keyword arguments to the beginning of
5265 construction variables in the environment. If the Environment does
5266 not have the specified construction variable, it is simply added to
5267 the environment. If the values of the construction variable and the
5268 keyword argument are the same type, then the two values will be
5269 simply added together. Otherwise, the construction variable and the
5270 value of the keyword argument are both coerced to lists, and the
5271 lists are added together. (See also the Append method, above.)
5272 Example:
5274 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
5276 env.PrependENVPath(name, newpath, [envname, sep, delete_existing])
5278 This appends new path elements to the given path in the specified
5279 external environment ($ENV by default). This will only add any
5280 particular path once (leaving the first one it encounters and
5281 ignoring the rest, to preserve path order), and to help assure
5282 this, will normalize all paths (using os.path.normpath and
5283 os.path.normcase). This can also handle the case where the given
5284 old path variable is a list instead of a string, in which case a
5285 list will be returned instead of a string.
5286 If delete_existing is 0, then adding a path that already exists
5288 will not move it to the beginning; it will stay where it is in the
5289 list.
5290 Example:
5292 print 'before:',env['ENV']['INCLUDE']
5294 include_path = '/foo/bar:/foo'
5295 env.PrependENVPath('INCLUDE', include_path)
5296 print 'after:',env['ENV']['INCLUDE']
5297 The above example will print:
5299 before: /biz:/foo
5301 after: /foo/bar:/foo:/biz
5302 env.PrependUnique(key=val, delete_existing=0, [...])
5304 Appends the specified keyword arguments to the beginning of
5305 construction variables in the environment. If the Environment does
5306 not have the specified construction variable, it is simply added to
5307 the environment. If the construction variable being appended to is
5308 a list, then any value(s) that already exist in the construction
5309 variable will not be added again to the list. However, if
5310 delete_existing is 1, existing matching values are removed first,
5311 so existing values in the arg list move to the front of the list.
5312 Example:
5314 env.PrependUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
5316 Progress(callable, [interval]), Progress(string, [interval, file,
5318 overwrite]), Progress(list_of_strings, [interval, file, overwrite])
5319 Allows SCons to show progress made during the build by displaying a
5320 string or calling a function while evaluating Nodes (e.g. files).
5321 If the first specified argument is a Python callable (a function or
5323 an object that has a __call__() method), the function will be
5324 called once every interval times a Node is evaluated. The callable
5325 will be passed the evaluated Node as its only argument. (For future
5326 compatibility, it's a good idea to also add *args and **kw as
5327 arguments to your function or method. This will prevent the code
5328 from breaking if SCons ever changes the interface to call the
5329 function with additional arguments in the future.)
5330 An example of a simple custom progress function that prints a
5332 string containing the Node name every 10 Nodes:
5333 def my_progress_function(node, *args, **kw):
5335 print('Evaluating node %s!' % node)
5336 Progress(my_progress_function, interval=10)
5337 A more complicated example of a custom progress display object that
5339 prints a string containing a count every 100 evaluated Nodes. Note
5340 the use of \r (a carriage return) at the end so that the string
5341 will overwrite itself on a display:
5342 import sys
5344 class ProgressCounter(object):
5345 count = 0
5346 def __call__(self, node, *args, **kw):
5347 self.count += 100
5348 sys.stderr.write('Evaluated %s nodes\r' % self.count)
5349 Progress(ProgressCounter(), interval=100)
5350 If the first argument Progress is a string, the string will be
5352 displayed every interval evaluated Nodes. The default is to print
5353 the string on standard output; an alternate output stream may be
5354 specified with the file= argument. The following will print a
5355 series of dots on the error output, one dot for every 100 evaluated
5356 Nodes:
5357 import sys
5359 Progress('.', interval=100, file=sys.stderr)
5360 If the string contains the verbatim substring $TARGET, it will be
5362 replaced with the Node. Note that, for performance reasons, this is
5363 not a regular SCons variable substition, so you can not use other
5364 variables or use curly braces. The following example will print the
5365 name of every evaluated Node, using a \r (carriage return) to cause
5366 each line to overwritten by the next line, and the overwrite=
5367 keyword argument to make sure the previously-printed file name is
5368 overwritten with blank spaces:
5369 import sys
5371 Progress('$TARGET\r', overwrite=True)
5372 If the first argument to Progress is a list of strings, then each
5374 string in the list will be displayed in rotating fashion every
5375 interval evaluated Nodes. This can be used to implement a "spinner"
5376 on the user's screen as follows:
5377 Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5)
5379 Pseudo(target, ...), env.Pseudo(target, ...)
5381 This indicates that each given target should not be created by the
5382 build rule, and if the target is created, an error will be
5383 generated. This is similar to the gnu make .PHONY target. However,
5384 in the vast majority of cases, an Alias is more appropriate.
5385 Multiple targets can be passed in to a single call to Pseudo.
5386 PyPackageDir(modulename), env.PyPackageDir(modulename)
5388 This returns a Directory Node similar to Dir. The python module /
5389 package is looked up and if located the directory is returned for
5390 the location. modulename Is a named python package / module to
5391 lookup the directory for it's location.
5392 If modulename is a list, SCons returns a list of Dir nodes.
5394 Construction variables are expanded in modulename.
5395 env.Replace(key=val, [...])
5397 Replaces construction variables in the Environment with the
5398 specified keyword arguments.
5399 Example:
5401 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
5403 Repository(directory), env.Repository(directory)
5405 Specifies that directory is a repository to be searched for files.
5406 Multiple calls to Repository are legal, and each one adds to the
5407 list of repositories that will be searched.
5408 To scons, a repository is a copy of the source tree, from the
5410 top-level directory on down, which may contain both source files
5411 and derived files that can be used to build targets in the local
5412 source tree. The canonical example would be an official source tree
5413 maintained by an integrator. If the repository contains derived
5414 files, then the derived files should have been built using scons,
5415 so that the repository contains the necessary signature information
5416 to allow scons to figure out when it is appropriate to use the
5417 repository copy of a derived file, instead of building one locally.
5418 Note that if an up-to-date derived file already exists in a
5420 repository, scons will not make a copy in the local directory tree.
5421 In order to guarantee that a local copy will be made, use the Local
5422 method.
5423 Requires(target, prerequisite), env.Requires(target, prerequisite)
5425 Specifies an order-only relationship between the specified target
5426 file(s) and the specified prerequisite file(s). The prerequisite
5427 file(s) will be (re)built, if necessary, before the target file(s),
5428 but the target file(s) do not actually depend on the prerequisites
5429 and will not be rebuilt simply because the prerequisite file(s)
5430 change.
5431 Example:
5433 env.Requires('foo', 'file-that-must-be-built-before-foo')
5435 Return([vars..., stop=])
5437 By default, this stops processing the current SConscript file and
5438 returns to the calling SConscript file the values of the variables
5439 named in the vars string arguments. Multiple strings contaning
5440 variable names may be passed to Return. Any strings that contain
5441 white space
5442 The optional stop= keyword argument may be set to a false value to
5444 continue processing the rest of the SConscript file after the
5445 Return call. This was the default behavior prior to SCons 0.98.
5446 However, the values returned are still the values of the variables
5447 in the named vars at the point Return is called.
5448 Examples:
5450 # Returns without returning a value.
5452 Return()
5453 # Returns the value of the 'foo' Python variable.
5455 Return("foo")
5456 # Returns the values of the Python variables 'foo' and 'bar'.
5458 Return("foo", "bar")
5459 # Returns the values of Python variables 'val1' and 'val2'.
5461 Return('val1 val2')
5462 Scanner(function, [argument, keys, path_function, node_class,
5464 node_factory, scan_check, recursive]), env.Scanner(function, [argument,
5465 keys, path_function, node_class, node_factory, scan_check, recursive])
5466 Creates a Scanner object for the specified function. See the
5467 section "Scanner Objects," below, for a complete explanation of the
5468 arguments and behavior.
5469 SConscript(scripts, [exports, variant_dir, duplicate]),
5471 env.SConscript(scripts, [exports, variant_dir, duplicate]),
5472 SConscript(dirs=subdirs, [name=script, exports, variant_dir,
5473 duplicate]), env.SConscript(dirs=subdirs, [name=script, exports,
5474 variant_dir, duplicate])
5475 This tells scons to execute one or more subsidiary SConscript
5476 (configuration) files. Any variables returned by a called script
5477 using Return will be returned by the call to SConscript. There are
5478 two ways to call the SConscript function.
5479 The first way you can call SConscript is to explicitly specify one
5481 or more scripts as the first argument. A single script may be
5482 specified as a string; multiple scripts must be specified as a list
5483 (either explicitly or as created by a function like Split).
5484 Examples:
5485 SConscript('SConscript') # run SConscript in the current directory
5487 SConscript('src/SConscript') # run SConscript in the src directory
5488 SConscript(['src/SConscript', 'doc/SConscript'])
5489 config = SConscript('MyConfig.py')
5490 The second way you can call SConscript is to specify a list of
5492 (sub)directory names as a dirs=subdirs keyword argument. In this
5493 case, scons will, by default, execute a subsidiary configuration
5494 file named SConscript in each of the specified directories. You may
5495 specify a name other than SConscript by supplying an optional
5496 name=script keyword argument. The first three examples below have
5497 the same effect as the first three examples above:
5498 SConscript(dirs='.') # run SConscript in the current directory
5500 SConscript(dirs='src') # run SConscript in the src directory
5501 SConscript(dirs=['src', 'doc'])
5502 SConscript(dirs=['sub1', 'sub2'], name='MySConscript')
5503 The optional exports argument provides a list of variable names or
5505 a dictionary of named values to export to the script(s). These
5506 variables are locally exported only to the specified script(s), and
5507 do not affect the global pool of variables used by the Export
5508 function. The subsidiary script(s) must use the Import function to
5509 import the variables. Examples:
5510 foo = SConscript('sub/SConscript', exports='env')
5512 SConscript('dir/SConscript', exports=['env', 'variable'])
5513 SConscript(dirs='subdir', exports='env variable')
5514 SConscript(dirs=['one', 'two', 'three'], exports='shared_info')
5515 If the optional variant_dir argument is present, it causes an
5517 effect equivalent to the VariantDir method described below. (If
5518 variant_dir is not present, the
5519 duplicate argument is ignored.) The variant_dir argument is
5521 interpreted relative to the directory of the calling SConscript
5522 file. See the description of the VariantDir function below for
5523 additional details and restrictions.
5524 If variant_dir is present, the source directory is the directory in
5526 which the SConscript file resides and the SConscript file is
5527 evaluated as if it were in the variant_dir directory:
5528 SConscript('src/SConscript', variant_dir = 'build')
5530 is equivalent to
5532 VariantDir('build', 'src')
5534 SConscript('build/SConscript')
5535 This later paradigm is often used when the sources are in the same
5537 directory as the SConstruct:
5538 SConscript('SConscript', variant_dir = 'build')
5540 is equivalent to
5542 VariantDir('build', '.')
5544 SConscript('build/SConscript')
5545 Here are some composite examples:
5549 # collect the configuration information and use it to build src and doc
5551 shared_info = SConscript('MyConfig.py')
5552 SConscript('src/SConscript', exports='shared_info')
5553 SConscript('doc/SConscript', exports='shared_info')
5554 # build debugging and production versions. SConscript
5556 # can use Dir('.').path to determine variant.
5557 SConscript('SConscript', variant_dir='debug', duplicate=0)
5558 SConscript('SConscript', variant_dir='prod', duplicate=0)
5559 # build debugging and production versions. SConscript
5561 # is passed flags to use.
5562 opts = { 'CPPDEFINES' : ['DEBUG'], 'CCFLAGS' : '-pgdb' }
5563 SConscript('SConscript', variant_dir='debug', duplicate=0, exports=opts)
5564 opts = { 'CPPDEFINES' : ['NODEBUG'], 'CCFLAGS' : '-O' }
5565 SConscript('SConscript', variant_dir='prod', duplicate=0, exports=opts)
5566 # build common documentation and compile for different architectures
5568 SConscript('doc/SConscript', variant_dir='build/doc', duplicate=0)
5569 SConscript('src/SConscript', variant_dir='build/x86', duplicate=0)
5570 SConscript('src/SConscript', variant_dir='build/ppc', duplicate=0)
5571 SConscriptChdir(value), env.SConscriptChdir(value)
5573 By default, scons changes its working directory to the directory in
5574 which each subsidiary SConscript file lives. This behavior may be
5575 disabled by specifying either:
5576 SConscriptChdir(0)
5578 env.SConscriptChdir(0)
5579 in which case scons will stay in the top-level directory while
5581 reading all SConscript files. (This may be necessary when building
5582 from repositories, when all the directories in which SConscript
5583 files may be found don't necessarily exist locally.) You may enable
5584 and disable this ability by calling SConscriptChdir() multiple
5585 times.
5586 Example:
5588 env = Environment()
5590 SConscriptChdir(0)
5591 SConscript('foo/SConscript') # will not chdir to foo
5592 env.SConscriptChdir(1)
5593 SConscript('bar/SConscript') # will chdir to bar
5594 SConsignFile([file, dbm_module]), env.SConsignFile([file, dbm_module])
5596 This tells scons to store all file signatures in the specified
5597 database file. If the file name is omitted, .sconsign is used by
5598 default. (The actual file name(s) stored on disk may have an
5599 appropriated suffix appended by the
5600 dbm_module.) If file is not an absolute path name, the file is
5601 placed in the same directory as the top-level SConstruct file.
5602 If file is None, then scons will store file signatures in a
5604 separate .sconsign file in each directory, not in one global
5605 database file. (This was the default behavior prior to SCons
5606 0.96.91 and 0.97.)
5607 The optional dbm_module argument can be used to specify which
5609 Python database module The default is to use a custom SCons.dblite
5610 module that uses pickled Python data structures, and which works on
5611 all Python versions.
5612 Examples:
5614 # Explicitly stores signatures in ".sconsign.dblite"
5616 # in the top-level SConstruct directory (the
5617 # default behavior).
5618 SConsignFile()
5619 # Stores signatures in the file "etc/scons-signatures"
5621 # relative to the top-level SConstruct directory.
5622 SConsignFile("etc/scons-signatures")
5623 # Stores signatures in the specified absolute file name.
5625 SConsignFile("/home/me/SCons/signatures")
5626 # Stores signatures in a separate .sconsign file
5628 # in each directory.
5629 SConsignFile(None)
5630 env.SetDefault(key=val, [...])
5632 Sets construction variables to default values specified with the
5633 keyword arguments if (and only if) the variables are not already
5634 set. The following statements are equivalent:
5635 env.SetDefault(FOO = 'foo')
5637 if 'FOO' not in env: env['FOO'] = 'foo'
5639 SetOption(name, value), env.SetOption(name, value)
5641 This function provides a way to set a select subset of the scons
5642 command line options from a SConscript file. The options supported
5643 are:
5644 clean
5646 which corresponds to -c, --clean and --remove;
5647 duplicate
5649 which corresponds to --duplicate;
5650 help
5652 which corresponds to -h and --help;
5653 implicit_cache
5655 which corresponds to --implicit-cache;
5656 max_drift
5658 which corresponds to --max-drift;
5659 no_exec
5661 which corresponds to -n, --no-exec, --just-print, --dry-run and
5662 --recon;
5663 num_jobs
5665 which corresponds to -j and --jobs;
5666 random
5668 which corresponds to --random; and
5669 silent
5671 which corresponds to --silent.
5672 stack_size
5674 which corresponds to --stack-size.
5675 See the documentation for the corresponding command line object for
5677 information about each specific option.
5678 Example:
5680 SetOption('max_drift', 1)
5682 SideEffect(side_effect, target), env.SideEffect(side_effect, target)
5684 Declares side_effect as a side effect of building target. Both
5685 side_effect and target can be a list, a file name, or a node. A
5686 side effect is a target file that is created or updated as a side
5687 effect of building other targets. For example, a Windows PDB file
5688 is created as a side effect of building the .obj files for a static
5689 library, and various log files are created updated as side effects
5690 of various TeX commands. If a target is a side effect of multiple
5691 build commands, scons will ensure that only one set of commands is
5692 executed at a time. Consequently, you only need to use this method
5693 for side-effect targets that are built as a result of multiple
5694 build commands.
5695 Because multiple build commands may update the same side effect
5697 file, by default the side_effect target is not automatically
5698 removed when the target is removed by the -c option. (Note,
5699 however, that the side_effect might be removed as part of cleaning
5700 the directory in which it lives.) If you want to make sure the
5701 side_effect is cleaned whenever a specific target is cleaned, you
5702 must specify this explicitly with the Clean or env.Clean function.
5703 SourceCode(entries, builder), env.SourceCode(entries, builder)
5705 This function and its associate factory functions are deprecated.
5706 There is no replacement. The intended use was to keep a local tree
5707 in sync with an archive, but in actuality the function only causes
5708 the archive to be fetched on the first run. Synchronizing with the
5709 archive is best done external to SCons.
5710 Arrange for non-existent source files to be fetched from a source
5712 code management system using the specified builder. The specified
5713 entries may be a Node, string or list of both, and may represent
5714 either individual source files or directories in which source files
5715 can be found.
5716 For any non-existent source files, scons will search up the
5718 directory tree and use the first SourceCode builder it finds. The
5719 specified builder may be None, in which case scons will not use a
5720 builder to fetch source files for the specified entries, even if a
5721 SourceCode builder has been specified for a directory higher up the
5722 tree.
5723 scons will, by default, fetch files from SCCS or RCS subdirectories
5726 without explicit configuration. This takes some extra processing
5727 time to search for the necessary source code management files on
5728 disk. You can avoid these extra searches and speed up your build a
5729 little by disabling these searches as follows:
5730 env.SourceCode('.', None)
5732 Note that if the specified builder is one you create by hand, it
5734 must have an associated construction environment to use when
5735 fetching a source file.
5736 scons provides a set of canned factory functions that return
5739 appropriate Builders for various popular source code management
5740 systems. Canonical examples of invocation include:
5741 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
5743 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
5744 env.SourceCode('/', env.RCS())
5745 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
5746 env.SourceCode('no_source.c', None)
5747 SourceSignatures(type), env.SourceSignatures(type)
5751 Note: Although it is not yet officially deprecated, use of this
5752 function is discouraged. See the Decider function for a more
5753 flexible and straightforward way to configure SCons'
5754 decision-making.
5755 The SourceSignatures function tells scons how to decide if a source
5757 file (a file that is not built from any other files) has changed
5758 since the last time it was used to build a particular target file.
5759 Legal values are MD5 or timestamp.
5760 If the environment method is used, the specified type of source
5762 signature is only used when deciding whether targets built with
5763 that environment are up-to-date or must be rebuilt. If the global
5764 function is used, the specified type of source signature becomes
5765 the default used for all decisions about whether targets are
5766 up-to-date.
5767 MD5 means scons decides that a source file has changed if the MD5
5770 checksum of its contents has changed since the last time it was
5771 used to rebuild a particular target file.
5772 timestamp means scons decides that a source file has changed if its
5775 timestamp (modification time) has changed since the last time it
5776 was used to rebuild a particular target file. (Note that although
5777 this is similar to the behavior of Make, by default it will also
5778 rebuild if the dependency is older than the last time it was used
5779 to rebuild the target file.)
5780 There is no different between the two behaviors for Python Value
5782 node objects.
5783 MD5 signatures take longer to compute, but are more accurate than
5786 timestamp signatures. The default value is MD5.
5787 Note that the default TargetSignatures setting (see below) is to
5789 use this SourceSignatures setting for any target files that are
5790 used to build other target files. Consequently, changing the value
5791 of SourceSignatures will, by default, affect the up-to-date
5792 decision for all files in the build (or all files built with a
5793 specific construction environment when env.SourceSignatures is
5794 used).
5795 Split(arg), env.Split(arg)
5797 Returns a list of file names or other objects. If arg is a string,
5798 it will be split on strings of white-space characters within the
5799 string, making it easier to write long lists of file names. If arg
5800 is already a list, the list will be returned untouched. If arg is
5801 any other type of object, it will be returned as a list containing
5802 just the object.
5803 Example:
5805 files = Split("f1.c f2.c f3.c")
5807 files = env.Split("f4.c f5.c f6.c")
5808 files = Split("""
5809 f7.c
5810 f8.c
5811 f9.c
5812 """)
5813 env.subst(input, [raw, target, source, conv])
5815 Performs construction variable interpolation on the specified
5816 string or sequence argument input.
5817 By default, leading or trailing white space will be removed from
5819 the result. and all sequences of white space will be compressed to
5820 a single space character. Additionally, any $( and $) character
5821 sequences will be stripped from the returned string, The optional
5822 raw argument may be set to 1 if you want to preserve white space
5823 and $(-$) sequences. The raw argument may be set to 2 if you want
5824 to strip all characters between any $( and $) pairs (as is done for
5825 signature calculation).
5826 If the input is a sequence (list or tuple), the individual elements
5828 of the sequence will be expanded, and the results will be returned
5829 as a list.
5830 The optional target and source keyword arguments must be set to
5832 lists of target and source nodes, respectively, if you want the
5833 $TARGET, $TARGETS, $SOURCE and $SOURCES to be available for
5834 expansion. This is usually necessary if you are calling env.subst
5835 from within a Python function used as an SCons action.
5836 Returned string values or sequence elements are converted to their
5838 string representation by default. The optional conv argument may
5839 specify a conversion function that will be used in place of the
5840 default. For example, if you want Python objects (including SCons
5841 Nodes) to be returned as Python objects, you can use the Python Λ
5842 idiom to pass in an unnamed function that simply returns its
5843 unconverted argument.
5844 Example:
5846 print env.subst("The C compiler is: $CC")
5848 def compile(target, source, env):
5850 sourceDir = env.subst("${SOURCE.srcdir}",
5851 target=target,
5852 source=source)
5853 source_nodes = env.subst('$EXPAND_TO_NODELIST',
5855 conv=lambda x: x)
5856 Tag(node, tags)
5858 Annotates file or directory Nodes with information about how the
5859 Package Builder should package those files or directories. All tags
5860 are optional.
5861 Examples:
5863 # makes sure the built library will be installed with 0644 file
5865 # access mode
5866 Tag( Library( 'lib.c' ), UNIX_ATTR="0644" )
5867 # marks file2.txt to be a documentation file
5869 Tag( 'file2.txt', DOC )
5870 TargetSignatures(type), env.TargetSignatures(type)
5872 Note: Although it is not yet officially deprecated, use of this
5873 function is discouraged. See the Decider function for a more
5874 flexible and straightforward way to configure SCons'
5875 decision-making.
5876 The TargetSignatures function tells scons how to decide if a target
5878 file (a file that is built from any other files) has changed since
5879 the last time it was used to build some other target file. Legal
5880 values are "build"; "content" (or its synonym "MD5"); "timestamp";
5881 or "source".
5882 If the environment method is used, the specified type of target
5884 signature is only used for targets built with that environment. If
5885 the global function is used, the specified type of signature
5886 becomes the default used for all target files that don't have an
5887 explicit target signature type specified for their environments.
5888 "content" (or its synonym "MD5") means scons decides that a target
5891 file has changed if the MD5 checksum of its contents has changed
5892 since the last time it was used to rebuild some other target file.
5893 This means scons will open up MD5 sum the contents of target files
5894 after they're built, and may decide that it does not need to
5895 rebuild "downstream" target files if a file was rebuilt with
5896 exactly the same contents as the last time.
5897 "timestamp" means scons decides that a target file has changed if
5900 its timestamp (modification time) has changed since the last time
5901 it was used to rebuild some other target file. (Note that although
5902 this is similar to the behavior of Make, by default it will also
5903 rebuild if the dependency is older than the last time it was used
5904 to rebuild the target file.)
5905 "source" means scons decides that a target file has changed as
5908 specified by the corresponding SourceSignatures setting ("MD5" or
5909 "timestamp"). This means that scons will treat all input files to a
5910 target the same way, regardless of whether they are source files or
5911 have been built from other files.
5912 "build" means scons decides that a target file has changed if it
5915 has been rebuilt in this invocation or if its content or timestamp
5916 have changed as specified by the corresponding SourceSignatures
5917 setting. This "propagates" the status of a rebuilt file so that
5918 other "downstream" target files will always be rebuilt, even if the
5919 contents or the timestamp have not changed.
5920 "build" signatures are fastest because "content" (or "MD5")
5923 signatures take longer to compute, but are more accurate than
5924 "timestamp" signatures, and can prevent unnecessary "downstream"
5925 rebuilds when a target file is rebuilt to the exact same contents
5926 as the previous build. The "source" setting provides the most
5927 consistent behavior when other target files may be rebuilt from
5928 both source and target input files. The default value is "source".
5929 Because the default setting is "source", using SourceSignatures is
5931 generally preferable to TargetSignatures, so that the up-to-date
5932 decision will be consistent for all files (or all files built with
5933 a specific construction environment). Use of TargetSignatures
5934 provides specific control for how built target files affect their
5935 "downstream" dependencies.
5936 Tool(string, [toolpath, **kw]), env.Tool(string, [toolpath, **kw])
5938 The Tool form of the function returns a callable object that can be
5939 used to initialize a construction environment using the tools
5940 keyword of the Environment() method. The object may be called with
5941 a construction environment as an argument, in which case the object
5942 will add the necessary variables to the construction environment
5943 and the name of the tool will be added to the $TOOLS construction
5944 variable.
5945 Additional keyword arguments are passed to the tool's generate()
5947 method.
5948 Examples:
5950 env = Environment(tools = [ Tool('msvc') ])
5952 env = Environment()
5954 t = Tool('msvc')
5955 t(env) # adds 'msvc' to the TOOLS variable
5956 u = Tool('opengl', toolpath = ['tools'])
5957 u(env) # adds 'opengl' to the TOOLS variable
5958 The env.Tool form of the function applies the callable object for
5960 the specified tool string to the environment through which the
5961 method was called.
5962 Additional keyword arguments are passed to the tool's generate()
5964 method.
5965 env.Tool('gcc')
5967 env.Tool('opengl', toolpath = ['build/tools'])
5968 Value(value, [built_value]), env.Value(value, [built_value])
5970 Returns a Node object representing the specified Python value.
5971 Value Nodes can be used as dependencies of targets. If the result
5972 of calling str(value) changes between SCons runs, any targets
5973 depending on Value(value) will be rebuilt. (This is true even when
5974 using timestamps to decide if files are up-to-date.) When using
5975 timestamp source signatures, Value Nodes' timestamps are equal to
5976 the system time when the Node is created.
5977 The returned Value Node object has a write() method that can be
5979 used to "build" a Value Node by setting a new value. The optional
5980 built_value argument can be specified when the Value Node is
5981 created to indicate the Node should already be considered "built."
5982 There is a corresponding read() method that will return the built
5983 value of the Node.
5984 Examples:
5986 env = Environment()
5988 def create(target, source, env):
5990 # A function that will write a 'prefix=$SOURCE'
5991 # string into the file name specified as the
5992 # $TARGET.
5993 f = open(str(target[0]), 'wb')
5994 f.write('prefix=' + source[0].get_contents())
5995 # Fetch the prefix= argument, if any, from the command
5997 # line, and use /usr/local as the default.
5998 prefix = ARGUMENTS.get('prefix', '/usr/local')
5999 # Attach a .Config() builder for the above function action
6001 # to the construction environment.
6002 env['BUILDERS']['Config'] = Builder(action = create)
6003 env.Config(target = 'package-config', source = Value(prefix))
6004 def build_value(target, source, env):
6006 # A function that "builds" a Python Value by updating
6007 # the the Python value with the contents of the file
6008 # specified as the source of the Builder call ($SOURCE).
6009 target[0].write(source[0].get_contents())
6010 output = env.Value('before')
6012 input = env.Value('after')
6013 # Attach a .UpdateValue() builder for the above function
6015 # action to the construction environment.
6016 env['BUILDERS']['UpdateValue'] = Builder(action = build_value)
6017 env.UpdateValue(target = Value(output), source = Value(input))
6018 VariantDir(variant_dir, src_dir, [duplicate]),
6020 env.VariantDir(variant_dir, src_dir, [duplicate])
6021 Use the VariantDir function to create a copy of your sources in
6022 another location: if a name under variant_dir is not found but
6023 exists under src_dir, the file or directory is copied to
6024 variant_dir. Target files can be built in a different directory
6025 than the original sources by simply refering to the sources (and
6026 targets) within the variant tree.
6027 VariantDir can be called multiple times with the same src_dir to
6030 set up multiple builds with different options (variants). The
6031 src_dir location must be in or underneath the SConstruct file's
6032 directory, and variant_dir may not be underneath src_dir.
6033 The default behavior is for scons to physically duplicate the
6035 source files in the variant tree. Thus, a build performed in the
6036 variant tree is guaranteed to be identical to a build performed in
6037 the source tree even if intermediate source files are generated
6038 during the build, or preprocessors or other scanners search for
6039 included files relative to the source file, or individual compilers
6040 or other invoked tools are hard-coded to put derived files in the
6041 same directory as source files.
6042 If possible on the platform, the duplication is performed by
6044 linking rather than copying; see also the --duplicate command-line
6045 option. Moreover, only the files needed for the build are
6046 duplicated; files and directories that are not used are not present
6047 in variant_dir.
6048 Duplicating the source tree may be disabled by setting the
6050 duplicate argument to 0 (zero). This will cause scons to invoke
6051 Builders using the path names of source files in src_dir and the
6052 path names of derived files within variant_dir. This is always more
6053 efficient than duplicate=1, and is usually safe for most builds
6054 (but see above for cases that may cause problems).
6055 Note that VariantDir works most naturally with a subsidiary
6057 SConscript file. However, you would then call the subsidiary
6058 SConscript file not in the source directory, but in the
6059 variant_dir, regardless of the value of duplicate. This is how you
6060 tell scons which variant of a source tree to build:
6061 # run src/SConscript in two variant directories
6063 VariantDir('build/variant1', 'src')
6064 SConscript('build/variant1/SConscript')
6065 VariantDir('build/variant2', 'src')
6066 SConscript('build/variant2/SConscript')
6067 See also the SConscript function, described above, for another way
6069 to specify a variant directory in conjunction with calling a
6070 subsidiary SConscript file.
6071 Examples:
6073 # use names in the build directory, not the source directory
6075 VariantDir('build', 'src', duplicate=0)
6076 Program('build/prog', 'build/source.c')
6077 # this builds both the source and docs in a separate subtree
6079 VariantDir('build', '.', duplicate=0)
6080 SConscript(dirs=['build/src','build/doc'])
6081 # same as previous example, but only uses SConscript
6083 SConscript(dirs='src', variant_dir='build/src', duplicate=0)
6084 SConscript(dirs='doc', variant_dir='build/doc', duplicate=0)
6085 WhereIs(program, [path, pathext, reject]), env.WhereIs(program, [path,
6087 pathext, reject])
6088 Searches for the specified executable program, returning the full
6089 path name to the program if it is found, and returning None if not.
6090 Searches the specified path, the value of the calling environment's
6091 PATH (env['ENV']['PATH']), or the user's current external PATH
6092 (os.environ['PATH']) by default. On Windows systems, searches for
6093 executable programs with any of the file extensions listed in the
6094 specified pathext, the calling environment's PATHEXT
6095 (env['ENV']['PATHEXT']) or the user's current PATHEXT
6096 (os.environ['PATHEXT']) by default. Will not select any path name
6097 or names in the specified reject list, if any.
6098 SConscript Variables
6100 In addition to the global functions and methods, scons supports a
6101 number of Python variables that can be used in SConscript files to
6102 affect how you want the build to be performed. These variables may be
6103 accessed from custom Python modules that you import into an SConscript
6104 file by adding the following to the Python module:
6105 from SCons.Script import *
6107 ARGLIST
6109 A list keyword=value arguments specified on the command line. Each
6110 element in the list is a tuple containing the (keyword,value) of
6111 the argument. The separate keyword and value elements of the tuple
6112 can be accessed by subscripting for element [0] and [1] of the
6113 tuple, respectively.
6114 Example:
6116 print("first keyword, value =", ARGLIST[0][0], ARGLIST[0][1])
6118 print("second keyword, value =", ARGLIST[1][0], ARGLIST[1][1])
6119 third_tuple = ARGLIST[2]
6120 print("third keyword, value =", third_tuple[0], third_tuple[1])
6121 for key, value in ARGLIST:
6122 # process key and value
6123 ARGUMENTS
6125 A dictionary of all the keyword=value arguments specified on the
6126 command line. The dictionary is not in order, and if a given
6127 keyword has more than one value assigned to it on the command line,
6128 the last (right-most) value is the one in the ARGUMENTS dictionary.
6129 Example:
6131 if ARGUMENTS.get('debug', 0):
6133 env = Environment(CCFLAGS = '-g')
6134 else:
6135 env = Environment()
6136 BUILD_TARGETS
6138 A list of the targets which scons will actually try to build,
6139 regardless of whether they were specified on the command line or
6140 via the Default() function or method. The elements of this list may
6141 be strings or nodes, so you should run the list through the Python
6142 str function to make sure any Node path names are converted to
6143 strings.
6144 Because this list may be taken from the list of targets specified
6146 using the Default() function or method, the contents of the list
6147 may change on each successive call to Default(). See the
6148 DEFAULT_TARGETS list, below, for additional information.
6149 Example:
6151 if 'foo' in BUILD_TARGETS:
6153 print("Don't forget to test the `foo' program!")
6154 if 'special/program' in BUILD_TARGETS:
6155 SConscript('special')
6156 Note that the BUILD_TARGETS list only contains targets expected listed
6158 on the command line or via calls to the Default() function or method.
6159 It does not contain all dependent targets that will be built as a
6160 result of making the sure the explicitly-specified targets are up to
6161 date.
6162 COMMAND_LINE_TARGETS
6164 A list of the targets explicitly specified on the command line. If
6165 there are no targets specified on the command line, the list is
6166 empty. This can be used, for example, to take specific actions only
6167 when a certain target or targets is explicitly being built.
6168 Example:
6170 if 'foo' in COMMAND_LINE_TARGETS:
6172 print("Don't forget to test the `foo' program!")
6173 if 'special/program' in COMMAND_LINE_TARGETS:
6174 SConscript('special')
6175 DEFAULT_TARGETS
6177 A list of the target nodes that have been specified using the
6178 Default() function or method. The elements of the list are nodes,
6179 so you need to run them through the Python str function to get at
6180 the path name for each Node.
6181 Example:
6183 print(str(DEFAULT_TARGETS[0]))
6185 if 'foo' in map(str, DEFAULT_TARGETS):
6186 print("Don't forget to test the `foo' program!")
6187 The contents of the DEFAULT_TARGETS list change on on each successive
6189 call to the Default() function:
6190 print(map(str, DEFAULT_TARGETS)) # originally []
6192 Default('foo')
6193 print(map(str, DEFAULT_TARGETS)) # now a node ['foo']
6194 Default('bar')
6195 print(map(str, DEFAULT_TARGETS)) # now a node ['foo', 'bar']
6196 Default(None)
6197 print(map(str, DEFAULT_TARGETS)) # back to []
6198 Consequently, be sure to use DEFAULT_TARGETS only after you've made all
6200 of your Default() calls, or else simply be careful of the order of
6201 these statements in your SConscript files so that you don't look for a
6202 specific default target before it's actually been added to the list.
6203 Construction Variables
6205 A construction environment has an associated dictionary of construction
6206 variables that are used by built-in or user-supplied build rules.
6207 Construction variables must follow the same rules for Python
6208 identifiers: the initial character must be an underscore or letter,
6209 followed by any number of underscores, letters, or digits.
6210 A number of useful construction variables are automatically defined by
6212 scons for each supported platform, and additional construction
6213 variables can be defined by the user. The following is a list of the
6214 automatically defined construction variables:
6215 __LDMODULEVERSIONFLAGS
6217 This construction variable automatically introduces
6218 $_LDMODULEVERSIONFLAGS if $LDMODULEVERSION is set. Othervise it
6219 evaluates to an empty string.
6220 __SHLIBVERSIONFLAGS
6222 This construction variable automatically introduces
6223 $_SHLIBVERSIONFLAGS if $SHLIBVERSION is set. Othervise it evaluates
6224 to an empty string.
6225 AR
6227 The static library archiver.
6228 ARCHITECTURE
6230 Specifies the system architecture for which the package is being
6231 built. The default is the system architecture of the machine on
6232 which SCons is running. This is used to fill in the Architecture:
6233 field in an Ipkg control file, and as part of the name of a
6234 generated RPM file.
6235 ARCOM
6237 The command line used to generate a static library from object
6238 files.
6239 ARCOMSTR
6241 The string displayed when an object file is generated from an
6242 assembly-language source file. If this is not set, then $ARCOM (the
6243 command line) is displayed.
6244 env = Environment(ARCOMSTR = "Archiving $TARGET")
6246 ARFLAGS
6248 General options passed to the static library archiver.
6249 AS
6251 The assembler.
6252 ASCOM
6254 The command line used to generate an object file from an
6255 assembly-language source file.
6256 ASCOMSTR
6258 The string displayed when an object file is generated from an
6259 assembly-language source file. If this is not set, then $ASCOM (the
6260 command line) is displayed.
6261 env = Environment(ASCOMSTR = "Assembling $TARGET")
6263 ASFLAGS
6265 General options passed to the assembler.
6266 ASPPCOM
6268 The command line used to assemble an assembly-language source file
6269 into an object file after first running the file through the C
6270 preprocessor. Any options specified in the $ASFLAGS and $CPPFLAGS
6271 construction variables are included on this command line.
6272 ASPPCOMSTR
6274 The string displayed when an object file is generated from an
6275 assembly-language source file after first running the file through
6276 the C preprocessor. If this is not set, then $ASPPCOM (the command
6277 line) is displayed.
6278 env = Environment(ASPPCOMSTR = "Assembling $TARGET")
6280 ASPPFLAGS
6282 General options when an assembling an assembly-language source file
6283 into an object file after first running the file through the C
6284 preprocessor. The default is to use the value of $ASFLAGS.
6285 BIBTEX
6287 The bibliography generator for the TeX formatter and typesetter and
6288 the LaTeX structured formatter and typesetter.
6289 BIBTEXCOM
6291 The command line used to call the bibliography generator for the
6292 TeX formatter and typesetter and the LaTeX structured formatter and
6293 typesetter.
6294 BIBTEXCOMSTR
6296 The string displayed when generating a bibliography for TeX or
6297 LaTeX. If this is not set, then $BIBTEXCOM (the command line) is
6298 displayed.
6299 env = Environment(BIBTEXCOMSTR = "Generating bibliography $TARGET")
6301 BIBTEXFLAGS
6303 General options passed to the bibliography generator for the TeX
6304 formatter and typesetter and the LaTeX structured formatter and
6305 typesetter.
6306 BUILDERS
6308 A dictionary mapping the names of the builders available through
6309 this environment to underlying Builder objects. Builders named
6310 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and
6311 Program are available by default. If you initialize this variable
6312 when an Environment is created:
6313 env = Environment(BUILDERS = {'NewBuilder' : foo})
6315 the default Builders will no longer be available. To use a new
6317 Builder object in addition to the default Builders, add your new
6318 Builder object like this:
6319 env = Environment()
6321 env.Append(BUILDERS = {'NewBuilder' : foo})
6322 or this:
6324 env = Environment()
6326 env['BUILDERS]['NewBuilder'] = foo
6327 CC
6329 The C compiler.
6330 CCCOM
6332 The command line used to compile a C source file to a (static)
6333 object file. Any options specified in the $CFLAGS, $CCFLAGS and
6334 $CPPFLAGS construction variables are included on this command line.
6335 CCCOMSTR
6337 The string displayed when a C source file is compiled to a (static)
6338 object file. If this is not set, then $CCCOM (the command line) is
6339 displayed.
6340 env = Environment(CCCOMSTR = "Compiling static object $TARGET")
6342 CCFLAGS
6344 General options that are passed to the C and C++ compilers.
6345 CCPCHFLAGS
6347 Options added to the compiler command line to support building with
6348 precompiled headers. The default value expands expands to the
6349 appropriate Microsoft Visual C++ command-line options when the $PCH
6350 construction variable is set.
6351 CCPDBFLAGS
6353 Options added to the compiler command line to support storing
6354 debugging information in a Microsoft Visual C++ PDB file. The
6355 default value expands expands to appropriate Microsoft Visual C++
6356 command-line options when the $PDB construction variable is set.
6357 The Visual C++ compiler option that SCons uses by default to
6359 generate PDB information is /Z7. This works correctly with parallel
6360 (-j) builds because it embeds the debug information in the
6361 intermediate object files, as opposed to sharing a single PDB file
6362 between multiple object files. This is also the only way to get
6363 debug information embedded into a static library. Using the /Zi
6364 instead may yield improved link-time performance, although parallel
6365 builds will no longer work.
6366 You can generate PDB files with the /Zi switch by overriding the
6368 default $CCPDBFLAGS variable as follows:
6369 env['CCPDBFLAGS'] = ['${(PDB and "/Zi /Fd%s" % File(PDB)) or ""}']
6371 An alternative would be to use the /Zi to put the debugging
6373 information in a separate .pdb file for each object file by
6374 overriding the $CCPDBFLAGS variable as follows:
6375 env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb'
6377 CCVERSION
6379 The version number of the C compiler. This may or may not be set,
6380 depending on the specific C compiler being used.
6381 CFILESUFFIX
6383 The suffix for C source files. This is used by the internal CFile
6384 builder when generating C files from Lex (.l) or YACC (.y) input
6385 files. The default suffix, of course, is .c (lower case). On
6386 case-insensitive systems (like Windows), SCons also treats .C
6387 (upper case) files as C files.
6388 CFLAGS
6390 General options that are passed to the C compiler (C only; not
6391 C++).
6392 CHANGE_SPECFILE
6394 A hook for modifying the file that controls the packaging build
6395 (the .spec for RPM, the control for Ipkg, the .wxs for MSI). If
6396 set, the function will be called after the SCons template for the
6397 file has been written. XXX
6398 CHANGED_SOURCES
6400 A reserved variable name that may not be set or used in a
6401 construction environment. (See "Variable Substitution," below.)
6402 CHANGED_TARGETS
6404 A reserved variable name that may not be set or used in a
6405 construction environment. (See "Variable Substitution," below.)
6406 CHANGELOG
6408 The name of a file containing the change log text to be included in
6409 the package. This is included as the %changelog section of the RPM
6410 .spec file.
6411 _concat
6413 A function used to produce variables like $_CPPINCFLAGS. It takes
6414 four or five arguments: a prefix to concatenate onto each element,
6415 a list of elements, a suffix to concatenate onto each element, an
6416 environment for variable interpolation, and an optional function
6417 that will be called to transform the list before concatenation.
6418 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
6420 CONFIGUREDIR
6422 The name of the directory in which Configure context test files are
6423 written. The default is .sconf_temp in the top-level directory
6424 containing the SConstruct file.
6425 CONFIGURELOG
6427 The name of the Configure context log file. The default is
6428 config.log in the top-level directory containing the SConstruct
6429 file.
6430 _CPPDEFFLAGS
6432 An automatically-generated construction variable containing the C
6433 preprocessor command-line options to define values. The value of
6434 $_CPPDEFFLAGS is created by appending $CPPDEFPREFIX and
6435 $CPPDEFSUFFIX to the beginning and end of each definition in
6436 $CPPDEFINES.
6437 CPPDEFINES
6439 A platform independent specification of C preprocessor definitions.
6440 The definitions will be added to command lines through the
6441 automatically-generated $_CPPDEFFLAGS construction variable (see
6442 above), which is constructed according to the type of value of
6443 $CPPDEFINES:
6444 If $CPPDEFINES is a string, the values of the $CPPDEFPREFIX and
6446 $CPPDEFSUFFIX construction variables will be added to the beginning
6447 and end.
6448 # Will add -Dxyz to POSIX compiler command lines,
6450 # and /Dxyz to Microsoft Visual C++ command lines.
6451 env = Environment(CPPDEFINES='xyz')
6452 If $CPPDEFINES is a list, the values of the $CPPDEFPREFIX and
6454 $CPPDEFSUFFIX construction variables will be appended to the
6455 beginning and end of each element in the list. If any element is a
6456 list or tuple, then the first item is the name being defined and
6457 the second item is its value:
6458 # Will add -DB=2 -DA to POSIX compiler command lines,
6460 # and /DB=2 /DA to Microsoft Visual C++ command lines.
6461 env = Environment(CPPDEFINES=[('B', 2), 'A'])
6462 If $CPPDEFINES is a dictionary, the values of the $CPPDEFPREFIX and
6464 $CPPDEFSUFFIX construction variables will be appended to the
6465 beginning and end of each item from the dictionary. The key of each
6466 dictionary item is a name being defined to the dictionary item's
6467 corresponding value; if the value is None, then the name is defined
6468 without an explicit value. Note that the resulting flags are sorted
6469 by keyword to ensure that the order of the options on the command
6470 line is consistent each time scons is run.
6471 # Will add -DA -DB=2 to POSIX compiler command lines,
6473 # and /DA /DB=2 to Microsoft Visual C++ command lines.
6474 env = Environment(CPPDEFINES={'B':2, 'A':None})
6475 CPPDEFPREFIX
6477 The prefix used to specify preprocessor definitions on the C
6478 compiler command line. This will be appended to the beginning of
6479 each definition in the $CPPDEFINES construction variable when the
6480 $_CPPDEFFLAGS variable is automatically generated.
6481 CPPDEFSUFFIX
6483 The suffix used to specify preprocessor definitions on the C
6484 compiler command line. This will be appended to the end of each
6485 definition in the $CPPDEFINES construction variable when the
6486 $_CPPDEFFLAGS variable is automatically generated.
6487 CPPFLAGS
6489 User-specified C preprocessor options. These will be included in
6490 any command that uses the C preprocessor, including not just
6491 compilation of C and C++ source files via the $CCCOM, $SHCCCOM,
6492 $CXXCOM and $SHCXXCOM command lines, but also the $FORTRANPPCOM,
6493 $SHFORTRANPPCOM, $F77PPCOM and $SHF77PPCOM command lines used to
6494 compile a Fortran source file, and the $ASPPCOM command line used
6495 to assemble an assembly language source file, after first running
6496 each file through the C preprocessor. Note that this variable does
6497 not contain -I (or similar) include search path options that scons
6498 generates automatically from $CPPPATH. See $_CPPINCFLAGS, below,
6499 for the variable that expands to those options.
6500 _CPPINCFLAGS
6502 An automatically-generated construction variable containing the C
6503 preprocessor command-line options for specifying directories to be
6504 searched for include files. The value of $_CPPINCFLAGS is created
6505 by appending $INCPREFIX and $INCSUFFIX to the beginning and end of
6506 each directory in $CPPPATH.
6507 CPPPATH
6509 The list of directories that the C preprocessor will search for
6510 include directories. The C/C++ implicit dependency scanner will
6511 search these directories for include files. Don't explicitly put
6512 include directory arguments in CCFLAGS or CXXFLAGS because the
6513 result will be non-portable and the directories will not be
6514 searched by the dependency scanner. Note: directory names in
6515 CPPPATH will be looked-up relative to the SConscript directory when
6516 they are used in a command. To force scons to look-up a directory
6517 relative to the root of the source tree use #:
6518 env = Environment(CPPPATH='#/include')
6520 The directory look-up can also be forced using the Dir() function:
6522 include = Dir('include')
6524 env = Environment(CPPPATH=include)
6525 The directory list will be added to command lines through the
6527 automatically-generated $_CPPINCFLAGS construction variable, which
6528 is constructed by appending the values of the $INCPREFIX and
6529 $INCSUFFIX construction variables to the beginning and end of each
6530 directory in $CPPPATH. Any command lines you define that need the
6531 CPPPATH directory list should include $_CPPINCFLAGS:
6532 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
6534 CPPSUFFIXES
6536 The list of suffixes of files that will be scanned for C
6537 preprocessor implicit dependencies (#include lines). The default
6538 list is:
6539 [".c", ".C", ".cxx", ".cpp", ".c++", ".cc",
6541 ".h", ".H", ".hxx", ".hpp", ".hh",
6542 ".F", ".fpp", ".FPP",
6543 ".m", ".mm",
6544 ".S", ".spp", ".SPP"]
6545 CXX
6547 The C++ compiler.
6548 CXXCOM
6550 The command line used to compile a C++ source file to an object
6551 file. Any options specified in the $CXXFLAGS and $CPPFLAGS
6552 construction variables are included on this command line.
6553 CXXCOMSTR
6555 The string displayed when a C++ source file is compiled to a
6556 (static) object file. If this is not set, then $CXXCOM (the command
6557 line) is displayed.
6558 env = Environment(CXXCOMSTR = "Compiling static object $TARGET")
6560 CXXFILESUFFIX
6562 The suffix for C++ source files. This is used by the internal
6563 CXXFile builder when generating C++ files from Lex (.ll) or YACC
6564 (.yy) input files. The default suffix is .cc. SCons also treats
6565 files with the suffixes .cpp, .cxx, .c++, and .C++ as C++ files,
6566 and files with .mm suffixes as Objective C++ files. On
6567 case-sensitive systems (Linux, UNIX, and other POSIX-alikes), SCons
6568 also treats .C (upper case) files as C++ files.
6569 CXXFLAGS
6571 General options that are passed to the C++ compiler. By default,
6572 this includes the value of $CCFLAGS, so that setting $CCFLAGS
6573 affects both C and C++ compilation. If you want to add C++-specific
6574 flags, you must set or override the value of $CXXFLAGS.
6575 CXXVERSION
6577 The version number of the C++ compiler. This may or may not be set,
6578 depending on the specific C++ compiler being used.
6579 DC
6581 The D compiler to use.
6582 The D compiler to use.
6584 The D compiler to use.
6586 DCOM
6588 The command line used to compile a D file to an object file. Any
6589 options specified in the $DFLAGS construction variable is included
6590 on this command line.
6591 The command line used to compile a D file to an object file. Any
6593 options specified in the $DFLAGS construction variable is included
6594 on this command line.
6595 The command line used to compile a D file to an object file. Any
6597 options specified in the $DFLAGS construction variable is included
6598 on this command line.
6599 DDEBUG
6601 List of debug tags to enable when compiling.
6602 List of debug tags to enable when compiling.
6604 List of debug tags to enable when compiling.
6606 DDEBUGPREFIX
6608 DDEBUGPREFIX.
6609 DDEBUGPREFIX.
6611 DDEBUGPREFIX.
6613 DDEBUGSUFFIX
6615 DDEBUGSUFFIX.
6616 DDEBUGSUFFIX.
6618 DDEBUGSUFFIX.
6620 DESCRIPTION
6622 A long description of the project being packaged. This is included
6623 in the relevant section of the file that controls the packaging
6624 build.
6625 DESCRIPTION_lang
6627 A language-specific long description for the specified lang. This
6628 is used to populate a %description -l section of an RPM .spec file.
6629 DFILESUFFIX
6631 DFILESUFFIX.
6632 DFILESUFFIX.
6634 DFILESUFFIX.
6636 DFLAGPREFIX
6638 DFLAGPREFIX.
6639 DFLAGPREFIX.
6641 DFLAGPREFIX.
6643 DFLAGS
6645 General options that are passed to the D compiler.
6646 General options that are passed to the D compiler.
6648 General options that are passed to the D compiler.
6650 DFLAGSUFFIX
6652 DFLAGSUFFIX.
6653 DFLAGSUFFIX.
6655 DFLAGSUFFIX.
6657 DINCPREFIX
6659 DINCPREFIX.
6660 DINCPREFIX.
6662 DINCPREFIX.
6664 DINCSUFFIX
6666 DLIBFLAGSUFFIX.
6667 DLIBFLAGSUFFIX.
6669 DLIBFLAGSUFFIX.
6671 Dir
6673 A function that converts a string into a Dir instance relative to
6674 the target being built.
6675 A function that converts a string into a Dir instance relative to
6677 the target being built.
6678 Dirs
6680 A function that converts a list of strings into a list of Dir
6681 instances relative to the target being built.
6682 DLIB
6684 Name of the lib tool to use for D codes.
6685 Name of the lib tool to use for D codes.
6687 Name of the lib tool to use for D codes.
6689 DLIBCOM
6691 The command line to use when creating libraries.
6692 The command line to use when creating libraries.
6694 The command line to use when creating libraries.
6696 DLIBDIRPREFIX
6698 DLIBLINKPREFIX.
6699 DLIBLINKPREFIX.
6701 DLIBLINKPREFIX.
6703 DLIBDIRSUFFIX
6705 DLIBLINKSUFFIX.
6706 DLIBLINKSUFFIX.
6708 DLIBLINKSUFFIX.
6710 DLIBFLAGPREFIX
6712 DLIBFLAGPREFIX.
6713 DLIBFLAGPREFIX.
6715 DLIBFLAGPREFIX.
6717 DLIBFLAGSUFFIX
6719 DLIBFLAGSUFFIX.
6720 DLIBFLAGSUFFIX.
6722 DLIBFLAGSUFFIX.
6724 DLIBLINKPREFIX
6726 DLIBLINKPREFIX.
6727 DLIBLINKPREFIX.
6729 DLIBLINKPREFIX.
6731 DLIBLINKSUFFIX
6733 DLIBLINKSUFFIX.
6734 DLIBLINKSUFFIX.
6736 DLIBLINKSUFFIX.
6738 DLINK
6740 Name of the linker to use for linking systems including D sources.
6741 Name of the linker to use for linking systems including D sources.
6743 Name of the linker to use for linking systems including D sources.
6745 DLINKCOM
6747 The command line to use when linking systems including D sources.
6748 The command line to use when linking systems including D sources.
6750 The command line to use when linking systems including D sources.
6752 DLINKFLAGPREFIX
6754 DLINKFLAGPREFIX.
6755 DLINKFLAGPREFIX.
6757 DLINKFLAGPREFIX.
6759 DLINKFLAGS
6761 List of linker flags.
6762 List of linker flags.
6764 List of linker flags.
6766 DLINKFLAGSUFFIX
6768 DLINKFLAGSUFFIX.
6769 DLINKFLAGSUFFIX.
6771 DLINKFLAGSUFFIX.
6773 DOCBOOK_DEFAULT_XSL_EPUB
6775 The default XSLT file for the DocbookEpub builder within the
6776 current environment, if no other XSLT gets specified via keyword.
6777 DOCBOOK_DEFAULT_XSL_HTML
6779 The default XSLT file for the DocbookHtml builder within the
6780 current environment, if no other XSLT gets specified via keyword.
6781 DOCBOOK_DEFAULT_XSL_HTMLCHUNKED
6783 The default XSLT file for the DocbookHtmlChunked builder within the
6784 current environment, if no other XSLT gets specified via keyword.
6785 DOCBOOK_DEFAULT_XSL_HTMLHELP
6787 The default XSLT file for the DocbookHtmlhelp builder within the
6788 current environment, if no other XSLT gets specified via keyword.
6789 DOCBOOK_DEFAULT_XSL_MAN
6791 The default XSLT file for the DocbookMan builder within the current
6792 environment, if no other XSLT gets specified via keyword.
6793 DOCBOOK_DEFAULT_XSL_PDF
6795 The default XSLT file for the DocbookPdf builder within the current
6796 environment, if no other XSLT gets specified via keyword.
6797 DOCBOOK_DEFAULT_XSL_SLIDESHTML
6799 The default XSLT file for the DocbookSlidesHtml builder within the
6800 current environment, if no other XSLT gets specified via keyword.
6801 DOCBOOK_DEFAULT_XSL_SLIDESPDF
6803 The default XSLT file for the DocbookSlidesPdf builder within the
6804 current environment, if no other XSLT gets specified via keyword.
6805 DOCBOOK_FOP
6807 The path to the PDF renderer fop or xep, if one of them is
6808 installed (fop gets checked first).
6809 DOCBOOK_FOPCOM
6811 The full command-line for the PDF renderer fop or xep.
6812 DOCBOOK_FOPCOMSTR
6814 The string displayed when a renderer like fop or xep is used to
6815 create PDF output from an XML file.
6816 DOCBOOK_FOPFLAGS
6818 Additonal command-line flags for the PDF renderer fop or xep.
6819 DOCBOOK_XMLLINT
6821 The path to the external executable xmllint, if it's installed.
6822 Note, that this is only used as last fallback for resolving
6823 XIncludes, if no libxml2 or lxml Python binding can be imported in
6824 the current system.
6825 DOCBOOK_XMLLINTCOM
6827 The full command-line for the external executable xmllint.
6828 DOCBOOK_XMLLINTCOMSTR
6830 The string displayed when xmllint is used to resolve XIncludes for
6831 a given XML file.
6832 DOCBOOK_XMLLINTFLAGS
6834 Additonal command-line flags for the external executable xmllint.
6835 DOCBOOK_XSLTPROC
6837 The path to the external executable xsltproc (or saxon, xalan), if
6838 one of them is installed. Note, that this is only used as last
6839 fallback for XSL transformations, if no libxml2 or lxml Python
6840 binding can be imported in the current system.
6841 DOCBOOK_XSLTPROCCOM
6843 The full command-line for the external executable xsltproc (or
6844 saxon, xalan).
6845 DOCBOOK_XSLTPROCCOMSTR
6847 The string displayed when xsltproc is used to transform an XML file
6848 via a given XSLT stylesheet.
6849 DOCBOOK_XSLTPROCFLAGS
6851 Additonal command-line flags for the external executable xsltproc
6852 (or saxon, xalan).
6853 DOCBOOK_XSLTPROCPARAMS
6855 Additonal parameters that are not intended for the XSLT processor
6856 executable, but the XSL processing itself. By default, they get
6857 appended at the end of the command line for saxon and saxon-xslt,
6858 respectively.
6859 DPATH
6861 List of paths to search for import modules.
6862 List of paths to search for import modules.
6864 List of paths to search for import modules.
6866 DRPATHPREFIX
6868 DRPATHPREFIX.
6869 DRPATHSUFFIX
6871 DRPATHSUFFIX.
6872 DShLibSonameGenerator
6874 DShLibSonameGenerator.
6875 DSUFFIXES
6877 The list of suffixes of files that will be scanned for imported D
6878 package files. The default list is:
6879 ['.d']
6881 DVERPREFIX
6883 DVERPREFIX.
6884 DVERPREFIX.
6886 DVERPREFIX.
6888 DVERSIONS
6890 List of version tags to enable when compiling.
6891 List of version tags to enable when compiling.
6893 List of version tags to enable when compiling.
6895 DVERSUFFIX
6897 DVERSUFFIX.
6898 DVERSUFFIX.
6900 DVERSUFFIX.
6902 DVIPDF
6904 The TeX DVI file to PDF file converter.
6905 DVIPDFCOM
6907 The command line used to convert TeX DVI files into a PDF file.
6908 DVIPDFCOMSTR
6910 The string displayed when a TeX DVI file is converted into a PDF
6911 file. If this is not set, then $DVIPDFCOM (the command line) is
6912 displayed.
6913 DVIPDFFLAGS
6915 General options passed to the TeX DVI file to PDF file converter.
6916 DVIPS
6918 The TeX DVI file to PostScript converter.
6919 DVIPSFLAGS
6921 General options passed to the TeX DVI file to PostScript converter.
6922 ENV
6924 A dictionary of environment variables to use when invoking
6925 commands. When $ENV is used in a command all list values will be
6926 joined using the path separator and any other non-string values
6927 will simply be coerced to a string. Note that, by default, scons
6928 does not propagate the environment in force when you execute scons
6929 to the commands used to build target files. This is so that builds
6930 will be guaranteed repeatable regardless of the environment
6931 variables set at the time scons is invoked.
6932 If you want to propagate your environment variables to the commands
6934 executed to build target files, you must do so explicitly:
6935 import os
6937 env = Environment(ENV = os.environ)
6938 Note that you can choose only to propagate certain environment
6940 variables. A common example is the system PATH environment
6941 variable, so that scons uses the same utilities as the invoking
6942 shell (or other process):
6943 import os
6945 env = Environment(ENV = {'PATH' : os.environ['PATH']})
6946 ESCAPE
6948 A function that will be called to escape shell special characters
6949 in command lines. The function should take one argument: the
6950 command line string to escape; and should return the escaped
6951 command line.
6952 F03
6954 The Fortran 03 compiler. You should normally set the $FORTRAN
6955 variable, which specifies the default Fortran compiler for all
6956 Fortran versions. You only need to set $F03 if you need to use a
6957 specific compiler or compiler version for Fortran 03 files.
6958 F03COM
6960 The command line used to compile a Fortran 03 source file to an
6961 object file. You only need to set $F03COM if you need to use a
6962 specific command line for Fortran 03 files. You should normally set
6963 the $FORTRANCOM variable, which specifies the default command line
6964 for all Fortran versions.
6965 F03COMSTR
6967 The string displayed when a Fortran 03 source file is compiled to
6968 an object file. If this is not set, then $F03COM or $FORTRANCOM
6969 (the command line) is displayed.
6970 F03FILESUFFIXES
6972 The list of file extensions for which the F03 dialect will be used.
6973 By default, this is ['.f03']
6974 F03FLAGS
6976 General user-specified options that are passed to the Fortran 03
6977 compiler. Note that this variable does not contain -I (or similar)
6978 include search path options that scons generates automatically from
6979 $F03PATH. See $_F03INCFLAGS below, for the variable that expands to
6980 those options. You only need to set $F03FLAGS if you need to define
6981 specific user options for Fortran 03 files. You should normally set
6982 the $FORTRANFLAGS variable, which specifies the user-specified
6983 options passed to the default Fortran compiler for all Fortran
6984 versions.
6985 _F03INCFLAGS
6987 An automatically-generated construction variable containing the
6988 Fortran 03 compiler command-line options for specifying directories
6989 to be searched for include files. The value of $_F03INCFLAGS is
6990 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
6991 end of each directory in $F03PATH.
6992 F03PATH
6994 The list of directories that the Fortran 03 compiler will search
6995 for include directories. The implicit dependency scanner will
6996 search these directories for include files. Don't explicitly put
6997 include directory arguments in $F03FLAGS because the result will be
6998 non-portable and the directories will not be searched by the
6999 dependency scanner. Note: directory names in $F03PATH will be
7000 looked-up relative to the SConscript directory when they are used
7001 in a command. To force scons to look-up a directory relative to the
7002 root of the source tree use #: You only need to set $F03PATH if you
7003 need to define a specific include path for Fortran 03 files. You
7004 should normally set the $FORTRANPATH variable, which specifies the
7005 include path for the default Fortran compiler for all Fortran
7006 versions.
7007 env = Environment(F03PATH='#/include')
7009 The directory look-up can also be forced using the Dir() function:
7011 include = Dir('include')
7013 env = Environment(F03PATH=include)
7014 The directory list will be added to command lines through the
7016 automatically-generated $_F03INCFLAGS construction variable, which
7017 is constructed by appending the values of the $INCPREFIX and
7018 $INCSUFFIX construction variables to the beginning and end of each
7019 directory in $F03PATH. Any command lines you define that need the
7020 F03PATH directory list should include $_F03INCFLAGS:
7021 env = Environment(F03COM="my_compiler $_F03INCFLAGS -c -o $TARGET $SOURCE")
7023 F03PPCOM
7025 The command line used to compile a Fortran 03 source file to an
7026 object file after first running the file through the C
7027 preprocessor. Any options specified in the $F03FLAGS and $CPPFLAGS
7028 construction variables are included on this command line. You only
7029 need to set $F03PPCOM if you need to use a specific C-preprocessor
7030 command line for Fortran 03 files. You should normally set the
7031 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7032 command line for all Fortran versions.
7033 F03PPCOMSTR
7035 The string displayed when a Fortran 03 source file is compiled to
7036 an object file after first running the file through the C
7037 preprocessor. If this is not set, then $F03PPCOM or $FORTRANPPCOM
7038 (the command line) is displayed.
7039 F03PPFILESUFFIXES
7041 The list of file extensions for which the compilation +
7042 preprocessor pass for F03 dialect will be used. By default, this is
7043 empty
7044 F08
7046 The Fortran 08 compiler. You should normally set the $FORTRAN
7047 variable, which specifies the default Fortran compiler for all
7048 Fortran versions. You only need to set $F08 if you need to use a
7049 specific compiler or compiler version for Fortran 08 files.
7050 F08COM
7052 The command line used to compile a Fortran 08 source file to an
7053 object file. You only need to set $F08COM if you need to use a
7054 specific command line for Fortran 08 files. You should normally set
7055 the $FORTRANCOM variable, which specifies the default command line
7056 for all Fortran versions.
7057 F08COMSTR
7059 The string displayed when a Fortran 08 source file is compiled to
7060 an object file. If this is not set, then $F08COM or $FORTRANCOM
7061 (the command line) is displayed.
7062 F08FILESUFFIXES
7064 The list of file extensions for which the F08 dialect will be used.
7065 By default, this is ['.f08']
7066 F08FLAGS
7068 General user-specified options that are passed to the Fortran 08
7069 compiler. Note that this variable does not contain -I (or similar)
7070 include search path options that scons generates automatically from
7071 $F08PATH. See $_F08INCFLAGS below, for the variable that expands to
7072 those options. You only need to set $F08FLAGS if you need to define
7073 specific user options for Fortran 08 files. You should normally set
7074 the $FORTRANFLAGS variable, which specifies the user-specified
7075 options passed to the default Fortran compiler for all Fortran
7076 versions.
7077 _F08INCFLAGS
7079 An automatically-generated construction variable containing the
7080 Fortran 08 compiler command-line options for specifying directories
7081 to be searched for include files. The value of $_F08INCFLAGS is
7082 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7083 end of each directory in $F08PATH.
7084 F08PATH
7086 The list of directories that the Fortran 08 compiler will search
7087 for include directories. The implicit dependency scanner will
7088 search these directories for include files. Don't explicitly put
7089 include directory arguments in $F08FLAGS because the result will be
7090 non-portable and the directories will not be searched by the
7091 dependency scanner. Note: directory names in $F08PATH will be
7092 looked-up relative to the SConscript directory when they are used
7093 in a command. To force scons to look-up a directory relative to the
7094 root of the source tree use #: You only need to set $F08PATH if you
7095 need to define a specific include path for Fortran 08 files. You
7096 should normally set the $FORTRANPATH variable, which specifies the
7097 include path for the default Fortran compiler for all Fortran
7098 versions.
7099 env = Environment(F08PATH='#/include')
7101 The directory look-up can also be forced using the Dir() function:
7103 include = Dir('include')
7105 env = Environment(F08PATH=include)
7106 The directory list will be added to command lines through the
7108 automatically-generated $_F08INCFLAGS construction variable, which
7109 is constructed by appending the values of the $INCPREFIX and
7110 $INCSUFFIX construction variables to the beginning and end of each
7111 directory in $F08PATH. Any command lines you define that need the
7112 F08PATH directory list should include $_F08INCFLAGS:
7113 env = Environment(F08COM="my_compiler $_F08INCFLAGS -c -o $TARGET $SOURCE")
7115 F08PPCOM
7117 The command line used to compile a Fortran 08 source file to an
7118 object file after first running the file through the C
7119 preprocessor. Any options specified in the $F08FLAGS and $CPPFLAGS
7120 construction variables are included on this command line. You only
7121 need to set $F08PPCOM if you need to use a specific C-preprocessor
7122 command line for Fortran 08 files. You should normally set the
7123 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7124 command line for all Fortran versions.
7125 F08PPCOMSTR
7127 The string displayed when a Fortran 08 source file is compiled to
7128 an object file after first running the file through the C
7129 preprocessor. If this is not set, then $F08PPCOM or $FORTRANPPCOM
7130 (the command line) is displayed.
7131 F08PPFILESUFFIXES
7133 The list of file extensions for which the compilation +
7134 preprocessor pass for F08 dialect will be used. By default, this is
7135 empty
7136 F77
7138 The Fortran 77 compiler. You should normally set the $FORTRAN
7139 variable, which specifies the default Fortran compiler for all
7140 Fortran versions. You only need to set $F77 if you need to use a
7141 specific compiler or compiler version for Fortran 77 files.
7142 F77COM
7144 The command line used to compile a Fortran 77 source file to an
7145 object file. You only need to set $F77COM if you need to use a
7146 specific command line for Fortran 77 files. You should normally set
7147 the $FORTRANCOM variable, which specifies the default command line
7148 for all Fortran versions.
7149 F77COMSTR
7151 The string displayed when a Fortran 77 source file is compiled to
7152 an object file. If this is not set, then $F77COM or $FORTRANCOM
7153 (the command line) is displayed.
7154 F77FILESUFFIXES
7156 The list of file extensions for which the F77 dialect will be used.
7157 By default, this is ['.f77']
7158 F77FLAGS
7160 General user-specified options that are passed to the Fortran 77
7161 compiler. Note that this variable does not contain -I (or similar)
7162 include search path options that scons generates automatically from
7163 $F77PATH. See $_F77INCFLAGS below, for the variable that expands to
7164 those options. You only need to set $F77FLAGS if you need to define
7165 specific user options for Fortran 77 files. You should normally set
7166 the $FORTRANFLAGS variable, which specifies the user-specified
7167 options passed to the default Fortran compiler for all Fortran
7168 versions.
7169 _F77INCFLAGS
7171 An automatically-generated construction variable containing the
7172 Fortran 77 compiler command-line options for specifying directories
7173 to be searched for include files. The value of $_F77INCFLAGS is
7174 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7175 end of each directory in $F77PATH.
7176 F77PATH
7178 The list of directories that the Fortran 77 compiler will search
7179 for include directories. The implicit dependency scanner will
7180 search these directories for include files. Don't explicitly put
7181 include directory arguments in $F77FLAGS because the result will be
7182 non-portable and the directories will not be searched by the
7183 dependency scanner. Note: directory names in $F77PATH will be
7184 looked-up relative to the SConscript directory when they are used
7185 in a command. To force scons to look-up a directory relative to the
7186 root of the source tree use #: You only need to set $F77PATH if you
7187 need to define a specific include path for Fortran 77 files. You
7188 should normally set the $FORTRANPATH variable, which specifies the
7189 include path for the default Fortran compiler for all Fortran
7190 versions.
7191 env = Environment(F77PATH='#/include')
7193 The directory look-up can also be forced using the Dir() function:
7195 include = Dir('include')
7197 env = Environment(F77PATH=include)
7198 The directory list will be added to command lines through the
7200 automatically-generated $_F77INCFLAGS construction variable, which
7201 is constructed by appending the values of the $INCPREFIX and
7202 $INCSUFFIX construction variables to the beginning and end of each
7203 directory in $F77PATH. Any command lines you define that need the
7204 F77PATH directory list should include $_F77INCFLAGS:
7205 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
7207 F77PPCOM
7209 The command line used to compile a Fortran 77 source file to an
7210 object file after first running the file through the C
7211 preprocessor. Any options specified in the $F77FLAGS and $CPPFLAGS
7212 construction variables are included on this command line. You only
7213 need to set $F77PPCOM if you need to use a specific C-preprocessor
7214 command line for Fortran 77 files. You should normally set the
7215 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7216 command line for all Fortran versions.
7217 F77PPCOMSTR
7219 The string displayed when a Fortran 77 source file is compiled to
7220 an object file after first running the file through the C
7221 preprocessor. If this is not set, then $F77PPCOM or $FORTRANPPCOM
7222 (the command line) is displayed.
7223 F77PPFILESUFFIXES
7225 The list of file extensions for which the compilation +
7226 preprocessor pass for F77 dialect will be used. By default, this is
7227 empty
7228 F90
7230 The Fortran 90 compiler. You should normally set the $FORTRAN
7231 variable, which specifies the default Fortran compiler for all
7232 Fortran versions. You only need to set $F90 if you need to use a
7233 specific compiler or compiler version for Fortran 90 files.
7234 F90COM
7236 The command line used to compile a Fortran 90 source file to an
7237 object file. You only need to set $F90COM if you need to use a
7238 specific command line for Fortran 90 files. You should normally set
7239 the $FORTRANCOM variable, which specifies the default command line
7240 for all Fortran versions.
7241 F90COMSTR
7243 The string displayed when a Fortran 90 source file is compiled to
7244 an object file. If this is not set, then $F90COM or $FORTRANCOM
7245 (the command line) is displayed.
7246 F90FILESUFFIXES
7248 The list of file extensions for which the F90 dialect will be used.
7249 By default, this is ['.f90']
7250 F90FLAGS
7252 General user-specified options that are passed to the Fortran 90
7253 compiler. Note that this variable does not contain -I (or similar)
7254 include search path options that scons generates automatically from
7255 $F90PATH. See $_F90INCFLAGS below, for the variable that expands to
7256 those options. You only need to set $F90FLAGS if you need to define
7257 specific user options for Fortran 90 files. You should normally set
7258 the $FORTRANFLAGS variable, which specifies the user-specified
7259 options passed to the default Fortran compiler for all Fortran
7260 versions.
7261 _F90INCFLAGS
7263 An automatically-generated construction variable containing the
7264 Fortran 90 compiler command-line options for specifying directories
7265 to be searched for include files. The value of $_F90INCFLAGS is
7266 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7267 end of each directory in $F90PATH.
7268 F90PATH
7270 The list of directories that the Fortran 90 compiler will search
7271 for include directories. The implicit dependency scanner will
7272 search these directories for include files. Don't explicitly put
7273 include directory arguments in $F90FLAGS because the result will be
7274 non-portable and the directories will not be searched by the
7275 dependency scanner. Note: directory names in $F90PATH will be
7276 looked-up relative to the SConscript directory when they are used
7277 in a command. To force scons to look-up a directory relative to the
7278 root of the source tree use #: You only need to set $F90PATH if you
7279 need to define a specific include path for Fortran 90 files. You
7280 should normally set the $FORTRANPATH variable, which specifies the
7281 include path for the default Fortran compiler for all Fortran
7282 versions.
7283 env = Environment(F90PATH='#/include')
7285 The directory look-up can also be forced using the Dir() function:
7287 include = Dir('include')
7289 env = Environment(F90PATH=include)
7290 The directory list will be added to command lines through the
7292 automatically-generated $_F90INCFLAGS construction variable, which
7293 is constructed by appending the values of the $INCPREFIX and
7294 $INCSUFFIX construction variables to the beginning and end of each
7295 directory in $F90PATH. Any command lines you define that need the
7296 F90PATH directory list should include $_F90INCFLAGS:
7297 env = Environment(F90COM="my_compiler $_F90INCFLAGS -c -o $TARGET $SOURCE")
7299 F90PPCOM
7301 The command line used to compile a Fortran 90 source file to an
7302 object file after first running the file through the C
7303 preprocessor. Any options specified in the $F90FLAGS and $CPPFLAGS
7304 construction variables are included on this command line. You only
7305 need to set $F90PPCOM if you need to use a specific C-preprocessor
7306 command line for Fortran 90 files. You should normally set the
7307 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7308 command line for all Fortran versions.
7309 F90PPCOMSTR
7311 The string displayed when a Fortran 90 source file is compiled
7312 after first running the file through the C preprocessor. If this is
7313 not set, then $F90PPCOM or $FORTRANPPCOM (the command line) is
7314 displayed.
7315 F90PPFILESUFFIXES
7317 The list of file extensions for which the compilation +
7318 preprocessor pass for F90 dialect will be used. By default, this is
7319 empty
7320 F95
7322 The Fortran 95 compiler. You should normally set the $FORTRAN
7323 variable, which specifies the default Fortran compiler for all
7324 Fortran versions. You only need to set $F95 if you need to use a
7325 specific compiler or compiler version for Fortran 95 files.
7326 F95COM
7328 The command line used to compile a Fortran 95 source file to an
7329 object file. You only need to set $F95COM if you need to use a
7330 specific command line for Fortran 95 files. You should normally set
7331 the $FORTRANCOM variable, which specifies the default command line
7332 for all Fortran versions.
7333 F95COMSTR
7335 The string displayed when a Fortran 95 source file is compiled to
7336 an object file. If this is not set, then $F95COM or $FORTRANCOM
7337 (the command line) is displayed.
7338 F95FILESUFFIXES
7340 The list of file extensions for which the F95 dialect will be used.
7341 By default, this is ['.f95']
7342 F95FLAGS
7344 General user-specified options that are passed to the Fortran 95
7345 compiler. Note that this variable does not contain -I (or similar)
7346 include search path options that scons generates automatically from
7347 $F95PATH. See $_F95INCFLAGS below, for the variable that expands to
7348 those options. You only need to set $F95FLAGS if you need to define
7349 specific user options for Fortran 95 files. You should normally set
7350 the $FORTRANFLAGS variable, which specifies the user-specified
7351 options passed to the default Fortran compiler for all Fortran
7352 versions.
7353 _F95INCFLAGS
7355 An automatically-generated construction variable containing the
7356 Fortran 95 compiler command-line options for specifying directories
7357 to be searched for include files. The value of $_F95INCFLAGS is
7358 created by appending $INCPREFIX and $INCSUFFIX to the beginning and
7359 end of each directory in $F95PATH.
7360 F95PATH
7362 The list of directories that the Fortran 95 compiler will search
7363 for include directories. The implicit dependency scanner will
7364 search these directories for include files. Don't explicitly put
7365 include directory arguments in $F95FLAGS because the result will be
7366 non-portable and the directories will not be searched by the
7367 dependency scanner. Note: directory names in $F95PATH will be
7368 looked-up relative to the SConscript directory when they are used
7369 in a command. To force scons to look-up a directory relative to the
7370 root of the source tree use #: You only need to set $F95PATH if you
7371 need to define a specific include path for Fortran 95 files. You
7372 should normally set the $FORTRANPATH variable, which specifies the
7373 include path for the default Fortran compiler for all Fortran
7374 versions.
7375 env = Environment(F95PATH='#/include')
7377 The directory look-up can also be forced using the Dir() function:
7379 include = Dir('include')
7381 env = Environment(F95PATH=include)
7382 The directory list will be added to command lines through the
7384 automatically-generated $_F95INCFLAGS construction variable, which
7385 is constructed by appending the values of the $INCPREFIX and
7386 $INCSUFFIX construction variables to the beginning and end of each
7387 directory in $F95PATH. Any command lines you define that need the
7388 F95PATH directory list should include $_F95INCFLAGS:
7389 env = Environment(F95COM="my_compiler $_F95INCFLAGS -c -o $TARGET $SOURCE")
7391 F95PPCOM
7393 The command line used to compile a Fortran 95 source file to an
7394 object file after first running the file through the C
7395 preprocessor. Any options specified in the $F95FLAGS and $CPPFLAGS
7396 construction variables are included on this command line. You only
7397 need to set $F95PPCOM if you need to use a specific C-preprocessor
7398 command line for Fortran 95 files. You should normally set the
7399 $FORTRANPPCOM variable, which specifies the default C-preprocessor
7400 command line for all Fortran versions.
7401 F95PPCOMSTR
7403 The string displayed when a Fortran 95 source file is compiled to
7404 an object file after first running the file through the C
7405 preprocessor. If this is not set, then $F95PPCOM or $FORTRANPPCOM
7406 (the command line) is displayed.
7407 F95PPFILESUFFIXES
7409 The list of file extensions for which the compilation +
7410 preprocessor pass for F95 dialect will be used. By default, this is
7411 empty
7412 File
7414 A function that converts a string into a File instance relative to
7415 the target being built.
7416 A function that converts a string into a File instance relative to
7418 the target being built.
7419 FORTRAN
7421 The default Fortran compiler for all versions of Fortran.
7422 FORTRANCOM
7424 The command line used to compile a Fortran source file to an object
7425 file. By default, any options specified in the $FORTRANFLAGS,
7426 $CPPFLAGS, $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS
7427 construction variables are included on this command line.
7428 FORTRANCOMSTR
7430 The string displayed when a Fortran source file is compiled to an
7431 object file. If this is not set, then $FORTRANCOM (the command
7432 line) is displayed.
7433 FORTRANFILESUFFIXES
7435 The list of file extensions for which the FORTRAN dialect will be
7436 used. By default, this is ['.f', '.for', '.ftn']
7437 FORTRANFLAGS
7439 General user-specified options that are passed to the Fortran
7440 compiler. Note that this variable does not contain -I (or similar)
7441 include or module search path options that scons generates
7442 automatically from $FORTRANPATH. See $_FORTRANINCFLAGS and
7443 $_FORTRANMODFLAG, below, for the variables that expand those
7444 options.
7445 _FORTRANINCFLAGS
7447 An automatically-generated construction variable containing the
7448 Fortran compiler command-line options for specifying directories to
7449 be searched for include files and module files. The value of
7450 $_FORTRANINCFLAGS is created by prepending/appending $INCPREFIX and
7451 $INCSUFFIX to the beginning and end of each directory in
7452 $FORTRANPATH.
7453 FORTRANMODDIR
7455 Directory location where the Fortran compiler should place any
7456 module files it generates. This variable is empty, by default. Some
7457 Fortran compilers will internally append this directory in the
7458 search path for module files, as well.
7459 FORTRANMODDIRPREFIX
7461 The prefix used to specify a module directory on the Fortran
7462 compiler command line. This will be appended to the beginning of
7463 the directory in the $FORTRANMODDIR construction variables when the
7464 $_FORTRANMODFLAG variables is automatically generated.
7465 FORTRANMODDIRSUFFIX
7467 The suffix used to specify a module directory on the Fortran
7468 compiler command line. This will be appended to the beginning of
7469 the directory in the $FORTRANMODDIR construction variables when the
7470 $_FORTRANMODFLAG variables is automatically generated.
7471 _FORTRANMODFLAG
7473 An automatically-generated construction variable containing the
7474 Fortran compiler command-line option for specifying the directory
7475 location where the Fortran compiler should place any module files
7476 that happen to get generated during compilation. The value of
7477 $_FORTRANMODFLAG is created by prepending/appending
7478 $FORTRANMODDIRPREFIX and $FORTRANMODDIRSUFFIX to the beginning and
7479 end of the directory in $FORTRANMODDIR.
7480 FORTRANMODPREFIX
7482 The module file prefix used by the Fortran compiler. SCons assumes
7483 that the Fortran compiler follows the quasi-standard naming
7484 convention for module files of module_name.mod. As a result, this
7485 variable is left empty, by default. For situations in which the
7486 compiler does not necessarily follow the normal convention, the
7487 user may use this variable. Its value will be appended to every
7488 module file name as scons attempts to resolve dependencies.
7489 FORTRANMODSUFFIX
7491 The module file suffix used by the Fortran compiler. SCons assumes
7492 that the Fortran compiler follows the quasi-standard naming
7493 convention for module files of module_name.mod. As a result, this
7494 variable is set to ".mod", by default. For situations in which the
7495 compiler does not necessarily follow the normal convention, the
7496 user may use this variable. Its value will be appended to every
7497 module file name as scons attempts to resolve dependencies.
7498 FORTRANPATH
7500 The list of directories that the Fortran compiler will search for
7501 include files and (for some compilers) module files. The Fortran
7502 implicit dependency scanner will search these directories for
7503 include files (but not module files since they are autogenerated
7504 and, as such, may not actually exist at the time the scan takes
7505 place). Don't explicitly put include directory arguments in
7506 FORTRANFLAGS because the result will be non-portable and the
7507 directories will not be searched by the dependency scanner. Note:
7508 directory names in FORTRANPATH will be looked-up relative to the
7509 SConscript directory when they are used in a command. To force
7510 scons to look-up a directory relative to the root of the source
7511 tree use #:
7512 env = Environment(FORTRANPATH='#/include')
7514 The directory look-up can also be forced using the Dir() function:
7516 include = Dir('include')
7518 env = Environment(FORTRANPATH=include)
7519 The directory list will be added to command lines through the
7521 automatically-generated $_FORTRANINCFLAGS construction variable,
7522 which is constructed by appending the values of the $INCPREFIX and
7523 $INCSUFFIX construction variables to the beginning and end of each
7524 directory in $FORTRANPATH. Any command lines you define that need
7525 the FORTRANPATH directory list should include $_FORTRANINCFLAGS:
7526 env = Environment(FORTRANCOM="my_compiler $_FORTRANINCFLAGS -c -o $TARGET $SOURCE")
7528 FORTRANPPCOM
7530 The command line used to compile a Fortran source file to an object
7531 file after first running the file through the C preprocessor. By
7532 default, any options specified in the $FORTRANFLAGS, $CPPFLAGS,
7533 $_CPPDEFFLAGS, $_FORTRANMODFLAG, and $_FORTRANINCFLAGS construction
7534 variables are included on this command line.
7535 FORTRANPPCOMSTR
7537 The string displayed when a Fortran source file is compiled to an
7538 object file after first running the file through the C
7539 preprocessor. If this is not set, then $FORTRANPPCOM (the command
7540 line) is displayed.
7541 FORTRANPPFILESUFFIXES
7543 The list of file extensions for which the compilation +
7544 preprocessor pass for FORTRAN dialect will be used. By default,
7545 this is ['.fpp', '.FPP']
7546 FORTRANSUFFIXES
7548 The list of suffixes of files that will be scanned for Fortran
7549 implicit dependencies (INCLUDE lines and USE statements). The
7550 default list is:
7551 [".f", ".F", ".for", ".FOR", ".ftn", ".FTN", ".fpp", ".FPP",
7553 ".f77", ".F77", ".f90", ".F90", ".f95", ".F95"]
7554 FRAMEWORKPATH
7556 On Mac OS X with gcc, a list containing the paths to search for
7557 frameworks. Used by the compiler to find framework-style includes
7558 like #include <Fmwk/Header.h>. Used by the linker to find
7559 user-specified frameworks when linking (see $FRAMEWORKS). For
7560 example:
7561 env.AppendUnique(FRAMEWORKPATH='#myframeworkdir')
7563 will add
7565 ... -Fmyframeworkdir
7567 to the compiler and linker command lines.
7569 _FRAMEWORKPATH
7571 On Mac OS X with gcc, an automatically-generated construction
7572 variable containing the linker command-line options corresponding
7573 to $FRAMEWORKPATH.
7574 FRAMEWORKPATHPREFIX
7576 On Mac OS X with gcc, the prefix to be used for the FRAMEWORKPATH
7577 entries. (see $FRAMEWORKPATH). The default value is -F.
7578 FRAMEWORKPREFIX
7580 On Mac OS X with gcc, the prefix to be used for linking in
7581 frameworks (see $FRAMEWORKS). The default value is -framework.
7582 _FRAMEWORKS
7584 On Mac OS X with gcc, an automatically-generated construction
7585 variable containing the linker command-line options for linking
7586 with FRAMEWORKS.
7587 FRAMEWORKS
7589 On Mac OS X with gcc, a list of the framework names to be linked
7590 into a program or shared library or bundle. The default value is
7591 the empty list. For example:
7592 env.AppendUnique(FRAMEWORKS=Split('System Cocoa SystemConfiguration'))
7594 FRAMEWORKSFLAGS
7596 On Mac OS X with gcc, general user-supplied frameworks options to
7597 be added at the end of a command line building a loadable module.
7598 (This has been largely superseded by the $FRAMEWORKPATH,
7599 $FRAMEWORKPATHPREFIX, $FRAMEWORKPREFIX and $FRAMEWORKS variables
7600 described above.)
7601 GS
7603 The Ghostscript program used, e.g. to convert PostScript to PDF
7604 files.
7605 GSCOM
7607 The full Ghostscript command line used for the conversion process.
7608 Its default value is “$GS $GSFLAGS -sOutputFile=$TARGET $SOURCES”.
7609 GSCOMSTR
7611 The string displayed when Ghostscript is called for the conversion
7612 process. If this is not set (the default), then $GSCOM (the command
7613 line) is displayed.
7614 GSFLAGS
7616 General options passed to the Ghostscript program, when converting
7617 PostScript to PDF files for example. Its default value is
7618 “-dNOPAUSE -dBATCH -sDEVICE=pdfwrite”
7619 HOST_ARCH
7621 The name of the host hardware architecture used to create the
7622 Environment. If a platform is specified when creating the
7623 Environment, then that Platform's logic will handle setting this
7624 value. This value is immutable, and should not be changed by the
7625 user after the Environment is initialized. Currently only set for
7626 Win32.
7627 Sets the host architecture for Visual Studio compiler. If not set,
7629 default to the detected host architecture: note that this may
7630 depend on the python you are using. This variable must be passed as
7631 an argument to the Environment() constructor; setting it later has
7632 no effect.
7633 Valid values are the same as for $TARGET_ARCH.
7635 This is currently only used on Windows, but in the future it will
7637 be used on other OSes as well.
7638 HOST_OS
7640 The name of the host operating system used to create the
7641 Environment. If a platform is specified when creating the
7642 Environment, then that Platform's logic will handle setting this
7643 value. This value is immutable, and should not be changed by the
7644 user after the Environment is initialized. Currently only set for
7645 Win32.
7646 IDLSUFFIXES
7648 The list of suffixes of files that will be scanned for IDL implicit
7649 dependencies (#include or import lines). The default list is:
7650 [".idl", ".IDL"]
7652 IMPLIBNOVERSIONSYMLINKS
7654 Used to override $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS
7655 when creating versioned import library for a shared
7656 library/loadable module. If not defined, then
7657 $SHLIBNOVERSIONSYMLINKS/$LDMODULENOVERSIONSYMLINKS is used to
7658 determine whether to disable symlink generation or not.
7659 IMPLIBPREFIX
7661 The prefix used for import library names. For example, cygwin uses
7662 import libraries (libfoo.dll.a) in pair with dynamic libraries
7663 (cygfoo.dll). The cyglink linker sets $IMPLIBPREFIX to 'lib' and
7664 $SHLIBPREFIX to 'cyg'.
7665 IMPLIBSUFFIX
7667 The suffix used for import library names. For example, cygwin uses
7668 import libraries (libfoo.dll.a) in pair with dynamic libraries
7669 (cygfoo.dll). The cyglink linker sets $IMPLIBSUFFIX to '.dll.a' and
7670 $SHLIBSUFFIX to '.dll'.
7671 IMPLIBVERSION
7673 Used to override $SHLIBVERSION/$LDMODULEVERSION when generating
7674 versioned import library for a shared library/loadable module. If
7675 undefined, the $SHLIBVERSION/$LDMODULEVERSION is used to determine
7676 the version of versioned import library.
7677 IMPLICIT_COMMAND_DEPENDENCIES
7679 Controls whether or not SCons will add implicit dependencies for
7680 the commands executed to build targets.
7681 By default, SCons will add to each target an implicit dependency on
7683 the command represented by the first argument on any command line
7684 it executes. The specific file for the dependency is found by
7685 searching the PATH variable in the ENV environment used to execute
7686 the command.
7687 If the construction variable $IMPLICIT_COMMAND_DEPENDENCIES is set
7689 to a false value (None, False, 0, etc.), then the implicit
7690 dependency will not be added to the targets built with that
7691 construction environment.
7692 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
7694 INCPREFIX
7696 The prefix used to specify an include directory on the C compiler
7697 command line. This will be appended to the beginning of each
7698 directory in the $CPPPATH and $FORTRANPATH construction variables
7699 when the $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are
7700 automatically generated.
7701 INCSUFFIX
7703 The suffix used to specify an include directory on the C compiler
7704 command line. This will be appended to the end of each directory in
7705 the $CPPPATH and $FORTRANPATH construction variables when the
7706 $_CPPINCFLAGS and $_FORTRANINCFLAGS variables are automatically
7707 generated.
7708 INSTALL
7710 A function to be called to install a file into a destination file
7711 name. The default function copies the file into the destination
7712 (and sets the destination file's mode and permission bits to match
7713 the source file's). The function takes the following arguments:
7714 def install(dest, source, env):
7716 dest is the path name of the destination file. source is the path
7719 name of the source file. env is the construction environment (a
7720 dictionary of construction values) in force for this file
7721 installation.
7722 INSTALLSTR
7724 The string displayed when a file is installed into a destination
7725 file name. The default is:
7726 Install file: "$SOURCE" as "$TARGET"
7728 INTEL_C_COMPILER_VERSION
7730 Set by the "intelc" Tool to the major version number of the Intel C
7731 compiler selected for use.
7732 JAR
7734 The Java archive tool.
7735 The Java archive tool.
7737 JARCHDIR
7739 The directory to which the Java archive tool should change (using
7740 the -C option).
7741 The directory to which the Java archive tool should change (using
7743 the -C option).
7744 JARCOM
7746 The command line used to call the Java archive tool.
7747 The command line used to call the Java archive tool.
7749 JARCOMSTR
7751 The string displayed when the Java archive tool is called If this
7752 is not set, then $JARCOM (the command line) is displayed.
7753 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
7755 The string displayed when the Java archive tool is called If this
7757 is not set, then $JARCOM (the command line) is displayed.
7758 env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
7760 JARFLAGS
7762 General options passed to the Java archive tool. By default this is
7763 set to cf to create the necessary jar file.
7764 General options passed to the Java archive tool. By default this is
7766 set to cf to create the necessary jar file.
7767 JARSUFFIX
7769 The suffix for Java archives: .jar by default.
7770 The suffix for Java archives: .jar by default.
7772 JAVABOOTCLASSPATH
7774 Specifies the list of directories that will be added to the javac
7775 command line via the -bootclasspath option. The individual
7776 directory names will be separated by the operating system's path
7777 separate character (: on UNIX/Linux/POSIX, ; on Windows).
7778 JAVAC
7780 The Java compiler.
7781 JAVACCOM
7783 The command line used to compile a directory tree containing Java
7784 source files to corresponding Java class files. Any options
7785 specified in the $JAVACFLAGS construction variable are included on
7786 this command line.
7787 JAVACCOMSTR
7789 The string displayed when compiling a directory tree of Java source
7790 files to corresponding Java class files. If this is not set, then
7791 $JAVACCOM (the command line) is displayed.
7792 env = Environment(JAVACCOMSTR = "Compiling class files $TARGETS from $SOURCES")
7794 JAVACFLAGS
7796 General options that are passed to the Java compiler.
7797 JAVACLASSDIR
7799 The directory in which Java class files may be found. This is
7800 stripped from the beginning of any Java .class file names supplied
7801 to the JavaH builder.
7802 JAVACLASSPATH
7804 Specifies the list of directories that will be searched for Java
7805 .class file. The directories in this list will be added to the
7806 javac and javah command lines via the -classpath option. The
7807 individual directory names will be separated by the operating
7808 system's path separate character (: on UNIX/Linux/POSIX, ; on
7809 Windows).
7810 Note that this currently just adds the specified directory via the
7812 -classpath option. SCons does not currently search the
7813 $JAVACLASSPATH directories for dependency .class files.
7814 JAVACLASSSUFFIX
7816 The suffix for Java class files; .class by default.
7817 JAVAH
7819 The Java generator for C header and stub files.
7820 JAVAHCOM
7822 The command line used to generate C header and stub files from Java
7823 classes. Any options specified in the $JAVAHFLAGS construction
7824 variable are included on this command line.
7825 JAVAHCOMSTR
7827 The string displayed when C header and stub files are generated
7828 from Java classes. If this is not set, then $JAVAHCOM (the command
7829 line) is displayed.
7830 env = Environment(JAVAHCOMSTR = "Generating header/stub file(s) $TARGETS from $SOURCES")
7832 JAVAHFLAGS
7834 General options passed to the C header and stub file generator for
7835 Java classes.
7836 JAVASOURCEPATH
7838 Specifies the list of directories that will be searched for input
7839 .java file. The directories in this list will be added to the javac
7840 command line via the -sourcepath option. The individual directory
7841 names will be separated by the operating system's path separate
7842 character (: on UNIX/Linux/POSIX, ; on Windows).
7843 Note that this currently just adds the specified directory via the
7845 -sourcepath option. SCons does not currently search the
7846 $JAVASOURCEPATH directories for dependency .java files.
7847 JAVASUFFIX
7849 The suffix for Java files; .java by default.
7850 JAVAVERSION
7852 Specifies the Java version being used by the Java builder. This is
7853 not currently used to select one version of the Java compiler vs.
7854 another. Instead, you should set this to specify the version of
7855 Java supported by your javac compiler. The default is 1.4.
7856 This is sometimes necessary because Java 1.5 changed the file names
7858 that are created for nested anonymous inner classes, which can
7859 cause a mismatch with the files that SCons expects will be
7860 generated by the javac compiler. Setting $JAVAVERSION to 1.5 (or
7861 1.6, as appropriate) can make SCons realize that a Java 1.5 or 1.6
7862 build is actually up to date.
7863 LATEX
7865 The LaTeX structured formatter and typesetter.
7866 LATEXCOM
7868 The command line used to call the LaTeX structured formatter and
7869 typesetter.
7870 LATEXCOMSTR
7872 The string displayed when calling the LaTeX structured formatter
7873 and typesetter. If this is not set, then $LATEXCOM (the command
7874 line) is displayed.
7875 env = Environment(LATEXCOMSTR = "Building $TARGET from LaTeX input $SOURCES")
7877 LATEXFLAGS
7879 General options passed to the LaTeX structured formatter and
7880 typesetter.
7881 LATEXRETRIES
7883 The maximum number of times that LaTeX will be re-run if the .log
7884 generated by the $LATEXCOM command indicates that there are
7885 undefined references. The default is to try to resolve undefined
7886 references by re-running LaTeX up to three times.
7887 LATEXSUFFIXES
7889 The list of suffixes of files that will be scanned for LaTeX
7890 implicit dependencies (\include or \import files). The default list
7891 is:
7892 [".tex", ".ltx", ".latex"]
7894 LDMODULE
7896 The linker for building loadable modules. By default, this is the
7897 same as $SHLINK.
7898 LDMODULECOM
7900 The command line for building loadable modules. On Mac OS X, this
7901 uses the $LDMODULE, $LDMODULEFLAGS and $FRAMEWORKSFLAGS variables.
7902 On other systems, this is the same as $SHLINK.
7903 LDMODULECOMSTR
7905 The string displayed when building loadable modules. If this is not
7906 set, then $LDMODULECOM (the command line) is displayed.
7907 LDMODULEFLAGS
7909 General user options passed to the linker for building loadable
7910 modules.
7911 LDMODULENOVERSIONSYMLINKS
7913 Instructs the LoadableModule builder to not automatically create
7914 symlinks for versioned modules. Defaults to $SHLIBNOVERSIONSYMLINKS
7915 LDMODULEPREFIX
7917 The prefix used for loadable module file names. On Mac OS X, this
7918 is null; on other systems, this is the same as $SHLIBPREFIX.
7919 _LDMODULESONAME
7921 A macro that automatically generates loadable module's SONAME based
7922 on $TARGET, $LDMODULEVERSION and $LDMODULESUFFIX. Used by
7923 LoadableModule builder when the linker tool supports SONAME (e.g.
7924 gnulink).
7925 LDMODULESUFFIX
7927 The suffix used for loadable module file names. On Mac OS X, this
7928 is null; on other systems, this is the same as $SHLIBSUFFIX.
7929 LDMODULEVERSION
7931 When this construction variable is defined, a versioned loadable
7932 module is created by LoadableModule builder. This activates the
7933 $_LDMODULEVERSIONFLAGS and thus modifies the $LDMODULECOM as
7934 required, adds the version number to the library name, and creates
7935 the symlinks that are needed. $LDMODULEVERSION versions should
7936 exist in the same format as $SHLIBVERSION.
7937 LDMODULEVERSIONFLAGS
7939 Extra flags added to $LDMODULECOM when building versioned
7940 LoadableModule. These flags are only used when $LDMODULEVERSION is
7941 set.
7942 _LDMODULEVERSIONFLAGS
7944 This macro automatically introduces extra flags to $LDMODULECOM
7945 when building versioned LoadableModule (that is when
7946 $LDMODULEVERSION is set). _LDMODULEVERSIONFLAGS usually adds
7947 $SHLIBVERSIONFLAGS and some extra dynamically generated options
7948 (such as -Wl,-soname=$_LDMODULESONAME). It is unused by plain
7949 (unversioned) loadable modules.
7950 LEX
7952 The lexical analyzer generator.
7953 LEXCOM
7955 The command line used to call the lexical analyzer generator to
7956 generate a source file.
7957 LEXCOMSTR
7959 The string displayed when generating a source file using the
7960 lexical analyzer generator. If this is not set, then $LEXCOM (the
7961 command line) is displayed.
7962 env = Environment(LEXCOMSTR = "Lex'ing $TARGET from $SOURCES")
7964 LEXFLAGS
7966 General options passed to the lexical analyzer generator.
7967 _LIBDIRFLAGS
7969 An automatically-generated construction variable containing the
7970 linker command-line options for specifying directories to be
7971 searched for library. The value of $_LIBDIRFLAGS is created by
7972 appending $LIBDIRPREFIX and $LIBDIRSUFFIX to the beginning and end
7973 of each directory in $LIBPATH.
7974 LIBDIRPREFIX
7976 The prefix used to specify a library directory on the linker
7977 command line. This will be appended to the beginning of each
7978 directory in the $LIBPATH construction variable when the
7979 $_LIBDIRFLAGS variable is automatically generated.
7980 LIBDIRSUFFIX
7982 The suffix used to specify a library directory on the linker
7983 command line. This will be appended to the end of each directory in
7984 the $LIBPATH construction variable when the $_LIBDIRFLAGS variable
7985 is automatically generated.
7986 LIBEMITTER
7988 TODO
7989 _LIBFLAGS
7991 An automatically-generated construction variable containing the
7992 linker command-line options for specifying libraries to be linked
7993 with the resulting target. The value of $_LIBFLAGS is created by
7994 appending $LIBLINKPREFIX and $LIBLINKSUFFIX to the beginning and
7995 end of each filename in $LIBS.
7996 LIBLINKPREFIX
7998 The prefix used to specify a library to link on the linker command
7999 line. This will be appended to the beginning of each library in the
8000 $LIBS construction variable when the $_LIBFLAGS variable is
8001 automatically generated.
8002 LIBLINKSUFFIX
8004 The suffix used to specify a library to link on the linker command
8005 line. This will be appended to the end of each library in the $LIBS
8006 construction variable when the $_LIBFLAGS variable is automatically
8007 generated.
8008 LIBPATH
8010 The list of directories that will be searched for libraries. The
8011 implicit dependency scanner will search these directories for
8012 include files. Don't explicitly put include directory arguments in
8013 $LINKFLAGS or $SHLINKFLAGS because the result will be non-portable
8014 and the directories will not be searched by the dependency scanner.
8015 Note: directory names in LIBPATH will be looked-up relative to the
8016 SConscript directory when they are used in a command. To force
8017 scons to look-up a directory relative to the root of the source
8018 tree use #:
8019 env = Environment(LIBPATH='#/libs')
8021 The directory look-up can also be forced using the Dir() function:
8023 libs = Dir('libs')
8025 env = Environment(LIBPATH=libs)
8026 The directory list will be added to command lines through the
8028 automatically-generated $_LIBDIRFLAGS construction variable, which
8029 is constructed by appending the values of the $LIBDIRPREFIX and
8030 $LIBDIRSUFFIX construction variables to the beginning and end of
8031 each directory in $LIBPATH. Any command lines you define that need
8032 the LIBPATH directory list should include $_LIBDIRFLAGS:
8033 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8035 LIBPREFIX
8037 The prefix used for (static) library file names. A default value is
8038 set for each platform (posix, win32, os2, etc.), but the value is
8039 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8040 etc.) to reflect the names of the libraries they create.
8041 LIBPREFIXES
8043 A list of all legal prefixes for library file names. When searching
8044 for library dependencies, SCons will look for files with these
8045 prefixes, the base library name, and suffixes in the $LIBSUFFIXES
8046 list.
8047 LIBS
8049 A list of one or more libraries that will be linked with any
8050 executable programs created by this environment.
8051 The library list will be added to command lines through the
8053 automatically-generated $_LIBFLAGS construction variable, which is
8054 constructed by appending the values of the $LIBLINKPREFIX and
8055 $LIBLINKSUFFIX construction variables to the beginning and end of
8056 each filename in $LIBS. Any command lines you define that need the
8057 LIBS library list should include $_LIBFLAGS:
8058 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
8060 If you add a File object to the $LIBS list, the name of that file
8062 will be added to $_LIBFLAGS, and thus the link line, as is, without
8063 $LIBLINKPREFIX or $LIBLINKSUFFIX. For example:
8064 env.Append(LIBS=File('/tmp/mylib.so'))
8066 In all cases, scons will add dependencies from the executable
8068 program to all the libraries in this list.
8069 LIBSUFFIX
8071 The suffix used for (static) library file names. A default value is
8072 set for each platform (posix, win32, os2, etc.), but the value is
8073 overridden by individual tools (ar, mslib, sgiar, sunar, tlib,
8074 etc.) to reflect the names of the libraries they create.
8075 LIBSUFFIXES
8077 A list of all legal suffixes for library file names. When searching
8078 for library dependencies, SCons will look for files with prefixes,
8079 in the $LIBPREFIXES list, the base library name, and these
8080 suffixes.
8081 LICENSE
8083 The abbreviated name of the license under which this project is
8084 released (gpl, lpgl, bsd etc.). See
8085 http://www.opensource.org/licenses/alphabetical for a list of
8086 license names.
8087 LINESEPARATOR
8089 The separator used by the Substfile and Textfile builders. This
8090 value is used between sources when constructing the target. It
8091 defaults to the current system line separator.
8092 LINGUAS_FILE
8094 The $LINGUAS_FILE defines file(s) containing list of additional
8095 linguas to be processed by POInit, POUpdate or MOFiles builders. It
8096 also affects Translate builder. If the variable contains a string,
8097 it defines name of the list file. The $LINGUAS_FILE may be a list
8098 of file names as well. If $LINGUAS_FILE is set to True (or non-zero
8099 numeric value), the list will be read from default file named
8100 LINGUAS.
8101 LINK
8103 The linker.
8104 LINKCOM
8106 The command line used to link object files into an executable.
8107 LINKCOMSTR
8109 The string displayed when object files are linked into an
8110 executable. If this is not set, then $LINKCOM (the command line) is
8111 displayed.
8112 env = Environment(LINKCOMSTR = "Linking $TARGET")
8114 LINKFLAGS
8116 General user options passed to the linker. Note that this variable
8117 should not contain -l (or similar) options for linking with the
8118 libraries listed in $LIBS, nor -L (or similar) library search path
8119 options that scons generates automatically from $LIBPATH. See
8120 $_LIBFLAGS above, for the variable that expands to library-link
8121 options, and $_LIBDIRFLAGS above, for the variable that expands to
8122 library search path options.
8123 M4
8125 The M4 macro preprocessor.
8126 M4COM
8128 The command line used to pass files through the M4 macro
8129 preprocessor.
8130 M4COMSTR
8132 The string displayed when a file is passed through the M4 macro
8133 preprocessor. If this is not set, then $M4COM (the command line) is
8134 displayed.
8135 M4FLAGS
8137 General options passed to the M4 macro preprocessor.
8138 MAKEINDEX
8140 The makeindex generator for the TeX formatter and typesetter and
8141 the LaTeX structured formatter and typesetter.
8142 MAKEINDEXCOM
8144 The command line used to call the makeindex generator for the TeX
8145 formatter and typesetter and the LaTeX structured formatter and
8146 typesetter.
8147 MAKEINDEXCOMSTR
8149 The string displayed when calling the makeindex generator for the
8150 TeX formatter and typesetter and the LaTeX structured formatter and
8151 typesetter. If this is not set, then $MAKEINDEXCOM (the command
8152 line) is displayed.
8153 MAKEINDEXFLAGS
8155 General options passed to the makeindex generator for the TeX
8156 formatter and typesetter and the LaTeX structured formatter and
8157 typesetter.
8158 MAXLINELENGTH
8160 The maximum number of characters allowed on an external command
8161 line. On Win32 systems, link lines longer than this many characters
8162 are linked via a temporary file name.
8163 MIDL
8165 The Microsoft IDL compiler.
8166 MIDLCOM
8168 The command line used to pass files to the Microsoft IDL compiler.
8169 MIDLCOMSTR
8171 The string displayed when the Microsoft IDL copmiler is called. If
8172 this is not set, then $MIDLCOM (the command line) is displayed.
8173 MIDLFLAGS
8175 General options passed to the Microsoft IDL compiler.
8176 MOSUFFIX
8178 Suffix used for MO files (default: '.mo'). See msgfmt tool and
8179 MOFiles builder.
8180 MSGFMT
8182 Absolute path to msgfmt(1) binary, found by Detect(). See msgfmt
8183 tool and MOFiles builder.
8184 MSGFMTCOM
8186 Complete command line to run msgfmt(1) program. See msgfmt tool and
8187 MOFiles builder.
8188 MSGFMTCOMSTR
8190 String to display when msgfmt(1) is invoked (default: '', which
8191 means ``print $MSGFMTCOM''). See msgfmt tool and MOFiles builder.
8192 MSGFMTFLAGS
8194 Additional flags to msgfmt(1). See msgfmt tool and MOFiles builder.
8195 MSGINIT
8197 Path to msginit(1) program (found via Detect()). See msginit tool
8198 and POInit builder.
8199 MSGINITCOM
8201 Complete command line to run msginit(1) program. See msginit tool
8202 and POInit builder.
8203 MSGINITCOMSTR
8205 String to display when msginit(1) is invoked (default: '', which
8206 means ``print $MSGINITCOM''). See msginit tool and POInit builder.
8207 MSGINITFLAGS
8209 List of additional flags to msginit(1) (default: []). See msginit
8210 tool and POInit builder.
8211 _MSGINITLOCALE
8213 Internal ``macro''. Computes locale (language) name based on target
8214 filename (default: '${TARGET.filebase}').
8215 See msginit tool and POInit builder.
8217 MSGMERGE
8219 Absolute path to msgmerge(1) binary as found by Detect(). See
8220 msgmerge tool and POUpdate builder.
8221 MSGMERGECOM
8223 Complete command line to run msgmerge(1) command. See msgmerge tool
8224 and POUpdate builder.
8225 MSGMERGECOMSTR
8227 String to be displayed when msgmerge(1) is invoked (default: '',
8228 which means ``print $MSGMERGECOM''). See msgmerge tool and POUpdate
8229 builder.
8230 MSGMERGEFLAGS
8232 Additional flags to msgmerge(1) command. See msgmerge tool and
8233 POUpdate builder.
8234 MSSDK_DIR
8236 The directory containing the Microsoft SDK (either Platform SDK or
8237 Windows SDK) to be used for compilation.
8238 MSSDK_VERSION
8240 The version string of the Microsoft SDK (either Platform SDK or
8241 Windows SDK) to be used for compilation. Supported versions include
8242 6.1, 6.0A, 6.0, 2003R2 and 2003R1.
8243 MSVC_BATCH
8245 When set to any true value, specifies that SCons should batch
8246 compilation of object files when calling the Microsoft Visual C/C++
8247 compiler. All compilations of source files from the same source
8248 directory that generate target files in a same output directory and
8249 were configured in SCons using the same construction environment
8250 will be built in a single call to the compiler. Only source files
8251 that have changed since their object files were built will be
8252 passed to each compiler invocation (via the $CHANGED_SOURCES
8253 construction variable). Any compilations where the object (target)
8254 file base name (minus the .obj) does not match the source file base
8255 name will be compiled separately.
8256 MSVC_USE_SCRIPT
8258 Use a batch script to set up Microsoft Visual Studio compiler
8259 $MSVC_USE_SCRIPT overrides $MSVC_VERSION and $TARGET_ARCH. If set
8262 to the name of a Visual Studio .bat file (e.g. vcvars.bat), SCons
8263 will run that bat file and extract the relevant variables from the
8264 result (typically %INCLUDE%, %LIB%, and %PATH%). Setting
8265 MSVC_USE_SCRIPT to None bypasses the Visual Studio autodetection
8266 entirely; use this if you are running SCons in a Visual Studio cmd
8267 window and importing the shell's environment variables.
8268 MSVC_UWP_APP
8270 Build libraries for a Universal Windows Platform (UWP) Application.
8271 If $MSVC_UWP_APP is set, the Visual Studio environment will be set
8273 up to point to the Windows Store compatible libraries and Visual
8274 Studio runtimes. In doing so, any libraries that are built will be
8275 able to be used in a UWP App and published to the Windows Store.
8276 This flag will only have an effect with Visual Studio 2015+. This
8277 variable must be passed as an argument to the Environment()
8278 constructor; setting it later has no effect.
8279 Valid values are '1' or '0'
8281 MSVC_VERSION
8283 Sets the preferred version of Microsoft Visual C/C++ to use.
8284 If $MSVC_VERSION is not set, SCons will (by default) select the
8286 latest version of Visual C/C++ installed on your system. If the
8287 specified version isn't installed, tool initialization will fail.
8288 This variable must be passed as an argument to the Environment()
8289 constructor; setting it later has no effect.
8290 Valid values for Windows are 14.0, 14.0Exp, 12.0, 12.0Exp, 11.0,
8292 11.0Exp, 10.0, 10.0Exp, 9.0, 9.0Exp, 8.0, 8.0Exp, 7.1, 7.0, and
8293 6.0. Versions ending in Exp refer to "Express" or "Express for
8294 Desktop" editions.
8295 MSVS
8297 When the Microsoft Visual Studio tools are initialized, they set up
8298 this dictionary with the following keys:
8299 VERSION
8301 the version of MSVS being used (can be set via $MSVS_VERSION)
8302 VERSIONS
8304 the available versions of MSVS installed
8305 VCINSTALLDIR
8307 installed directory of Visual C++
8308 VSINSTALLDIR
8310 installed directory of Visual Studio
8311 FRAMEWORKDIR
8313 installed directory of the .NET framework
8314 FRAMEWORKVERSIONS
8316 list of installed versions of the .NET framework, sorted latest
8317 to oldest.
8318 FRAMEWORKVERSION
8320 latest installed version of the .NET framework
8321 FRAMEWORKSDKDIR
8323 installed location of the .NET SDK.
8324 PLATFORMSDKDIR
8326 installed location of the Platform SDK.
8327 PLATFORMSDK_MODULES
8329 dictionary of installed Platform SDK modules, where the
8330 dictionary keys are keywords for the various modules, and the
8331 values are 2-tuples where the first is the release date, and
8332 the second is the version number.
8333 If a value isn't set, it wasn't available in the registry.
8335 MSVS_ARCH
8337 Sets the architecture for which the generated project(s) should
8338 build.
8339 The default value is x86. amd64 is also supported by SCons for
8341 some Visual Studio versions. Trying to set $MSVS_ARCH to an
8342 architecture that's not supported for a given Visual Studio version
8343 will generate an error.
8344 MSVS_PROJECT_GUID
8346 The string placed in a generated Microsoft Visual Studio project
8347 file as the value of the ProjectGUID attribute. There is no default
8348 value. If not defined, a new GUID is generated.
8349 MSVS_SCC_AUX_PATH
8351 The path name placed in a generated Microsoft Visual Studio project
8352 file as the value of the SccAuxPath attribute if the
8353 MSVS_SCC_PROVIDER construction variable is also set. There is no
8354 default value.
8355 MSVS_SCC_CONNECTION_ROOT
8357 The root path of projects in your SCC workspace, i.e the path under
8358 which all project and solution files will be generated. It is used
8359 as a reference path from which the relative paths of the generated
8360 Microsoft Visual Studio project and solution files are computed.
8361 The relative project file path is placed as the value of the
8362 SccLocalPath attribute of the project file and as the values of the
8363 SccProjectFilePathRelativizedFromConnection[i] (where [i] ranges
8364 from 0 to the number of projects in the solution) attributes of the
8365 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8366 Studio solution file. Similarly the relative solution file path is
8367 placed as the values of the SccLocalPath[i] (where [i] ranges from
8368 0 to the number of projects in the solution) attributes of the
8369 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8370 Studio solution file. This is used only if the MSVS_SCC_PROVIDER
8371 construction variable is also set. The default value is the current
8372 working directory.
8373 MSVS_SCC_PROJECT_NAME
8375 The project name placed in a generated Microsoft Visual Studio
8376 project file as the value of the SccProjectName attribute if the
8377 MSVS_SCC_PROVIDER construction variable is also set. In this case
8378 the string is also placed in the SccProjectName0 attribute of the
8379 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8380 Studio solution file. There is no default value.
8381 MSVS_SCC_PROVIDER
8383 The string placed in a generated Microsoft Visual Studio project
8384 file as the value of the SccProvider attribute. The string is also
8385 placed in the SccProvider0 attribute of the
8386 GlobalSection(SourceCodeControl) section of the Microsoft Visual
8387 Studio solution file. There is no default value.
8388 MSVS_VERSION
8390 Sets the preferred version of Microsoft Visual Studio to use.
8391 If $MSVS_VERSION is not set, SCons will (by default) select the
8393 latest version of Visual Studio installed on your system. So, if
8394 you have version 6 and version 7 (MSVS .NET) installed, it will
8395 prefer version 7. You can override this by specifying the
8396 MSVS_VERSION variable in the Environment initialization, setting it
8397 to the appropriate version ('6.0' or '7.0', for example). If the
8398 specified version isn't installed, tool initialization will fail.
8399 This is obsolete: use $MSVC_VERSION instead. If $MSVS_VERSION is
8401 set and $MSVC_VERSION is not, $MSVC_VERSION will be set
8402 automatically to $MSVS_VERSION. If both are set to different
8403 values, scons will raise an error.
8404 MSVSBUILDCOM
8406 The build command line placed in a generated Microsoft Visual
8407 Studio project file. The default is to have Visual Studio invoke
8408 SCons with any specified build targets.
8409 MSVSCLEANCOM
8411 The clean command line placed in a generated Microsoft Visual
8412 Studio project file. The default is to have Visual Studio invoke
8413 SCons with the -c option to remove any specified targets.
8414 MSVSENCODING
8416 The encoding string placed in a generated Microsoft Visual Studio
8417 project file. The default is encoding Windows-1252.
8418 MSVSPROJECTCOM
8420 The action used to generate Microsoft Visual Studio project files.
8421 MSVSPROJECTSUFFIX
8423 The suffix used for Microsoft Visual Studio project (DSP) files.
8424 The default value is .vcproj when using Visual Studio version 7.x
8425 (.NET) or later version, and .dsp when using earlier versions of
8426 Visual Studio.
8427 MSVSREBUILDCOM
8429 The rebuild command line placed in a generated Microsoft Visual
8430 Studio project file. The default is to have Visual Studio invoke
8431 SCons with any specified rebuild targets.
8432 MSVSSCONS
8434 The SCons used in generated Microsoft Visual Studio project files.
8435 The default is the version of SCons being used to generate the
8436 project file.
8437 MSVSSCONSCOM
8439 The default SCons command used in generated Microsoft Visual Studio
8440 project files.
8441 MSVSSCONSCRIPT
8443 The sconscript file (that is, SConstruct or SConscript file) that
8444 will be invoked by Visual Studio project files (through the
8445 $MSVSSCONSCOM variable). The default is the same sconscript file
8446 that contains the call to MSVSProject to build the project file.
8447 MSVSSCONSFLAGS
8449 The SCons flags used in generated Microsoft Visual Studio project
8450 files.
8451 MSVSSOLUTIONCOM
8453 The action used to generate Microsoft Visual Studio solution files.
8454 MSVSSOLUTIONSUFFIX
8456 The suffix used for Microsoft Visual Studio solution (DSW) files.
8457 The default value is .sln when using Visual Studio version 7.x
8458 (.NET), and .dsw when using earlier versions of Visual Studio.
8459 MT
8461 The program used on Windows systems to embed manifests into DLLs
8462 and EXEs. See also $WINDOWS_EMBED_MANIFEST.
8463 MTEXECOM
8465 The Windows command line used to embed manifests into executables.
8466 See also $MTSHLIBCOM.
8467 MTFLAGS
8469 Flags passed to the $MT manifest embedding program (Windows only).
8470 MTSHLIBCOM
8472 The Windows command line used to embed manifests into shared
8473 libraries (DLLs). See also $MTEXECOM.
8474 MWCW_VERSION
8476 The version number of the MetroWerks CodeWarrior C compiler to be
8477 used.
8478 MWCW_VERSIONS
8480 A list of installed versions of the MetroWerks CodeWarrior C
8481 compiler on this system.
8482 NAME
8484 Specfies the name of the project to package.
8485 no_import_lib
8487 When set to non-zero, suppresses creation of a corresponding
8488 Windows static import lib by the SharedLibrary builder when used
8489 with MinGW, Microsoft Visual Studio or Metrowerks. This also
8490 suppresses creation of an export (.exp) file when using Microsoft
8491 Visual Studio.
8492 OBJPREFIX
8494 The prefix used for (static) object file names.
8495 OBJSUFFIX
8497 The suffix used for (static) object file names.
8498 PACKAGEROOT
8500 Specifies the directory where all files in resulting archive will
8501 be placed if applicable. The default value is "$NAME-$VERSION".
8502 PACKAGETYPE
8504 Selects the package type to build. Currently these are available:
8505 * msi - Microsoft Installer * rpm - Redhat Package Manger * ipkg -
8507 Itsy Package Management System * tarbz2 - compressed tar * targz -
8508 compressed tar * zip - zip file * src_tarbz2 - compressed tar
8509 source * src_targz - compressed tar source * src_zip - zip file
8510 source
8511 This may be overridden with the "package_type" command line option.
8513 PACKAGEVERSION
8515 The version of the package (not the underlying project). This is
8516 currently only used by the rpm packager and should reflect changes
8517 in the packaging, not the underlying project code itself.
8518 PCH
8520 The Microsoft Visual C++ precompiled header that will be used when
8521 compiling object files. This variable is ignored by tools other
8522 than Microsoft Visual C++. When this variable is defined SCons will
8523 add options to the compiler command line to cause it to use the
8524 precompiled header, and will also set up the dependencies for the
8525 PCH file. Example:
8526 env['PCH'] = 'StdAfx.pch'
8528 PCHCOM
8530 The command line used by the PCH builder to generated a precompiled
8531 header.
8532 PCHCOMSTR
8534 The string displayed when generating a precompiled header. If this
8535 is not set, then $PCHCOM (the command line) is displayed.
8536 PCHPDBFLAGS
8538 A construction variable that, when expanded, adds the /yD flag to
8539 the command line only if the $PDB construction variable is set.
8540 PCHSTOP
8542 This variable specifies how much of a source file is precompiled.
8543 This variable is ignored by tools other than Microsoft Visual C++,
8544 or when the PCH variable is not being used. When this variable is
8545 define it must be a string that is the name of the header that is
8546 included at the end of the precompiled portion of the source files,
8547 or the empty string if the "#pragma hrdstop" construct is being
8548 used:
8549 env['PCHSTOP'] = 'StdAfx.h'
8551 PDB
8553 The Microsoft Visual C++ PDB file that will store debugging
8554 information for object files, shared libraries, and programs. This
8555 variable is ignored by tools other than Microsoft Visual C++. When
8556 this variable is defined SCons will add options to the compiler and
8557 linker command line to cause them to generate external debugging
8558 information, and will also set up the dependencies for the PDB
8559 file. Example:
8560 env['PDB'] = 'hello.pdb'
8562 The Visual C++ compiler switch that SCons uses by default to
8564 generate PDB information is /Z7. This works correctly with parallel
8565 (-j) builds because it embeds the debug information in the
8566 intermediate object files, as opposed to sharing a single PDB file
8567 between multiple object files. This is also the only way to get
8568 debug information embedded into a static library. Using the /Zi
8569 instead may yield improved link-time performance, although parallel
8570 builds will no longer work. You can generate PDB files with the /Zi
8571 switch by overriding the default $CCPDBFLAGS variable; see the
8572 entry for that variable for specific examples.
8573 PDFCOM
8575 A deprecated synonym for $DVIPDFCOM.
8576 PDFLATEX
8578 The pdflatex utility.
8579 PDFLATEXCOM
8581 The command line used to call the pdflatex utility.
8582 PDFLATEXCOMSTR
8584 The string displayed when calling the pdflatex utility. If this is
8585 not set, then $PDFLATEXCOM (the command line) is displayed.
8586 env = Environment(PDFLATEX;COMSTR = "Building $TARGET from LaTeX input $SOURCES")
8588 PDFLATEXFLAGS
8590 General options passed to the pdflatex utility.
8591 PDFPREFIX
8593 The prefix used for PDF file names.
8594 PDFSUFFIX
8596 The suffix used for PDF file names.
8597 PDFTEX
8599 The pdftex utility.
8600 PDFTEXCOM
8602 The command line used to call the pdftex utility.
8603 PDFTEXCOMSTR
8605 The string displayed when calling the pdftex utility. If this is
8606 not set, then $PDFTEXCOM (the command line) is displayed.
8607 env = Environment(PDFTEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
8609 PDFTEXFLAGS
8611 General options passed to the pdftex utility.
8612 PKGCHK
8614 On Solaris systems, the package-checking program that will be used
8615 (along with $PKGINFO) to look for installed versions of the Sun PRO
8616 C++ compiler. The default is /usr/sbin/pgkchk.
8617 PKGINFO
8619 On Solaris systems, the package information program that will be
8620 used (along with $PKGCHK) to look for installed versions of the Sun
8621 PRO C++ compiler. The default is pkginfo.
8622 PLATFORM
8624 The name of the platform used to create the Environment. If no
8625 platform is specified when the Environment is created, scons
8626 autodetects the platform.
8627 env = Environment(tools = [])
8629 if env['PLATFORM'] == 'cygwin':
8630 Tool('mingw')(env)
8631 else:
8632 Tool('msvc')(env)
8633 POAUTOINIT
8635 The $POAUTOINIT variable, if set to True (on non-zero numeric
8636 value), let the msginit tool to automatically initialize missing PO
8637 files with msginit(1). This applies to both, POInit and POUpdate
8638 builders (and others that use any of them).
8639 POCREATE_ALIAS
8641 Common alias for all PO files created with POInit builder (default:
8642 'po-create'). See msginit tool and POInit builder.
8643 POSUFFIX
8645 Suffix used for PO files (default: '.po') See msginit tool and
8646 POInit builder.
8647 POTDOMAIN
8649 The $POTDOMAIN defines default domain, used to generate POT
8650 filename as $POTDOMAIN.pot when no POT file name is provided by the
8651 user. This applies to POTUpdate, POInit and POUpdate builders (and
8652 builders, that use them, e.g. Translate). Normally (if $POTDOMAIN
8653 is not defined), the builders use messages.pot as default POT file
8654 name.
8655 POTSUFFIX
8657 Suffix used for PO Template files (default: '.pot'). See xgettext
8658 tool and POTUpdate builder.
8659 POTUPDATE_ALIAS
8661 Name of the common phony target for all PO Templates created with
8662 POUpdate (default: 'pot-update'). See xgettext tool and POTUpdate
8663 builder.
8664 POUPDATE_ALIAS
8666 Common alias for all PO files being defined with POUpdate builder
8667 (default: 'po-update'). See msgmerge tool and POUpdate builder.
8668 PRINT_CMD_LINE_FUNC
8670 A Python function used to print the command lines as they are
8671 executed (assuming command printing is not disabled by the -q or -s
8672 options or their equivalents). The function should take four
8673 arguments: s, the command being executed (a string), target, the
8674 target being built (file node, list, or string name(s)), source,
8675 the source(s) used (file node, list, or string name(s)), and env,
8676 the environment being used.
8677 The function must do the printing itself. The default
8679 implementation, used if this variable is not set or is None, is:
8680 def print_cmd_line(s, target, source, env):
8682 sys.stdout.write(s + "\n")
8683 Here's an example of a more interesting function:
8685 def print_cmd_line(s, target, source, env):
8687 sys.stdout.write("Building %s -> %s...\n" %
8688 (' and '.join([str(x) for x in source]),
8689 ' and '.join([str(x) for x in target])))
8690 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
8691 env.Program('foo', 'foo.c')
8692 This just prints "Building targetname from sourcename..." instead
8694 of the actual commands. Such a function could also log the actual
8695 commands to a log file, for example.
8696 PROGEMITTER
8698 TODO
8699 PROGPREFIX
8701 The prefix used for executable file names.
8702 PROGSUFFIX
8704 The suffix used for executable file names.
8705 PSCOM
8707 The command line used to convert TeX DVI files into a PostScript
8708 file.
8709 PSCOMSTR
8711 The string displayed when a TeX DVI file is converted into a
8712 PostScript file. If this is not set, then $PSCOM (the command line)
8713 is displayed.
8714 PSPREFIX
8716 The prefix used for PostScript file names.
8717 PSSUFFIX
8719 The prefix used for PostScript file names.
8720 QT_AUTOSCAN
8722 Turn off scanning for mocable files. Use the Moc Builder to
8723 explicitly specify files to run moc on.
8724 QT_BINPATH
8726 The path where the qt binaries are installed. The default value is
8727 '$QTDIR/bin'.
8728 QT_CPPPATH
8730 The path where the qt header files are installed. The default value
8731 is '$QTDIR/include'. Note: If you set this variable to None, the
8732 tool won't change the $CPPPATH construction variable.
8733 QT_DEBUG
8735 Prints lots of debugging information while scanning for moc files.
8736 QT_LIB
8738 Default value is 'qt'. You may want to set this to 'qt-mt'. Note:
8739 If you set this variable to None, the tool won't change the $LIBS
8740 variable.
8741 QT_LIBPATH
8743 The path where the qt libraries are installed. The default value is
8744 '$QTDIR/lib'. Note: If you set this variable to None, the tool
8745 won't change the $LIBPATH construction variable.
8746 QT_MOC
8748 Default value is '$QT_BINPATH/moc'.
8749 QT_MOCCXXPREFIX
8751 Default value is ''. Prefix for moc output files, when source is a
8752 cxx file.
8753 QT_MOCCXXSUFFIX
8755 Default value is '.moc'. Suffix for moc output files, when source
8756 is a cxx file.
8757 QT_MOCFROMCXXCOM
8759 Command to generate a moc file from a cpp file.
8760 QT_MOCFROMCXXCOMSTR
8762 The string displayed when generating a moc file from a cpp file. If
8763 this is not set, then $QT_MOCFROMCXXCOM (the command line) is
8764 displayed.
8765 QT_MOCFROMCXXFLAGS
8767 Default value is '-i'. These flags are passed to moc, when moccing
8768 a C++ file.
8769 QT_MOCFROMHCOM
8771 Command to generate a moc file from a header.
8772 QT_MOCFROMHCOMSTR
8774 The string displayed when generating a moc file from a cpp file. If
8775 this is not set, then $QT_MOCFROMHCOM (the command line) is
8776 displayed.
8777 QT_MOCFROMHFLAGS
8779 Default value is ''. These flags are passed to moc, when moccing a
8780 header file.
8781 QT_MOCHPREFIX
8783 Default value is 'moc_'. Prefix for moc output files, when source
8784 is a header.
8785 QT_MOCHSUFFIX
8787 Default value is '$CXXFILESUFFIX'. Suffix for moc output files,
8788 when source is a header.
8789 QT_UIC
8791 Default value is '$QT_BINPATH/uic'.
8792 QT_UICCOM
8794 Command to generate header files from .ui files.
8795 QT_UICCOMSTR
8797 The string displayed when generating header files from .ui files.
8798 If this is not set, then $QT_UICCOM (the command line) is
8799 displayed.
8800 QT_UICDECLFLAGS
8802 Default value is ''. These flags are passed to uic, when creating a
8803 a h file from a .ui file.
8804 QT_UICDECLPREFIX
8806 Default value is ''. Prefix for uic generated header files.
8807 QT_UICDECLSUFFIX
8809 Default value is '.h'. Suffix for uic generated header files.
8810 QT_UICIMPLFLAGS
8812 Default value is ''. These flags are passed to uic, when creating a
8813 cxx file from a .ui file.
8814 QT_UICIMPLPREFIX
8816 Default value is 'uic_'. Prefix for uic generated implementation
8817 files.
8818 QT_UICIMPLSUFFIX
8820 Default value is '$CXXFILESUFFIX'. Suffix for uic generated
8821 implementation files.
8822 QT_UISUFFIX
8824 Default value is '.ui'. Suffix of designer input files.
8825 QTDIR
8827 The qt tool tries to take this from os.environ. It also initializes
8828 all QT_* construction variables listed below. (Note that all paths
8829 are constructed with python's os.path.join() method, but are listed
8830 here with the '/' separator for easier reading.) In addition, the
8831 construction environment variables $CPPPATH, $LIBPATH and $LIBS may
8832 be modified and the variables $PROGEMITTER, $SHLIBEMITTER and
8833 $LIBEMITTER are modified. Because the build-performance is affected
8834 when using this tool, you have to explicitly specify it at
8835 Environment creation:
8836 Environment(tools=['default','qt'])
8838 The qt tool supports the following operations:
8840 Automatic moc file generation from header files. You do not have
8843 to specify moc files explicitly, the tool does it for you. However,
8844 there are a few preconditions to do so: Your header file must have
8845 the same filebase as your implementation file and must stay in the
8846 same directory. It must have one of the suffixes .h, .hpp, .H,
8847 .hxx, .hh. You can turn off automatic moc file generation by
8848 setting QT_AUTOSCAN to 0. See also the corresponding Moc() builder
8849 method.
8850 Automatic moc file generation from cxx files. As stated in the qt
8853 documentation, include the moc file at the end of the cxx file.
8854 Note that you have to include the file, which is generated by the
8855 transformation ${QT_MOCCXXPREFIX}<basename>${QT_MOCCXXSUFFIX}, by
8856 default <basename>.moc. A warning is generated after building the
8857 moc file, if you do not include the correct file. If you are using
8858 VariantDir, you may need to specify duplicate=1. You can turn off
8859 automatic moc file generation by setting QT_AUTOSCAN to 0. See also
8860 the corresponding Moc builder method.
8861 Automatic handling of .ui files. The implementation files
8864 generated from .ui files are handled much the same as yacc or lex
8865 files. Each .ui file given as a source of Program, Library or
8866 SharedLibrary will generate three files, the declaration file, the
8867 implementation file and a moc file. Because there are also
8868 generated headers, you may need to specify duplicate=1 in calls to
8869 VariantDir. See also the corresponding Uic builder method.
8870 RANLIB
8872 The archive indexer.
8873 RANLIBCOM
8875 The command line used to index a static library archive.
8876 RANLIBCOMSTR
8878 The string displayed when a static library archive is indexed. If
8879 this is not set, then $RANLIBCOM (the command line) is displayed.
8880 env = Environment(RANLIBCOMSTR = "Indexing $TARGET")
8882 RANLIBFLAGS
8884 General options passed to the archive indexer.
8885 RC
8887 The resource compiler used to build a Microsoft Visual C++ resource
8888 file.
8889 RCCOM
8891 The command line used to build a Microsoft Visual C++ resource
8892 file.
8893 RCCOMSTR
8895 The string displayed when invoking the resource compiler to build a
8896 Microsoft Visual C++ resource file. If this is not set, then $RCCOM
8897 (the command line) is displayed.
8898 RCFLAGS
8900 The flags passed to the resource compiler by the RES builder.
8901 RCINCFLAGS
8903 An automatically-generated construction variable containing the
8904 command-line options for specifying directories to be searched by
8905 the resource compiler. The value of $RCINCFLAGS is created by
8906 appending $RCINCPREFIX and $RCINCSUFFIX to the beginning and end of
8907 each directory in $CPPPATH.
8908 RCINCPREFIX
8910 The prefix (flag) used to specify an include directory on the
8911 resource compiler command line. This will be appended to the
8912 beginning of each directory in the $CPPPATH construction variable
8913 when the $RCINCFLAGS variable is expanded.
8914 RCINCSUFFIX
8916 The suffix used to specify an include directory on the resource
8917 compiler command line. This will be appended to the end of each
8918 directory in the $CPPPATH construction variable when the
8919 $RCINCFLAGS variable is expanded.
8920 RDirs
8922 A function that converts a string into a list of Dir instances by
8923 searching the repositories.
8924 REGSVR
8926 The program used on Windows systems to register a newly-built DLL
8927 library whenever the SharedLibrary builder is passed a keyword
8928 argument of register=1.
8929 REGSVRCOM
8931 The command line used on Windows systems to register a newly-built
8932 DLL library whenever the SharedLibrary builder is passed a keyword
8933 argument of register=1.
8934 REGSVRCOMSTR
8936 The string displayed when registering a newly-built DLL file. If
8937 this is not set, then $REGSVRCOM (the command line) is displayed.
8938 REGSVRFLAGS
8940 Flags passed to the DLL registration program on Windows systems
8941 when a newly-built DLL library is registered. By default, this
8942 includes the /s that prevents dialog boxes from popping up and
8943 requiring user attention.
8944 RMIC
8946 The Java RMI stub compiler.
8947 RMICCOM
8949 The command line used to compile stub and skeleton class files from
8950 Java classes that contain RMI implementations. Any options
8951 specified in the $RMICFLAGS construction variable are included on
8952 this command line.
8953 RMICCOMSTR
8955 The string displayed when compiling stub and skeleton class files
8956 from Java classes that contain RMI implementations. If this is not
8957 set, then $RMICCOM (the command line) is displayed.
8958 env = Environment(RMICCOMSTR = "Generating stub/skeleton class files $TARGETS from $SOURCES")
8960 RMICFLAGS
8962 General options passed to the Java RMI stub compiler.
8963 _RPATH
8965 An automatically-generated construction variable containing the
8966 rpath flags to be used when linking a program with shared
8967 libraries. The value of $_RPATH is created by appending
8968 $RPATHPREFIX and $RPATHSUFFIX to the beginning and end of each
8969 directory in $RPATH.
8970 RPATH
8972 A list of paths to search for shared libraries when running
8973 programs. Currently only used in the GNU (gnulink), IRIX (sgilink)
8974 and Sun (sunlink) linkers. Ignored on platforms and toolchains that
8975 don't support it. Note that the paths added to RPATH are not
8976 transformed by scons in any way: if you want an absolute path, you
8977 must make it absolute yourself.
8978 RPATHPREFIX
8980 The prefix used to specify a directory to be searched for shared
8981 libraries when running programs. This will be appended to the
8982 beginning of each directory in the $RPATH construction variable
8983 when the $_RPATH variable is automatically generated.
8984 RPATHSUFFIX
8986 The suffix used to specify a directory to be searched for shared
8987 libraries when running programs. This will be appended to the end
8988 of each directory in the $RPATH construction variable when the
8989 $_RPATH variable is automatically generated.
8990 RPCGEN
8992 The RPC protocol compiler.
8993 RPCGENCLIENTFLAGS
8995 Options passed to the RPC protocol compiler when generating client
8996 side stubs. These are in addition to any flags specified in the
8997 $RPCGENFLAGS construction variable.
8998 RPCGENFLAGS
9000 General options passed to the RPC protocol compiler.
9001 RPCGENHEADERFLAGS
9003 Options passed to the RPC protocol compiler when generating a
9004 header file. These are in addition to any flags specified in the
9005 $RPCGENFLAGS construction variable.
9006 RPCGENSERVICEFLAGS
9008 Options passed to the RPC protocol compiler when generating server
9009 side stubs. These are in addition to any flags specified in the
9010 $RPCGENFLAGS construction variable.
9011 RPCGENXDRFLAGS
9013 Options passed to the RPC protocol compiler when generating XDR
9014 routines. These are in addition to any flags specified in the
9015 $RPCGENFLAGS construction variable.
9016 SCANNERS
9018 A list of the available implicit dependency scanners. New file
9019 scanners may be added by appending to this list, although the more
9020 flexible approach is to associate scanners with a specific Builder.
9021 See the sections "Builder Objects" and "Scanner Objects," below,
9022 for more information.
9023 SCONS_HOME
9025 The (optional) path to the SCons library directory, initialized
9026 from the external environment. If set, this is used to construct a
9027 shorter and more efficient search path in the $MSVSSCONS command
9028 line executed from Microsoft Visual Studio project files.
9029 SHCC
9031 The C compiler used for generating shared-library objects.
9032 SHCCCOM
9034 The command line used to compile a C source file to a
9035 shared-library object file. Any options specified in the $SHCFLAGS,
9036 $SHCCFLAGS and $CPPFLAGS construction variables are included on
9037 this command line.
9038 SHCCCOMSTR
9040 The string displayed when a C source file is compiled to a shared
9041 object file. If this is not set, then $SHCCCOM (the command line)
9042 is displayed.
9043 env = Environment(SHCCCOMSTR = "Compiling shared object $TARGET")
9045 SHCCFLAGS
9047 Options that are passed to the C and C++ compilers to generate
9048 shared-library objects.
9049 SHCFLAGS
9051 Options that are passed to the C compiler (only; not C++) to
9052 generate shared-library objects.
9053 SHCXX
9055 The C++ compiler used for generating shared-library objects.
9056 SHCXXCOM
9058 The command line used to compile a C++ source file to a
9059 shared-library object file. Any options specified in the
9060 $SHCXXFLAGS and $CPPFLAGS construction variables are included on
9061 this command line.
9062 SHCXXCOMSTR
9064 The string displayed when a C++ source file is compiled to a shared
9065 object file. If this is not set, then $SHCXXCOM (the command line)
9066 is displayed.
9067 env = Environment(SHCXXCOMSTR = "Compiling shared object $TARGET")
9069 SHCXXFLAGS
9071 Options that are passed to the C++ compiler to generate
9072 shared-library objects.
9073 SHDC
9075 The name of the compiler to use when compiling D source destined to
9076 be in a shared objects.
9077 The name of the compiler to use when compiling D source destined to
9079 be in a shared objects.
9080 The name of the compiler to use when compiling D source destined to
9082 be in a shared objects.
9083 SHDCOM
9085 The command line to use when compiling code to be part of shared
9086 objects.
9087 The command line to use when compiling code to be part of shared
9089 objects.
9090 The command line to use when compiling code to be part of shared
9092 objects.
9093 SHDLIBVERSION
9095 SHDLIBVERSION.
9096 SHDLIBVERSIONFLAGS
9098 SHDLIBVERSIONFLAGS.
9099 SHDLINK
9101 The linker to use when creating shared objects for code bases
9102 include D sources.
9103 The linker to use when creating shared objects for code bases
9105 include D sources.
9106 The linker to use when creating shared objects for code bases
9108 include D sources.
9109 SHDLINKCOM
9111 The command line to use when generating shared objects.
9112 The command line to use when generating shared objects.
9114 The command line to use when generating shared objects.
9116 SHDLINKFLAGS
9118 The list of flags to use when generating a shared object.
9119 The list of flags to use when generating a shared object.
9121 The list of flags to use when generating a shared object.
9123 SHELL
9125 A string naming the shell program that will be passed to the $SPAWN
9126 function. See the $SPAWN construction variable for more
9127 information.
9128 SHF03
9130 The Fortran 03 compiler used for generating shared-library objects.
9131 You should normally set the $SHFORTRAN variable, which specifies
9132 the default Fortran compiler for all Fortran versions. You only
9133 need to set $SHF03 if you need to use a specific compiler or
9134 compiler version for Fortran 03 files.
9135 SHF03COM
9137 The command line used to compile a Fortran 03 source file to a
9138 shared-library object file. You only need to set $SHF03COM if you
9139 need to use a specific command line for Fortran 03 files. You
9140 should normally set the $SHFORTRANCOM variable, which specifies the
9141 default command line for all Fortran versions.
9142 SHF03COMSTR
9144 The string displayed when a Fortran 03 source file is compiled to a
9145 shared-library object file. If this is not set, then $SHF03COM or
9146 $SHFORTRANCOM (the command line) is displayed.
9147 SHF03FLAGS
9149 Options that are passed to the Fortran 03 compiler to generated
9150 shared-library objects. You only need to set $SHF03FLAGS if you
9151 need to define specific user options for Fortran 03 files. You
9152 should normally set the $SHFORTRANFLAGS variable, which specifies
9153 the user-specified options passed to the default Fortran compiler
9154 for all Fortran versions.
9155 SHF03PPCOM
9157 The command line used to compile a Fortran 03 source file to a
9158 shared-library object file after first running the file through the
9159 C preprocessor. Any options specified in the $SHF03FLAGS and
9160 $CPPFLAGS construction variables are included on this command line.
9161 You only need to set $SHF03PPCOM if you need to use a specific
9162 C-preprocessor command line for Fortran 03 files. You should
9163 normally set the $SHFORTRANPPCOM variable, which specifies the
9164 default C-preprocessor command line for all Fortran versions.
9165 SHF03PPCOMSTR
9167 The string displayed when a Fortran 03 source file is compiled to a
9168 shared-library object file after first running the file through the
9169 C preprocessor. If this is not set, then $SHF03PPCOM or
9170 $SHFORTRANPPCOM (the command line) is displayed.
9171 SHF08
9173 The Fortran 08 compiler used for generating shared-library objects.
9174 You should normally set the $SHFORTRAN variable, which specifies
9175 the default Fortran compiler for all Fortran versions. You only
9176 need to set $SHF08 if you need to use a specific compiler or
9177 compiler version for Fortran 08 files.
9178 SHF08COM
9180 The command line used to compile a Fortran 08 source file to a
9181 shared-library object file. You only need to set $SHF08COM if you
9182 need to use a specific command line for Fortran 08 files. You
9183 should normally set the $SHFORTRANCOM variable, which specifies the
9184 default command line for all Fortran versions.
9185 SHF08COMSTR
9187 The string displayed when a Fortran 08 source file is compiled to a
9188 shared-library object file. If this is not set, then $SHF08COM or
9189 $SHFORTRANCOM (the command line) is displayed.
9190 SHF08FLAGS
9192 Options that are passed to the Fortran 08 compiler to generated
9193 shared-library objects. You only need to set $SHF08FLAGS if you
9194 need to define specific user options for Fortran 08 files. You
9195 should normally set the $SHFORTRANFLAGS variable, which specifies
9196 the user-specified options passed to the default Fortran compiler
9197 for all Fortran versions.
9198 SHF08PPCOM
9200 The command line used to compile a Fortran 08 source file to a
9201 shared-library object file after first running the file through the
9202 C preprocessor. Any options specified in the $SHF08FLAGS and
9203 $CPPFLAGS construction variables are included on this command line.
9204 You only need to set $SHF08PPCOM if you need to use a specific
9205 C-preprocessor command line for Fortran 08 files. You should
9206 normally set the $SHFORTRANPPCOM variable, which specifies the
9207 default C-preprocessor command line for all Fortran versions.
9208 SHF08PPCOMSTR
9210 The string displayed when a Fortran 08 source file is compiled to a
9211 shared-library object file after first running the file through the
9212 C preprocessor. If this is not set, then $SHF08PPCOM or
9213 $SHFORTRANPPCOM (the command line) is displayed.
9214 SHF77
9216 The Fortran 77 compiler used for generating shared-library objects.
9217 You should normally set the $SHFORTRAN variable, which specifies
9218 the default Fortran compiler for all Fortran versions. You only
9219 need to set $SHF77 if you need to use a specific compiler or
9220 compiler version for Fortran 77 files.
9221 SHF77COM
9223 The command line used to compile a Fortran 77 source file to a
9224 shared-library object file. You only need to set $SHF77COM if you
9225 need to use a specific command line for Fortran 77 files. You
9226 should normally set the $SHFORTRANCOM variable, which specifies the
9227 default command line for all Fortran versions.
9228 SHF77COMSTR
9230 The string displayed when a Fortran 77 source file is compiled to a
9231 shared-library object file. If this is not set, then $SHF77COM or
9232 $SHFORTRANCOM (the command line) is displayed.
9233 SHF77FLAGS
9235 Options that are passed to the Fortran 77 compiler to generated
9236 shared-library objects. You only need to set $SHF77FLAGS if you
9237 need to define specific user options for Fortran 77 files. You
9238 should normally set the $SHFORTRANFLAGS variable, which specifies
9239 the user-specified options passed to the default Fortran compiler
9240 for all Fortran versions.
9241 SHF77PPCOM
9243 The command line used to compile a Fortran 77 source file to a
9244 shared-library object file after first running the file through the
9245 C preprocessor. Any options specified in the $SHF77FLAGS and
9246 $CPPFLAGS construction variables are included on this command line.
9247 You only need to set $SHF77PPCOM if you need to use a specific
9248 C-preprocessor command line for Fortran 77 files. You should
9249 normally set the $SHFORTRANPPCOM variable, which specifies the
9250 default C-preprocessor command line for all Fortran versions.
9251 SHF77PPCOMSTR
9253 The string displayed when a Fortran 77 source file is compiled to a
9254 shared-library object file after first running the file through the
9255 C preprocessor. If this is not set, then $SHF77PPCOM or
9256 $SHFORTRANPPCOM (the command line) is displayed.
9257 SHF90
9259 The Fortran 90 compiler used for generating shared-library objects.
9260 You should normally set the $SHFORTRAN variable, which specifies
9261 the default Fortran compiler for all Fortran versions. You only
9262 need to set $SHF90 if you need to use a specific compiler or
9263 compiler version for Fortran 90 files.
9264 SHF90COM
9266 The command line used to compile a Fortran 90 source file to a
9267 shared-library object file. You only need to set $SHF90COM if you
9268 need to use a specific command line for Fortran 90 files. You
9269 should normally set the $SHFORTRANCOM variable, which specifies the
9270 default command line for all Fortran versions.
9271 SHF90COMSTR
9273 The string displayed when a Fortran 90 source file is compiled to a
9274 shared-library object file. If this is not set, then $SHF90COM or
9275 $SHFORTRANCOM (the command line) is displayed.
9276 SHF90FLAGS
9278 Options that are passed to the Fortran 90 compiler to generated
9279 shared-library objects. You only need to set $SHF90FLAGS if you
9280 need to define specific user options for Fortran 90 files. You
9281 should normally set the $SHFORTRANFLAGS variable, which specifies
9282 the user-specified options passed to the default Fortran compiler
9283 for all Fortran versions.
9284 SHF90PPCOM
9286 The command line used to compile a Fortran 90 source file to a
9287 shared-library object file after first running the file through the
9288 C preprocessor. Any options specified in the $SHF90FLAGS and
9289 $CPPFLAGS construction variables are included on this command line.
9290 You only need to set $SHF90PPCOM if you need to use a specific
9291 C-preprocessor command line for Fortran 90 files. You should
9292 normally set the $SHFORTRANPPCOM variable, which specifies the
9293 default C-preprocessor command line for all Fortran versions.
9294 SHF90PPCOMSTR
9296 The string displayed when a Fortran 90 source file is compiled to a
9297 shared-library object file after first running the file through the
9298 C preprocessor. If this is not set, then $SHF90PPCOM or
9299 $SHFORTRANPPCOM (the command line) is displayed.
9300 SHF95
9302 The Fortran 95 compiler used for generating shared-library objects.
9303 You should normally set the $SHFORTRAN variable, which specifies
9304 the default Fortran compiler for all Fortran versions. You only
9305 need to set $SHF95 if you need to use a specific compiler or
9306 compiler version for Fortran 95 files.
9307 SHF95COM
9309 The command line used to compile a Fortran 95 source file to a
9310 shared-library object file. You only need to set $SHF95COM if you
9311 need to use a specific command line for Fortran 95 files. You
9312 should normally set the $SHFORTRANCOM variable, which specifies the
9313 default command line for all Fortran versions.
9314 SHF95COMSTR
9316 The string displayed when a Fortran 95 source file is compiled to a
9317 shared-library object file. If this is not set, then $SHF95COM or
9318 $SHFORTRANCOM (the command line) is displayed.
9319 SHF95FLAGS
9321 Options that are passed to the Fortran 95 compiler to generated
9322 shared-library objects. You only need to set $SHF95FLAGS if you
9323 need to define specific user options for Fortran 95 files. You
9324 should normally set the $SHFORTRANFLAGS variable, which specifies
9325 the user-specified options passed to the default Fortran compiler
9326 for all Fortran versions.
9327 SHF95PPCOM
9329 The command line used to compile a Fortran 95 source file to a
9330 shared-library object file after first running the file through the
9331 C preprocessor. Any options specified in the $SHF95FLAGS and
9332 $CPPFLAGS construction variables are included on this command line.
9333 You only need to set $SHF95PPCOM if you need to use a specific
9334 C-preprocessor command line for Fortran 95 files. You should
9335 normally set the $SHFORTRANPPCOM variable, which specifies the
9336 default C-preprocessor command line for all Fortran versions.
9337 SHF95PPCOMSTR
9339 The string displayed when a Fortran 95 source file is compiled to a
9340 shared-library object file after first running the file through the
9341 C preprocessor. If this is not set, then $SHF95PPCOM or
9342 $SHFORTRANPPCOM (the command line) is displayed.
9343 SHFORTRAN
9345 The default Fortran compiler used for generating shared-library
9346 objects.
9347 SHFORTRANCOM
9349 The command line used to compile a Fortran source file to a
9350 shared-library object file.
9351 SHFORTRANCOMSTR
9353 The string displayed when a Fortran source file is compiled to a
9354 shared-library object file. If this is not set, then $SHFORTRANCOM
9355 (the command line) is displayed.
9356 SHFORTRANFLAGS
9358 Options that are passed to the Fortran compiler to generate
9359 shared-library objects.
9360 SHFORTRANPPCOM
9362 The command line used to compile a Fortran source file to a
9363 shared-library object file after first running the file through the
9364 C preprocessor. Any options specified in the $SHFORTRANFLAGS and
9365 $CPPFLAGS construction variables are included on this command line.
9366 SHFORTRANPPCOMSTR
9368 The string displayed when a Fortran source file is compiled to a
9369 shared-library object file after first running the file through the
9370 C preprocessor. If this is not set, then $SHFORTRANPPCOM (the
9371 command line) is displayed.
9372 SHLIBEMITTER
9374 TODO
9375 SHLIBNOVERSIONSYMLINKS
9377 Instructs the SharedLibrary builder to not create symlinks for
9378 versioned shared libraries.
9379 SHLIBPREFIX
9381 The prefix used for shared library file names.
9382 _SHLIBSONAME
9384 A macro that automatically generates shared library's SONAME based
9385 on $TARGET, $SHLIBVERSION and $SHLIBSUFFIX. Used by SharedLibrary
9386 builder when the linker tool supports SONAME (e.g. gnulink).
9387 SHLIBSUFFIX
9389 The suffix used for shared library file names.
9390 SHLIBVERSION
9392 When this construction variable is defined, a versioned shared
9393 library is created by SharedLibrary builder. This activates the
9394 $_SHLIBVERSIONFLAGS and thus modifies the $SHLINKCOM as required,
9395 adds the version number to the library name, and creates the
9396 symlinks that are needed. $SHLIBVERSION versions should exist as
9397 alpha-numeric, decimal-delimited values as defined by the regular
9398 expression "\w+[\.\w+]*". Example $SHLIBVERSION values include '1',
9399 '1.2.3', and '1.2.gitaa412c8b'.
9400 _SHLIBVERSIONFLAGS
9402 This macro automatically introduces extra flags to $SHLINKCOM when
9403 building versioned SharedLibrary (that is when $SHLIBVERSION is
9404 set). _SHLIBVERSIONFLAGS usually adds $SHLIBVERSIONFLAGS and some
9405 extra dynamically generated options (such as
9406 -Wl,-soname=$_SHLIBSONAME. It is unused by "plain" (unversioned)
9407 shared libraries.
9408 SHLIBVERSIONFLAGS
9410 Extra flags added to $SHLINKCOM when building versioned
9411 SharedLibrary. These flags are only used when $SHLIBVERSION is set.
9412 SHLINK
9414 The linker for programs that use shared libraries.
9415 SHLINKCOM
9417 The command line used to link programs using shared libraries.
9418 SHLINKCOMSTR
9420 The string displayed when programs using shared libraries are
9421 linked. If this is not set, then $SHLINKCOM (the command line) is
9422 displayed.
9423 env = Environment(SHLINKCOMSTR = "Linking shared $TARGET")
9425 SHLINKFLAGS
9427 General user options passed to the linker for programs using shared
9428 libraries. Note that this variable should not contain -l (or
9429 similar) options for linking with the libraries listed in $LIBS,
9430 nor -L (or similar) include search path options that scons
9431 generates automatically from $LIBPATH. See $_LIBFLAGS above, for
9432 the variable that expands to library-link options, and
9433 $_LIBDIRFLAGS above, for the variable that expands to library
9434 search path options.
9435 SHOBJPREFIX
9437 The prefix used for shared object file names.
9438 SHOBJSUFFIX
9440 The suffix used for shared object file names.
9441 SONAME
9443 Variable used to hard-code SONAME for versioned shared
9444 library/loadable module.
9445 env.SharedLibrary('test', 'test.c', SHLIBVERSION='0.1.2', SONAME='libtest.so.2')
9447 The variable is used, for example, by gnulink linker tool.
9449 SOURCE
9451 A reserved variable name that may not be set or used in a
9452 construction environment. (See "Variable Substitution," below.)
9453 SOURCE_URL
9455 The URL (web address) of the location from which the project was
9456 retrieved. This is used to fill in the Source: field in the
9457 controlling information for Ipkg and RPM packages.
9458 SOURCES
9460 A reserved variable name that may not be set or used in a
9461 construction environment. (See "Variable Substitution," below.)
9462 SPAWN
9464 A command interpreter function that will be called to execute
9465 command line strings. The function must expect the following
9466 arguments:
9467 def spawn(shell, escape, cmd, args, env):
9469 sh is a string naming the shell program to use. escape is a
9472 function that can be called to escape shell special characters in
9473 the command line. cmd is the path to the command to be executed.
9474 args is the arguments to the command. env is a dictionary of the
9475 environment variables in which the command should be executed.
9476 STATIC_AND_SHARED_OBJECTS_ARE_THE_SAME
9478 When this variable is true, static objects and shared objects are
9479 assumed to be the same; that is, SCons does not check for linking
9480 static objects into a shared library.
9481 SUBST_DICT
9483 The dictionary used by the Substfile or Textfile builders for
9484 substitution values. It can be anything acceptable to the dict()
9485 constructor, so in addition to a dictionary, lists of tuples are
9486 also acceptable.
9487 SUBSTFILEPREFIX
9489 The prefix used for Substfile file names, the null string by
9490 default.
9491 SUBSTFILESUFFIX
9493 The suffix used for Substfile file names, the null string by
9494 default.
9495 SUMMARY
9497 A short summary of what the project is about. This is used to fill
9498 in the Summary: field in the controlling information for Ipkg and
9499 RPM packages, and as the Description: field in MSI packages.
9500 SWIG
9502 The scripting language wrapper and interface generator.
9503 SWIGCFILESUFFIX
9505 The suffix that will be used for intermediate C source files
9506 generated by the scripting language wrapper and interface
9507 generator. The default value is _wrap$CFILESUFFIX. By default, this
9508 value is used whenever the -c++ option is not specified as part of
9509 the $SWIGFLAGS construction variable.
9510 SWIGCOM
9512 The command line used to call the scripting language wrapper and
9513 interface generator.
9514 SWIGCOMSTR
9516 The string displayed when calling the scripting language wrapper
9517 and interface generator. If this is not set, then $SWIGCOM (the
9518 command line) is displayed.
9519 SWIGCXXFILESUFFIX
9521 The suffix that will be used for intermediate C++ source files
9522 generated by the scripting language wrapper and interface
9523 generator. The default value is _wrap$CFILESUFFIX. By default, this
9524 value is used whenever the -c++ option is specified as part of the
9525 $SWIGFLAGS construction variable.
9526 SWIGDIRECTORSUFFIX
9528 The suffix that will be used for intermediate C++ header files
9529 generated by the scripting language wrapper and interface
9530 generator. These are only generated for C++ code when the SWIG
9531 'directors' feature is turned on. The default value is _wrap.h.
9532 SWIGFLAGS
9534 General options passed to the scripting language wrapper and
9535 interface generator. This is where you should set -python, -perl5,
9536 -tcl, or whatever other options you want to specify to SWIG. If you
9537 set the -c++ option in this variable, scons will, by default,
9538 generate a C++ intermediate source file with the extension that is
9539 specified as the $CXXFILESUFFIX variable.
9540 _SWIGINCFLAGS
9542 An automatically-generated construction variable containing the
9543 SWIG command-line options for specifying directories to be searched
9544 for included files. The value of $_SWIGINCFLAGS is created by
9545 appending $SWIGINCPREFIX and $SWIGINCSUFFIX to the beginning and
9546 end of each directory in $SWIGPATH.
9547 SWIGINCPREFIX
9549 The prefix used to specify an include directory on the SWIG command
9550 line. This will be appended to the beginning of each directory in
9551 the $SWIGPATH construction variable when the $_SWIGINCFLAGS
9552 variable is automatically generated.
9553 SWIGINCSUFFIX
9555 The suffix used to specify an include directory on the SWIG command
9556 line. This will be appended to the end of each directory in the
9557 $SWIGPATH construction variable when the $_SWIGINCFLAGS variable is
9558 automatically generated.
9559 SWIGOUTDIR
9561 Specifies the output directory in which the scripting language
9562 wrapper and interface generator should place generated
9563 language-specific files. This will be used by SCons to identify the
9564 files that will be generated by the swig call, and translated into
9565 the swig -outdir option on the command line.
9566 SWIGPATH
9568 The list of directories that the scripting language wrapper and
9569 interface generate will search for included files. The SWIG
9570 implicit dependency scanner will search these directories for
9571 include files. The default value is an empty list.
9572 Don't explicitly put include directory arguments in SWIGFLAGS; the
9574 result will be non-portable and the directories will not be
9575 searched by the dependency scanner. Note: directory names in
9576 SWIGPATH will be looked-up relative to the SConscript directory
9577 when they are used in a command. To force scons to look-up a
9578 directory relative to the root of the source tree use #:
9579 env = Environment(SWIGPATH='#/include')
9581 The directory look-up can also be forced using the Dir() function:
9583 include = Dir('include')
9585 env = Environment(SWIGPATH=include)
9586 The directory list will be added to command lines through the
9588 automatically-generated $_SWIGINCFLAGS construction variable, which
9589 is constructed by appending the values of the $SWIGINCPREFIX and
9590 $SWIGINCSUFFIX construction variables to the beginning and end of
9591 each directory in $SWIGPATH. Any command lines you define that need
9592 the SWIGPATH directory list should include $_SWIGINCFLAGS:
9593 env = Environment(SWIGCOM="my_swig -o $TARGET $_SWIGINCFLAGS $SOURCES")
9595 SWIGVERSION
9597 The version number of the SWIG tool.
9598 TAR
9600 The tar archiver.
9601 TARCOM
9603 The command line used to call the tar archiver.
9604 TARCOMSTR
9606 The string displayed when archiving files using the tar archiver.
9607 If this is not set, then $TARCOM (the command line) is displayed.
9608 env = Environment(TARCOMSTR = "Archiving $TARGET")
9610 TARFLAGS
9612 General options passed to the tar archiver.
9613 TARGET
9615 A reserved variable name that may not be set or used in a
9616 construction environment. (See "Variable Substitution," below.)
9617 TARGET_ARCH
9619 The name of the target hardware architecture for the compiled
9620 objects created by this Environment. This defaults to the value of
9621 HOST_ARCH, and the user can override it. Currently only set for
9622 Win32.
9623 Sets the target architecture for Visual Studio compiler (i.e. the
9625 arch of the binaries generated by the compiler). If not set,
9626 default to $HOST_ARCH, or, if that is unset, to the architecture of
9627 the running machine's OS (note that the python build or
9628 architecture has no effect). This variable must be passed as an
9629 argument to the Environment() constructor; setting it later has no
9630 effect. This is currently only used on Windows, but in the future
9631 it will be used on other OSes as well.
9632 Valid values for Windows are x86, i386 (for 32 bits); amd64, emt64,
9634 x86_64 (for 64 bits); and ia64 (Itanium). For example, if you want
9635 to compile 64-bit binaries, you would set TARGET_ARCH='x86_64' in
9636 your SCons environment.
9637 TARGET_OS
9639 The name of the target operating system for the compiled objects
9640 created by this Environment. This defaults to the value of HOST_OS,
9641 and the user can override it. Currently only set for Win32.
9642 TARGETS
9644 A reserved variable name that may not be set or used in a
9645 construction environment. (See "Variable Substitution," below.)
9646 TARSUFFIX
9648 The suffix used for tar file names.
9649 TEMPFILEPREFIX
9651 The prefix for a temporary file used to execute lines longer than
9652 $MAXLINELENGTH. The default is '@'. This may be set for toolchains
9653 that use other values, such as '-@' for the diab compiler or '-via'
9654 for ARM toolchain.
9655 TEX
9657 The TeX formatter and typesetter.
9658 TEXCOM
9660 The command line used to call the TeX formatter and typesetter.
9661 TEXCOMSTR
9663 The string displayed when calling the TeX formatter and typesetter.
9664 If this is not set, then $TEXCOM (the command line) is displayed.
9665 env = Environment(TEXCOMSTR = "Building $TARGET from TeX input $SOURCES")
9667 TEXFLAGS
9669 General options passed to the TeX formatter and typesetter.
9670 TEXINPUTS
9672 List of directories that the LaTeX program will search for include
9673 directories. The LaTeX implicit dependency scanner will search
9674 these directories for \include and \import files.
9675 TEXTFILEPREFIX
9677 The prefix used for Textfile file names, the null string by
9678 default.
9679 TEXTFILESUFFIX
9681 The suffix used for Textfile file names; .txt by default.
9682 TOOLS
9684 A list of the names of the Tool specifications that are part of
9685 this construction environment.
9686 UNCHANGED_SOURCES
9688 A reserved variable name that may not be set or used in a
9689 construction environment. (See "Variable Substitution," below.)
9690 UNCHANGED_TARGETS
9692 A reserved variable name that may not be set or used in a
9693 construction environment. (See "Variable Substitution," below.)
9694 VENDOR
9696 The person or organization who supply the packaged software. This
9697 is used to fill in the Vendor: field in the controlling information
9698 for RPM packages, and the Manufacturer: field in the controlling
9699 information for MSI packages.
9700 VERSION
9702 The version of the project, specified as a string.
9703 WIN32_INSERT_DEF
9705 A deprecated synonym for $WINDOWS_INSERT_DEF.
9706 WIN32DEFPREFIX
9708 A deprecated synonym for $WINDOWSDEFPREFIX.
9709 WIN32DEFSUFFIX
9711 A deprecated synonym for $WINDOWSDEFSUFFIX.
9712 WIN32EXPPREFIX
9714 A deprecated synonym for $WINDOWSEXPSUFFIX.
9715 WIN32EXPSUFFIX
9717 A deprecated synonym for $WINDOWSEXPSUFFIX.
9718 WINDOWS_EMBED_MANIFEST
9720 Set this variable to True or 1 to embed the compiler-generated
9721 manifest (normally ${TARGET}.manifest) into all Windows exes and
9722 DLLs built with this environment, as a resource during their link
9723 step. This is done using $MT and $MTEXECOM and $MTSHLIBCOM.
9724 WINDOWS_INSERT_DEF
9726 When this is set to true, a library build of a Windows shared
9727 library (.dll file) will also build a corresponding .def file at
9728 the same time, if a .def file is not already listed as a build
9729 target. The default is 0 (do not build a .def file).
9730 WINDOWS_INSERT_MANIFEST
9732 When this is set to true, scons will be aware of the .manifest
9733 files generated by Microsoft Visua C/C++ 8.
9734 WINDOWSDEFPREFIX
9736 The prefix used for Windows .def file names.
9737 WINDOWSDEFSUFFIX
9739 The suffix used for Windows .def file names.
9740 WINDOWSEXPPREFIX
9742 The prefix used for Windows .exp file names.
9743 WINDOWSEXPSUFFIX
9745 The suffix used for Windows .exp file names.
9746 WINDOWSPROGMANIFESTPREFIX
9748 The prefix used for executable program .manifest files generated by
9749 Microsoft Visual C/C++.
9750 WINDOWSPROGMANIFESTSUFFIX
9752 The suffix used for executable program .manifest files generated by
9753 Microsoft Visual C/C++.
9754 WINDOWSSHLIBMANIFESTPREFIX
9756 The prefix used for shared library .manifest files generated by
9757 Microsoft Visual C/C++.
9758 WINDOWSSHLIBMANIFESTSUFFIX
9760 The suffix used for shared library .manifest files generated by
9761 Microsoft Visual C/C++.
9762 X_IPK_DEPENDS
9764 This is used to fill in the Depends: field in the controlling
9765 information for Ipkg packages.
9766 X_IPK_DESCRIPTION
9768 This is used to fill in the Description: field in the controlling
9769 information for Ipkg packages. The default value is
9770 $SUMMARY\n$DESCRIPTION
9771 X_IPK_MAINTAINER
9773 This is used to fill in the Maintainer: field in the controlling
9774 information for Ipkg packages.
9775 X_IPK_PRIORITY
9777 This is used to fill in the Priority: field in the controlling
9778 information for Ipkg packages.
9779 X_IPK_SECTION
9781 This is used to fill in the Section: field in the controlling
9782 information for Ipkg packages.
9783 X_MSI_LANGUAGE
9785 This is used to fill in the Language: attribute in the controlling
9786 information for MSI packages.
9787 X_MSI_LICENSE_TEXT
9789 The text of the software license in RTF format. Carriage return
9790 characters will be replaced with the RTF equivalent \\par.
9791 X_MSI_UPGRADE_CODE
9793 TODO
9794 X_RPM_AUTOREQPROV
9796 This is used to fill in the AutoReqProv: field in the RPM .spec
9797 file.
9798 X_RPM_BUILD
9800 internal, but overridable
9801 X_RPM_BUILDREQUIRES
9803 This is used to fill in the BuildRequires: field in the RPM .spec
9804 file.
9805 X_RPM_BUILDROOT
9807 internal, but overridable
9808 X_RPM_CLEAN
9810 internal, but overridable
9811 X_RPM_CONFLICTS
9813 This is used to fill in the Conflicts: field in the RPM .spec file.
9814 X_RPM_DEFATTR
9816 This value is used as the default attributes for the files in the
9817 RPM package. The default value is (-,root,root).
9818 X_RPM_DISTRIBUTION
9820 This is used to fill in the Distribution: field in the RPM .spec
9821 file.
9822 X_RPM_EPOCH
9824 This is used to fill in the Epoch: field in the controlling
9825 information for RPM packages.
9826 X_RPM_EXCLUDEARCH
9828 This is used to fill in the ExcludeArch: field in the RPM .spec
9829 file.
9830 X_RPM_EXLUSIVEARCH
9832 This is used to fill in the ExclusiveArch: field in the RPM .spec
9833 file.
9834 X_RPM_GROUP
9836 This is used to fill in the Group: field in the RPM .spec file.
9837 X_RPM_GROUP_lang
9839 This is used to fill in the Group(lang): field in the RPM .spec
9840 file. Note that lang is not literal and should be replaced by the
9841 appropriate language code.
9842 X_RPM_ICON
9844 This is used to fill in the Icon: field in the RPM .spec file.
9845 X_RPM_INSTALL
9847 internal, but overridable
9848 X_RPM_PACKAGER
9850 This is used to fill in the Packager: field in the RPM .spec file.
9851 X_RPM_POSTINSTALL
9853 This is used to fill in the %post: section in the RPM .spec file.
9854 X_RPM_POSTUNINSTALL
9856 This is used to fill in the %postun: section in the RPM .spec file.
9857 X_RPM_PREFIX
9859 This is used to fill in the Prefix: field in the RPM .spec file.
9860 X_RPM_PREINSTALL
9862 This is used to fill in the %pre: section in the RPM .spec file.
9863 X_RPM_PREP
9865 internal, but overridable
9866 X_RPM_PREUNINSTALL
9868 This is used to fill in the %preun: section in the RPM .spec file.
9869 X_RPM_PROVIDES
9871 This is used to fill in the Provides: field in the RPM .spec file.
9872 X_RPM_REQUIRES
9874 This is used to fill in the Requires: field in the RPM .spec file.
9875 X_RPM_SERIAL
9877 This is used to fill in the Serial: field in the RPM .spec file.
9878 X_RPM_URL
9880 This is used to fill in the Url: field in the RPM .spec file.
9881 XGETTEXT
9883 Path to xgettext(1) program (found via Detect()). See xgettext tool
9884 and POTUpdate builder.
9885 XGETTEXTCOM
9887 Complete xgettext command line. See xgettext tool and POTUpdate
9888 builder.
9889 XGETTEXTCOMSTR
9891 A string that is shown when xgettext(1) command is invoked
9892 (default: '', which means "print $XGETTEXTCOM"). See xgettext tool
9893 and POTUpdate builder.
9894 _XGETTEXTDOMAIN
9896 Internal "macro". Generates xgettext domain name form source and
9897 target (default: '${TARGET.filebase}').
9898 XGETTEXTFLAGS
9900 Additional flags to xgettext(1). See xgettext tool and POTUpdate
9901 builder.
9902 XGETTEXTFROM
9904 Name of file containing list of xgettext(1)'s source files.
9905 Autotools' users know this as POTFILES.in so they will in most
9906 cases set XGETTEXTFROM="POTFILES.in" here. The $XGETTEXTFROM files
9907 have same syntax and semantics as the well known GNU POTFILES.in.
9908 See xgettext tool and POTUpdate builder.
9909 _XGETTEXTFROMFLAGS
9911 Internal "macro". Genrates list of -D<dir> flags from the
9912 $XGETTEXTPATH list.
9913 XGETTEXTFROMPREFIX
9915 This flag is used to add single $XGETTEXTFROM file to xgettext(1)'s
9916 commandline (default: '-f').
9917 XGETTEXTFROMSUFFIX
9919 (default: '')
9920 XGETTEXTPATH
9922 List of directories, there xgettext(1) will look for source files
9923 (default: []).
9924 Note
9926 This variable works only together with $XGETTEXTFROM
9927 See also xgettext tool and POTUpdate builder.
9928 _XGETTEXTPATHFLAGS
9930 Internal "macro". Generates list of -f<file> flags from
9931 $XGETTEXTFROM.
9932 XGETTEXTPATHPREFIX
9934 This flag is used to add single search path to xgettext(1)'s
9935 commandline (default: '-D').
9936 XGETTEXTPATHSUFFIX
9938 (default: '')
9939 YACC
9941 The parser generator.
9942 YACCCOM
9944 The command line used to call the parser generator to generate a
9945 source file.
9946 YACCCOMSTR
9948 The string displayed when generating a source file using the parser
9949 generator. If this is not set, then $YACCCOM (the command line) is
9950 displayed.
9951 env = Environment(YACCCOMSTR = "Yacc'ing $TARGET from $SOURCES")
9953 YACCFLAGS
9955 General options passed to the parser generator. If $YACCFLAGS
9956 contains a -d option, SCons assumes that the call will also create
9957 a .h file (if the yacc source file ends in a .y suffix) or a .hpp
9958 file (if the yacc source file ends in a .yy suffix)
9959 YACCHFILESUFFIX
9961 The suffix of the C header file generated by the parser generator
9962 when the -d option is used. Note that setting this variable does
9963 not cause the parser generator to generate a header file with the
9964 specified suffix, it exists to allow you to specify what suffix the
9965 parser generator will use of its own accord. The default value is
9966 .h.
9967 YACCHXXFILESUFFIX
9969 The suffix of the C++ header file generated by the parser generator
9970 when the -d option is used. Note that setting this variable does
9971 not cause the parser generator to generate a header file with the
9972 specified suffix, it exists to allow you to specify what suffix the
9973 parser generator will use of its own accord. The default value is
9974 .hpp, except on Mac OS X, where the default is ${TARGET.suffix}.h.
9975 because the default bison parser generator just appends .h to the
9976 name of the generated C++ file.
9977 YACCVCGFILESUFFIX
9979 The suffix of the file containing the VCG grammar automaton
9980 definition when the --graph= option is used. Note that setting this
9981 variable does not cause the parser generator to generate a VCG file
9982 with the specified suffix, it exists to allow you to specify what
9983 suffix the parser generator will use of its own accord. The default
9984 value is .vcg.
9985 ZIP
9987 The zip compression and file packaging utility.
9988 ZIPCOM
9990 The command line used to call the zip utility, or the internal
9991 Python function used to create a zip archive.
9992 ZIPCOMPRESSION
9994 The compression flag from the Python zipfile module used by the
9995 internal Python function to control whether the zip archive is
9996 compressed or not. The default value is zipfile.ZIP_DEFLATED, which
9997 creates a compressed zip archive. This value has no effect if the
9998 zipfile module is unavailable.
9999 ZIPCOMSTR
10001 The string displayed when archiving files using the zip utility. If
10002 this is not set, then $ZIPCOM (the command line or internal Python
10003 function) is displayed.
10004 env = Environment(ZIPCOMSTR = "Zipping $TARGET")
10006 ZIPFLAGS
10008 General options passed to the zip utility.
10009 ZIPROOT
10011 An optional zip root directory (default empty). The filenames
10012 stored in the zip file will be relative to this directory, if
10013 given. Otherwise the filenames are relative to the current
10014 directory of the command. For instance:
10015 env = Environment()
10017 env.Zip('foo.zip', 'subdir1/subdir2/file1', ZIPROOT='subdir1')
10018 will produce a zip file foo.zip containing a file with the name
10020 subdir2/file1 rather than subdir1/subdir2/file1.
10021 ZIPSUFFIX
10023 The suffix used for zip file names.
10024 Construction variables can be retrieved and set using the Dictionary
10026 method of the construction environment:
10027 dict = env.Dictionary()
10029 dict["CC"] = "cc"
10030 or using the [] operator:
10032 env["CC"] = "cc"
10034 Construction variables can also be passed to the construction
10036 environment constructor:
10037 env = Environment(CC="cc")
10039 or when copying a construction environment using the Clone method:
10041 env2 = env.Clone(CC="cl.exe")
10043 Configure Contexts
10045 scons supports configure contexts, an integrated mechanism similar to
10046 the various AC_CHECK macros in GNU autoconf for testing for the
10047 existence of C header files, libraries, etc. In contrast to autoconf,
10048 scons does not maintain an explicit cache of the tested values, but
10049 uses its normal dependency tracking to keep the checked values up to
10050 date. However, users may override this behaviour with the --config
10051 command line option.
10052 The following methods can be used to perform checks:
10054 Configure(env, [custom_tests, conf_dir, log_file, config_h, clean,
10056 help]), env.Configure([custom_tests, conf_dir, log_file, config_h,
10057 clean, help])
10058 This creates a configure context, which can be used to perform
10059 checks. env specifies the environment for building the tests. This
10060 environment may be modified when performing checks. custom_tests
10061 is a dictionary containing custom tests. See also the section about
10062 custom tests below. By default, no custom tests are added to the
10063 configure context. conf_dir specifies a directory where the test
10064 cases are built. Note that this directory is not used for building
10065 normal targets. The default value is the directory #/.sconf_temp.
10066 log_file specifies a file which collects the output from commands
10067 that are executed to check for the existence of header files,
10068 libraries, etc. The default is the file #/config.log. If you are
10069 using the VariantDir() method, you may want to specify a
10070 subdirectory under your variant directory. config_h specifies a C
10071 header file where the results of tests will be written, e.g.
10072 #define HAVE_STDIO_H, #define HAVE_LIBM, etc. The default is to not
10073 write a config.h file. You can specify the same config.h file in
10074 multiple calls to Configure, in which case scons will concatenate
10075 all results in the specified file. Note that SCons uses its normal
10076 dependency checking to decide if it's necessary to rebuild the
10077 specified config_h file. This means that the file is not
10078 necessarily re-built each time scons is run, but is only rebuilt if
10079 its contents will have changed and some target that depends on the
10080 config_h file is being built.
10081 The optional clean and help arguments can be used to suppress
10083 execution of the configuration tests when the -c/--clean or
10084 -H/-h/--help options are used, respectively. The default behavior
10085 is always to execute configure context tests, since the results of
10086 the tests may affect the list of targets to be cleaned or the help
10087 text. If the configure tests do not affect these, then you may add
10088 the clean=False or help=False arguments (or both) to avoid
10089 unnecessary test execution.
10090 A created Configure instance has the following associated methods:
10092 SConf.Finish(context), sconf.Finish()
10094 This method should be called after configuration is done. It
10095 returns the environment as modified by the configuration checks
10096 performed. After this method is called, no further checks can be
10097 performed with this configuration context. However, you can create
10098 a new Configure context to perform additional checks. Only one
10099 context should be active at a time.
10100 The following Checks are predefined. (This list will likely grow
10102 larger as time goes by and developers contribute new useful tests.)
10103 SConf.CheckHeader(context, header, [include_quotes, language]),
10105 sconf.CheckHeader(header, [include_quotes, language])
10106 Checks if header is usable in the specified language. header may
10107 be a list, in which case the last item in the list is the header
10108 file to be checked, and the previous list items are header files
10109 whose #include lines should precede the header line being checked
10110 for. The optional argument include_quotes must be a two character
10111 string, where the first character denotes the opening quote and the
10112 second character denotes the closing quote. By default, both
10113 characters are " (double quote). The optional argument language
10114 should be either C or C++ and selects the compiler to be used for
10115 the check. Returns 1 on success and 0 on failure.
10116 SConf.CheckCHeader(context, header, [include_quotes]),
10118 sconf.CheckCHeader(header, [include_quotes])
10119 This is a wrapper around SConf.CheckHeader which checks if header
10120 is usable in the C language. header may be a list, in which case
10121 the last item in the list is the header file to be checked, and the
10122 previous list items are header files whose #include lines should
10123 precede the header line being checked for. The optional argument
10124 include_quotes must be a two character string, where the first
10125 character denotes the opening quote and the second character
10126 denotes the closing quote (both default to \N'34'). Returns 1 on
10127 success and 0 on failure.
10128 SConf.CheckCXXHeader(context, header, [include_quotes]),
10130 sconf.CheckCXXHeader(header, [include_quotes])
10131 This is a wrapper around SConf.CheckHeader which checks if header
10132 is usable in the C++ language. header may be a list, in which case
10133 the last item in the list is the header file to be checked, and the
10134 previous list items are header files whose #include lines should
10135 precede the header line being checked for. The optional argument
10136 include_quotes must be a two character string, where the first
10137 character denotes the opening quote and the second character
10138 denotes the closing quote (both default to \N'34'). Returns 1 on
10139 success and 0 on failure.
10140 SConf.CheckFunc(context,, function_name, [header, language]),
10142 sconf.CheckFunc(function_name, [header, language])
10143 Checks if the specified C or C++ function is available.
10144 function_name is the name of the function to check for. The
10145 optional header argument is a string that will be placed at the top
10146 of the test file that will be compiled to check if the function
10147 exists; the default is:
10148 #ifdef __cplusplus
10150 extern "C"
10151 #endif
10152 char function_name();
10153 The optional language argument should be C or C++ and selects the
10155 compiler to be used for the check; the default is "C".
10156 SConf.CheckLib(context, [library, symbol, header, language,
10158 autoadd=1]), sconf.CheckLib([library, symbol, header, language,
10159 autoadd=1])
10160 Checks if library provides symbol. If the value of autoadd is 1 and
10161 the library provides the specified symbol, appends the library to
10162 the LIBS construction environment variable. library may also be
10163 None (the default), in which case symbol is checked with the
10164 current LIBS variable, or a list of library names, in which case
10165 each library in the list will be checked for symbol. If symbol is
10166 not set or is None, then SConf.CheckLib() just checks if you can
10167 link against the specified library. The optional language argument
10168 should be C or C++ and selects the compiler to be used for the
10169 check; the default is "C". The default value for autoadd is 1. This
10170 method returns 1 on success and 0 on error.
10171 SConf.CheckLibWithHeader(context, library, header, language, [call,
10173 autoadd]), sconf.CheckLibWithHeader(library, header, language, [call,
10174 autoadd])
10175 In contrast to the SConf.CheckLib call, this call provides a more
10176 sophisticated way to check against libraries. Again, library
10177 specifies the library or a list of libraries to check. header
10178 specifies a header to check for. header may be a list, in which
10179 case the last item in the list is the header file to be checked,
10180 and the previous list items are header files whose #include lines
10181 should precede the header line being checked for. language may be
10182 one of 'C','c','CXX','cxx','C++' and 'c++'. call can be any valid
10183 expression (with a trailing ';'). If call is not set, the default
10184 simply checks that you can link against the specified library.
10185 autoadd specifies whether to add the library to the environment
10186 (only if the check succeeds). This method returns 1 on success and
10187 0 on error.
10188 SConf.CheckType(context, type_name, [includes, language]),
10190 sconf.CheckType(type_name, [includes, language])
10191 Checks for the existence of a type defined by typedef. type_name
10192 specifies the typedef name to check for. includes is a string
10193 containing one or more #include lines that will be inserted into
10194 the program that will be run to test for the existence of the type.
10195 The optional language argument should be C or C++ and selects the
10196 compiler to be used for the check; the default is "C". Example:
10197 sconf.CheckType('foo_type', '#include "my_types.h"', 'C++')
10199 Configure.CheckCC(self)
10201 Checks whether the C compiler (as defined by the CC construction
10202 variable) works by trying to compile a small source file.
10203 By default, SCons only detects if there is a program with the
10205 correct name, not if it is a functioning compiler.
10206 This uses the exact same command than the one used by the object
10208 builder for C source file, so it can be used to detect if a
10209 particular compiler flag works or not.
10210 Configure.CheckCXX(self)
10212 Checks whether the C++ compiler (as defined by the CXX construction
10213 variable) works by trying to compile a small source file. By
10214 default, SCons only detects if there is a program with the correct
10215 name, not if it is a functioning compiler.
10216 This uses the exact same command than the one used by the object
10218 builder for CXX source files, so it can be used to detect if a
10219 particular compiler flag works or not.
10220 Configure.CheckSHCC(self)
10222 Checks whether the C compiler (as defined by the SHCC construction
10223 variable) works by trying to compile a small source file. By
10224 default, SCons only detects if there is a program with the correct
10225 name, not if it is a functioning compiler.
10226 This uses the exact same command than the one used by the object
10228 builder for C source file, so it can be used to detect if a
10229 particular compiler flag works or not. This does not check whether
10230 the object code can be used to build a shared library, only that
10231 the compilation (not link) succeeds.
10232 Configure.CheckSHCXX(self)
10234 Checks whether the C++ compiler (as defined by the SHCXX
10235 construction variable) works by trying to compile a small source
10236 file. By default, SCons only detects if there is a program with the
10237 correct name, not if it is a functioning compiler.
10238 This uses the exact same command than the one used by the object
10240 builder for CXX source files, so it can be used to detect if a
10241 particular compiler flag works or not. This does not check whether
10242 the object code can be used to build a shared library, only that
10243 the compilation (not link) succeeds.
10244 Example of a typical Configure usage:
10246 env = Environment()
10248 conf = Configure( env )
10249 if not conf.CheckCHeader( 'math.h' ):
10250 print('We really need math.h!')
10251 Exit(1)
10252 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++',
10253 'QApplication qapp(0,0);' ):
10254 # do stuff for qt - usage, e.g.
10255 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
10256 env = conf.Finish()
10257 SConf.CheckTypeSize(context, type_name, [header, language, expect]),
10259 sconf.CheckTypeSize(type_name, [header, language, expect])
10260 Checks for the size of a type defined by typedef. type_name
10261 specifies the typedef name to check for. The optional header
10262 argument is a string that will be placed at the top of the test
10263 file that will be compiled to check if the function exists; the
10264 default is empty. The optional language argument should be C or C++
10265 and selects the compiler to be used for the check; the default is
10266 "C". The optional expect argument should be an integer. If this
10267 argument is used, the function will only check whether the type
10268 given in type_name has the expected size (in bytes). For example,
10269 CheckTypeSize('short', expect = 2) will return success only if
10270 short is two bytes.
10271 SConf.CheckDeclaration(context, symbol, [includes, language]),
10274 sconf.CheckDeclaration(symbol, [includes, language])
10275 Checks if the specified symbol is declared. includes is a string
10276 containing one or more #include lines that will be inserted into
10277 the program that will be run to test for the existence of the type.
10278 The optional language argument should be C or C++ and selects the
10279 compiler to be used for the check; the default is "C".
10280 SConf.Define(context, symbol, [value, comment]), sconf.Define(symbol,
10282 [value, comment])
10283 This function does not check for anything, but defines a
10284 preprocessor symbol that will be added to the configuration header
10285 file. It is the equivalent of AC_DEFINE, and defines the symbol
10286 name with the optional value and the optional comment comment.
10287 Examples:
10289 env = Environment()
10291 conf = Configure( env )
10292 # Puts the following line in the config header file:
10294 # #define A_SYMBOL
10295 conf.Define('A_SYMBOL')
10296 # Puts the following line in the config header file:
10298 # #define A_SYMBOL 1
10299 conf.Define('A_SYMBOL', 1)
10300 Be careful about quoting string values, though:
10302 env = Environment()
10304 conf = Configure( env )
10305 # Puts the following line in the config header file:
10307 # #define A_SYMBOL YA
10308 conf.Define('A_SYMBOL', "YA")
10309 # Puts the following line in the config header file:
10311 # #define A_SYMBOL "YA"
10312 conf.Define('A_SYMBOL', '"YA"')
10313 For comment:
10315 env = Environment()
10317 conf = Configure( env )
10318 # Puts the following lines in the config header file:
10320 # /* Set to 1 if you have a symbol */
10321 # #define A_SYMBOL 1
10322 conf.Define('A_SYMBOL', 1, 'Set to 1 if you have a symbol')
10323 You can define your own custom checks. in addition to the predefined
10325 checks. These are passed in a dictionary to the Configure function.
10326 This dictionary maps the names of the checks to user defined Python
10327 callables (either Python functions or class instances implementing the
10328 __call__ method). The first argument of the call is always a
10329 CheckContext instance followed by the arguments, which must be supplied
10330 by the user of the check. These CheckContext instances define the
10331 following methods:
10332 CheckContext.Message(self, text)
10334 Usually called before the check is started. text will be displayed
10335 to the user, e.g. 'Checking for library X...'
10336 CheckContext.Result(self,, res)
10338 Usually called after the check is done. res can be either an
10339 integer or a string. In the former case, 'yes' (res != 0) or 'no'
10340 (res == 0) is displayed to the user, in the latter case the given
10341 string is displayed.
10342 CheckContext.TryCompile(self, text, extension)
10344 Checks if a file with the specified extension (e.g. '.c')
10345 containing text can be compiled using the environment's Object
10346 builder. Returns 1 on success and 0 on failure.
10347 CheckContext.TryLink(self, text, extension)
10349 Checks, if a file with the specified extension (e.g. '.c')
10350 containing text can be compiled using the environment's Program
10351 builder. Returns 1 on success and 0 on failure.
10352 CheckContext.TryRun(self, text, extension)
10354 Checks, if a file with the specified extension (e.g. '.c')
10355 containing text can be compiled using the environment's Program
10356 builder. On success, the program is run. If the program executes
10357 successfully (that is, its return status is 0), a tuple (1,
10358 outputStr) is returned, where outputStr is the standard output of
10359 the program. If the program fails execution (its return status is
10360 non-zero), then (0, '') is returned.
10361 CheckContext.TryAction(self, action, [text, extension])
10363 Checks if the specified action with an optional source file
10364 (contents text , extension extension = '' ) can be executed.
10365 action may be anything which can be converted to a scons Action. On
10366 success, (1, outputStr) is returned, where outputStr is the content
10367 of the target file. On failure (0, '') is returned.
10368 CheckContext.TryBuild(self, builder, [text, extension])
10370 Low level implementation for testing specific builds; the methods
10371 above are based on this method. Given the Builder instance builder
10372 and the optional text of a source file with optional extension,
10373 this method returns 1 on success and 0 on failure. In addition,
10374 self.lastTarget is set to the build target node, if the build was
10375 successful.
10376 Example for implementing and using custom tests:
10378 def CheckQt(context, qtdir):
10380 context.Message( 'Checking for qt ...' )
10381 lastLIBS = context.env['LIBS']
10382 lastLIBPATH = context.env['LIBPATH']
10383 lastCPPPATH= context.env['CPPPATH']
10384 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
10385 ret = context.TryLink("""
10386 #include <qapp.h>
10387 int main(int argc, char **argv) {
10388 QApplication qapp(argc, argv);
10389 return 0;
10390 }
10391 """)
10392 if not ret:
10393 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
10394 context.Result( ret )
10395 return ret
10396 env = Environment()
10398 conf = Configure( env, custom_tests = { 'CheckQt' : CheckQt } )
10399 if not conf.CheckQt('/usr/lib/qt'):
10400 print('We really need qt!')
10401 Exit(1)
10402 env = conf.Finish()
10403 Command-Line Construction Variables
10405 Often when building software, some variables must be specified at build
10406 time. For example, libraries needed for the build may be in
10407 non-standard locations, or site-specific compiler options may need to
10408 be passed to the compiler. scons provides a Variables object to
10409 support overriding construction variables on the command line:
10410 $ scons VARIABLE=foo
10412 The variable values can also be specified in a text-based SConscript
10414 file. To create a Variables object, call the Variables() function:
10415 Variables([files], [args])
10417 This creates a Variables object that will read construction
10418 variables from the file or list of filenames specified in files. If
10419 no files are specified, or the files argument is None, then no
10420 files will be read. The optional argument args is a dictionary of
10421 values that will override anything read from the specified files;
10422 it is primarily intended to be passed the ARGUMENTS dictionary that
10423 holds variables specified on the command line. Example:
10424 vars = Variables('custom.py')
10426 vars = Variables('overrides.py', ARGUMENTS)
10427 vars = Variables(None, {FOO:'expansion', BAR:7})
10428 Variables objects have the following methods:
10430 Add(key, [help, default, validator, converter])
10432 This adds a customizable construction variable to the Variables
10433 object. key is the name of the variable. help is the help text
10434 for the variable. default is the default value of the variable; if
10435 the default value is None and there is no explicit value specified,
10436 the construction variable will not be added to the construction
10437 environment. validator is called to validate the value of the
10438 variable, and should take three arguments: key, value, and
10439 environment. The recommended way to handle an invalid value is to
10440 raise an exception (see example below). converter is called to
10441 convert the value before putting it in the environment, and should
10442 take either a value, or the value and environment, as parameters.
10443 The converter must return a value, which will be converted into a
10444 string before being validated by the validator (if any) and then
10445 added to the environment.
10446 Examples:
10448 vars.Add('CC', 'The C compiler')
10450 def validate_color(key, val, env):
10452 if not val in ['red', 'blue', 'yellow']:
10453 raise Exception("Invalid color value '%s'" % val)
10454 vars.Add('COLOR', validator=valid_color)
10455 AddVariables(list)
10457 A wrapper script that adds multiple customizable construction
10458 variables to a Variables object. list is a list of tuple or list
10459 objects that contain the arguments for an individual call to the
10460 Add method.
10461 opt.AddVariables(
10463 ('debug', '', 0),
10464 ('CC', 'The C compiler'),
10465 ('VALIDATE', 'An option for testing validation',
10466 'notset', validator, None),
10467 )
10468 Update(env, [args])
10470 This updates a construction environment env with the customized
10471 construction variables. Any specified variables that are not
10472 configured for the Variables object will be saved and may be
10473 retrieved with the UnknownVariables() method, below.
10474 Normally this method is not called directly, but is called
10476 indirectly by passing the Variables object to the Environment()
10477 function:
10478 env = Environment(variables=vars)
10480 The text file(s) that were specified when the Variables object was
10482 created are executed as Python scripts, and the values of (global)
10483 Python variables set in the file are added to the construction
10484 environment.
10485 Example:
10487 CC = 'my_cc'
10489 UnknownVariables()
10491 Returns a dictionary containing any variables that were specified
10492 either in the files or the dictionary with which the Variables
10493 object was initialized, but for which the Variables object was not
10494 configured.
10495 env = Environment(variables=vars)
10497 for key, value in vars.UnknownVariables():
10498 print("unknown variable: %s=%s" % (key, value))
10499 Save(filename, env)
10501 This saves the currently set variables into a script file named
10502 filename that can be used on the next invocation to automatically
10503 load the current settings. This method combined with the Variables
10504 method can be used to support caching of variables between runs.
10505 env = Environment()
10507 vars = Variables(['variables.cache', 'custom.py'])
10508 vars.Add(...)
10509 vars.Update(env)
10510 vars.Save('variables.cache', env)
10511 GenerateHelpText(env, [sort])
10513 This generates help text documenting the customizable construction
10514 variables suitable to passing in to the Help() function. env is
10515 the construction environment that will be used to get the actual
10516 values of customizable variables. Calling with an optional sort
10517 function will cause the output to be sorted by the specified
10518 argument. The specific sort function should take two arguments and
10519 return -1, 0 or 1 (like the standard Python cmp function).
10520 Optionally a Boolean value of True for sort will cause a standard
10521 alphabetical sort to be performed
10522 Help(vars.GenerateHelpText(env))
10524 Help(vars.GenerateHelpText(env, sort=cmp))
10525 FormatVariableHelpText(env, opt, help, default, actual)
10527 This method returns a formatted string containing the printable
10528 help text for one option. It is normally not called directly, but
10529 is called by the GenerateHelpText() method to create the returned
10530 help text. It may be overridden with your own function that takes
10531 the arguments specified above and returns a string of help text
10532 formatted to your liking. Note that the GenerateHelpText() will not
10533 put any blank lines or extra characters in between the entries, so
10534 you must add those characters to the returned string if you want
10535 the entries separated.
10536 def my_format(env, opt, help, default, actual):
10538 fmt = "\n%s: default=%s actual=%s (%s)\n"
10539 return fmt % (opt, default. actual, help)
10540 vars.FormatVariableHelpText = my_format
10541 To make it more convenient to work with customizable Variables,
10543 scons provides a number of functions that make it easy to set up
10544 various types of Variables:
10545 BoolVariable(key, help, default)
10547 Return a tuple of arguments to set up a Boolean option. The option
10548 will use the specified name key, have a default value of default,
10549 and display the specified help text. The option will interpret the
10550 values y, yes, t, true, 1, on and all as true, and the values n,
10551 no, f, false, 0, off and none as false.
10552 EnumVariable(key, help, default, allowed_values, [map, ignorecase])
10554 Return a tuple of arguments to set up an option whose value may be
10555 one of a specified list of legal enumerated values. The option will
10556 use the specified name key, have a default value of default, and
10557 display the specified help text. The option will only support those
10558 values in the allowed_values list. The optional map argument is a
10559 dictionary that can be used to convert input values into specific
10560 legal values in the allowed_values list. If the value of
10561 ignore_case is 0 (the default), then the values are case-sensitive.
10562 If the value of ignore_case is 1, then values will be matched
10563 case-insensitive. If the value of ignore_case is 2, then values
10564 will be matched case-insensitive, and all input values will be
10565 converted to lower case.
10566 ListVariable(key, help, default, names, [,map])
10568 Return a tuple of arguments to set up an option whose value may be
10569 one or more of a specified list of legal enumerated values. The
10570 option will use the specified name key, have a default value of
10571 default, and display the specified help text. The option will only
10572 support the values all, none, or the values in the names list. More
10573 than one value may be specified, with all values separated by
10574 commas. The default may be a string of comma-separated default
10575 values, or a list of the default values. The optional map argument
10576 is a dictionary that can be used to convert input values into
10577 specific legal values in the names list.
10578 PackageVariable(key, help, default)
10580 Return a tuple of arguments to set up an option whose value is a
10581 path name of a package that may be enabled, disabled or given an
10582 explicit path name. The option will use the specified name key,
10583 have a default value of default, and display the specified help
10584 text. The option will support the values yes, true, on, enable or
10585 search, in which case the specified default will be used, or the
10586 option may be set to an arbitrary string (typically the path name
10587 to a package that is being enabled). The option will also support
10588 the values no, false, off or disable to disable use of the
10589 specified option.
10590 PathVariable(key, help, default, [validator])
10592 Return a tuple of arguments to set up an option whose value is
10593 expected to be a path name. The option will use the specified name
10594 key, have a default value of default, and display the specified
10595 help text. An additional validator may be specified that will be
10596 called to verify that the specified path is acceptable. SCons
10597 supplies the following ready-made validators:
10598 PathVariable.PathExists (the default), which verifies that the
10599 specified path exists; PathVariable.PathIsFile, which verifies that
10600 the specified path is an existing file; PathVariable.PathIsDir,
10601 which verifies that the specified path is an existing directory;
10602 PathVariable.PathIsDirCreate, which verifies that the specified
10603 path is a directory and will create the specified directory if the
10604 path does not exist; and PathVariable.PathAccept, which simply
10605 accepts the specific path name argument without validation, and
10606 which is suitable if you want your users to be able to specify a
10607 directory path that will be created as part of the build process,
10608 for example. You may supply your own validator function, which must
10609 take three arguments (key, the name of the variable to be set; val,
10610 the specified value being checked; and env, the construction
10611 environment) and should raise an exception if the specified value
10612 is not acceptable.
10613 These functions make it convenient to create a number of variables with
10615 consistent behavior in a single call to the AddVariables method:
10616 vars.AddVariables(
10618 BoolVariable('warnings', 'compilation with -Wall and similiar', 1),
10619 EnumVariable('debug', 'debug output and symbols', 'no'
10620 allowed_values=('yes', 'no', 'full'),
10621 map={}, ignorecase=0), # case sensitive
10622 ListVariable('shared',
10623 'libraries to build as shared libraries',
10624 'all',
10625 names = list_of_libs),
10626 PackageVariable('x11',
10627 'use X11 installed here (yes = search some places)',
10628 'yes'),
10629 PathVariable('qtdir', 'where the root of Qt is installed', qtdir),
10630 PathVariable('foopath', 'where the foo library is installed', foopath,
10631 PathVariable.PathIsDir),
10632 )
10634 File and Directory Nodes
10636 The File() and Dir() functions return File and Dir Nodes, respectively.
10637 python objects, respectively. Those objects have several user-visible
10638 attributes and methods that are often useful:
10639 path
10641 The build path of the given file or directory. This path is
10642 relative to the top-level directory (where the SConstruct file is
10643 found). The build path is the same as the source path if
10644 variant_dir is not being used.
10645 abspath
10647 The absolute build path of the given file or directory.
10648 srcnode()
10650 The srcnode() method returns another File or Dir object
10651 representing the source path of the given File or Dir. The
10652 # Get the current build dir's path, relative to top.
10654 Dir('.').path
10655 # Current dir's absolute path
10656 Dir('.').abspath
10657 # Next line is always '.', because it is the top dir's path relative to itself.
10658 Dir('#.').path
10659 File('foo.c').srcnode().path # source path of the given source file.
10660 # Builders also return File objects:
10662 foo = env.Program('foo.c')
10663 print("foo will be built in %s"%foo.path)
10664 A Dir Node or File Node can also be used to create file and
10666 subdirectory Nodes relative to the generating Node. A Dir Node will
10667 place the new Nodes within the directory it represents. A File node
10668 will place the new Nodes within its parent directory (that is,
10669 "beside" the file in question). If d is a Dir (directory) Node and
10670 f is a File (file) Node, then these methods are available:
10671 d.Dir(name)
10673 Returns a directory Node for a subdirectory of d named name.
10674 d.File(name)
10676 Returns a file Node for a file within d named name.
10677 d.Entry(name)
10679 Returns an unresolved Node within d named name.
10680 f.Dir(name)
10682 Returns a directory named name within the parent directory of f.
10683 f.File(name)
10685 Returns a file named name within the parent directory of f.
10686 f.Entry(name)
10688 Returns an unresolved Node named name within the parent directory
10689 of f.
10690 For example:
10692 # Get a Node for a file within a directory
10694 incl = Dir('include')
10695 f = incl.File('header.h')
10696 # Get a Node for a subdirectory within a directory
10698 dist = Dir('project-3.2.1)
10699 src = dist.Dir('src')
10700 # Get a Node for a file in the same directory
10702 cfile = File('sample.c')
10703 hfile = cfile.File('sample.h')
10704 # Combined example
10706 docs = Dir('docs')
10707 html = docs.Dir('html')
10708 index = html.File('index.html')
10709 css = index.File('app.css')
10710
10712 Builder Objects
10713 scons can be extended to build different types of targets by adding new
10714 Builder objects to a construction environment. In general, you should
10715 only need to add a new Builder object when you want to build a new type
10716 of file or other external target. If you just want to invoke a
10717 different compiler or other tool to build a Program, Object, Library,
10718 or any other type of output file for which scons already has an
10719 existing Builder, it is generally much easier to use those existing
10720 Builders in a construction environment that sets the appropriate
10721 construction variables (CC, LINK, etc.).
10722 Builder objects are created using the Builder function. The Builder
10724 function accepts the following arguments:
10725 action
10727 The command line string used to build the target from the source.
10728 action can also be: a list of strings representing the command to
10729 be executed and its arguments (suitable for enclosing white space
10730 in an argument), a dictionary mapping source file name suffixes to
10731 any combination of command line strings (if the builder should
10732 accept multiple source file extensions), a Python function; an
10733 Action object (see the next section); or a list of any of the
10734 above.
10735 An action function takes three arguments: source - a list of source
10737 nodes, target - a list of target nodes, env - the construction
10738 environment.
10739 prefix
10741 The prefix that will be prepended to the target file name. This may
10742 be specified as a: * string,
10743 * callable object - a function or other callable that takes two
10745 arguments (a construction environment and a list of sources) and
10746 returns a prefix,
10747 * dictionary - specifies a mapping from a specific source suffix
10749 (of the first source specified) to a corresponding target prefix.
10750 Both the source suffix and target prefix specifications may use
10751 environment variable substitution, and the target prefix (the
10752 'value' entries in the dictionary) may also be a callable object.
10753 The default target prefix may be indicated by a dictionary entry
10754 with a key value of None.
10755 b = Builder("build_it < $SOURCE > $TARGET",
10757 prefix = "file-")
10758 def gen_prefix(env, sources):
10760 return "file-" + env['PLATFORM'] + '-'
10761 b = Builder("build_it < $SOURCE > $TARGET",
10762 prefix = gen_prefix)
10763 b = Builder("build_it < $SOURCE > $TARGET",
10765 suffix = { None: "file-",
10766 "$SRC_SFX_A": gen_prefix })
10767 suffix
10769 The suffix that will be appended to the target file name. This may
10770 be specified in the same manner as the prefix above. If the suffix
10771 is a string, then scons will append a '.' to the beginning of the
10772 suffix if it's not already there. The string returned by callable
10773 object (or obtained from the dictionary) is untouched and must
10774 append its own '.' to the beginning if one is desired.
10775 b = Builder("build_it < $SOURCE > $TARGET"
10777 suffix = "-file")
10778 def gen_suffix(env, sources):
10780 return "." + env['PLATFORM'] + "-file"
10781 b = Builder("build_it < $SOURCE > $TARGET",
10782 suffix = gen_suffix)
10783 b = Builder("build_it < $SOURCE > $TARGET",
10785 suffix = { None: ".sfx1",
10786 "$SRC_SFX_A": gen_suffix })
10787 ensure_suffix
10789 When set to any true value, causes scons to add the target suffix
10790 specified by the suffix keyword to any target strings that have a
10791 different suffix. (The default behavior is to leave untouched any
10792 target file name that looks like it already has any suffix.)
10793 b1 = Builder("build_it < $SOURCE > $TARGET"
10795 suffix = ".out")
10796 b2 = Builder("build_it < $SOURCE > $TARGET"
10797 suffix = ".out",
10798 ensure_suffix)
10799 env = Environment()
10800 env['BUILDERS']['B1'] = b1
10801 env['BUILDERS']['B2'] = b2
10802 # Builds "foo.txt" because ensure_suffix is not set.
10804 env.B1('foo.txt', 'foo.in')
10805 # Builds "bar.txt.out" because ensure_suffix is set.
10807 env.B2('bar.txt', 'bar.in')
10808 src_suffix
10810 The expected source file name suffix. This may be a string or a
10811 list of strings.
10812 target_scanner
10814 A Scanner object that will be invoked to find implicit dependencies
10815 for this target file. This keyword argument should be used for
10816 Scanner objects that find implicit dependencies based only on the
10817 target file and the construction environment, not for implicit
10818 dependencies based on source files. (See the section "Scanner
10819 Objects" below, for information about creating Scanner objects.)
10820 source_scanner
10822 A Scanner object that will be invoked to find implicit dependencies
10823 in any source files used to build this target file. This is where
10824 you would specify a scanner to find things like #include lines in
10825 source files. The pre-built DirScanner Scanner object may be used
10826 to indicate that this Builder should scan directory trees for
10827 on-disk changes to files that scons does not know about from other
10828 Builder or function calls. (See the section "Scanner Objects"
10829 below, for information about creating your own Scanner objects.)
10830 target_factory
10832 A factory function that the Builder will use to turn any targets
10833 specified as strings into SCons Nodes. By default, SCons assumes
10834 that all targets are files. Other useful target_factory values
10835 include Dir, for when a Builder creates a directory target, and
10836 Entry, for when a Builder can create either a file or directory
10837 target.
10838 Example:
10840 MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir)
10842 env = Environment()
10843 env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder})
10844 env.MakeDirectory('new_directory', [])
10845 Note that the call to the MakeDirectory Builder needs to specify an
10847 empty source list to make the string represent the builder's
10848 target; without that, it would assume the argument is the source,
10849 and would try to deduce the target name from it, which in the
10850 absence of an automatically-added prefix or suffix would lead to a
10851 matching target and source name and a circular dependency.
10852 source_factory
10854 A factory function that the Builder will use to turn any sources
10855 specified as strings into SCons Nodes. By default, SCons assumes
10856 that all source are files. Other useful source_factory values
10857 include Dir, for when a Builder uses a directory as a source, and
10858 Entry, for when a Builder can use files or directories (or both) as
10859 sources.
10860 Example:
10862 CollectBuilder = Builder(action=my_mkdir, source_factory=Entry)
10864 env = Environment()
10865 env.Append(BUILDERS = {'Collect':CollectBuilder})
10866 env.Collect('archive', ['directory_name', 'file_name'])
10867 emitter
10869 A function or list of functions to manipulate the target and source
10870 lists before dependencies are established and the target(s) are
10871 actually built. emitter can also be a string containing a
10872 construction variable to expand to an emitter function or list of
10873 functions, or a dictionary mapping source file suffixes to emitter
10874 functions. (Only the suffix of the first source file is used to
10875 select the actual emitter function from an emitter dictionary.)
10876 An emitter function takes three arguments: source - a list of
10878 source nodes, target - a list of target nodes, env - the
10879 construction environment. An emitter must return a tuple containing
10880 two lists, the list of targets to be built by this builder, and the
10881 list of sources for this builder.
10882 Example:
10884 def e(target, source, env):
10886 return (target + ['foo.foo'], source + ['foo.src'])
10887 # Simple association of an emitter function with a Builder.
10889 b = Builder("my_build < $TARGET > $SOURCE",
10890 emitter = e)
10891 def e2(target, source, env):
10893 return (target + ['bar.foo'], source + ['bar.src'])
10894 # Simple association of a list of emitter functions with a Builder.
10896 b = Builder("my_build < $TARGET > $SOURCE",
10897 emitter = [e, e2])
10898 # Calling an emitter function through a construction variable.
10900 env = Environment(MY_EMITTER = e)
10901 b = Builder("my_build < $TARGET > $SOURCE",
10902 emitter = '$MY_EMITTER')
10903 # Calling a list of emitter functions through a construction variable.
10905 env = Environment(EMITTER_LIST = [e, e2])
10906 b = Builder("my_build < $TARGET > $SOURCE",
10907 emitter = '$EMITTER_LIST')
10908 # Associating multiple emitters with different file
10910 # suffixes using a dictionary.
10911 def e_suf1(target, source, env):
10912 return (target + ['another_target_file'], source)
10913 def e_suf2(target, source, env):
10914 return (target, source + ['another_source_file'])
10915 b = Builder("my_build < $TARGET > $SOURCE",
10916 emitter = {'.suf1' : e_suf1,
10917 '.suf2' : e_suf2})
10918 multi
10920 Specifies whether this builder is allowed to be called multiple
10921 times for the same target file(s). The default is 0, which means
10922 the builder can not be called multiple times for the same target
10923 file(s). Calling a builder multiple times for the same target
10924 simply adds additional source files to the target; it is not
10925 allowed to change the environment associated with the target,
10926 specify addition environment overrides, or associate a different
10927 builder with the target.
10928 env
10930 A construction environment that can be used to fetch source code
10931 using this Builder. (Note that this environment is not used for
10932 normal builds of normal target files, which use the environment
10933 that was used to call the Builder for the target file.)
10934 generator
10936 A function that returns a list of actions that will be executed to
10937 build the target(s) from the source(s). The returned action(s) may
10938 be an Action object, or anything that can be converted into an
10939 Action object (see the next section).
10940 The generator function takes four arguments: source - a list of
10942 source nodes, target - a list of target nodes, env - the
10943 construction environment, for_signature - a Boolean value that
10944 specifies whether the generator is being called for generating a
10945 build signature (as opposed to actually executing the command).
10946 Example:
10947 def g(source, target, env, for_signature):
10949 return [["gcc", "-c", "-o"] + target + source]
10950 b = Builder(generator=g)
10952 The generator and action arguments must not both be used for the
10954 same Builder.
10955 src_builder
10957 Specifies a builder to use when a source file name suffix does not
10958 match any of the suffixes of the builder. Using this argument
10959 produces a multi-stage builder.
10960 single_source
10962 Specifies that this builder expects exactly one source file per
10963 call. Giving more than one source file without target files results
10964 in implicitly calling the builder multiple times (once for each
10965 source given). Giving multiple source files together with target
10966 files results in a UserError exception.
10967 The generator and action arguments must not both be used for the same
10969 Builder.
10970 source_ext_match
10972 When the specified action argument is a dictionary, the default
10973 behavior when a builder is passed multiple source files is to make
10974 sure that the extensions of all the source files match. If it is
10975 legal for this builder to be called with a list of source files
10976 with different extensions, this check can be suppressed by setting
10977 source_ext_match to None or some other non-true value. When
10978 source_ext_match is disable, scons will use the suffix of the first
10979 specified source file to select the appropriate action from the
10980 action dictionary.
10981 In the following example, the setting of source_ext_match prevents
10983 scons from exiting with an error due to the mismatched suffixes of
10984 foo.in and foo.extra.
10985 b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
10987 source_ext_match = None)
10988 env = Environment(BUILDERS = {'MyBuild':b})
10990 env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
10991 env
10993 A construction environment that can be used to fetch source code
10994 using this Builder. (Note that this environment is not used for
10995 normal builds of normal target files, which use the environment
10996 that was used to call the Builder for the target file.)
10997 b = Builder(action="build < $SOURCE > $TARGET")
10999 env = Environment(BUILDERS = {'MyBuild' : b})
11000 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
11001 chdir
11003 A directory from which scons will execute the action(s) specified
11004 for this Builder. If the chdir argument is a string or a directory
11005 Node, scons will change to the specified directory. If the chdir is
11006 not a string or Node and is non-zero, then scons will change to the
11007 target file's directory.
11008 Note that scons will not automatically modify its expansion of
11010 construction variables like $TARGET and $SOURCE when using the
11011 chdir keyword argument--that is, the expanded file names will still
11012 be relative to the top-level SConstruct directory, and consequently
11013 incorrect relative to the chdir directory. Builders created using
11014 chdir keyword argument, will need to use construction variable
11015 expansions like ${TARGET.file} and ${SOURCE.file} to use just the
11016 filename portion of the targets and source.
11017 b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}",
11019 chdir=1)
11020 env = Environment(BUILDERS = {'MyBuild' : b})
11021 env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
11022 WARNING: Python only keeps one current directory location for all
11024 of the threads. This means that use of the chdir argument will not
11025 work with the SCons -j option, because individual worker threads
11026 spawned by SCons interfere with each other when they start changing
11027 directory.
11028 Any additional keyword arguments supplied when a Builder object is
11030 created (that is, when the Builder() function is called) will be set in
11031 the executing construction environment when the Builder object is
11032 called. The canonical example here would be to set a construction
11033 variable to the repository of a source code system.
11034 Any additional keyword arguments supplied when a Builder object is
11036 called will only be associated with the target created by that
11037 particular Builder call (and any other files built as a result of the
11038 call).
11039 These extra keyword arguments are passed to the following functions:
11041 command generator functions, function Actions, and emitter functions.
11042 Action Objects
11044 The Builder() function will turn its action keyword argument into an
11045 appropriate internal Action object. You can also explicitly create
11046 Action objects using the Action() global function, which can then be
11047 passed to the Builder() function. This can be used to configure an
11048 Action object more flexibly, or it may simply be more efficient than
11049 letting each separate Builder object create a separate Action when
11050 multiple Builder objects need to do the same thing.
11051 The Action() global function returns an appropriate object for the
11053 action represented by the type of the first argument:
11054 Action
11056 If the first argument is already an Action object, the object is
11057 simply returned.
11058 String
11060 If the first argument is a string, a command-line Action is
11061 returned. Note that the command-line string may be preceded by an @
11062 (at-sign) to suppress printing of the specified command line, or by
11063 a - (hyphen) to ignore the exit status from the specified command:
11064 Action('$CC -c -o $TARGET $SOURCES')
11066 # Doesn't print the line being executed.
11068 Action('@build $TARGET $SOURCES')
11069 # Ignores return value
11071 Action('-build $TARGET $SOURCES')
11072 List
11074 If the first argument is a list, then a list of Action objects is
11075 returned. An Action object is created as necessary for each element
11076 in the list. If an element within the list is itself a list, the
11077 internal list is the command and arguments to be executed via the
11078 command line. This allows white space to be enclosed in an argument
11079 by defining a command in a list within a list:
11080 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
11082 Function
11084 If the first argument is a Python function, a function Action is
11085 returned. The Python function must take three keyword arguments,
11086 target (a Node object representing the target file), source (a Node
11087 object representing the source file) and env (the construction
11088 environment used for building the target file). The target and
11089 source arguments may be lists of Node objects if there is more than
11090 one target file or source file. The actual target and source file
11091 name(s) may be retrieved from their Node objects via the built-in
11092 Python str() function:
11093 target_file_name = str(target)
11095 source_file_names = map(lambda x: str(x), source)
11096 The function should return 0 or None to indicate a successful build
11098 of the target file(s). The function may raise an exception or
11099 return a non-zero exit status to indicate an unsuccessful build.
11100 def build_it(target = None, source = None, env = None):
11102 # build the target from the source
11103 return 0
11104 a = Action(build_it)
11106 If the action argument is not one of the above, None is returned.
11108 The second argument is optional and is used to define the output which
11110 is printed when the Action is actually performed. In the absence of
11111 this parameter, or if it's an empty string, a default output depending
11112 on the type of the action is used. For example, a command-line action
11113 will print the executed command. The argument must be either a Python
11114 function or a string.
11115 In the first case, it's a function that returns a string to be printed
11117 to describe the action being executed. The function may also be
11118 specified by the strfunction= keyword argument. Like a function to
11119 build a file, this function must take three keyword arguments: target
11120 (a Node object representing the target file), source (a Node object
11121 representing the source file) and env (a construction environment). The
11122 target and source arguments may be lists of Node objects if there is
11123 more than one target file or source file.
11124 In the second case, you provide the string itself. The string may also
11126 be specified by the cmdstr= keyword argument. The string typically
11127 contains variables, notably $TARGET(S) and $SOURCE(S), or consists of
11128 just a single variable, which is optionally defined somewhere else.
11129 SCons itself heavily uses the latter variant.
11130 Examples:
11132 def build_it(target, source, env):
11134 # build the target from the source
11135 return 0
11136 def string_it(target, source, env):
11138 return "building '%s' from '%s'" % (target[0], source[0])
11139 # Use a positional argument.
11141 f = Action(build_it, string_it)
11142 s = Action(build_it, "building '$TARGET' from '$SOURCE'")
11143 # Alternatively, use a keyword argument.
11145 f = Action(build_it, strfunction=string_it)
11146 s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
11147 # You can provide a configurable variable.
11149 l = Action(build_it, '$STRINGIT')
11150 The third and succeeding arguments, if present, may either be a
11152 construction variable or a list of construction variables whose values
11153 will be included in the signature of the Action when deciding whether a
11154 target should be rebuilt because the action changed. The variables may
11155 also be specified by a varlist= keyword parameter; if both are present,
11156 they are combined. This is necessary whenever you want a target to be
11157 rebuilt when a specific construction variable changes. This is not
11158 often needed for a string action, as the expanded variables will
11159 normally be part of the command line, but may be needed if a Python
11160 function action uses the value of a construction variable when
11161 generating the command line.
11162 def build_it(target, source, env):
11164 # build the target from the 'XXX' construction variable
11165 open(target[0], 'w').write(env['XXX'])
11166 return 0
11167 # Use positional arguments.
11169 a = Action(build_it, '$STRINGIT', ['XXX'])
11170 # Alternatively, use a keyword argument.
11172 a = Action(build_it, varlist=['XXX'])
11173 The Action() global function can be passed the following optional
11175 keyword arguments to modify the Action object's behavior:
11176 chdir The chdir keyword argument specifies that scons will execute the
11178 action after changing to the specified directory. If the chdir argument
11179 is a string or a directory Node, scons will change to the specified
11180 directory. If the chdir argument is not a string or Node and is
11181 non-zero, then scons will change to the target file's directory.
11182 Note that scons will not automatically modify its expansion of
11184 construction variables like $TARGET and $SOURCE when using the chdir
11185 keyword argument--that is, the expanded file names will still be
11186 relative to the top-level SConstruct directory, and consequently
11187 incorrect relative to the chdir directory. Builders created using chdir
11188 keyword argument, will need to use construction variable expansions
11189 like ${TARGET.file} and ${SOURCE.file} to use just the filename portion
11190 of the targets and source.
11191 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
11193 chdir=1)
11194 exitstatfunc The Action() global function also takes an exitstatfunc
11196 keyword argument which specifies a function that is passed the exit
11197 status (or return value) from the specified action and can return an
11198 arbitrary or modified value. This can be used, for example, to specify
11199 that an Action object's return value should be ignored under special
11200 conditions and SCons should, therefore, consider that the action always
11201 suceeds:
11202 def always_succeed(s):
11204 # Always return 0, which indicates success.
11205 return 0
11206 a = Action("build < ${SOURCE.file} > ${TARGET.file}",
11207 exitstatfunc=always_succeed)
11208 batch_key The batch_key keyword argument can be used to specify that
11210 the Action can create multiple target files by processing multiple
11211 independent source files simultaneously. (The canonical example is
11212 "batch compilation" of multiple object files by passing multiple source
11213 files to a single invocation of a compiler such as Microsoft's Visual C
11214 / C++ compiler.) If the batch_key argument is any non-False,
11215 non-callable Python value, the configured Action object will cause
11216 scons to collect all targets built with the Action object and
11217 configured with the same construction environment into single
11218 invocations of the Action object's command line or function. Command
11219 lines will typically want to use the CHANGED_SOURCES construction
11220 variable (and possibly CHANGED_TARGETS as well) to only pass to the
11221 command line those sources that have actually changed since their
11222 targets were built.
11223 Example:
11225 a = Action('build $CHANGED_SOURCES', batch_key=True)
11227 The batch_key argument may also be a callable function that returns a
11229 key that will be used to identify different "batches" of target files
11230 to be collected for batch building. A batch_key function must take the
11231 following arguments:
11232 action
11234 The action object.
11235 env
11237 The construction environment configured for the target.
11238 target
11240 The list of targets for a particular configured action.
11241 source
11243 The list of source for a particular configured action.
11244 The returned key should typically be a tuple of values derived from
11246 the arguments, using any appropriate logic to decide how multiple
11247 invocations should be batched. For example, a batch_key function
11248 may decide to return the value of a specific construction variable
11249 from the env argument which will cause scons to batch-build targets
11250 with matching values of that variable, or perhaps return the id()
11251 of the entire construction environment, in which case scons will
11252 batch-build all targets configured with the same construction
11253 environment. Returning None indicates that the particular target
11254 should not be part of any batched build, but instead will be built
11255 by a separate invocation of action's command or function. Example:
11256 def batch_key(action, env, target, source):
11258 tdir = target[0].dir
11259 if tdir.name == 'special':
11260 # Don't batch-build any target
11261 # in the special/ subdirectory.
11262 return None
11263 return (id(action), id(env), tdir)
11264 a = Action('build $CHANGED_SOURCES', batch_key=batch_key)
11265 Miscellaneous Action Functions
11267 scons supplies a number of functions that arrange for various common
11268 file and directory manipulations to be performed. These are similar in
11269 concept to "tasks" in the Ant build tool, although the implementation
11270 is slightly different. These functions do not actually perform the
11271 specified action at the time the function is called, but instead return
11272 an Action object that can be executed at the appropriate time. (In
11273 Object-Oriented terminology, these are actually Action Factory
11274 functions that return Action objects.)
11275 In practice, there are two natural ways that these Action Functions are
11277 intended to be used.
11278 First, if you need to perform the action at the time the SConscript
11280 file is being read, you can use the Execute global function to do so:
11281 Execute(Touch('file'))
11283 Second, you can use these functions to supply Actions in a list for use
11285 by the Command method. This can allow you to perform more complicated
11286 sequences of file manipulation without relying on platform-specific
11287 external commands: that
11288 env = Environment(TMPBUILD = '/tmp/builddir')
11290 env.Command('foo.out', 'foo.in',
11291 [Mkdir('$TMPBUILD'),
11292 Copy('$TMPBUILD', '${SOURCE.dir}'),
11293 "cd $TMPBUILD && make",
11294 Delete('$TMPBUILD')])
11295 Chmod(dest, mode)
11297 Returns an Action object that changes the permissions on the
11298 specified dest file or directory to the specified mode which can be
11299 octal or string, similar to the bash command. Examples:
11300 Execute(Chmod('file', 0755))
11302 env.Command('foo.out', 'foo.in',
11304 [Copy('$TARGET', '$SOURCE'),
11305 Chmod('$TARGET', 0755)])
11306 Execute(Chmod('file', "ugo+w"))
11308 env.Command('foo.out', 'foo.in',
11310 [Copy('$TARGET', '$SOURCE'),
11311 Chmod('$TARGET', "ugo+w")])
11312 Copy(dest, src)
11314 Returns an Action object that will copy the src source file or
11315 directory to the dest destination file or directory. Examples:
11316 Execute(Copy('foo.output', 'foo.input'))
11318 env.Command('bar.out', 'bar.in',
11320 Copy('$TARGET', '$SOURCE'))
11321 Delete(entry, [must_exist])
11323 Returns an Action that deletes the specified entry, which may be a
11324 file or a directory tree. If a directory is specified, the entire
11325 directory tree will be removed. If the must_exist flag is set, then
11326 a Python error will be thrown if the specified entry does not
11327 exist; the default is must_exist=0, that is, the Action will
11328 silently do nothing if the entry does not exist. Examples:
11329 Execute(Delete('/tmp/buildroot'))
11331 env.Command('foo.out', 'foo.in',
11333 [Delete('${TARGET.dir}'),
11334 MyBuildAction])
11335 Execute(Delete('file_that_must_exist', must_exist=1))
11337 Mkdir(dir)
11339 Returns an Action that creates the specified directory dir .
11340 Examples:
11341 Execute(Mkdir('/tmp/outputdir'))
11343 env.Command('foo.out', 'foo.in',
11345 [Mkdir('/tmp/builddir'),
11346 Copy('/tmp/builddir/foo.in', '$SOURCE'),
11347 "cd /tmp/builddir && make",
11348 Copy('$TARGET', '/tmp/builddir/foo.out')])
11349 Move(dest, src)
11351 Returns an Action that moves the specified src file or directory to
11352 the specified dest file or directory. Examples:
11353 Execute(Move('file.destination', 'file.source'))
11355 env.Command('output_file', 'input_file',
11357 [MyBuildAction,
11358 Move('$TARGET', 'file_created_by_MyBuildAction')])
11359 Touch(file)
11361 Returns an Action that updates the modification time on the
11362 specified file. Examples:
11363 Execute(Touch('file_to_be_touched'))
11365 env.Command('marker', 'input_file',
11367 [MyBuildAction,
11368 Touch('$TARGET')])
11369 Variable Substitution
11371 Before executing a command, scons performs construction variable
11372 interpolation on the strings that make up the command line of builders.
11373 Variables are introduced by a $ prefix. Besides construction variables,
11374 scons provides the following variables for each command execution:
11375 CHANGED_SOURCES
11377 The file names of all sources of the build command that have
11378 changed since the target was last built.
11379 CHANGED_TARGETS
11381 The file names of all targets that would be built from sources that
11382 have changed since the target was last built.
11383 SOURCE
11385 The file name of the source of the build command, or the file name
11386 of the first source if multiple sources are being built.
11387 SOURCES
11389 The file names of the sources of the build command.
11390 TARGET
11392 The file name of the target being built, or the file name of the
11393 first target if multiple targets are being built.
11394 TARGETS
11396 The file names of all targets being built.
11397 UNCHANGED_SOURCES
11399 The file names of all sources of the build command that have not
11400 changed since the target was last built.
11401 UNCHANGED_TARGETS
11403 The file names of all targets that would be built from sources that
11404 have not changed since the target was last built.
11405 (Note that the above variables are reserved and may not be set in a
11407 construction environment.)
11408 For example, given the construction variable CC='cc', targets=['foo'],
11410 and sources=['foo.c', 'bar.c']:
11411 action='$CC -c -o $TARGET $SOURCES'
11413 would produce the command line:
11415 cc -c -o foo foo.c bar.c
11417 Variable names may be surrounded by curly braces ({}) to separate the
11419 name from the trailing characters. Within the curly braces, a variable
11420 name may have a Python slice subscript appended to select one or more
11421 items from a list. In the previous example, the string:
11422 ${SOURCES[1]}
11424 would produce:
11426 bar.c
11428 Additionally, a variable name may have the following special modifiers
11430 appended within the enclosing curly braces to modify the interpolated
11431 string:
11432 base
11434 The base path of the file name, including the directory path but
11435 excluding any suffix.
11436 dir
11438 The name of the directory in which the file exists.
11439 file
11441 The file name, minus any directory portion.
11442 filebase
11444 Just the basename of the file, minus any suffix and minus the
11445 directory.
11446 suffix
11448 Just the file suffix.
11449 abspath
11451 The absolute path name of the file.
11452 posix
11454 The POSIX form of the path, with directories separated by /
11455 (forward slashes) not backslashes. This is sometimes necessary on
11456 Windows systems when a path references a file on other (POSIX)
11457 systems.
11458 srcpath
11460 The directory and file name to the source file linked to this file
11461 through VariantDir(). If this file isn't linked, it just returns
11462 the directory and filename unchanged.
11463 srcdir
11465 The directory containing the source file linked to this file
11466 through VariantDir(). If this file isn't linked, it just returns
11467 the directory part of the filename.
11468 rsrcpath
11470 The directory and file name to the source file linked to this file
11471 through VariantDir(). If the file does not exist locally but exists
11472 in a Repository, the path in the Repository is returned. If this
11473 file isn't linked, it just returns the directory and filename
11474 unchanged.
11475 rsrcdir
11477 The Repository directory containing the source file linked to this
11478 file through VariantDir(). If this file isn't linked, it just
11479 returns the directory part of the filename.
11480 For example, the specified target will expand as follows for the
11482 corresponding modifiers:
11483 $TARGET => sub/dir/file.x
11485 ${TARGET.base} => sub/dir/file
11486 ${TARGET.dir} => sub/dir
11487 ${TARGET.file} => file.x
11488 ${TARGET.filebase} => file
11489 ${TARGET.suffix} => .x
11490 ${TARGET.abspath} => /top/dir/sub/dir/file.x
11491 SConscript('src/SConscript', variant_dir='sub/dir')
11493 $SOURCE => sub/dir/file.x
11494 ${SOURCE.srcpath} => src/file.x
11495 ${SOURCE.srcdir} => src
11496 Repository('/usr/repository')
11498 $SOURCE => sub/dir/file.x
11499 ${SOURCE.rsrcpath} => /usr/repository/src/file.x
11500 ${SOURCE.rsrcdir} => /usr/repository/src
11501 Note that curly braces braces may also be used to enclose arbitrary
11503 Python code to be evaluated. (In fact, this is how the above modifiers
11504 are substituted, they are simply attributes of the Python objects that
11505 represent TARGET, SOURCES, etc.) See the section "Python Code
11506 Substitution" below, for more thorough examples of how this can be
11507 used.
11508 Lastly, a variable name may be a callable Python function associated
11510 with a construction variable in the environment. The function should
11511 take four arguments: target - a list of target nodes, source - a list
11512 of source nodes, env - the construction environment, for_signature - a
11513 Boolean value that specifies whether the function is being called for
11514 generating a build signature. SCons will insert whatever the called
11515 function returns into the expanded string:
11516 def foo(target, source, env, for_signature):
11518 return "bar"
11519 # Will expand $BAR to "bar baz"
11521 env=Environment(FOO=foo, BAR="$FOO baz")
11522 You can use this feature to pass arguments to a Python function by
11524 creating a callable class that stores one or more arguments in an
11525 object, and then uses them when the __call__() method is called. Note
11526 that in this case, the entire variable expansion must be enclosed by
11527 curly braces so that the arguments will be associated with the
11528 instantiation of the class:
11529 class foo(object):
11531 def __init__(self, arg):
11532 self.arg = arg
11533 def __call__(self, target, source, env, for_signature):
11535 return self.arg + " bar"
11536 # Will expand $BAR to "my argument bar baz"
11538 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
11539 The special pseudo-variables $( and $) may be used to surround parts of
11541 a command line that may change without causing a rebuild--that is,
11542 which are not included in the signature of target files built with this
11543 command. All text between $( and $) will be removed from the command
11544 line before it is added to file signatures, and the $( and $) will be
11545 removed before the command is executed. For example, the command line:
11546 echo Last build occurred $( $TODAY $). > $TARGET
11548 would execute the command:
11550 echo Last build occurred $TODAY. > $TARGET
11552 but the command signature added to any target files would be:
11554 echo Last build occurred . > $TARGET
11556 Python Code Substitution
11558 Any python code within ${-} pairs gets evaluated by python 'eval', with
11559 the python globals set to the current environment's set of construction
11560 variables. So in the following case:
11561 env['COND'] = 0
11563 env.Command('foo.out', 'foo.in',
11564 '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''')
11565 the command executed will be either
11567 echo FOO > foo.out
11569 or
11571 echo BAR > foo.out
11573 according to the current value of env['COND'] when the command is
11575 executed. The evaluation occurs when the target is being built, not
11576 when the SConscript is being read. So if env['COND'] is changed later
11577 in the SConscript, the final value will be used.
11578 Here's a more interesting example. Note that all of COND, FOO, and BAR
11580 are environment variables, and their values are substituted into the
11581 final command. FOO is a list, so its elements are interpolated
11582 separated by spaces.
11583 env=Environment()
11585 env['COND'] = 0
11586 env['FOO'] = ['foo1', 'foo2']
11587 env['BAR'] = 'barbar'
11588 env.Command('foo.out', 'foo.in',
11589 'echo ${COND==1 and FOO or BAR} > $TARGET')
11590 # Will execute this:
11592 # echo foo1 foo2 > foo.out
11593 SCons uses the following rules when converting construction variables
11595 into command lines:
11596 String
11598 When the value is a string it is interpreted as a space delimited
11599 list of command line arguments.
11600 List
11602 When the value is a list it is interpreted as a list of command
11603 line arguments. Each element of the list is converted to a string.
11604 Other
11606 Anything that is not a list or string is converted to a string and
11607 interpreted as a single command line argument.
11608 Newline
11610 Newline characters (\n) delimit lines. The newline parsing is done
11611 after all other parsing, so it is not possible for arguments (e.g.
11612 file names) to contain embedded newline characters. This limitation
11613 will likely go away in a future version of SCons.
11614 Scanner Objects
11616 You can use the Scanner function to define objects to scan new file
11617 types for implicit dependencies. The Scanner function accepts the
11618 following arguments:
11619 function
11621 This can be either: 1) a Python function that will process the Node
11622 (file) and return a list of File Nodes representing the implicit
11623 dependencies (file names) found in the contents; or: 2) a
11624 dictionary that maps keys (typically the file suffix, but see below
11625 for more discussion) to other Scanners that should be called.
11626 If the argument is actually a Python function, the function must
11628 take three or four arguments:
11629 def scanner_function(node, env, path):
11631 def scanner_function(node, env, path, arg=None):
11633 The node argument is the internal SCons node representing the file.
11635 Use str(node) to fetch the name of the file, and
11636 node.get_contents() to fetch contents of the file. Note that the
11637 file is not guaranteed to exist before the scanner is called, so
11638 the scanner function should check that if there's any chance that
11639 the scanned file might not exist (for example, if it's built from
11640 other files).
11641 The env argument is the construction environment for the scan.
11643 Fetch values from it using the env.Dictionary() method.
11644 The path argument is a tuple (or list) of directories that can be
11646 searched for files. This will usually be the tuple returned by the
11647 path_function argument (see below).
11648 The arg argument is the argument supplied when the scanner was
11650 created, if any.
11651 name
11653 The name of the Scanner. This is mainly used to identify the
11654 Scanner internally.
11655 argument
11657 An optional argument that, if specified, will be passed to the
11658 scanner function (described above) and the path function (specified
11659 below).
11660 skeys
11662 An optional list that can be used to determine which scanner should
11663 be used for a given Node. In the usual case of scanning for file
11664 names, this argument will be a list of suffixes for the different
11665 file types that this Scanner knows how to scan. If the argument is
11666 a string, then it will be expanded into a list by the current
11667 environment.
11668 path_function
11670 A Python function that takes four or five arguments: a construction
11671 environment, a Node for the directory containing the SConscript
11672 file in which the first target was defined, a list of target nodes,
11673 a list of source nodes, and an optional argument supplied when the
11674 scanner was created. The path_function returns a tuple of
11675 directories that can be searched for files to be returned by this
11676 Scanner object. (Note that the FindPathDirs() function can be used
11677 to return a ready-made path_function for a given construction
11678 variable name, instead of having to write your own function from
11679 scratch.)
11680 node_class
11682 The class of Node that should be returned by this Scanner object.
11683 Any strings or other objects returned by the scanner function that
11684 are not of this class will be run through the node_factory
11685 function.
11686 node_factory
11688 A Python function that will take a string or other object and turn
11689 it into the appropriate class of Node to be returned by this
11690 Scanner object.
11691 scan_check
11693 An optional Python function that takes two arguments, a Node (file)
11694 and a construction environment, and returns whether the Node
11695 should, in fact, be scanned for dependencies. This check can be
11696 used to eliminate unnecessary calls to the scanner function when,
11697 for example, the underlying file represented by a Node does not yet
11698 exist.
11699 recursive
11701 An optional flag that specifies whether this scanner should be
11702 re-invoked on the dependency files returned by the scanner. When
11703 this flag is not set, the Node subsystem will only invoke the
11704 scanner on the file being scanned, and not (for example) also on
11705 the files specified by the #include lines in the file being
11706 scanned. recursive may be a callable function, in which case it
11707 will be called with a list of Nodes found and should return a list
11708 of Nodes that should be scanned recursively; this can be used to
11709 select a specific subset of Nodes for additional scanning.
11710 Note that scons has a global SourceFileScanner object that is used by
11712 the Object(), SharedObject(), and StaticObject() builders to decide
11713 which scanner should be used for different file extensions. You can
11714 using the SourceFileScanner.add_scanner() method to add your own
11715 Scanner object to the scons infrastructure that builds target programs
11716 or libraries from a list of source files of different types:
11717 def xyz_scan(node, env, path):
11719 contents = node.get_text_contents()
11720 # Scan the contents and return the included files.
11721 XYZScanner = Scanner(xyz_scan)
11723 SourceFileScanner.add_scanner('.xyz', XYZScanner)
11725 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
11727
11729 SCons and its configuration files are very portable, due largely to its
11730 implementation in Python. There are, however, a few portability issues
11731 waiting to trap the unwary.
11732 .C file suffix
11734 SCons handles the upper-case .C file suffix differently, depending on
11735 the capabilities of the underlying system. On a case-sensitive system
11736 such as Linux or UNIX, SCons treats a file with a .C suffix as a C++
11737 source file. On a case-insensitive system such as Windows, SCons treats
11738 a file with a .C suffix as a C source file.
11739 .F file suffix
11741 SCons handles the upper-case .F file suffix differently, depending on
11742 the capabilities of the underlying system. On a case-sensitive system
11743 such as Linux or UNIX, SCons treats a file with a .F suffix as a
11744 Fortran source file that is to be first run through the standard C
11745 preprocessor. On a case-insensitive system such as Windows, SCons
11746 treats a file with a .F suffix as a Fortran source file that should not
11747 be run through the C preprocessor.
11748 Windows: Cygwin Tools and Cygwin Python vs. Windows Pythons
11750 Cygwin supplies a set of tools and utilities that let users work on a
11751 Windows system using a more POSIX-like environment. The Cygwin tools,
11752 including Cygwin Python, do this, in part, by sharing an ability to
11753 interpret UNIX-like path names. For example, the Cygwin tools will
11754 internally translate a Cygwin path name like /cygdrive/c/mydir to an
11755 equivalent Windows pathname of C:/mydir (equivalent to C:\mydir).
11756 Versions of Python that are built for native Windows execution, such as
11758 the python.org and ActiveState versions, do not have the Cygwin path
11759 name semantics. This means that using a native Windows version of
11760 Python to build compiled programs using Cygwin tools (such as gcc,
11761 bison, and flex) may yield unpredictable results. "Mixing and matching"
11762 in this way can be made to work, but it requires careful attention to
11763 the use of path names in your SConscript files.
11764 In practice, users can sidestep the issue by adopting the following
11766 rules: When using gcc, use the Cygwin-supplied Python interpreter to
11767 run SCons; when using Microsoft Visual C/C++ (or some other Windows
11768 compiler) use the python.org or ActiveState version of Python to run
11769 SCons.
11770 Windows: scons.bat file
11772 On Windows systems, SCons is executed via a wrapper scons.bat file.
11773 This has (at least) two ramifications:
11774 First, Windows command-line users that want to use variable assignment
11776 on the command line may have to put double quotes around the
11777 assignments:
11778 scons "FOO=BAR" "BAZ=BLEH"
11780 Second, the Cygwin shell does not recognize this file as being the same
11782 as an scons command issued at the command-line prompt. You can work
11783 around this either by executing scons.bat from the Cygwin command line,
11784 or by creating a wrapper shell script named scons .
11785 MinGW
11787 The MinGW bin directory must be in your PATH environment variable or
11788 the PATH variable under the ENV construction variable for SCons to
11789 detect and use the MinGW tools. When running under the native Windows
11790 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
11791 tools, if they are both installed, regardless of the order of the bin
11792 directories in the PATH variable. If you have both MSVC and MinGW
11793 installed and you want to use MinGW instead of MSVC, then you must
11794 explicitly tell SCons to use MinGW by passing
11795 tools=['mingw']
11797 to the Environment() function, because SCons will prefer the MSVC tools
11799 over the MinGW tools.
11800
11802 To help you get started using SCons, this section contains a brief
11803 overview of some common tasks.
11804 Basic Compilation From a Single Source File
11806 env = Environment()
11807 env.Program(target = 'foo', source = 'foo.c')
11808 Note: Build the file by specifying the target as an argument ("scons
11810 foo" or "scons foo.exe"). or by specifying a dot ("scons .").
11811 Basic Compilation From Multiple Source Files
11813 env = Environment()
11814 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
11815 Setting a Compilation Flag
11817 env = Environment(CCFLAGS = '-g')
11818 env.Program(target = 'foo', source = 'foo.c')
11819 Search The Local Directory For .h Files
11821 Note: You do not need to set CCFLAGS to specify -I options by hand.
11822 SCons will construct the right -I options from CPPPATH.
11823 env = Environment(CPPPATH = ['.'])
11825 env.Program(target = 'foo', source = 'foo.c')
11826 Search Multiple Directories For .h Files
11828 env = Environment(CPPPATH = ['include1', 'include2'])
11829 env.Program(target = 'foo', source = 'foo.c')
11830 Building a Static Library
11832 env = Environment()
11833 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
11834 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
11835 Building a Shared Library
11837 env = Environment()
11838 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
11839 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
11840 Linking a Local Library Into a Program
11842 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
11843 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
11844 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
11845 Defining Your Own Builder Object
11847 Notice that when you invoke the Builder, you can leave off the target
11848 file suffix, and SCons will add it automatically.
11849 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
11851 suffix = '.pdf',
11852 src_suffix = '.tex')
11853 env = Environment(BUILDERS = {'PDFBuilder' : bld})
11854 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
11855 # The following creates "bar.pdf" from "bar.tex"
11857 env.PDFBuilder(target = 'bar', source = 'bar')
11858 Note also that the above initialization overwrites the default Builder
11860 objects, so the Environment created above can not be used call Builders
11861 like env.Program(), env.Object(), env.StaticLibrary(), etc.
11862 Adding Your Own Builder Object to an Environment
11864 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
11865 suffix = '.pdf',
11866 src_suffix = '.tex')
11867 env = Environment()
11868 env.Append(BUILDERS = {'PDFBuilder' : bld})
11869 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
11870 env.Program(target = 'bar', source = 'bar.c')
11871 You also can use other Pythonic techniques to add to the BUILDERS
11873 construction variable, such as:
11874 env = Environment()
11876 env['BUILDERS]['PDFBuilder'] = bld
11877 Defining Your Own Scanner Object
11879 The following example shows an extremely simple scanner (the
11880 kfile_scan() function) that doesn't use a search path at all and simply
11881 returns the file names present on any include lines in the scanned
11882 file. This would implicitly assume that all included files live in the
11883 top-level directory:
11884 import re
11886 include_re = re.compile(r'^include\s+(\S+)$', re.M)
11888 def kfile_scan(node, env, path, arg):
11890 contents = node.get_text_contents()
11891 includes = include_re.findall(contents)
11892 return env.File(includes)
11893 kscan = Scanner(name = 'kfile',
11895 function = kfile_scan,
11896 argument = None,
11897 skeys = ['.k'])
11898 scanners = Environment().Dictionary('SCANNERS')
11899 env = Environment(SCANNERS = scanners + [kscan])
11900 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
11902 bar_in = File('bar.in')
11904 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
11905 bar_in.target_scanner = kscan
11906 It is important to note that you have to return a list of File nodes
11908 from the scan function, simple strings for the file names won't do. As
11909 in the examples we are showing here, you can use the File() function of
11910 your current Environment in order to create nodes on the fly from a
11911 sequence of file names with relative paths.
11912 Here is a similar but more complete example that searches a path of
11914 directories (specified as the MYPATH construction variable) for files
11915 that actually exist:
11916 import re
11918 import os
11919 include_re = re.compile(r'^include\s+(\S+)$', re.M)
11920 def my_scan(node, env, path, arg):
11922 contents = node.get_text_contents()
11923 includes = include_re.findall(contents)
11924 if includes == []:
11925 return []
11926 results = []
11927 for inc in includes:
11928 for dir in path:
11929 file = str(dir) + os.sep + inc
11930 if os.path.exists(file):
11931 results.append(file)
11932 break
11933 return env.File(results)
11934 scanner = Scanner(name = 'myscanner',
11936 function = my_scan,
11937 argument = None,
11938 skeys = ['.x'],
11939 path_function = FindPathDirs('MYPATH')
11940 )
11941 scanners = Environment().Dictionary('SCANNERS')
11942 env = Environment(SCANNERS = scanners + [scanner],
11943 MYPATH = ['incs'])
11944 env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
11946 The FindPathDirs() function used in the previous example returns a
11948 function (actually a callable Python object) that will return a list of
11949 directories specified in the $MYPATH construction variable. It lets
11950 SCons detect the file incs/foo.inc , even if foo.x contains the line
11951 include foo.inc only. If you need to customize how the search path is
11952 derived, you would provide your own path_function argument when
11953 creating the Scanner object, as follows:
11954 # MYPATH is a list of directories to search for files in
11956 def pf(env, dir, target, source, arg):
11957 top_dir = Dir('#').abspath
11958 results = []
11959 if 'MYPATH' in env:
11960 for p in env['MYPATH']:
11961 results.append(top_dir + os.sep + p)
11962 return results
11963 scanner = Scanner(name = 'myscanner',
11965 function = my_scan,
11966 argument = None,
11967 skeys = ['.x'],
11968 path_function = pf
11969 )
11970 Creating a Hierarchical Build
11972 Notice that the file names specified in a subdirectory's SConscript
11973 file are relative to that subdirectory.
11974 SConstruct:
11976 env = Environment()
11978 env.Program(target = 'foo', source = 'foo.c')
11979 SConscript('sub/SConscript')
11981 sub/SConscript:
11983 env = Environment()
11985 # Builds sub/foo from sub/foo.c
11986 env.Program(target = 'foo', source = 'foo.c')
11987 SConscript('dir/SConscript')
11989 sub/dir/SConscript:
11991 env = Environment()
11993 # Builds sub/dir/foo from sub/dir/foo.c
11994 env.Program(target = 'foo', source = 'foo.c')
11995 Sharing Variables Between SConscript Files
11997 You must explicitly Export() and Import() variables that you want to
11998 share between SConscript files.
11999 SConstruct:
12001 env = Environment()
12003 env.Program(target = 'foo', source = 'foo.c')
12004 Export("env")
12006 SConscript('subdirectory/SConscript')
12007 subdirectory/SConscript:
12009 Import("env")
12011 env.Program(target = 'foo', source = 'foo.c')
12012 Building Multiple Variants From the Same Source
12014 Use the variant_dir keyword argument to the SConscript function to
12015 establish one or more separate variant build directory trees for a
12016 given source directory:
12017 SConstruct:
12019 cppdefines = ['FOO']
12021 Export("cppdefines")
12022 SConscript('src/SConscript', variant_dir='foo')
12023 cppdefines = ['BAR']
12025 Export("cppdefines")
12026 SConscript('src/SConscript', variant_dir='bar')
12027 src/SConscript:
12029 Import("cppdefines")
12031 env = Environment(CPPDEFINES = cppdefines)
12032 env.Program(target = 'src', source = 'src.c')
12033 Note the use of the Export() method to set the "cppdefines" variable to
12035 a different value each time we call the SConscript function.
12036 Hierarchical Build of Two Libraries Linked With a Program
12038 SConstruct:
12039 env = Environment(LIBPATH = ['#libA', '#libB'])
12041 Export('env')
12042 SConscript('libA/SConscript')
12043 SConscript('libB/SConscript')
12044 SConscript('Main/SConscript')
12045 libA/SConscript:
12047 Import('env')
12049 env.Library('a', Split('a1.c a2.c a3.c'))
12050 libB/SConscript:
12052 Import('env')
12054 env.Library('b', Split('b1.c b2.c b3.c'))
12055 Main/SConscript:
12057 Import('env')
12059 e = env.Copy(LIBS = ['a', 'b'])
12060 e.Program('foo', Split('m1.c m2.c m3.c'))
12061 The '#' in the LIBPATH directories specify that they're relative to the
12063 top-level directory, so they don't turn into "Main/libA" when they're
12064 used in Main/SConscript.
12065 Specifying only 'a' and 'b' for the library names allows SCons to
12067 append the appropriate library prefix and suffix for the current
12068 platform (for example, 'liba.a' on POSIX systems, 'a.lib' on Windows).
12069 Customizing construction variables from the command line.
12071 The following would allow the C compiler to be specified on the command
12072 line or in the file custom.py.
12073 vars = Variables('custom.py')
12075 vars.Add('CC', 'The C compiler.')
12076 env = Environment(variables=vars)
12077 Help(vars.GenerateHelpText(env))
12078 The user could specify the C compiler on the command line:
12080 scons "CC=my_cc"
12082 or in the custom.py file:
12084 CC = 'my_cc'
12086 or get documentation on the options:
12088 $ scons -h
12090 CC: The C compiler.
12092 default: None
12093 actual: cc
12094 Using Microsoft Visual C++ precompiled headers
12097 Since windows.h includes everything and the kitchen sink, it can take
12098 quite some time to compile it over and over again for a bunch of object
12099 files, so Microsoft provides a mechanism to compile a set of headers
12100 once and then include the previously compiled headers in any object
12101 file. This technology is called precompiled headers. The general recipe
12102 is to create a file named "StdAfx.cpp" that includes a single header
12103 named "StdAfx.h", and then include every header you want to precompile
12104 in "StdAfx.h", and finally include "StdAfx.h" as the first header in
12105 all the source files you are compiling to object files. For example:
12106 StdAfx.h:
12108 #include <windows.h>
12110 #include <my_big_header.h>
12111 StdAfx.cpp:
12113 #include <StdAfx.h>
12115 Foo.cpp:
12117 #include <StdAfx.h>
12119 /* do some stuff */
12121 Bar.cpp:
12123 #include <StdAfx.h>
12125 /* do some other stuff */
12127 SConstruct:
12129 env=Environment()
12131 env['PCHSTOP'] = 'StdAfx.h'
12132 env['PCH'] = env.PCH('StdAfx.cpp')[0]
12133 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
12134 For more information see the document for the PCH builder, and the PCH
12136 and PCHSTOP construction variables. To learn about the details of
12137 precompiled headers consult the MSDN documentation for /Yc, /Yu, and
12138 /Yp.
12139 Using Microsoft Visual C++ external debugging information
12141 Since including debugging information in programs and shared libraries
12142 can cause their size to increase significantly, Microsoft provides a
12143 mechanism for including the debugging information in an external file
12144 called a PDB file. SCons supports PDB files through the PDB
12145 construction variable.
12146 SConstruct:
12148 env=Environment()
12150 env['PDB'] = 'MyApp.pdb'
12151 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
12152 For more information see the document for the PDB construction
12154 variable.
12155
12157 SCONS_LIB_DIR
12158 Specifies the directory that contains the SCons Python module
12159 directory (e.g. /home/aroach/scons-src-0.01/src/engine).
12160 SCONSFLAGS
12162 A string of options that will be used by scons in addition to those
12163 passed on the command line.
12164
12166 scons User Manual, scons Design Document, scons source code.
12167
12169 Originally: Steven Knight <knight@baldmt.com> and Anthony Roach
12170 <aroach@electriceyeball.com> Since 2010: The SCons Development Team
12171 <scons-dev@scons.org>
12172
12174 Steven Knight
12175 Author.
12176 Steven Knight and the SCons Development Team
12178
12180 Copyright © 2004 - 2016 The SCons Foundation
12181SCons 3.0.1 version 3.0.1<pubdate>2004 - 2016</pubdate> SCONS(1)