3 .\" Permission is hereby granted, free of charge, to any person obtaining
4 .\" a copy of this software and associated documentation files (the
5 .\" "Software"), to deal in the Software without restriction, including
6 .\" without limitation the rights to use, copy, modify, merge, publish,
7 .\" distribute, sublicense, and/or sell copies of the Software, and to
8 .\" permit persons to whom the Software is furnished to do so, subject to
9 .\" the following conditions:
11 .\" The above copyright notice and this permission notice shall be included
12 .\" in all copies or substantial portions of the Software.
14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
15 .\" KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
16 .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17 .\" NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18 .\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19 .\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20 .\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 .\" __FILE__ __REVISION__ __DATE__ __DEVELOPER__
24 .\" ES - Example Start - indents and turns off line fill
29 .\" EE - Example End - ends indent and turns line fill back on
34 .TH SCONS 1 "April 2003"
36 scons \- a software construction tool
52 utility builds software (or other files) by determining which
53 component pieces must be rebuilt and executing the necessary commands to
58 searches for a file named
63 (in that order) in the current directory and reads its
64 configuration from the first file found.
65 An alternate file name may be
72 file can specify subsidiary
73 configuration files using the
77 these subsidiary files are named
79 although any name may be used.
80 (Because of this naming convention,
81 the term "SConscript files"
82 is sometimes used to refer
86 regardless of actual file name.)
88 The configuration files
89 specify the target files to be built, and
90 (optionally) the rules to build those targets. Reasonable default
91 rules exist for building common software components (executable
92 programs, object files, libraries), so that for most software
93 projects, only the target and input files need be specified.
96 reads and executes the SConscript files as Python scripts,
97 so you may use normal Python scripting capabilities
98 (such as flow control, data manipulation, and imported Python libraries)
99 to handle complicated build situations.
101 however, reads all of the SConscript files
103 it begins building any targets.
104 To make this obvious,
106 prints the following messages about what it is doing:
110 scons: Reading SConscript files ...
111 scons: done reading SConscript files.
112 scons: Building targets ...
114 scons: done building targets.
119 (everything except the line that reads "cp foo.in foo.out")
120 may be suppressed using the
125 can scan known input files automatically for dependency
126 information (for example, #include statements
127 in C or C++ files) and will rebuild dependent files appropriately
128 whenever any "included" input file changes.
131 ability to define new scanners for unknown input file types.
134 knows how to fetch files automatically from
135 SCCS or RCS subdirectories
136 using SCCS, RCS or BitKeeper.
139 is normally executed in a top-level directory containing a
141 file, optionally specifying
142 as command-line arguments
143 the target file or files to be built.
145 By default, the command
151 will build all target files in or below the current directory.
152 Explicit default targets
153 (to be built when no targets are specified on the command line)
154 may be defined the SConscript file(s)
157 function, described below.
161 targets are specified in the SConscript file(s),
162 all target files in or below the current directory
163 may be built by explicitly specifying
164 the current directory (.)
165 as a command-line target:
171 Building all target files,
172 including any files outside of the current directory,
173 may be specified by supplying a command-line target
174 of the root directory (on POSIX systems):
180 or the path name(s) of the volume(s) in which all the targets
181 should be built (on Windows systems):
187 To build only specific targets,
188 supply them as command-line arguments:
194 in which case only the specified targets will be built
195 (along with any derived files on which they depend).
197 Specifying "cleanup" targets in SConscript files is not
200 flag removes all files
201 necessary to build the specified target:
207 to remove all target files, or:
210 scons -c build export
213 to remove target files under build and export.
214 Additional files or directories to remove can be specified using the
217 A subset of a hierarchical tree may be built by
218 remaining at the top-level directory (where the
220 file lives) and specifying the subdirectory as the target to be
227 or by changing directory and invoking scons with the
229 option, which traverses up the directory
230 hierarchy until it finds the
232 file, and then builds
233 targets relatively to the current subdirectory:
241 supports building multiple targets in parallel via a
243 option that takes, as its argument, the number
244 of simultaneous tasks that may be spawned:
250 builds four targets in parallel, for example.
253 can maintain a cache of target (derived) files that can
254 be shared between multiple builds. When caching is enabled in a
255 SConscript file, any target files built by
258 to the cache. If an up-to-date target file is found in the cache, it
259 will be retrieved from the cache instead of being rebuilt locally.
260 Caching behavior may be disabled and controlled in other ways by the
262 .BR --cache-disable ,
265 command-line options. The
267 option is useful to prevent multiple builds
268 from trying to update the cache simultaneously.
270 Values of variables to be passed to the SConscript file(s)
271 may be specified on the command line:
277 These variables are available in SConscript files
278 through the ARGUMENTS dictionary,
279 and can be used in the SConscript file(s) to modify
280 the build in any way:
283 if ARGUMENTS.get('debug', 0):
284 env = Environment(CCFLAGS = '-g')
290 requires Python version 1.5.2 or later.
291 There should be no other dependencies or requirements to run
294 .\" The following paragraph reflects the default tool search orders
295 .\" currently in SCons/Tool/__init__.py. If any of those search orders
296 .\" change, this documentation should change, too.
299 knows how to search for available programming tools
303 searches in order for the
304 Microsoft Visual C++ tools,
305 the MinGW tool chain,
306 the Intel compiler tools,
307 and the PharLap ETS compiler.
310 searches in order for the
313 and the Microsoft Visual C++ tools,
314 On SGI IRIX, IBM AIX, Hewlett Packard HP-UX, and Sun Solaris systems,
316 searches for the native compiler tools
317 (MIPSpro, Visual Age, aCC, and Forte tools respectively)
318 and the GCC tool chain.
319 On all other platforms,
320 including POSIX (Linux and UNIX) platforms,
323 for the GCC tool chain,
324 the Microsoft Visual C++ tools,
325 and the Intel compiler tools.
326 You may, of course, override these default values
327 by appropriate configuration of
328 Environment construction variables.
333 supports the same command-line options as GNU
335 and many of those supported by
340 Ignored for compatibility with non-GNU versions of
344 -c, --clean, --remove
345 Clean up by removing all target files for which a construction
346 command is specified.
347 Also remove any files or directories associated to the construction command
348 using the Clean() function.
351 --cache-disable, --no-cache
352 Disable the derived-file caching specified by
355 will neither retrieve files from the cache
356 nor copy files to the cache.
359 --cache-force, --cache-populate
362 populate a cache by copying any already-existing, up-to-date
363 derived files to the cache,
364 in addition to files built by this invocation.
365 This is useful to populate a new cache with
366 all the current derived files,
367 or to add to the cache any derived files
368 recently built with caching disabled via the
376 and retrieving a derived file from the cache,
378 that would have been executed to build the file,
379 instead of the usual report,
380 "Retrieved `file' from cache."
381 This will produce consistent output for build logs,
382 regardless of whether a target
383 file was rebuilt or retrieved from the cache.
386 .RI "-C" " directory" ", --directory=" directory
387 Change to the specified
389 before searching for the
394 file, or doing anything
397 options are interpreted
398 relative to the previous one, and the right-most
400 option wins. (This option is nearly
402 .BR "-f directory/SConstruct" ,
403 except that it will search for
408 in the specified directory.)
412 .\" Display dependencies while building target files. Useful for
413 .\" figuring out why a specific file is being rebuilt, as well as
414 .\" general debugging of the build process.
418 Works exactly the same way as the
420 option except for the way default targets are handled.
421 When this option is used and no targets are specified on the command line,
422 all default targets are built, whether or not they are below the current
427 Debug the build process.
429 specifies what type of debugging:
433 Re-run SCons under the control of the
438 argument will be stripped from the command-line,
439 but all other arguments will be passed in-order
440 to the SCons invocation run by the debugger.
444 Print the dependency tree
445 after each top-level target is built. This prints out the complete
446 dependency tree including implicit dependencies and ignored
451 Print the dependency tree
452 after each top-level target is built. This prints out only derived files.
456 Prints various time profiling information: the time spent
457 executing each build command, the total build time, the total time spent
458 executing build commands, the total time spent executing SConstruct and
459 SConscript files, and the total time spent executing SCons itself.
463 Print the include tree after each top-level target is built.
464 This is generally used to find out what files are included by the sources
465 of a given derived file:
468 $ scons --debug=includes foo.o
472 -e, --environment-overrides
473 Variables from the execution environment override construction
474 variables from the SConscript files.
477 .RI -f " file" ", --file=" file ", --makefile=" file ", --sconstruct=" file
480 as the initial SConscript file.
484 Print a local help message for this build, if one is defined in
485 the SConscript file(s), plus a line that describes the
487 option for command-line option help. If no local help message
488 is defined, prints the standard help message about command-line
489 options. Exits after displaying the appropriate message.
493 Print the standard help message about command-line options and
498 Ignore all errors from commands executed to rebuild files.
501 .RI -I " directory" ", --include-dir=" directory
505 imported Python modules. If several
508 are used, the directories are searched in the order specified.
512 Cache implicit dependencies. This can cause
514 to miss changes in the implicit dependencies in cases where a new implicit
515 dependency is added earlier in the implicit dependency search path
516 (e.g. CPPPATH) than a current implicit dependency with the same name.
519 --implicit-deps-changed
520 Force SCons to ignore the cached implicit dependencies. This causes the
521 implicit dependencies to be rescanned and recached. This implies
522 .BR --implicit-cache .
525 --implicit-deps-unchanged
526 Force SCons to ignore changes in the implicit dependencies.
527 This causes cached implicit dependencies to always be used.
529 .BR --implicit-cache .
532 .RI -j " N" ", --jobs=" N
533 Specifies the number of jobs (commands) to run simultaneously.
534 If there is more than one
536 option, the last one is effective.
540 .\" is specified without an argument,
542 .\" will not limit the number of
543 .\" simultaneous jobs.
547 Continue as much as possible after an error. The target that
548 failed and those that depend on it will not be remade, but other
549 targets specified on the command line will still be processed.
552 .\" .RI -l " N" ", --load-average=" N ", --max-load=" N
553 .\" No new jobs (commands) will be started if
554 .\" there are other jobs running and the system load
555 .\" average is at least
557 .\" (a floating-point number).
561 .\" List derived files (targets, dependencies) that would be built,
562 .\" but do not build them.
563 .\" [XXX This can probably go away with the right
564 .\" combination of other options. Revisit this issue.]
568 .\" List derived files that would be built, with the actions
569 .\" (commands) that build them. Does not build the files.
570 .\" [XXX This can probably go away with the right
571 .\" combination of other options. Revisit this issue.]
575 .\" List derived files that would be built, plus where the file is
576 .\" defined (file name and line number). Does not build the files.
577 .\" [XXX This can probably go away with the right
578 .\" combination of other options. Revisit this issue.]
582 Ignored for compatibility with non-GNU versions of
586 .RI --max-drift= SECONDS
587 Set the maximum expected drift in the modification time of files to
589 This value determines how old a file must be before its content signature
590 is cached. The default value is 2 days, which means a file must have a
591 modification time of at least two days ago in order to have its content
592 signature cached. A negative value means to never cache the content
593 signature and to ignore the cached value if there already is one. A value
594 of 0 means to always cache the signature, no matter how old the file is.
597 -n, --just-print, --dry-run, --recon
598 No execute. Print the commands that would be executed to build
599 any out-of-date target files, but do not execute the commands.
602 .\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
606 .\" not rebuild anything due to changes in the contents of
609 .\" .RI --override " file"
610 .\" Read values to override specific build environment variables
611 .\" from the specified
615 .\" Print the data base (construction environments,
616 .\" Builder and Scanner objects) that are defined
617 .\" after reading the SConscript files.
618 .\" After printing, a normal build is performed
619 .\" as usual, as specified by other command-line options.
620 .\" This also prints version information
625 .\" To print the database without performing a build do:
633 Run SCons under the Python profiler
634 and save the results in the specified
636 The results may be analyzed using the Python
640 Do not run any commands, or print anything. Just return an exit
641 status that is zero if the specified targets are already up to
642 date, non-zero otherwise.
645 Quiets SCons status messages about
646 reading SConscript files,
648 and entering directories.
649 Commands that are executed
650 to rebuild target files are still printed.
653 .\" -r, -R, --no-builtin-rules, --no-builtin-variables
654 .\" Clear the default construction variables. Construction
655 .\" environments that are created will be completely empty.
659 Build dependencies in a random order. This is useful when
660 building multiple trees simultaneously with caching enabled,
661 to prevent multiple builds from simultaneously trying to build
662 or retrieve the same target files.
665 -s, --silent, --quiet
666 Silent. Do not print commands that are executed to rebuild
668 Also suppresses SCons status messages.
671 -S, --no-keep-going, --stop
672 Ignored for compatibility with GNU
677 Ignored for compatibility with GNU
679 (Touching a file to make it
680 appear up-to-date is unnecessary when using
684 -u, --up, --search-up
685 Walks up the directory structure until an
690 file is found, and uses that
691 as the top of the directory tree. Only targets at or below the
692 current directory will be built.
696 Works exactly the same way as the
698 option except for the way default targets are handled.
699 When this option is used and no targets are specified on the command line,
700 all default targets that are defined in the SConscript(s) in the current
701 directory are built, regardless of what directory the resultant targets end
708 version, copyright information,
709 list of authors, and any other relevant information.
713 -w, --print-directory
714 Print a message containing the working directory before and
715 after other processing.
718 .RI --warn= type ", --warn=no-" type
719 Enable or disable warnings.
721 specifies the type of warnings to be enabled or disabled:
724 .RI --warn=all ", " --warn=no-all
725 Enables or disables all warnings.
728 .RI --warn=dependency ", " --warn=no-dependency
729 Enables or disables warnings about dependencies.
730 These warnings are disabled by default.
733 .RI --warn=deprecated ", " --warn=no-deprecated
734 Enables or disables warnings about use of deprecated features.
735 These warnings are enabled by default.
739 Turn off -w, even if it was turned on implicitly.
742 .\" .RI --write-filenames= file
743 .\" Write all filenames considered into
747 .\" .RI -W " file" ", --what-if=" file ", --new-file=" file ", --assume-new=" file
748 .\" Pretend that the target
751 .\" modified. When used with the
754 .\" show you what would be rebuilt if you were to modify that file.
760 .\" --warn-undefined-variables
761 .\" Warn when an undefined variable is referenced.
764 .RI -Y " repository" ", --repository=" repository
765 Search the specified repository for any input and target
766 files not found in the local directory hierarchy. Multiple
768 options may specified, in which case the
769 repositories are searched in the order specified.
771 .SH CONFIGURATION FILE REFERENCE
772 .\" .SS Python Basics
773 .\" XXX Adding this in the future would be a help.
774 .SS Construction Environments
775 A construction environment is the basic means by which the SConscript
776 files communicate build information to
778 A new construction environment is created using the
786 By default, a new construction environment is
787 initialized with a set of builder methods
788 and construction variables that are appropriate
789 for the current platform.
790 An optional platform keyword argument may be
791 used to specify that an environment should
792 be initialized for a different platform:
795 env = Environment(platform = 'cygwin')
796 env = Environment(platform = 'os2')
797 env = Environment(platform = 'posix')
798 env = Environment(platform = 'win32')
801 Specifying a platform initializes the appropriate
802 construction variables in the environment
803 to use and generate file names with prefixes
804 and suffixes appropriate for the platform.
810 variable from the user's external environment
811 to the construction environment's
814 This is so that any executed commands
815 that use sockets to connect with other systems
816 (such as fetching source files from
817 external CVS repository specifications like
818 .BR :pserver:anonymous:@cvs.sourceforge.net:/cvsroot/scons )
819 will work on Win32 systems.
821 The platform argument may be function or callable object,
822 in which case the Environment() method
823 will call the specified argument to update
824 the new construction environment:
827 def my_platform(env):
830 env = Environment(platform = my_platform)
833 Additionally, a specific set of tools
834 with which to initialize the environment
835 may specified as an optional keyword argument:
838 env = Environment(tools = ['msvc', 'lex'])
841 The elements of the tools list may also
842 be functions or callable objects,
843 in which case the Environment() method
844 will call the specified elements
845 to update the new construction environment:
849 env['XYZZY'] = 'xyzzy'
851 env = Environment(tools = [my_tool])
854 The tool definition (i.e. my_tool()) can use the PLATFORM variable from
855 the environment it receives to customize the tool for different platforms.
857 If no tool list is specified, then SCons will auto-detect the installed
858 tools using the PATH variable in the ENV construction variable and the
859 platform name when the Environment is constructed. Changing the PATH
860 variable after the Environment is constructed will not cause the tools to
863 SCons supports the following tool specifications
864 out of the box on all platforms:
904 Additionally, there is a "tool" named
907 environment with a default set of tools for the current platform.
909 On posix and cygwin platforms
910 the GNU tools (e.g. gcc) are preferred by SCons,
911 on win32 the Microsoft tools (e.g. msvc)
912 followed by MinGW are preferred by SCons,
913 and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.
917 Build rules are specified by calling a construction
918 environment's builder methods.
919 The arguments to the builder methods are
921 (a list of target files)
924 (a list of source files).
926 Because long lists of file names
927 can lead to a lot of quoting,
931 function that splits a single string
932 into a list, separated on
933 strings of white-space characters.
934 (This is similar to the
935 string.split() method
936 from the standard Python library.)
938 Like all Python arguments,
939 the target and source arguments to a builder
940 can be specified either with or without
941 the "target" and "source" keywords.
942 When the keywords are omitted,
944 followed by the source.
945 The following are equivalent examples of calling the Program builder:
948 env.Program('bar', ['bar.c', 'foo.c'])
949 env.Program('bar', Split('bar.c foo.c'))
950 env.Program(source = ['bar.c', 'foo.c'], target = 'bar')
951 env.Program(target = 'bar', Split('bar.c foo.c'))
952 env.Program('bar', source = string.split('bar.c foo.c'))
955 When the target shares the same base name
956 as the source and only the suffix varies,
957 and if the builder has a suffix defined for the target file type,
958 then the target argument may be omitted completely,
961 will deduce the target file name from
962 the source file name.
963 The following examples all build the
970 from the bar.c source file:
973 env.Program(target = 'bar', source = 'bar.c')
974 env.Program('bar', source = 'bar.c')
975 env.Program(source = 'bar.c')
979 It is possible to override or add construction variables when calling a
980 builder by passing additional keyword arguments. These overridden or added
981 variables will only be in effect when building the target, so they will not
982 affect other parts of the build. For example, if you want to add additional
983 libraries for just one program:
986 env.Program('hello', 'hello.c', LIBS=['gl', 'glut'])
989 or generate a shared library with a nonstandard suffix:
992 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
995 All Builders return a Node or a list of Nodes,
996 representing the target or targets that will be built.
997 A list of Nodes is returned if there is more than one target,
998 and a single Node is returned if there is only one target.
1001 is an internal SCons object
1003 build targets or sources.
1005 The returned Node(s)
1006 can be passed to other builder methods as source(s)
1007 or passed into to any SCons function or method
1008 where a filename would normally be accepted.
1009 For example, if it were necessary
1012 flag when compiling one specific object file:
1015 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1016 env.Program(source = ['foo.c', bar_obj, 'main.c'])
1019 Using a Node in this way
1020 makes for a more portable build
1021 by avoiding having to specify
1022 a platform-specific object suffix
1023 when calling the Program() builder.
1025 The path name for a Node's file may be used
1026 by passing the Node to the Python-builtin
1031 bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
1032 print "The path to bar_obj is:", str(bar_obj)
1036 provides the following builders:
1039 Builds a static object file
1040 from one or more C, C++, or Fortran source files.
1041 Source files must have one of the following extensions:
1043 .asm assembly language file
1044 .ASM assembly language file
1055 .F WIN32: Fortran file
1056 POSIX: Fortran file + C pre-processor
1059 .fpp Fortran file + C pre-processor
1060 .FPP Fortran file + C pre-processor
1061 .s assembly language file
1062 .S WIN32: assembly language file
1063 POSIX: assembly language file + C pre-processor
1064 .spp assembly language file + C pre-processor
1065 .SPP assembly language file + C pre-processor
1068 The target object file prefix
1069 (specified by the $OBJPREFIX construction variable; nothing by default)
1071 (specified by the $OBJSUFFIX construction variable;
1072 \.obj on Windows systems, .o on POSIX systems)
1073 are automatically added to the target if not already present.
1077 env.StaticObject(target = 'aaa', source = 'aaa.c')
1078 env.StaticObject(target = 'bbb.o', source = 'bbb.c++')
1079 env.StaticObject(target = 'ccc.obj', source = 'ccc.f')
1082 Builds an object file for
1083 inclusion in a shared library.
1084 Source files must have one of the same set of extensions
1085 specified above for the
1087 builder. On some platforms building a shared object requires additional
1088 compiler options (e.g. -fPIC for gcc) in addition to those needed to build a
1089 normal (static) object, but on some platforms there is no difference between a
1090 shared object and a normal (static) one. When there is a difference, SCons
1091 will only allow shared objects to be linked into a shared library, and will
1092 use a different suffix for shared objects. On platforms where there is no
1093 difference, SCons will allow both normal (static)
1094 and shared objects to be linked into a
1095 shared library, and will use the same suffix for shared and normal
1097 The target object file prefix
1098 (specified by the $SHOBJPREFIX construction variable;
1099 by default, the same as $OBJPREFIX)
1101 (specified by the $SHOBJSUFFIX construction variable)
1102 are automatically added to the target if not already present.
1106 env.SharedObject(target = 'ddd', source = 'ddd.c')
1107 env.SharedObject(target = 'eee.o', source = 'eee.cpp')
1108 env.SharedObject(target = 'fff.obj', source = 'fff.for')
1117 Builds a Microsoft Visual C++ precompiled header. Calling this builder
1118 returns a list of two targets: the PCH as the first element, and the object
1119 file as the second element. Normally the object file is ignored. This builder is only
1120 provided when Microsoft Visual C++ is being used as the compiler.
1121 The PCH builder is generally used in
1122 conjuction with the PCH construction variable to force object files to use
1123 the precompiled header:
1126 env['PCH'] = env.PCH('StdAfx.cpp')[0]
1130 Builds an executable given one or more object files or C, C++
1131 or Fortran source files.
1132 If any C, C++ or Fortran source files are specified,
1133 then they will be automatically
1134 compiled to object files using the
1137 see that builder's description for
1138 a list of legal source file suffixes
1139 and how they are interpreted.
1140 The target executable file prefix
1141 (specified by the $PROGPREFIX construction variable; nothing by default)
1143 (specified by the $PROGSUFFIX construction variable;
1144 by default, .exe on Windows systems, nothing on POSIX systems)
1145 are automatically added to the target if not already present.
1149 env.Program(target = 'foo', source = ['foo.o', 'bar.c', 'baz.f'])
1153 Builds a Microsoft Visual C++ resource file.
1154 This builder is only provided
1155 when Microsoft Visual C++ or MinGW is being used as the compiler. The
1159 for MinGW) suffix is added to the target name if no other suffix is given. The source
1160 file is scanned for implicit dependencies as though it were a C file. Example:
1163 env.RES('resource.rc')
1167 Builds a static library given one or more object files
1168 or C, C++ or Fortran source files.
1169 If any source files are given,
1170 then they will be automatically
1171 compiled to object files.
1172 The static library prefix and suffix (if any)
1173 are automatically added to the target.
1174 The target library file prefix
1175 (specified by the $LIBPREFIX construction variable;
1176 by default, lib on POSIX systems, nothing on Windows systems)
1178 (specified by the $LIBSUFFIX construction variable;
1179 by default, .lib on Windows systems, .a on POSIX systems)
1180 are automatically added to the target if not already present.
1184 env.StaticLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1188 Any object files listed in the
1190 must have been built for a static library
1195 will raise an error if there is any mismatch.
1198 Builds a shared library
1199 (.so on a POSIX system, .dll on WIN32)
1200 given one or more object files
1201 or C, C++ or Fortran source files.
1202 If any source files are given,
1203 then they will be automatically
1204 compiled to object files.
1205 The static library prefix and suffix (if any)
1206 are automatically added to the target.
1207 The target library file prefix
1208 (specified by the $SHLIBPREFIX construction variable;
1209 by default, lib on POSIX systems, nothing on Windows systems)
1211 (specified by the $SHLIBSUFFIX construction variable;
1212 by default, .dll on Windows systems, .so on POSIX systems)
1213 are automatically added to the target if not already present.
1217 env.SharedLibrary(target = 'bar', source = ['bar.c', 'foo.o'])
1220 On WIN32 systems, the
1222 builder will always build an import (.lib) library
1223 in addition to the shared (.dll) library,
1224 adding a .lib library with the same basename
1225 if there is not already a .lib file explicitly
1226 listed in the targets.
1228 Any object files listed in the
1230 must have been built for a shared library
1235 will raise an error if there is any mismatch.
1237 On WIN32 systems, specifying "register=1" will cause the dll to be
1238 registered after it is built using REGSVR32. The command that is run
1239 ("regsvr32" by default) is determined by $REGSVR construction
1240 variable, and the flags passed are determined by $REGSVRFLAGS. By
1241 default, $REGSVRFLAGS includes "/s", to prevent dialogs from popping
1242 up and requiring user attention when it is run. If you change
1243 $REGSVRFLAGS, be sure to include "/s". For example,
1246 env.SharedLibrary(target = 'bar',
1247 source = ['bar.cxx', 'foo.obj'],
1252 will register "bar.dll" as a COM object when it is done linking it.
1260 Builds a C source file given a lex (.l) or yacc (.y) input file.
1261 The suffix specified by the $CFILESUFFIX construction variable
1263 is automatically added to the target
1264 if it is not already present. Example:
1268 env.CFile(target = 'foo.c', source = 'foo.l')
1270 env.CFile(target = 'bar', source = 'bar.y')
1274 Builds a C++ source file given a lex (.ll) or yacc (.yy) input file.
1275 The suffix specified by the $CXXFILESUFFIX construction variable
1277 is automatically added to the target
1278 if it is not already present. Example:
1282 env.CXXFile(target = 'foo.cc', source = 'foo.ll')
1284 env.CXXFile(target = 'bar', source = 'bar.yy')
1288 Builds a Java archive (.jar) file
1289 from a source tree of .class files.
1291 env.Jar(target = 'foo.jar', source = 'classes')
1295 Builds one or more Java class files
1296 from a source tree of .java files.
1297 The class files will be placed underneath
1298 the specified target directory.
1299 SCons will parse each source .java file
1301 (including inner classes)
1302 defined within that file,
1303 and from that figure out the
1304 target .class files that will be created.
1305 SCons will also search each Java file
1306 for the Java package name,
1307 which it assumes can be found on a line
1308 beginning with the string
1310 in the first column;
1311 the resulting .class files
1312 will be placed in a directory reflecting
1313 the specified package name.
1317 defining a single public
1320 containing a package name of
1322 will generate a corresponding
1323 .IR sub/dir/Foo.class
1329 env.Java(target = 'classes', source = 'src')
1333 Builds a Windows type library (.tlb) file from and input IDL file
1334 (.idl). In addition, it will build the associated inteface stub and
1335 proxy source files. It names them according to the base name of the .idl file.
1340 env.TypeLibrary(source="foo.idl")
1343 Will create foo.tlb, foo.h, foo_i.c, foo_p.c, and foo_data.c.
1346 Builds a .dvi file from a .tex, .ltx or .latex input file.
1348 (hard-coded within TeX itself)
1349 is automatically added to the target
1350 if it is not already present. Example:
1353 # builds from aaa.tex
1354 env.DVI(target = 'aaa.dvi', source = 'aaa.tex')
1356 env.DVI(target = 'bbb', source = 'bbb.ltx')
1357 # builds from ccc.latex
1358 env.DVI(target = 'ccc.dvi', source = 'ccc.latex')
1362 Builds a .pdf file from a .dvi input file
1363 (or, by extension, a .tex, .ltx, or .latex input file).
1364 The suffix specified by the $PDFSUFFIX construction variable
1366 is added automatically to the target
1367 if it is not already present. Example:
1370 # builds from aaa.tex
1371 env.PDF(target = 'aaa.pdf', source = 'aaa.tex')
1372 # builds bbb.pdf from bbb.dvi
1373 env.PDF(target = 'bbb', source = 'bbb.dvi')
1377 Builds a .ps file from a .dvi input file
1378 (or, by extension, a .tex, .ltx, or .latex input file).
1379 The suffix specified by the $PSSUFFIX construction variable
1381 is added automatically to the target
1382 if it is not already present. Example:
1385 # builds from aaa.tex
1386 env.PostScript(target = 'aaa.ps', source = 'aaa.tex')
1387 # builds bbb.ps from bbb.dvi
1388 env.PostScript(target = 'bbb', source = 'bbb.dvi')
1393 C source files, C++ source files,
1394 Fortran source files with
1396 (POSIX systems only),
1401 and assembly language files with
1403 (POSIX systems only),
1408 for C preprocessor dependencies,
1409 so the dependencies do not need to be specified explicitly.
1410 In addition, all builder
1411 targets automatically depend on their sources.
1412 An explicit dependency can
1413 be specified using the
1415 method of a construction environment (see below).
1418 Builds a tar archive of the specified files
1420 Unlike most builders,
1423 builder may be called multiple times
1425 each additional call
1426 adds to the list of entries
1427 that will be built into the archive.
1430 env.Tar('src.tar', 'src')
1432 # Create the stuff.tar file.
1433 env.Tar('stuff', ['subdir1', 'subdir2'])
1434 # Also add "another" to the stuff.tar file.
1435 env.Tar('stuff', 'another')
1437 # Set TARFLAGS to create a gzip-filtered archive.
1438 env = Environment(TARFLAGS = '-c -z')
1439 env.Tar('foo.tar.gz', 'foo')
1441 # Also set the suffix to .tgz.
1442 env = Environment(TARFLAGS = '-c -z',
1448 Builds a zip archive of the specified files
1450 Unlike most builders,
1453 builder may be called multiple times
1455 each additional call
1456 adds to the list of entries
1457 that will be built into the archive.
1460 env.Zip('src.zip', 'src')
1462 # Create the stuff.zip file.
1463 env.Zip('stuff', ['subdir1', 'subdir2'])
1464 # Also add "another" to the stuff.tar file.
1465 env.Zip('stuff', 'another')
1468 .SS Other Construction Environment Methods
1469 Additional construction environment methods include:
1472 .RI Alias( alias ", " targets )
1473 Creates a phony target that
1474 expands to one or more other targets.
1475 Returns the Node object representing the alias,
1476 which exists outside of any file system.
1477 This Node object, or the alias name,
1478 may be used as a dependency of any other target,
1479 including another alias. Alias can be called multiple times for the same
1480 alias to add additional targets to the alias. There is also an Alias
1481 global function for creating or referencing an alias independently of
1482 any construction environment.
1485 env.Alias('install', ['/usr/local/bin', '/usr/local/lib'])
1486 env.Alias('install', ['/usr/local/man'])
1490 .RI Append( key = val ", [...])"
1491 Appends the specified keyword arguments
1492 to the end of construction variables in the environment.
1493 If the Environment does not have
1494 the specified construction variable,
1495 it is simply added to the environment.
1496 If the values of the construction variable
1497 and the keyword argument are the same type,
1498 then the two values will be simply added together.
1499 Otherwise, the construction variable
1500 and the value of the keyword argument
1501 are both coerced to lists,
1502 and the lists are added together.
1503 (See also the Prepend method, below.)
1506 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
1511 A factory function that
1512 returns a Builder object
1513 to be used to fetch source files
1515 The returned Builder
1516 is intended to be passed to the
1520 env.SourceCode('.', env.BitKeeper())
1524 .RI Command( target ", " source ", " commands )
1525 Executes a specific action
1526 (or list of actions)
1527 to build a target file or files.
1528 This is more convenient
1529 than defining a separate Builder object
1530 for a single special-case build.
1532 Note that an action can be an external command,
1533 specified as a string,
1534 or a callable Python object;
1535 see "Action Objects," below.
1539 env.Command('foo.out', 'foo.in',
1540 "$FOO_BUILD < $SOURCES > $TARGET")
1542 env.Command('bar.out', 'bar.in',
1544 "$BAR_BUILD < $SOURCES > $TARGET"])
1546 def rename(env, target, source):
1548 os.rename('.tmp', str(target[0]))
1550 env.Command('baz.out', 'baz.in',
1551 ["$BAZ_BUILD < $SOURCES > .tmp",
1556 .RI Copy([ key = val ", ...])"
1557 Return a separate copy of a construction environment.
1558 If there are any keyword arguments specified,
1559 they are added to the returned copy,
1560 overwriting any existing values
1565 env3 = env.Copy(CCFLAGS = '-g')
1569 .RI CVS( repository ", " module )
1570 A factory function that
1571 returns a Builder object
1572 to be used to fetch source files
1576 The returned Builder
1577 is intended to be passed to the
1581 The optional specified
1583 will be added to the beginning
1584 of all repository path names;
1585 this can be used, in essence,
1586 to strip initial directory names
1587 from the repository path names,
1588 so that you only have to
1589 replicate part of the repository
1590 directory hierarchy in your
1591 local build directory:
1594 # Will fetch foo/bar/src.c
1595 # from /usr/local/CVSROOT/foo/bar/src.c.
1596 env.SourceCode('.', env.CVS('/usr/local/CVSROOT'))
1598 # Will fetch bar/src.c
1599 # from /usr/local/CVSROOT/foo/bar/src.c.
1600 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo'))
1603 # from /usr/local/CVSROOT/foo/bar/src.c.
1604 env.SourceCode('.', env.CVS('/usr/local/CVSROOT', 'foo/bar'))
1608 .RI Depends( target ", " dependency )
1609 Specifies an explicit dependency;
1610 the target file(s) will be rebuilt
1611 whenever the dependency file(s) has changed.
1612 This should only be necessary
1613 for cases where the dependency
1614 is not caught by a Scanner
1618 env.Depends('foo', 'other-input-file-for-foo')
1622 .RI Dictionary([ vars ])
1623 Returns a dictionary object
1624 containing copies of all of the
1625 construction variables in the environment.
1626 If there are any variable names specified,
1627 only the specified construction
1628 variables are returned in the dictionary.
1631 dict = env.Dictionary()
1632 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
1636 .RI Ignore( target ", " dependency )
1637 The specified dependency file(s)
1638 will be ignored when deciding if
1639 the target file(s) need to be rebuilt.
1642 env.Ignore('foo', 'foo.c')
1643 env.Ignore('bar', ['bar1.h', 'bar2.h'])
1647 .RI Install( dir ", " source )
1648 Installs one or more files in a destination directory.
1649 The file names remain the same.
1652 env.Install(dir = '/usr/local/bin', source = ['foo', 'bar'])
1656 .RI InstallAs( target ", " source )
1657 Installs one or more files as specific file names,
1658 allowing changing a file name as part of the
1660 It is an error if the target and source
1661 list different numbers of files.
1664 env.InstallAs(target = '/usr/local/bin/foo',
1665 source = 'foo_debug')
1666 env.InstallAs(target = ['../lib/libfoo.a', '../lib/libbar.a'],
1667 source = ['libFOO.a', 'libBAR.a'])
1672 A factory function that
1673 returns a Builder object
1674 to be used to fetch source files
1675 from the Perforce source code management system.
1676 The returned Builder
1677 is intended to be passed to the
1681 env.SourceCode('.', env.Perforce())
1684 Perforce uses a number of external
1685 environment variables for its operation.
1686 Consequently, this function adds the
1687 following variables from the user's external environment
1688 to the construction environment's
1702 .RI Precious( target ", ...)"
1705 as precious so it is not deleted before it is rebuilt. Normally
1707 deletes a target before building it.
1708 Multiple targets can be passed in to a single call to
1712 .RI Prepend( key = val ", [...])"
1713 Appends the specified keyword arguments
1714 to the beginning of construction variables in the environment.
1715 If the Environment does not have
1716 the specified construction variable,
1717 it is simply added to the environment.
1718 If the values of the construction variable
1719 and the keyword argument are the same type,
1720 then the two values will be simply added together.
1721 Otherwise, the construction variable
1722 and the value of the keyword argument
1723 are both coerced to lists,
1724 and the lists are added together.
1725 (See also the Append method, above.)
1728 env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy'])
1733 A factory function that
1734 returns a Builder object
1735 to be used to fetch source files
1737 The returned Builder
1738 is intended to be passed to the
1742 env.SourceCode('.', env.RCS())
1746 will fetch source files
1747 from RCS subdirectories automatically,
1749 as demonstrated in the above example
1750 should only be necessary if
1751 you are fetching from
1754 directory as the source files,
1755 or if you need to explicitly specify RCS
1756 for a specific subdirectory.
1759 .RI Replace( key = val ", [...])"
1760 Replaces construction variables in the Environment
1761 with the specified keyword arguments.
1764 env.Replace(CCFLAGS = '-g', FOO = 'foo.xxx')
1769 A factory function that
1770 returns a Builder object
1771 to be used to fetch source files
1773 The returned Builder
1774 is intended to be passed to the
1778 env.SourceCode('.', env.SCCS())
1782 will fetch source files
1783 from SCCS subdirectories automatically,
1785 as demonstrated in the above example
1786 should only be necessary if
1787 you are fetching from
1790 directory as the source files,
1791 or if you need to explicitly specify SCCS
1792 for a specific subdirectory.
1795 .RI SideEffect( side_effect , target )
1798 as a side effect of building
1804 can be a list, a file name, or a node.
1805 A side effect is a target that is created
1806 as a side effect of building other targets.
1807 For example, a Windows PDB
1808 file is created as a side effect of building the .obj
1809 files for a static library.
1810 If a target is a side effect of multiple build commands,
1812 will ensure that only one set of commands
1813 is executed at a time.
1814 Consequently, you only need to use this method
1815 for side-effect targets that are built as a result of
1816 multiple build commands.
1819 .RI SourceCode( entries , builder )
1820 Arrange for non-existent source files to
1821 be fetched from a source code management system
1826 may be a Node, string or list of both,
1827 and may represent either individual
1828 source files or directories in which
1829 source files can be found.
1831 For any non-existent source files,
1833 will search up the directory tree
1843 will not use a builder to fetch
1844 source files for the specified
1848 builder has been specified
1849 for a directory higher up the tree.
1853 fetch files from SCCS or RCS subdirectories
1854 without explicit configuration.
1855 This takes some extra processing time
1856 to search for the necessary
1857 source code management files on disk.
1858 You can avoid these extra searches
1859 and speed up your build a little
1860 by disabling these searches as follows:
1862 env.SourceCode('.', None)
1865 Note that if the specified
1867 is one you create by hand,
1868 it must have an associated
1869 construction environment to use
1870 when fetching a source file.
1873 provides a set of canned factory
1874 functions that return appropriate
1875 Builders for various popular
1876 source code management systems.
1877 Canonical examples of invocation include:
1879 env.SourceCode('.', env.BitKeeper('/usr/local/BKsources'))
1880 env.SourceCode('src', env.CVS('/usr/local/CVSROOT'))
1881 env.SourceCode('/', env.RCS())
1882 env.SourceCode(['f1.c', 'f2.c'], env.SCCS())
1883 env.SourceCode('no_source.c', None)
1885 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
1888 '\".RI Subversion( repository ", " module )
1889 '\"A factory function that
1890 '\"returns a Builder object
1891 '\"to be used to fetch source files
1892 '\"from the specified Subversion
1894 '\"The returned Builder
1895 '\"is intended to be passed to the
1899 '\"The optional specified
1901 '\"will be added to the beginning
1902 '\"of all repository path names;
1903 '\"this can be used, in essence,
1904 '\"to strip initial directory names
1905 '\"from the repository path names,
1906 '\"so that you only have to
1907 '\"replicate part of the repository
1908 '\"directory hierarchy in your
1909 '\"local build directory:
1912 '\"# Will fetch foo/bar/src.c
1913 '\"# from /usr/local/Subversion/foo/bar/src.c.
1914 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion'))
1916 '\"# Will fetch bar/src.c
1917 '\"# from /usr/local/Subversion/foo/bar/src.c.
1918 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo'))
1920 '\"# Will fetch src.c
1921 '\"# from /usr/local/Subversion/foo/bar/src.c.
1922 '\"env.SourceCode('.', env.Subversion('file:///usr/local/Subversion', 'foo/bar'))
1925 .SS Construction Variables
1926 .\" XXX From Gary Ruben, 23 April 2002:
1927 .\" I think it would be good to have an example with each construction
1928 .\" variable description in the documentation.
1930 .\" CC The C compiler
1931 .\" Example: env["CC"] = "c68x"
1932 .\" Default: env["CC"] = "cc"
1934 .\" CCCOM The command line ...
1936 .\" To generate the compiler line c68x -ps -qq -mr -o $TARGET $SOURCES
1937 .\" env["CC"] = "c68x"
1938 .\" env["CFLAGS"] = "-ps -qq -mr"
1939 .\" env["CCCOM"] = "$CC $CFLAGS -o $TARGET $SOURCES
1941 .\" (I dunno what this is ;-)
1942 A construction environment has an associated dictionary of construction
1943 variables that are used by built-in or user-supplied build rules. A number
1944 of useful construction variables are automatically defined by scons for
1945 each supported platform, and additional construction variables can be defined
1946 by the user. The following is a list of the automatically defined construction
1950 The static library archiver.
1953 The command line used to generate a static library from object files.
1956 General options passed to the static library archiver.
1962 The command line used to generate an object file
1963 from an assembly-language source file.
1966 General options passed to the assembler.
1969 The command line used to assemble an assembly-language
1970 source file into an object file
1971 after first running the file through the C preprocessor.
1972 Any options specified in the $ASFLAGS and $CPPFLAGS construction variables
1973 are included on this command line.
1976 The BitKeeper executable.
1979 The command line for
1980 fetching source files using BitKEeper.
1983 The command ($BITKEEPER) and subcommand
1984 for fetching source files using BitKeeper.
1986 .IP BITKEEPERGETFLAGS
1987 Options that are passed to the BitKeeper
1992 A dictionary mapping the names of the builders
1993 available through this environment
1994 to underlying Builder objects.
1996 Alias, CFile, CXXFile, DVI, Library, Object, PDF, PostScript, and Program
1997 are available by default.
1998 If you initialize this variable when an
1999 Environment is created:
2001 env = Environment(BUILDERS = {'NewBuilder' : foo})
2003 the default Builders will no longer be available.
2004 To use a new Builder object in addition to the default Builders,
2005 add your new Builder object like this:
2008 env.Append(BUILDERS = {'NewBuilder' : foo})
2013 env['BUILDERS]['NewBuilder'] = foo
2020 The command line used to compile a C source file to a (static) object file.
2021 Any options specified in the $CCFLAGS and $CPPFLAGS construction variables
2022 are included on this command line.
2025 General options that are passed to the C compiler.
2028 The suffix for C source files.
2029 This is used by the internal CFile builder
2030 when generating C files from Lex (.l) or YACC (.y) input files.
2031 The default suffix, of course, is
2034 On case-insensitive systems (like Win32),
2041 A function used to produce variables like $_CPPINCFLAGS. It takes six
2042 arguments: a prefix to concatenate onto each element, a list of elements, a
2043 suffix to concatenate onto each element, a dictionary of global variables
2044 for variable interpolation, a list of local variables for variable
2045 interpolation, and an optional function that will be called to transform the list
2046 before concatenation.
2049 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, locals(), globals(), RDirs)} $)',
2053 C preprocessor options.
2054 These will be included in any command that uses the C preprocessor,
2055 including not just compilation of C and C++ source files
2056 via the $CCCOM, $SHCCCOM, $CXXCOM and $SHCXXCOM command lines,
2057 but also the $F77PPCOM command line
2058 used to compile a Fortran source file,
2059 and the $ASPPCOM command line
2060 used to assemble an assembly language source file,
2061 after first running each file through the C preprocessor.
2064 An automatically-generated construction variable
2065 containing the C preprocessor command-line options
2066 for specifying directories to be searched for include files.
2067 The value of $_CPPINCFLAGS is created
2068 by appending $INCPREFIX and $INCSUFFIX
2069 to the beginning and end
2070 of each directory in $CPPPATH.
2073 The list of directories that the C preprocessor will search for include
2074 directories. The C/C++ implicit dependency scanner will search these
2075 directories for include files. Don't explicitly put include directory
2076 arguments in CCFLAGS or CXXFLAGS because the result will be non-portable
2077 and the directories will not be searched by the dependency scanner. Note:
2078 directory names in CPPPATH will be looked-up relative to the SConscript
2079 directory when they are used in a command. To force
2081 to look-up a directory relative to the root of the source tree use #:
2084 env = Environment(CPPPATH='#/include')
2088 The directory look-up can also be forced using the
2093 include = Dir('include')
2094 env = Environment(CPPPATH=include)
2098 The directory list will be added to command lines
2099 through the automatically-generated
2101 construction variable,
2102 which is constructed by
2103 appending the values of the
2104 $INCPREFIX and $INCSUFFIX
2105 construction variables
2106 to the beginning and end
2107 of each directory in $CPPPATH.
2108 Any command lines you define that need
2109 the CPPPATH directory list should
2110 include $_CPPINCFLAGS:
2113 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
2120 Options that are passed to the CVS checkout subcommand.
2123 The command line used to
2124 fetch source files from a CVS repository.
2127 General options that are passed to CVS.
2128 By default, this is set to
2130 to specify from where the files must be fetched.
2133 The path to the CVS repository.
2134 This is referenced in the default
2141 The suffix for C++ source files.
2142 This is used by the internal CXXFile builder
2143 when generating C++ files from Lex (.ll) or YACC (.yy) input files.
2144 The default suffix is
2146 SCons also treats files with the suffixes
2153 On case-sensitive systems (Linux, UNIX, and other POSIX-alikes),
2160 The command line used to compile a C++ source file to an object file.
2161 Any options specified in the $CXXFLAGS and $CPPFLAGS construction variables
2162 are included on this command line.
2165 General options that are passed to the C++ compiler.
2168 A function that converts a file name into a Dir instance relative to the
2172 The TeX DVI file to PDF file converter.
2175 General options passed to the TeX DVI file to PDF file converter.
2178 The command line used to convert TeX DVI files into a PDF file.
2181 The TeX DVI file to PostScript converter.
2184 General options passed to the TeX DVI file to PostScript converter.
2187 A dictionary of environment variables
2188 to use when invoking commands.
2189 Note that, by default,
2193 propagate the environment in force when you
2196 to the commands used to build target files.
2197 This is so that builds will be guaranteed
2198 repeatable regardless of the environment
2199 variables set at the time
2203 If you want to propagate your
2204 environment variables
2205 to the commands executed
2206 to build target files,
2207 you must do so explicitly:
2211 env = Environment(ENV = os.environ)
2215 Note that you can choose only to propagate
2216 certain environment variables.
2220 environment variable,
2223 uses the same utilities
2224 as the invoking shell (or other process):
2229 env = Environment(ENV = {'PATH' : os.environ['PATH']})
2233 A function that will be called to escape shell special characters in
2234 command lines. The function should take one argument: the command line
2235 string to escape; and should return the escaped command line.
2238 The Fortran compiler.
2241 The command line used to compile a Fortran source file to an object file.
2244 General options that are passed to the Fortran compiler.
2247 An automatically-generated construction variable
2248 containing the Fortran compiler command-line options
2249 for specifying directories to be searched for include files.
2250 The value of $_F77INCFLAGS is created
2251 by appending $INCPREFIX and $INCSUFFIX
2252 to the beginning and end
2253 of each directory in $F77PATH.
2256 The list of directories that the Fortran compiler will search for include
2257 directories. The Fortran implicit dependency scanner will search these
2258 directories for include files. Don't explicitly put include directory
2259 arguments in F77FLAGS because the result will be non-portable
2260 and the directories will not be searched by the dependency scanner. Note:
2261 directory names in F77PATH will be looked-up relative to the SConscript
2262 directory when they are used in a command. To force
2264 to look-up a directory relative to the root of the source tree use #:
2267 env = Environment(F77PATH='#/include')
2271 The directory look-up can also be forced using the
2276 include = Dir('include')
2277 env = Environment(F77PATH=include)
2281 The directory list will be added to command lines
2282 through the automatically-generated
2284 construction variable,
2285 which is constructed by
2286 appending the values of the
2287 $INCPREFIX and $INCSUFFIX
2288 construction variables
2289 to the beginning and end
2290 of each directory in $F77PATH.
2291 Any command lines you define that need
2292 the F77PATH directory list should
2293 include $_F77INCFLAGS:
2296 env = Environment(F77COM="my_compiler $_F77INCFLAGS -c -o $TARGET $SOURCE")
2300 The command line used to compile a Fortran source file to an object file
2301 after first running the file through the C preprocessor.
2302 Any options specified in the $F77FLAGS and $CPPFLAGS construction variables
2303 are included on this command line.
2306 A function that converts a file name into a File instance relative to the
2310 The Ghostscript program used to convert PostScript to PDF files.
2313 General options passed to the Ghostscript program
2314 when converting PostScript to PDF files.
2317 The Ghostscript command line used to convert PostScript to PDF files.
2320 The prefix used to specify an include directory on the C compiler command
2322 This will be appended to the beginning of each directory
2323 in the $CPPPATH and $F77PATH construction variables
2324 when the $_CPPINCFLAGS and $_F77INCFLAGS
2325 variables are automatically generated.
2328 The suffix used to specify an include directory on the C compiler command
2330 This will be appended to the end of each directory
2331 in the $CPPPATH and $F77PATH construction variables
2332 when the $_CPPINCFLAGS and $_F77INCFLAGS
2333 variables are automatically generated.
2336 A function to be called to install a file into a
2337 destination file name.
2338 The default function copies the file into the destination
2339 (and sets the destination file's mode and permission bits
2340 to match the source file's).
2341 The function takes the following arguments:
2344 def install(dest, source, env):
2348 is the path name of the destination file.
2350 is the path name of the source file.
2352 is the construction environment
2353 (a dictionary of construction values)
2354 in force for this file installation.
2357 The Java archive tool.
2360 The command line used to call the Java archive tool.
2363 General options passed to the Java archive tool.
2364 By default this is set to
2366 to create the necessary
2371 The suffix for Java archives:
2379 The command line used to compile a directory tree containing
2380 Java source files to
2381 corresponding Java class files.
2382 Any options specified in the $JAVACFLAGS construction variable
2383 are included on this command line.
2386 General options that are passed to the Java compiler.
2389 The suffix for Java class files;
2394 The suffix for Java files;
2399 The LaTeX structured formatter and typesetter.
2402 The command line used to call the LaTeX structured formatter and typesetter.
2405 General options passed to the LaTeX structured formatter and typesetter.
2408 The lexical analyzer generator.
2411 General options passed to the lexical analyzer generator.
2414 The command line used to call the lexical analyzer generator
2415 to generate a source file.
2418 An automatically-generated construction variable
2419 containing the linker command-line options
2420 for specifying directories to be searched for library.
2421 The value of $_LIBDIRFLAGS is created
2422 by appending $LIBDIRPREFIX and $LIBDIRSUFFIX
2423 to the beginning and end
2424 of each directory in $LIBPATH.
2427 The prefix used to specify a library directory on the linker command line.
2428 This will be appended to the beginning of each directory
2429 in the $LIBPATH construction variable
2430 when the $_LIBDIRFLAGS variable is automatically generated.
2433 The suffix used to specify a library directory on the linker command line.
2434 This will be appended to the end of each directory
2435 in the $LIBPATH construction variable
2436 when the $_LIBDIRFLAGS variable is automatically generated.
2439 An automatically-generated construction variable
2440 containing the linker command-line options
2441 for specifying libraries to be linked with the resulting target.
2442 The value of $_LIBFLAGS is created
2443 by appending $LIBLINKPREFIX and $LIBLINKSUFFIX
2444 to the beginning and end
2445 of each directory in $LIBS.
2448 The prefix used to specify a library to link on the linker command line.
2449 This will be appended to the beginning of each library
2450 in the $LIBS construction variable
2451 when the $_LIBFLAGS variable is automatically generated.
2454 The suffix used to specify a library to link on the linker command line.
2455 This will be appended to the end of each library
2456 in the $LIBS construction variable
2457 when the $_LIBFLAGS variable is automatically generated.
2460 The list of directories that will be searched for libraries.
2461 The implicit dependency scanner will search these
2462 directories for include files. Don't explicitly put include directory
2463 arguments in LINKFLAGS because the result will be non-portable
2464 and the directories will not be searched by the dependency scanner. Note:
2465 directory names in LIBPATH will be looked-up relative to the SConscript
2466 directory when they are used in a command. To force
2468 to look-up a directory relative to the root of the source tree use #:
2471 env = Environment(LIBPATH='#/libs')
2475 The directory look-up can also be forced using the
2481 env = Environment(LIBPATH=libs)
2485 The directory list will be added to command lines
2486 through the automatically-generated
2488 construction variable,
2489 which is constructed by
2490 appending the values of the
2491 $LIBDIRPREFIX and $LIBDIRSUFFIX
2492 construction variables
2493 to the beginning and end
2494 of each directory in $LIBPATH.
2495 Any command lines you define that need
2496 the LIBPATH directory list should
2497 include $_LIBDIRFLAGS:
2500 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
2504 The prefix used for (static) library file names.
2507 An array of legal prefixes for library file names.
2510 A list of one or more libraries
2511 that will be linked with
2512 any executable programs
2513 created by this environment.
2516 The library list will be added to command lines
2517 through the automatically-generated
2519 construction variable,
2520 which is constructed by
2521 appending the values of the
2522 $LIBLINKPREFIX and $LIBLINKSUFFIX
2523 construction variables
2524 to the beginning and end
2525 of each directory in $LIBS.
2526 Any command lines you define that need
2527 the LIBS library list should
2531 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
2535 The suffix used for (static) library file names.
2538 An array of legal suffixes for library file names.
2544 General options passed to the linker.
2547 The command line used to link object files into an executable.
2550 The prefix used for (static) object file names.
2553 The suffix used for (static) object file names.
2556 The Perforce executable.
2559 The command line used to
2560 fetch source files from Perforce.
2563 General options that are passed to Perforce.
2566 The Microsoft Visual C++ precompiled header that will be used when compiling
2567 object files. This variable is ignored by tools other than Microsoft Visual C++.
2568 When this variable is
2569 defined SCons will add options to the compiler command line to
2570 cause it to use the precompiled header, and will also set up the
2571 dependencies for the PCH file. Example:
2574 env['PCH'] = 'StdAfx.pch'
2578 This variable specifies how much of a source file is precompiled. This
2579 variable is ignored by tools other than Microsoft Visual C++, or when
2580 the PCH variable is not being used. When this variable is define it
2581 must be a string that is the name of the header that
2582 is included at the end of the precompiled portion of the source files, or
2583 the empty string if the "#pragma hrdstop" construct is being used:
2586 env['PCHSTOP'] = 'StdAfx.h'
2590 The Microsoft Visual C++ PDB file that will store debugging information for
2591 object files, shared libraries, and programs. This variable is ignored by
2592 tools other than Microsoft Visual C++.
2593 When this variable is
2594 defined SCons will add options to the compiler and linker command line to
2595 cause them to generate external debugging information, and will also set up the
2596 dependencies for the PDB file. Example:
2599 env['PDB'] = 'hello.pdb'
2603 A deprecated synonym for $DVIPDFCOM.
2606 The prefix used for PDF file names.
2609 The suffix used for PDF file names.
2612 The name of the platform used to create the Environment. If no platform is
2613 specified when the Environment is created,
2615 autodetects the platform.
2618 env = Environment(tools = [])
2619 if env['PLATFORM'] == 'cygwin':
2626 The prefix used for executable file names.
2629 The suffix used for executable file names.
2632 The command line used to convert TeX DVI files into a PostScript file.
2635 The prefix used for PostScript file names.
2638 The prefix used for PostScript file names.
2641 The archive indexer.
2644 General options passed to the archive indexer.
2647 The resource compiler used by the RES builder.
2650 The command line used by the RES builder.
2653 The flags passed to the resource compiler by the RES builder.
2657 Note that this variable is not actually used
2658 for the command to fetch source files from RCS;
2661 construction variable, below.
2664 The RCS "checkout" executable,
2665 used to fetch source files from RCS.
2668 The command line used to
2669 fetch (checkout) source files from RCS.
2672 Options that are passed to the $RCS_CO command.
2675 A function that converts a file name into a list of Dir instances by
2676 searching the repositories.
2679 A list of the available implicit dependency scanners. [CScan] by default.
2682 The SCCS executable.
2685 The command line used to
2686 fetch source files from SCCS.
2689 General options that are passed to SCCS.
2692 Options that are passed specifically to the SCCS "get" subcommand.
2693 This can be set, for example, to
2695 to check out editable files from SCCS.
2698 The C compiler used for generating shared-library objects.
2701 The command line used to compile a C source file
2702 to a shared-library object file.
2703 Any options specified in the $SHCCFLAGS and $CPPFLAGS construction variables
2704 are included on this command line.
2707 Options that are passed to the C compiler
2708 to generate shared-library objects.
2711 The C++ compiler used for generating shared-library objects.
2714 The command line used to compile a C++ source file
2715 to a shared-library object file.
2716 Any options specified in the $SHCXXFLAGS and $CPPFLAGS construction variables
2717 are included on this command line.
2720 Options that are passed to the C++ compiler
2721 to generate shared-library objects.
2724 A string naming the shell program that will be passed to the
2729 construction variable for more information.
2732 The Fortran compiler used for generating shared-library objects.
2735 The command line used to compile a Fortran source file
2736 to a shared-library object file.
2739 Options that are passed to the Fortran compiler
2740 to generated shared-library objects.
2743 The command line used to compile a Fortran source file to a
2744 shared-library object file
2745 after first running the file through the C preprocessor.
2746 Any options specified in the $SHF77FLAGS and $CPPFLAGS construction variables
2747 are included on this command line.
2750 The prefix used for shared library file names.
2753 The suffix used for shared library file names.
2756 The linker for programs that use shared libraries.
2759 General options passed to the linker for programs using shared libraries.
2762 The prefix used for shared object file names.
2765 The suffix used for shared object file names.
2768 A reserved variable name
2769 that may not be set or used in a construction environment.
2770 (See "Variable Substitution," below.)
2773 A reserved variable name
2774 that may not be set or used in a construction environment.
2775 (See "Variable Substitution," below.)
2778 A command interpreter function that will be called to execute command line
2779 strings. The function must expect 4 arguments:
2782 def spawn(shell, escape, cmd, args, env):
2786 is a string naming the shell program to use.
2788 is a function that can be called to escape shell special characters in
2791 is the path to the command to be executed.
2793 is that arguments to the command.
2795 is a dictionary of the environment variables
2796 in which the command should be executed.
2799 '\"The Subversion executable (usually named
2803 '\"The command line used to
2804 '\"fetch source files from a Subversion repository.
2807 '\"General options that are passed to Subversion.
2813 The command line used to call the tar archiver.
2816 General options passed to the tar archiver.
2819 A reserved variable name
2820 that may not be set or used in a construction environment.
2821 (See "Variable Substitution," below.)
2824 A reserved variable name
2825 that may not be set or used in a construction environment.
2826 (See "Variable Substitution," below.)
2829 The suffix used for tar file names.
2832 The TeX formatter and typesetter.
2835 The command line used to call the TeX formatter and typesetter.
2838 General options passed to the TeX formatter and typesetter.
2840 .IP WIN32_INSERT_DEF
2841 When this is set to true,
2842 a library build of a WIN32 shared library (.dll file)
2843 will also build a corresponding .def file at the same time,
2844 if a .def file is not already listed as a build target.
2845 The default is 0 (do not build a .def file).
2848 The prefix used for WIN32 .def file names.
2851 The suffix used for WIN32 .def file names.
2854 The parser generator.
2857 The command line used to call the parser generator
2858 to generate a source file.
2861 General options passed to the parser generator.
2864 The zip compression and file packaging utility.
2867 The command line used to call the zip utility.
2870 General options passed to the zip utility.
2873 Construction variables can be retrieved and set using the
2875 method of the construction environment:
2878 dict = env.Dictionary()
2882 or using the [] operator:
2888 Construction variables can also be passed to the construction environment
2892 env = Environment(CC="cc")
2895 or when copying a construction environment using the
2900 env2 = env.Copy(CC="cl.exe")
2903 .SS Configure contexts
2907 .I configure contexts,
2908 an integrated mechanism similar to the
2909 various AC_CHECK macros in GNU autoconf
2910 for testing for the existence of C header
2911 files, libraries, etc.
2912 In contrast to autoconf,
2914 does not maintain an explicit cache of the tested values,
2915 but uses its normal dependency tracking to keep the checked values
2917 The following methods can be used to perform checks:
2920 .RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ])
2921 This creates a configure context, which can be used to perform checks.
2923 specifies the environment for building the tests.
2924 This environment may be modified when performing checks.
2926 is a dictionary containing custom tests.
2927 See also the section about custom tests below.
2928 By default, no custom tests are added to the configure context.
2930 specifies a directory where the test cases are built.
2931 Note that this directory is not used for building
2933 The default value is the directory
2936 specifies a file which collects the output from commands
2937 that are executed to check for the existence of header files, libraries, etc.
2938 The default is the file #/config.log.
2939 If you are using the
2942 you may want to specify a subdirectory under your build directory.
2947 instance has the following associated methods:
2950 .RI Configure.Finish( self )
2951 This method should be called after configuration is done.
2952 It returns the environment as modified
2953 by the configuration checks performed.
2954 After this method is called, no further checks can be performed
2955 with this configuration context.
2956 However, you can create a new
2958 context to perform additional checks.
2959 Only one context should be active at a time.
2961 The following Checks are predefined.
2962 (This list will likely grow larger as time
2963 goes by and developers contribute new useful tests.)
2966 .RI Configure.CheckCHeader( self ", " header )
2969 is usable in the C-language.
2970 Returns 1 on success and 0 on failure.
2973 .RI Configure.CheckCXXHeader( self ", " header )
2976 is usable in the C++ language.
2977 Returns 1 on success and 0 on failure.
2980 .RI Configure.CheckLib( self ", [" library ", " symbol ", " autoadd ])
2987 is 1 and the library provides the specified
2989 appends the library to the LIBS construction environment variable.
2991 may also be None (the default),
2994 is checked with the current LIBS variable.
2999 you can link against the specified
3001 The default value for
3004 It is assumed, that the C-language is used.
3005 This method returns 1 on success and 0 on error.
3008 .RI Configure.CheckLibWithHeader( self ", " library ", " header ", " language ", [" call ", " autoadd ])
3011 .RI Configure.CheckLib
3012 call, this call provides a more sophisticated way to check against libraries.
3015 specifies the library to check.
3017 specifies a header to check for.
3019 may be one of 'C','c','CXX','cxx','C++' and 'c++'.
3021 can be any valid expression (with a trailing ';'). The default is 'main();'.
3023 specifies whether to add the library to the environment (only if the check
3024 succeeds). This method returns 1 on success and 0 on error.
3027 Example of a typical Configure usage:
3031 conf = Configure( env )
3032 if not conf.CheckCHeader( 'math.h' ):
3033 print 'We really need math.h!'
3035 if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', 'QApplication qapp(0,0);' ):
3036 # do stuff for qt - usage, e.g.
3037 conf.env.Append( CPPFLAGS = '-DWITH_QT' )
3042 You can define your own custom checks.
3043 in addition to the predefined checks.
3044 These are passed in a dictionary to the Configure function.
3045 This dictionary maps the names of the checks
3046 to user defined Python callables
3047 (either Python functions or class instances implementing the
3050 The first argument of the call is always a
3052 instance followed by the arguments,
3053 which must be supplied by the user of the check.
3054 These CheckContext instances define the following methods:
3057 .RI CheckContext.Message( self ", " text )
3059 Usually called before the check is started.
3061 will be displayed to the user, e.g. 'Checking for library X...'
3064 .RI CheckContext.Result( self, ", " res )
3066 Usually called after the check is done.
3068 can be either an integer or a string. In the former case, 'ok' (res != 0)
3069 or 'failed' (res == 0) is displayed to the user, in the latter case the
3070 given string is displayed.
3073 .RI CheckContext.TryCompile( self ", " text ", " extension )
3074 Checks if a file with the specified
3076 (e.g. '.c') containing
3078 can be compiled using the environment's
3080 builder. Returns 1 on success and 0 on failure.
3083 .RI CheckContext.TryLink( self ", " text ", " extension )
3084 Checks, if a file with the specified
3086 (e.g. '.c') containing
3088 can be compiled using the environment's
3090 builder. Returns 1 on success and 0 on failure.
3093 .RI CheckContext.TryRun( self ", " text ", " extension )
3094 Checks, if a file with the specified
3096 (e.g. '.c') containing
3098 can be compiled using the environment's
3100 builder. On success, the program is run. If the program
3101 executes successfully
3102 (that is, its return status is 0),
3107 is the standard output of the
3109 If the program fails execution
3110 (its return status is non-zero),
3111 then (0, '') is returned.
3114 .RI CheckContext.TryAction( self ", " action ", [" text ", " extension ])
3115 Checks if the specified
3117 with an optional source file (contents
3124 may be anything which can be converted to a
3131 is the content of the target file.
3137 .RI CheckContext.TryBuild( self ", " builder ", [" text ", " extension ])
3138 Low level implementation for testing specific builds;
3139 the methods above are based on this metho.
3140 Given the Builder instance
3144 of a source file with optional
3146 this method returns 1 on success and 0 on failure. In addition,
3148 is set to the build target node, if the build was successful.
3151 Example for implementing and using custom tests:
3154 def CheckQt(context, qtdir):
3155 context.Message( 'Checking for qt ...' )
3156 lastLIBS = context.env['LIBS']
3157 lastLIBPATH = context.env['LIBPATH']
3158 lastCPPPATH= context.env['CPPPATH']
3159 context.env.Append(LIBS = 'qt', LIBPATH = qtdir + '/lib', CPPPATH = qtdir + '/include' )
3160 ret = context.TryLink("""
3162 int main(int argc, char **argv) {
3163 QApplication qapp(argc, argv);
3168 context.env.Replace(LIBS = lastLIBS, LIBPATH=lastLIBPATH, CPPPATH=lastCPPPATH)
3169 context.Result( ret )
3173 conf = Configure( env, custom_tests = 'CheckQt' : CheckQt )
3174 if not conf.CheckQt('/usr/lib/qt'):
3175 print 'We really need qt!'
3180 .SS Construction Variable Options
3182 Often when building software, various options need to be specified at build
3183 time that are not known when the SConstruct/SConscript files are
3184 written. For example, libraries needed for the build may be in non-standard
3185 locations, or site-specific compiler options may need to be passed to the
3188 provides a mechanism for overridding construction variables from the
3189 command line or a text-based SConscript file through an Options
3190 object. To create an Options object, call the Options() function:
3193 .RI Options([ files ])
3194 This creates an Options object that will read construction variables from
3195 the file or list of filenames given in the
3197 argument. If no files are given, then no files will be read. Example:
3200 opts = Options('custom.py')
3203 Options objects have the following methods:
3206 .RI Add( key ", [" help ", " default ", " validater ", " converter ])
3207 This adds a customizable construction variable to the Options object.
3209 is the name of the variable.
3211 is the help text for the variable.
3213 is the default value of the variable.
3215 is called to validate the value of the variable, and should take three
3216 arguments: key, value, and environment
3218 is called to convert the value before putting it in the environment, and
3219 should take a single argument: value. Example:
3222 opts.Add('CC', 'The C compiler')
3227 This updates a construction environment
3229 with the customized construction variables. Normally this method is not
3230 called directly, but is called indirectly by passing the Options object to
3231 the Environment() function:
3234 env = Environment(options=opts)
3238 .RI Save( filename ", " env )
3239 This saves the currently set options into a script file named
3241 that can be used on the next invocation to automatically load the current
3242 settings. This method combined with the Options method can be used to
3243 support caching of options between runs.
3247 opts = Options(['options.cache', 'custom.py'])
3250 opts.Save('options.cache', env)
3254 .RI GenerateHelpText( env ", [" sort ])
3255 This generates help text documenting the customizable construction
3256 variables suitable to passing in to the Help() function.
3258 is the construction environment that will be used to get the actual values
3259 of customizable variables. Calling with
3263 will cause the output to be sorted
3264 by the specified argument.
3268 should take two arguments
3271 (like the standard Python
3276 Help(opts.GenerateHelpText(env))
3277 Help(opts.GenerateHelpText(env, sort=cmp))
3280 The text based SConscript file is executed as a Python script, and the
3281 global variables are queried for customizable construction
3291 also provides various additional functions,
3292 not associated with a construction environment,
3293 that SConscript files can use:
3296 .RI AddPostAction ( target, action )
3297 Arranges for the specified
3303 The specified action(s) may be
3304 an Action object, or anything that
3305 can be converted into an Action object
3309 .RI AddPreAction ( target, action )
3310 Arranges for the specified
3313 before the specified
3316 The specified action(s) may be
3317 an Action object, or anything that
3318 can be converted into an Action object
3323 Creates or references an alias independent of the construction environment.
3330 .RI BuildDir( build_dir ", " src_dir ", [" duplicate ])
3331 This specifies a build directory
3333 in which to build all derived files
3334 that would normally be built under
3336 Multiple build directories can be set up for multiple build variants, for
3339 must be underneath the SConstruct file's directory,
3342 may not be underneath the
3345 The default behavior is for
3347 to duplicate all of the files in the tree underneath
3351 and then build the derived files within the copied tree.
3352 (The duplication is performed by
3354 depending on the platform.)
3355 This guarantees correct builds
3356 regardless of whether intermediate source files
3357 are generated during the build,
3358 where preprocessors or other scanners search
3360 or whether individual compilers or other invoked tools
3361 are hard-coded to put derived files in the same directory as source files.
3363 This behavior of making a complete copy of the source tree
3364 may be disabled by setting
3369 to invoke Builders using the
3370 path names of source files in
3372 and the path names of derived files within
3374 This is always more efficient than
3376 and is usually safe for most builds.
3380 may cause build problems
3381 if source files are generated during the build,
3382 if any invoked tools are hard-coded to
3383 put derived files in the same directory as the source files.
3385 Note that specifying a
3387 works most naturally
3388 with a subsidiary SConscript file
3389 in the source directory.
3391 you would then call the subsidiary SConscript file
3392 not in the source directory,
3397 had made a virtual copy of the source tree
3398 regardless of the value of
3400 This is how you tell
3402 which variant of a source tree to build.
3406 BuildDir('build-variant1', 'src')
3407 SConscript('build-variant1/SConscript')
3408 BuildDir('build-variant2', 'src')
3409 SConscript('build-variant2/SConscript')
3414 function, described below,
3416 specify a build directory
3417 in conjunction with calling a subsidiary
3421 .RI AddPostAction ( target, action )
3422 Arranges for the specified
3428 The specified action(s) may be
3429 an Action object, or anything that
3430 can be converted into an Action object
3434 .RI CacheDir ( cache_dir )
3437 will maintain a cache of derived files in
3439 The derived files in the cache will be shared
3440 among all the builds using the same
3448 finds a derived file that needs to be rebuilt,
3449 it will first look in the cache to see if a
3450 derived file has already been built
3451 from identical input files and an identical build action
3452 (as incorporated into the MD5 build signature).
3455 will retrieve the file from the cache.
3456 If the derived file is not present in the cache,
3459 then place a copy of the built file in the cache
3460 (identified by its MD5 build signature),
3461 so that it may be retrieved by other
3462 builds that need to build the same derived file
3463 from identical inputs.
3467 may be disabled for any invocation
3476 will place a copy of
3478 derived files in the cache,
3479 even if they already existed
3480 and were not built by this invocation.
3481 This is useful to populate a cache
3484 is added to a build,
3493 "Retrieved `file' from cache,"
3496 option is being used.
3501 will print the action that
3503 have been used to build the file,
3504 without any indication that
3505 the file was actually retrieved from the cache.
3506 This is useful to generate build logs
3507 that are equivalent regardless of whether
3508 a given derived file has been built in-place
3509 or retrieved from the cache.
3512 .RI Clean ( target, files_or_dirs )
3513 This specifies a list of files or directories which should be removed
3514 whenever the target is specified with the
3516 command line option.
3520 and create a new target or add files and directories to the
3521 clean list for the specified target.
3523 Multiple files or directories should be specified
3524 either as separate arguments to the
3526 method, or as a list.
3528 will also accept the return value of any of the construction environment
3533 Clean('foo', ['bar', 'baz'])
3534 Clean('dist', env.Program('hello', 'hello.c'))
3538 .RI Default( targets )
3539 This specifies a list of default targets,
3540 which will be built by
3542 if no explicit targets are given on the command line.
3546 and add to the list of default targets.
3548 Multiple targets should be specified as
3549 separate arguments to the
3551 method, or as a list.
3553 will also accept the Node returned by any
3554 of a construction environment's
3559 Default('foo', 'bar', 'baz')
3560 Default(['a', 'b', 'c'])
3561 hello = env.Program('hello', 'hello.c')
3569 will clear all default targets.
3572 will add to the (now empty) default-target list
3576 .RI Dir( name ", [" directory ])
3577 This returns an object that represents a given directory
3580 can be a relative or absolute path.
3582 is an optional directory that will be used as the parent directory.
3585 .RI EnsurePythonVersion( major ", " minor )
3586 Ensure that the Python version is at least
3589 print out an error message and exit SCons with a non-zero exit code if the
3590 actual Python version is not late enough.
3593 EnsurePythonVersion(2,2)
3597 .RI EnsureSConsVersion( major ", " minor )
3598 Ensure that the SCons version is at least
3601 print out an error message and exit SCons with a non-zero exit code if the
3602 actual SCons version is not late enough.
3605 EnsureSConsVersion(0,9)
3615 A default exit value of
3618 is used if no value is specified.
3624 to export a list of variables from the current
3625 SConscript file to all other SConscript files.
3626 The exported variables are kept in a global collection,
3627 so subsequent calls to
3629 will over-write previous exports that have the same name.
3630 Multiple variable names can be passed to
3632 as separate arguments or as a list. A dictionary can be used to map
3633 variables to a different name when exported. Both local variables and
3634 global variables can be exported.
3639 # Make env available for all SConscript files to Import().
3643 # Make env and package available for all SConscript files:.
3644 Export("env", "package")
3646 # Make env and package available for all SConscript files:
3647 Export(["env", "package"])
3649 # Make env available using the name debug:.
3650 Export({"debug":env})
3656 function supports an
3658 argument that makes it easier to to export a variable or
3659 set of variables to a single SConscript file.
3660 See the description of the
3665 .RI File( name ", [" directory ])
3666 This returns an object that represents a given file
3669 can be a relative or absolute path.
3671 is an optional directory that will be used as the parent directory.
3674 .RI FindFile( file ", " dirs )
3677 in the path specified by
3680 may be a list of file names or a single file name. In addition to searching
3681 for files that exist in the filesytem, this function also searches for
3682 derived files that have not yet been built.
3685 foo = FindFile('foo', ['dir1', 'dir2'])
3689 .\".RI GetBuildPath( XXX )
3693 .\".RI GetLaunchDir( XXX )
3698 Get the number of jobs (commands) that will be run simultaneously. See also
3705 This specifies help text to be printed if the
3707 argument is given to
3710 will exit after printing out the help text.
3716 to import a list of variables into the current SConscript file. This
3717 will import variables that were exported with
3723 Variables exported by
3726 Multiple variable names can be passed to
3728 as separate arguments or as a list. The variable "*" can be used
3729 to import all variables.
3734 Import("env", "variable")
3735 Import(["env", "variable"])
3740 .RI Literal( string )
3743 will be preserved as-is
3744 and not have construction variables expanded.
3747 .RI Local( targets )
3750 will have copies made in the local tree,
3751 even if an already up-to-date copy
3752 exists in a repository.
3755 .RI ParseConfig( env , command ", [" function ])
3758 to modify the specified environment
3760 as specified by the output of
3764 expects the output of a typical
3768 and parses the returned
3783 .RI Platform( string )
3784 Returns a callable object
3785 that can be used to initialize
3786 a construction environment using the
3787 platform keyword of the Environment() method.
3790 env = Environment(platform = Platform('win32'))
3797 variable from the user's external environment
3798 to the construction environment's
3801 This is so that any executed commands
3802 that use sockets to connect with other systems
3803 (such as fetching source files from
3804 external CVS repository specifications like
3805 .BR :pserver:anonymous:@cvs.sourceforge.net:/cvsroot/scons )
3806 will work on Win32 systems.
3809 .RI Repository( directory )
3812 is a repository to be searched for files.
3816 and each one adds to the list of
3817 repositories that will be searched.
3821 a repository is a copy of the source tree,
3822 from the top-level directory on down,
3824 both source files and derived files
3825 that can be used to build targets in
3826 the local source tree.
3827 The canonical example would be an
3828 official source tree maintained by an integrator.
3829 If the repository contains derived files,
3830 then the derived files should have been built using
3832 so that the repository contains the necessary
3833 signature information to allow
3835 to figure out when it is appropriate to
3836 use the repository copy of a derived file,
3837 instead of building one locally.
3839 Note that if an up-to-date derived file
3840 already exists in a repository,
3844 make a copy in the local directory tree.
3845 In order to guarantee that a local copy
3855 what variable(s) to use as the return value(s) of the current SConscript
3856 file. These variables will be returned to the "calling" SConscript file
3857 as the return value(s) of
3859 Multiple variable names should be passed to
3865 Return(["foo", "bar"])
3869 .RI SConscript( script ", [" exports ", " build_dir ", " src_dir ", " duplicate ])
3874 as a SConscript (configuration) file.
3878 argument provides a list of variable names or a dictionary of
3879 named values to export to
3881 These variables are locally exported only to the specified
3883 and do not affect the
3884 global pool of variables used by
3888 '\"If multiple dirs are provided,
3889 '\"each script gets a fresh export.
3894 function to import the variables.
3898 argument specifies that all of the target files
3899 (for example, object files and executables)
3900 that would normally be built in the subdirectory in which
3902 resides should actually
3907 argument specifies that the
3908 source files from which
3909 the target files should be built
3914 will link or copy (depending on the platform)
3915 all the source files into the build directory.
3916 This behavior may be disabled by
3917 setting the optional
3920 (it is set to 1 by default),
3923 will refer directly to
3924 the source files in their source directory
3925 when building target files.
3928 is usually safe, and always more efficient
3931 but it may cause build problems in certain end-cases,
3932 such as compiling from source files that
3933 are generated by the build.)
3935 Any variables returned by
3939 will be returned by the call to
3945 SConscript('subdir/SConscript')
3946 foo = SConscript('sub/SConscript', exports='env')
3947 SConscript('dir/SConscript', exports=['env', 'variable'])
3948 SConscript('src/SConscript', build_dir='build', duplicate=0)
3949 SConscript('bld/SConscript', src_dir='src', exports='env')
3953 .RI SConscriptChdir( value )
3956 changes its working directory
3957 to the directory in which each
3958 subsidiary SConscript file lives.
3959 This behavior may be disabled
3966 will stay in the top-level directory
3967 while reading all SConscript files.
3968 (This may be necessary when building from repositories,
3969 when all the directories in which SConscript files may be found
3970 don't necessarily exist locally.)
3972 You may enable and disable
3973 this ability by calling
3979 SConscript('foo/SConscript') # will not chdir to foo
3981 SConscript('bar/SConscript') # will chdir to bar
3985 .RI SetBuildSignatureType( type )
3987 This function tells SCons what type of build signature to use: "build" or
3988 "content". "build" means to concatenate the signatures of all source files
3989 of a derived file to make its signature, and "content" means to use
3990 the derived files content signature as its signature. "build" signatures
3991 are usually faster to compute, but "content" signatures can prevent
3992 redundant rebuilds. The default is "build".
3995 .RI SetContentSignatureType( type )
3997 This function tells SCons what type of content signature to use: "MD5" or
3998 "timestamp". "MD5" means to use the MD5 checksum of a files contents as
3999 its signature, and "timestamp" means to use a files timestamp as its
4000 signature. When using "timestamp" signatures, changes in the
4001 command line will not cause files to be rebuilt. "MD5" signatures take
4002 longer to compute, but "timestamp" signatures are less accurate. The
4007 Specifies the number of jobs (commands) to run simultaneously.
4009 overrides this function. See also
4016 Returns a list of file names or other objects.
4018 it will be split on strings of white-space characters
4020 making it easier to write long lists of file names.
4021 If arg is already a list,
4022 the list will be returned untouched.
4023 If arg is any other type of object,
4024 it will be returned as a list
4025 containing just the object.
4028 files = Split("f1.c f2.c f3.c")
4038 Returns a callable object
4039 that can be used to initialize
4040 a construction environment using the
4041 tools keyword of the Environment() method.
4044 env = Environment(tools = [ Tool('msvc') ])
4048 .RI WhereIs( program ", [" path ", [" pathext ]])
4050 Searches for the specified executable
4052 returning the full path name to the program
4054 and returning None if not.
4055 Searches the specified
4057 or the user's current PATH
4058 (os.environ['PATH'])
4060 On Win32 systems, searches for executable
4061 programs with any of the file extensions
4062 listed in the specified
4064 or the user's current PATHEXT
4065 (os.environ['PATHEXT'])
4071 can be extended by adding new builders to a construction
4072 environment using the
4077 function accepts the following arguments:
4080 The command line string used to build the target from the source.
4083 a list of strings representing the command
4084 to be executed and its arguments
4085 (suitable for enclosing white space in an argument),
4087 mapping source file name suffixes to
4088 any combination of command line strings
4089 (if the builder should accept multiple source file extensions),
4092 (see the next section);
4093 or a list of any of the above.
4096 takes three arguments:
4098 - a list of source nodes,
4100 - a list of target nodes,
4102 - the construction environment.
4105 Specifies whether this builder is allowed to be called multiple times for
4106 the same target file(s). The default is 0, which means the builder
4107 can not be called multiple times for the same target file(s). Calling a
4108 builder multiple times for the same target simply adds additional source
4109 files to the target; it is not allowed to change the environment associated
4110 with the target, specify addition environment overrides, or associate a different
4111 builder with the target.
4114 The prefix that will be prepended to the target file name.
4117 The suffix that will be appended to the target file name.
4120 The expected source file name suffix.
4123 Specifies a builder to use when a source file name suffix does not match
4124 any of the suffixes of the builder. Using this argument produces a
4125 multi-stage builder.
4128 A function that is passed the target, source, and environment,
4129 and which returns a tuple containing two lists,
4130 the list of targets to be built by this builder,
4131 and the list of sources for this builder.
4132 This allows the target and source lists to
4133 be manipulated before the target(s) are actually built.
4135 The emitter function
4136 takes three arguments:
4138 - a list of source nodes,
4140 - a list of target nodes,
4142 - the construction environment.
4147 def e(target, source, env):
4148 return (target + ['foo.foo'], source + ['foo.src'])
4150 b = Builder(emitter=e)
4154 A function that returns a list of actions that will be executed to build
4155 the target(s) from the source(s).
4156 The returned action(s) may be
4157 an Action object, or anything that
4158 can be converted into an Action object
4159 (see the next section).
4161 The generator function
4162 takes four arguments:
4164 - a list of source nodes,
4166 - a list of target nodes,
4168 - the construction environment.
4170 - a Boolean value that specifies
4171 whether the generator is being called
4172 for generating a build signature
4173 (as opposed to actually executing the command).
4177 def g(source, target, env, for_signature):
4178 return [["gcc", "-c", "-o"] + target + source]
4180 b = Builder(generator=g)
4187 arguments must not both be used for the same Builder.
4190 A construction environment that can be used
4191 to fetch source code using this Builder.
4192 (Note that this environment is
4194 used for normal builds of normal target files,
4195 which use the environment that was
4196 used to call the Builder for the target file.)
4199 A dictionary of construction variables
4200 that will be set in the executing
4201 construction environment when this
4203 The canonical example here would be
4204 to set a construction variable to
4205 the repository of a source code system.
4207 Any additional keyword arguments supplied
4208 when a Builder object is called
4209 will be associated with the target
4210 (and any other files built as a
4211 result of the call).
4214 b = Builder(action="build < $SOURCE > $TARGET")
4215 env = Environment(BUILDERS = {'MyBuild' : b})
4216 env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy')
4219 These extra keyword arguments are passed to the
4220 following functions:
4221 command generator functions,
4223 and emitter functions.
4227 The Builder function will turn its
4229 keyword argument into an appropriate
4230 internal Action object.
4231 Occasionally, it may be more efficient
4232 to create an explicit Action object
4233 and use it to initialize multiple
4235 rather than let each separate Builder object
4236 create a separate Action.
4238 The Action method takes one or two arguments
4239 and returns an appropriate object for the action
4240 represented by the type of the first argument:
4243 If the first argument is already an Action object,
4244 the object is simply returned.
4247 If the first argument is a string,
4248 a command-line Action is returned.
4251 Action('$CC -c -o $TARGET $SOURCES')
4254 .\" XXX From Gary Ruben, 23 April 2002:
4255 .\" What would be useful is a discussion of how you execute command
4256 .\" shell commands ie. what is the process used to spawn the shell, pass
4257 .\" environment variables to it etc., whether there is one shell per
4258 .\" environment or one per command etc. It might help to look at the Gnu
4259 .\" make documentation to see what they think is important to discuss about
4260 .\" a build system. I'm sure you can do a better job of organising the
4261 .\" documentation than they have :-)
4265 If the first argument is a list,
4266 then a list of Action objects is returned.
4267 An Action object is created as necessary
4268 for each element in the list.
4271 the list is itself a list,
4272 the internal list is the
4273 command and arguments to be executed via
4275 This allows white space to be enclosed
4276 in an argument by defining
4277 a command in a list within a list:
4279 Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']])
4283 If the first argument is a Python function,
4284 a function Action is returned.
4285 The Python function takes three keyword arguments,
4287 (a Node object representing the target file),
4289 (a Node object representing the source file)
4292 (the construction environment
4293 used for building the target file).
4298 arguments may be lists of Node objects if there is
4299 more than one target file or source file.
4300 The actual target and source file name(s) may
4301 be retrieved from their Node objects
4302 via the built-in Python str() function:
4304 target_file_name = str(target)
4305 source_file_names = map(lambda x: str(x), source)
4308 The function should return
4312 to indicate a successful build of the target file(s).
4313 The function may raise an exception
4314 or return a non-zero exit status
4315 to indicate an unsuccessful build.
4318 def build_it(target = None, source = None, env = None):
4319 # build the target from the source
4322 a = Action(build_it)
4325 The second, optional argument
4326 is a Python function that returns
4327 a string to be printed to describe the action being executed.
4328 Like the function to build a file,
4329 this function takes three arguments:
4331 (a Node object representing the target file),
4333 (a Node object representing the source file)
4336 (a construction environment).
4341 arguments may be lists of Node objects if there is
4342 more than one target file or source file.
4346 def build_it(target, source, env):
4347 # build the target from the source
4350 def string_it(target, source, env):
4351 return "building '%s' from '%s'" % (target[0], source[0])
4353 # Use a positional argument.
4354 a = Action(build_it, string_it)
4356 # Alternatively, use a keyword argument.
4357 a = Action(build_it, strfunction=string_it)
4360 The third, also optional argument
4361 is a list of construction variables
4362 whose values will be included
4363 in the signature of the Action
4364 when deciding whether a target should
4365 be rebuilt because the action changed.
4366 This is necessary whenever you want a target to
4367 be rebuilt when a specific
4368 construction variable changes,
4369 because the underlying Python code for a function
4370 will not change when the value of the construction variable does.
4373 def build_it(target, source, env):
4374 # build the target from the 'XXX' construction variable
4375 open(target[0], 'w').write(env['XXX'])
4378 def string_it(target, source):
4379 return "building '%s' from '%s'" % (target[0], source[0])
4381 # Use positional arguments.
4382 a = Action(build_it, string_it, ['XXX'])
4384 # Alternatively, use a keyword argument.
4385 a = Action(build_it, varlist=['XXX'])
4388 If the action argument is not one of the above,
4391 .SS Variable Substitution
4393 Before executing a command,
4395 performs construction variable interpolation on the strings that make up
4396 the command line of builders.
4397 Variables are introduced by a
4400 Besides construction variables, scons provides the following
4401 variables for each command execution:
4404 The file name of the target being built, or the file name of the first
4405 target if multiple targets are being built.
4408 The file names of all targets being built.
4411 The file name of the source of the build command, or the file name of the
4412 first source if multiple sources are being built.
4415 The file names of the sources of the build command.
4417 (Note that the above variables are reserved
4418 and may not be set in a construction environment.)
4421 For example, given the construction variable CC='cc', targets=['foo'], and
4422 sources=['foo.c', 'bar.c']:
4425 action='$CC -c -o $TARGET $SOURCES'
4428 would produce the command line:
4431 cc -c -o foo foo.c bar.c
4434 Variable names may be surrounded by curly braces ({})
4435 to separate the name from the trailing characters.
4436 Within the curly braces, a variable name may have
4437 a Python slice subscript appended to select one
4438 or more items from a list.
4439 In the previous example, the string:
4451 Additionally, a variable name may
4452 have the following special
4453 modifiers appended within the enclosing curly braces
4454 to modify the interpolated string:
4457 The base path of the file name,
4458 including the directory path
4459 but excluding any suffix.
4462 The name of the directory in which the file exists.
4466 minus any directory portion.
4469 Just the basename of the file,
4471 and minus the directory.
4474 Just the file suffix.
4477 The absolute path name of the file.
4480 The POSIX form of the path,
4481 with directories separated by
4485 This is sometimes necessary on Win32 systems
4486 when a path references a file on other (POSIX) systems.
4489 The directory and file name to the source file linked to this file
4490 through BuildDir. If this file isn't linked, it just returns the
4491 directory and filename unchanged.
4494 The directory containing the source file linked to this file
4495 through BuildDir. If this file isn't linked, it just returns the
4496 directory part of the filename.
4499 For example, the specified target will
4500 expand as follows for the corresponding modifiers:
4503 $TARGET => sub/dir/file.x
4504 ${TARGET.base} => sub/dir/file
4505 ${TARGET.dir} => sub/dir
4506 ${TARGET.file} => file.x
4507 ${TARGET.filebase} => file
4508 ${TARGET.suffix} => .x
4509 ${TARGET.abspath} => /top/dir/sub/dir/file.x
4511 BuildDir('sub/dir','src')
4512 $SOURCE => sub/dir/file.x
4513 ${SOURCE.srcpath} => src/file.x
4514 ${SOURCE.srcdir} => src
4517 Lastly, a variable name
4518 may be a callable Python function
4520 construction variable in the environment.
4522 take three arguments:
4524 - a list of target nodes,
4526 - a list of source nodes,
4528 - the construction environment.
4529 SCons will insert whatever
4530 the called function returns
4531 into the expanded string:
4534 def foo(target, source, env):
4537 # Will expand $BAR to "bar baz"
4538 env=Environment(FOO=foo, BAR="$FOO baz")
4541 You can use this feature to pass arguments to a
4542 Python function by creating a callable class
4543 that stores one or more arguments in an object,
4544 and then uses them when the
4547 Note that in this case,
4548 the entire variable expansion must
4549 be enclosed by curly braces
4550 so that the arguments will
4551 be associated with the
4552 instantiation of the class:
4556 def __init__(self, arg):
4559 def __call__(self, target, source, env):
4562 # Will expand $BAR to "my argument bar baz"
4563 env=Environment(FOO=foo, BAR="${FOO('my argument')} baz")
4567 The special pseudo-variables
4571 may be used to surround parts of a command line
4574 causing a rebuild--that is,
4575 which are not included in the signature
4576 of target files built with this command.
4581 will be removed from the command line
4582 before it is added to file signatures,
4587 will be removed before the command is executed.
4588 For example, the command line:
4591 echo Last build occurred $( $TODAY $). > $TARGET
4595 would execute the command:
4598 echo Last build occurred $TODAY. > $TARGET
4602 but the command signature added to any target files would be:
4605 echo Last build occurred . > $TARGET
4608 SCons uses the following rules when converting construction variables into
4612 When the value is a string it is interpreted as a space delimited list of
4613 command line arguments.
4616 When the value is a list it is interpreted as a list of command line
4617 arguments. Each element of the list is converted to a string.
4620 Anything that is not a list or string is converted to a string and
4621 interpreted as a single command line argument.
4624 Newline characters (\\n) delimit lines. The newline parsing is done after
4625 all other parsing, so it is not possible for arguments (e.g. file names) to
4626 contain embedded newline characters. This limitation will likely go away in
4627 a future version of SCons.
4635 new file types for implicit dependencies.
4636 Scanner accepts the following arguments:
4639 A Python function that will process
4641 and return a list of strings (file names)
4642 representing the implicit
4643 dependencies found in the contents.
4644 The function takes three or four arguments:
4646 def scanner_function(node, env, path):
4648 def scanner_function(node, env, path, arg):
4652 argument is the internal
4653 SCons node representing the file.
4656 to fetch the name of the file, and
4657 .B node.get_contents()
4658 to fetch contents of the file.
4662 argument is the construction environment for the scan.
4663 Fetch values from it using the
4669 argument is a tuple (or list)
4670 of directories that can be searched
4672 This will usually be the tuple returned by the
4674 argument (see below).
4678 argument is the argument supplied
4679 when the scanner was created, if any.
4682 The name of the Scanner.
4684 to identify the Scanner internally.
4687 An optional argument that, if specified,
4688 will be passed to the scanner function
4690 and the path function
4694 An optional list that can be used to
4695 determine which scanner should be used for
4697 In the usual case of scanning for file names,
4698 this array will be a list of suffixes
4699 for the different file types that this
4700 Scanner knows how to scan.
4703 A Python function that takes
4704 two or three arguments:
4705 a construction environment, directory Node,
4706 and optional argument supplied
4707 when the scanner was created.
4710 returns a tuple of directories
4711 that can be searched for files to be returned
4712 by this Scanner object.
4715 The class of Node that should be returned
4716 by this Scanner object.
4717 Any strings or other objects returned
4718 by the scanner function
4719 that are not of this class
4720 will be run through the
4725 A Python function that will take a string
4727 and turn it into the appropriate class of Node
4728 to be returned by this Scanner object.
4731 An optional Python function that takes a Node (file)
4732 as an argument and returns whether the
4733 Node should, in fact,
4734 be scanned for dependencies.
4735 This check can be used to eliminate unnecessary
4736 calls to the scanner function when,
4737 for example, the underlying file
4738 represented by a Node does not yet exist.
4741 An optional flag that
4742 specifies whether this scanner should be re-invoked
4743 on the dependency files returned by the scanner.
4744 When this flag is not set,
4745 the Node subsystem will
4746 only invoke the scanner on the file being scanned,
4747 and not (for example) also on the files
4748 specified by the #include lines
4749 in the file being scanned.
4751 .SH SYSTEM-SPECIFIC BEHAVIOR
4752 SCons and its configuration files are very portable,
4753 due largely to its implementation in Python.
4754 There are, however, a few portability
4755 issues waiting to trap the unwary.
4757 SCons handles the upper-case
4759 file suffix differently,
4760 depending on the capabilities of
4761 the underlying system.
4762 On a case-sensitive system
4763 such as Linux or UNIX,
4764 SCons treats a file with a
4766 suffix as a C++ source file.
4767 On a case-insensitive system
4769 SCons treats a file with a
4771 suffix as a C source file.
4773 SCons handles the upper-case
4775 file suffix differently,
4776 depending on the capabilities of
4777 the underlying system.
4778 On a case-sensitive system
4779 such as Linux or UNIX,
4780 SCons treats a file with a
4782 suffix as a Fortran source file
4783 that is to be first run through
4784 the standard C preprocessor.
4785 On a case-insensitive system
4787 SCons treats a file with a
4789 suffix as a Fortran source file that should
4791 be run through the C preprocessor.
4792 .SS WIN32: Cygwin Tools and Cygwin Python vs. Windows Pythons
4793 Cygwin supplies a set of tools and utilities
4794 that let users work on a
4795 Windows system using a more POSIX-like environment.
4796 The Cygwin tools, including Cygwin Python,
4798 by sharing an ability to interpret UNIX-like path names.
4799 For example, the Cygwin tools
4800 will internally translate a Cygwin path name
4801 like /cygdrive/c/mydir
4802 to an equivalent Windows pathname
4803 of C:/mydir (equivalent to C:\\mydir).
4806 that are built for native Windows execution,
4807 such as the python.org and ActiveState versions,
4808 do not have the Cygwin path name semantics.
4809 This means that using a native Windows version of Python
4810 to build compiled programs using Cygwin tools
4811 (such as gcc, bison, and flex)
4812 may yield unpredictable results.
4813 "Mixing and matching" in this way
4814 can be made to work,
4815 but it requires careful attention to the use of path names
4816 in your SConscript files.
4818 In practice, users can sidestep
4819 the issue by adopting the following rules:
4821 use the Cygwin-supplied Python interpreter
4823 when using Microsoft Visual C/C++
4824 (or some other Windows compiler)
4825 use the python.org or ActiveState version of Python
4827 .SS WIN32: scons.bat file
4829 SCons is executed via a wrapper
4832 This has (at least) two ramifications:
4834 First, Windows command-line users
4835 that want to use variable assignment
4837 may have to put double quotes
4838 around the assignments:
4841 scons "FOO=BAR" "BAZ=BLEH"
4844 Second, the Cygwin shell does not
4845 recognize this file as being the same
4848 command issued at the command-line prompt.
4849 You can work around this either by
4852 from the Cygwin command line,
4853 or by creating a wrapper shell
4859 The MinGW bin directory must be in your PATH environment variable or the
4860 PATH variable under the ENV construction variable for SCons
4861 to detect and use the MinGW tools. When running under the native Windows
4862 Python interpreter, SCons will prefer the MinGW tools over the Cygwin
4863 tools, if they are both installed, regardless of the order of the bin
4864 directories in the PATH variable. If you have both MSVC and MinGW
4865 installed and you want to use MinGW instead of MSVC,
4866 then you must explictly tell SCons to use MinGW by passing
4872 to the Environment() function, because SCons will prefer the MSVC tools
4873 over the MinGW tools.
4877 To help you get started using SCons,
4878 this section contains a brief overview of some common tasks.
4882 build all of its targets by default,
4883 like other build tools do.
4884 The canonical way to invoke SCons
4885 is with a target of '.' (dot)
4886 to represent all targets in and below the current directory:
4892 One or more default targets may be specified
4893 via the Default() method
4894 in the SConstruct file.
4896 .SS Basic Compilation From a Single Source File
4900 env.Program(target = 'foo', source = 'foo.c')
4903 Note: Build the file by specifying
4904 the target as an argument
4905 ("scons foo" or "scons foo.exe").
4906 or by specifying a dot ("scons .").
4908 .SS Basic Compilation From Multiple Source Files
4912 env.Program(target = 'foo', source = Split('f1.c f2.c f3.c'))
4915 .SS Setting a Compilation Flag
4918 env = Environment(CCFLAGS = '-g')
4919 env.Program(target = 'foo', source = 'foo.c')
4922 .SS Search The Local Directory For .h Files
4926 need to set CCFLAGS to specify -I options by hand.
4927 SCons will construct the right -I options from CPPPATH.
4930 env = Environment(CPPPATH = ['.'])
4931 env.Program(target = 'foo', source = 'foo.c')
4934 .SS Search Multiple Directories For .h Files
4937 env = Environment(CPPPATH = ['include1', 'include2'])
4938 env.Program(target = 'foo', source = 'foo.c')
4941 .SS Building a Static Library
4945 env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c'))
4946 env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c'])
4949 .SS Building a Shared Library
4953 env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c'])
4954 env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c'))
4957 .SS Linking a Local Library Into a Program
4960 env = Environment(LIBS = 'mylib', LIBPATH = ['.'])
4961 env.Library(target = 'mylib', source = Split('l1.c l2.c'))
4962 env.Program(target = 'prog', source = ['p1.c', 'p2.c'])
4965 .SS Defining Your Own Builder Object
4967 Notice that when you invoke the Builder,
4968 you can leave off the target file suffix,
4969 and SCons will add it automatically.
4972 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
4974 src_suffix = '.tex')
4975 env = Environment(BUILDERS = {'PDFBuilder' : bld})
4976 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
4978 # The following creates "bar.pdf" from "bar.tex"
4979 env.PDFBuilder(target = 'bar', source = 'bar')
4982 Note also that the above initialization
4983 overwrites the default Builder objects,
4984 so the Environment created above
4985 can not be used call Builders like env.Program(),
4986 env.Object(), env.StaticLibrary(), etc.
4988 .SS Adding Your Own Builder Object to an Environment
4991 bld = Builder(action = 'pdftex < $SOURCES > $TARGET'
4993 src_suffix = '.tex')
4995 env.Append(BUILDERS = {'PDFBuilder' : bld})
4996 env.PDFBuilder(target = 'foo.pdf', source = 'foo.tex')
4997 env.Program(target = 'bar', source = 'bar.c')
5000 You also can use other Pythonic techniques to add
5001 to the BUILDERS construction variable, such as:
5005 env.['BUILDERS]['PDFBuilder'] = bld
5008 .SS Defining Your Own Scanner Object
5013 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
5015 def kfile_scan(node, env, path, arg):
5016 contents = node.get_contents()
5017 includes = include_re.findall(contents)
5020 kscan = Scanner(name = 'kfile',
5021 function = kfile_scan,
5024 scanners = Environment().Dictionary('SCANNERS')
5025 env = Environment(SCANNERS = scanners + [kscan])
5027 env.Command('foo', 'foo.k', 'kprocess < $SOURCES > $TARGET')
5029 bar_in = File('bar.in')
5030 env.Command('bar', bar_in, 'kprocess $SOURCES > $TARGET')
5031 bar_in.target_scanner = kscan
5034 .SS Creating a Hierarchical Build
5036 Notice that the file names specified in a subdirectory's
5038 file are relative to that subdirectory.
5044 env.Program(target = 'foo', source = 'foo.c')
5046 SConscript('sub/SConscript')
5051 # Builds sub/foo from sub/foo.c
5052 env.Program(target = 'foo', source = 'foo.c')
5054 SConscript('dir/SConscript')
5059 # Builds sub/dir/foo from sub/dir/foo.c
5060 env.Program(target = 'foo', source = 'foo.c')
5063 .SS Sharing Variables Between SConscript Files
5065 You must explicitly Export() and Import() variables that
5066 you want to share between SConscript files.
5072 env.Program(target = 'foo', source = 'foo.c')
5075 SConscript('subdirectory/SConscript')
5077 subdirectory/SConscript:
5080 env.Program(target = 'foo', source = 'foo.c')
5083 .SS Building Multiple Variants From the Same Source
5085 Use the BuildDir() method to establish
5086 one or more separate build directories for
5087 a given source directory,
5088 then use the SConscript() method
5089 to specify the SConscript files
5090 in the build directories:
5097 BuildDir('foo', 'src')
5098 SConscript('foo/SConscript')
5102 BuildDir('bar', 'src')
5103 SConscript('bar/SConscript')
5108 env = Environment(CCFLAGS = ccflags)
5109 env.Program(target = 'src', source = 'src.c')
5112 Note the use of the Export() method
5113 to set the "ccflags" variable to a different
5114 value for each variant build.
5116 .SS Hierarchical Build of Two Libraries Linked With a Program
5121 env = Environment(LIBPATH = ['#libA', '#libB'])
5123 SConscript('libA/SConscript')
5124 SConscript('libB/SConscript')
5125 SConscript('Main/SConscript')
5130 env.Library('a', Split('a1.c a2.c a3.c'))
5135 env.Library('b', Split('b1.c b2.c b3.c'))
5140 e = env.Copy(LIBS = ['a', ','b'])
5141 e.Program('foo', Split('m1.c m2.c m3.c'))
5144 The '#' in the LIBPATH directories specify that they're relative to the
5145 top-level directory, so they don't turn into "Main/libA" when they're
5146 used in Main/SConscript.
5148 Specifying only 'a' and 'b' for the library names
5149 allows SCons to append the appropriate library
5150 prefix and suffix for the current platform
5151 (for example, 'liba.a' on POSIX systems,
5152 'a.lib' on Windows).
5154 .SS Customizing contruction variables from the command line.
5156 The following would allow the C compiler to be specified on the command
5157 line or in the file custom.py.
5160 opts = Options('custom.py')
5161 opts.Add('CC', 'The C compiler.')
5162 env = Environment(options=opts)
5163 Help(opts.GenerateHelpText(env))
5166 The user could specify the C compiler on the command line:
5172 or in the custom.py file:
5178 or get documentation on the options:
5189 .SS Using Microsoft Visual C++ precompiled headers
5191 Since windows.h includes everything and the kitchen sink, it can take quite
5192 some time to compile it over and over again for a bunch of object files, so
5193 Microsoft provides a mechanism to compile a set of headers once and then
5194 include the previously compiled headers in any object file. This
5195 technology is called precompiled headers. The general recipe is to create a
5196 file named "StdAfx.cpp" that includes a single header named "StdAfx.h", and
5197 then include every header you want to precompile in "StdAfx.h", and finally
5198 include "StdAfx.h" as the first header in all the source files you are
5199 compiling to object files. For example:
5203 #include <windows.h>
5204 #include <my_big_header.h>
5223 /* do some other stuff */
5229 env['PCHSTOP'] = 'StdAfx.h'
5230 env['PCH'] = env.PCH('StdAfx.cpp')[0]
5231 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
5234 For more information see the document for the PCH builder, and the PCH and
5235 PCHSTOP construction variables. To learn about the details of precompiled
5236 headers consult the MSDN documention for /Yc, /Yu, and /Yp.
5238 .SS Using Microsoft Visual C++ external debugging information
5240 Since including debugging information in programs and shared libraries can
5241 cause their size to increase significantly, Microsoft provides a mechanism
5242 for including the debugging information in an external file called a PDB
5243 file. SCons supports PDB files through the PDB construction
5249 env['PDB'] = 'MyApp.pdb'
5250 env.Program('MyApp', ['Foo.cpp', 'Bar.cpp'])
5253 For more information see the document for the PDB construction variable.
5258 Specifies the directory that contains the SCons Python module directory
5259 (e.g. /home/aroach/scons-src-0.01/src/engine).
5262 A string of options that will be used by scons in addition to those passed
5263 on the command line.
5274 Steven Knight <knight@baldmt.com>
5276 Anthony Roach <aroach@electriceyeball.com>